Migrating SonarQube Users Between Identity Providers (with a focus on LDAP β†’ SAML)

Introduction

SonarQube allows delegating authentication to a number of Identity Providers (LDAP, SAML, GitHub, GitLab, etc). It can happen that 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.

:warning: This guide assumes that SAML Authentication is already well configured on your SonarQube instance.

:warning: While this guide focuses on the migration from LDAP to SAML, the general principles can be applied for migrating between any two identity providers.

Changes from SonarQube v7.9 LTS to v8.9 LTS

A user should only authenticate to SonarQube with a single Identity Provider.

In SonarQube v8.9, a new Web API POST api/users/update_identity_provider is available to facilitate the migration of a user between Identity Providers.

While in previous versions of SonarQube it was possible to switch between Identity Providers if the login of a user matched, in SonarQube v8.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 sonarqube
HTTP Header Authentication sonarqube
SAML saml
GitHub github
GitLab gitlab

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

3 Likes