Can I migrate my IDP and preserve the same users on Jenkins®?

Can I migrate my IDP, i.e., from AD to SAML or from one AD server to another, and preserve the same users on Jenkins®? Will the previously existing users be able to log in and use the same user data as the API tokens and credentials?

The short answer: Yes, you can preserve the same users and their content when migrating your IDP. Please find further explanations below.

First of all, it is important to understand that Jenkins® users are not the same as IDP users. You may have users in your IDP that never log in on Jenkins®, therefore, those never generate Jenkins® users; and you may have Jenkins® users that belong to a different IDP (for example, users created when performing some tests using the Mock Security plugin) but are not present in your current IDP.

Taking that into consideration, when an IDP user logs in for the first time on Jenkins®, a new Jenkins® user is created, meaning that a new directory is generated in the filesystem under $JENKINS_HOME/users. The newly generated directory is called $JENKINS_USER_ID_$RANDOMLY_AUTOGENERATED_HASH, and inside are placed all the configuration files for the given user, for example, the config.xml that includes the list of its API Tokens, user-level credentials, etc., alongside the most important field: <id>.

When migrating, if the same Jenkins® user ID (the <id> field from the aforementioned config.xml) is honored for the IDP users, the Jenkins® users will be preserved. If not, they will be considered new users by Jenkins® and new directories like $JENKINS_USER_ID_$RANDOMLY_AUTOGENERATED_HASH will be generated under $JENKINS_HOME/users upon user login.

Taking SAML as an example, if during the migration the Username Attribute honor the value of the users Jenkins® ID, then the users will be preserved.

Following the SAML example, it is worth noting that the Display Name Attribute is not the same as Jenkins® ID, meaning that you can have two different Jenkins® users with same Display Name but different Jenkins® ID, and that can cause confusion. To corroborate they are different Jenkins® users, you should check their <id> values under their corresponding $JENKINS_USER_ID_$RANDOMLY_AUTOGENERATED_HASH/config.xml.