In this lesson, you will learn how to bridge the gap between legacy local UIDs and centralized identity providers by dynamically remapping user identifiers during the PAM authentication flow.
The Challenge of UID Fragmentation
When migrating users from a legacy local /etc/passwd database to a centralized identity service like LDAP or FreeIPA, you often run into "UID collision." A user might be uid=1005 on an old server, but their new global identity assigned by your directory service might be uid=2000. If you simply switch authentication methods, the user will lose access to their existing files, as the kernel still sees them as 1005 while the system now identifies them as 2000.
Dynamic Mapping with pam_substitute
Rather than manually re-chowning every file on your storage arrays, you can use the pam_substitute module (or similar custom logic within the PAM stack) to perform real-time ID translation. The goal is to instruct the system to "alias" the incoming identity to a different UID at the moment of login.
When a user authenticates, PAM intercepts the credentials and triggers a transformation. Instead of the system accepting the UID provided by the identity provider, the PAM module swaps the identity attributes before the session environment is fully initialized.
Configuration generally looks like this within your /etc/pam.d/common-auth stack:
# Remap legacy ID 1005 to modern ID 2000 during login
auth optional pam_substitute.so id_map=1005:2000
Why This Matters
By handling this at the PAM layer, you ensure that the transformation occurs during authentication, which is the precise moment the kernel maps the user to the process session. This allows for a "graceful migration": users can access their legacy files (owned by 1005) even though their system-level identity is now 2000. It prevents the massive downtime associated with bulk chown -R operations on high-latency network file systems.
Once your migration is complete and your storage permissions have been updated to the new global UIDs, you can simply remove the mapping line from your PAM configuration to clean up the environment.
Key Takeaway: PAM UID mapping acts as a shim that preserves file system compatibility for migrating users without requiring destructive permission changes across your entire storage infrastructure.