Introduction
SonarQube allows delegating authentication to several Identity Providers (LDAP, SAML, GitHub, GitLab, etc.). However, after some time, a SonarQube administrator may need to change the Identity Provider that their users authenticate with.
In particular, there are many organizations making the switch from LDAP Authentication to SAML Authentication for their applications. This guide aims to make it clear how to migrate those users from one Identity Provider to another, focusing on the common LDAP to SAML migration path.
This guide assumes that SAML Authentication is already well configured on your SonarQube instance.
While this guide focuses on migrating from LDAP to SAML, the general principles can be applied to migrating between any two identity providers.
Changes from SonarQube 9.9 LTA to 10.x
Since SonarQube 10.4, the POST /api/users/update_identity_provider is deprecated. With SonarQube 10.4 and later, you need to use PATCH /api/v2/users-management/users/{id} like so:
curl -X PATCH -u <USER-TOKEN>: '<SONARQUBE-HOSTNAME>/api/v2/users-management/users/<ID-OF-USER>' \
-H 'Content-Type: application/merge-patch+json' \
-d '{"externalLogin": "colin.mueller3@example.com", "externalProvider": "saml"}'
The <ID-OF-USER> can be obtained from GET /api/v2/users-management/users or a similar API. See Web API v2 documentation in your SonarQube instance for more details.
Changes from SonarQube 8.9 LTS to 9.9 LTA
No critical changes were made. The Web API POST /api/users/update_identity_provider can still be used.
Changes from SonarQube 7.9 LTS to 8.9 LTS
A user should only authenticate to SonarQube with a single Identity Provider.
In SonarQube 8.9, a new Web API POST /api/users/update_identity_provider facilitates a user’s migration between Identity Providers.
While in previous versions of SonarQube, it was possible to switch between Identity Providers if a user’s login matched, in SonarQube 8.9 LTS, this is no longer the case, and users must be migrated to the new Identity Provider by an administrator using this Web API.
Step-by-step instructions
To migrate a user from LDAP to SAML, a SonarQube administrator must call the POST /api/users/update_identity_provider Web API. Documentation for the Web API can, as always, be found in the footer of your SonarQube instance.
The Web API accepts 3 parameters, 2 of which are required:
Required: login - is the login of the user you plan to migrate
Required: newExternalProvider - is supplied the new Identity Provider key. You can find the keys for Identity Providers with first-party support below. The Identity Provider must be configured in SonarQube before users can be migrated.
| Identity Provider | Key |
|---|---|
| Local | sonarqube |
| LDAP | LDAP_default |
| LDAP customserver | LDAP_customserver |
| HTTP Header Authentication | sonarqube |
| SAML | saml |
| GitHub | github |
| GitLab | gitlab |
| Bitbucket | bitbucket |
Optional: newExternalIdentity - the identity associated with this user by your new Identity Provider. If not supplied, the existing identity will be used.
newExternalIdentity is most relevant in cases where your users are known by their e-mail address with the new Identity Provider rather than an LDAP login (colin.mueller3@example.com vs. cmueller3).
A basic curl command to transition a user with login cmueller3 to saml with the new identity colin.mueller3@example.com looks like this
curl -X POST -u TOKEN: 'http://localhost:9000/api/users/update_identity_provider?login=cmueller3&newExternalIdentity=colin.mueller3@example.com&newExternalProvider=saml'
Of course, this only affects the login of a single user. You should use this to test the migration before you consider migrating many users to ensure you’ve done it correctly.
With some scripting know-how, it’s easy to automate the change for the rest of your users. You can find such an example script here.
Tips
- The migration should be tested in a non-production environment prior to production
- It’s advised to have a local user assigned the global Administer permissions so that, if the migration goes wrong, you are not completely locked out of your SonarQube instance.
- It’s very important that the above user not be included in the migration.
Do you have more questions? Raise a new thread in Get Help > SonarQube