> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cloud/quickstart-guides/transition-from-devops-platform-authentication-to-sso.md).

# Transition from DevOps-platform authentication to SSO

How to move a SonarQube Cloud Enterprise from DevOps-platform authentication to SSO, including group mapping, provisioning, pilot rollout, and rollback.

This guide walks Enterprise administrators through moving a SonarQube Cloud Enterprise whose users currently sign in through GitHub, GitLab, Bitbucket Cloud, or Azure DevOps to enterprise SSO.

{% hint style="warning" %}
This isn't an in-place conversion of user accounts. The first SSO login creates a distinct SSO account. Existing DevOps-platform accounts can stay enabled during the transition, so you can roll out in stages and roll back if needed.
{% endhint %}

## Prerequisites

Before you start, confirm the following:

* Your subscription is SonarQube Cloud Enterprise.
* Your SonarQube admin or admins have the Administer Enterprise permission.
* Your identity provider (IdP) administrator is available.
* You've decided on a provisioning model:
  * SCIM, to provision and sync users and groups from the IdP.
  * JIT provisioning, if accounts should be created at first SSO login and SCIM isn't the first use case internally.
* You've identified:
  * At least one SSO test user.
  * At least two emergency or recovery DevOps-platform administrators.

## Important behavior to communicate before the change

* SonarQube Cloud supports both DevOps-platform authentication and SSO in the same enterprise during the transition, but only one SSO configuration can be managed at a time.
* SSO is service-provider initiated: users start from SonarQube Cloud, which redirects them to the IdP and back to SonarQube Cloud.
* The first SSO login creates a new user account. Comments, issue history, favorites, and similar personal history from the DevOps-platform account don't carry over.
* Group membership is handled on the IdP side. With JIT provisioning, SonarQube Cloud resets a user's SSO group membership to match the IdP at every login. SCIM synchronizes membership dynamically instead.
* With JIT provisioning, an SSO user gets organization access only when an IdP group matches a SonarQube Cloud group name exactly, including case. The user must belong to that group on the IdP side.
* With SCIM provisioning, the SonarQube admin must ensure to map the IdP group to the correct SonarQube Cloud organization, which is configured in SonarQube Cloud. Otherwise, users cannot see their organization.

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-7372323e9cbb921d9f43847216b398f7abb25418%2Fsonarqube-cloud-sso-transition-saml-flow.png?alt=media" alt="SAML authentication flow: a user in a web browser initiates login, handled by the service provider (SonarQube Cloud). The service provider requests authentication via SAML redirect from the authentication service provider, Auth0. Auth0 sends a SAML request to the SAML identity provider, which responds with a SAML assertion. Auth0 receives the assertion and returns a token via redirect to the service provider, authenticating the user."><figcaption><p>SAML SSO</p></figcaption></figure>

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-3dbe43e910527168776bd909b5a51b4ea4a55277%2Fsonarqube-cloud-sso-transition-oidc-flow.png?alt=media" alt="OIDC authentication flow for SonarQube: a login attempt from the browser goes to the service provider (SonarQube), which redirects the user to the OIDC provider (Okta) for authentication. After authentication, the OIDC provider issues an ID token back to the service provider, which verifies the token and logs the user in."><figcaption><p>OIDC SSO</p></figcaption></figure>

## Phase 1: Prepare groups and access

1. Inventory every organization in the enterprise.
2. For each organization, list:
   * Current SonarQube Cloud groups.
   * Users who need administrator or portfolio permissions.
3. In the IdP, create and validate the groups that will obtain SonarQube Cloud access.
4. Make sure each group name exactly matches its counterpart in the IdP, including case.
5. Assign the test user and recovery administrator to an IdP group that maps to the appropriate SonarQube Cloud organization group.

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-61a11acf2506b13e413b11e285e5bcdb21410176%2Fsonarqube-cloud-sso-transition-idp-group-sync-jit.png?alt=media" alt="Integration between an identity provider and SonarQube Cloud for an SSO-enabled enterprise with JIT provisioning: a user account in the IdP is tied to a SAML SSO user account in SonarQube Cloud. A user group in the IdP, which the user is a member of, has the same name as a user group in SonarQube Cloud. That group is automatically synchronized and assigned to the organization in SonarQube Cloud, making the user a member through the group."><figcaption></figcaption></figure>

{% hint style="warning" %}
Don't manually add SSO users to non-IdP groups. That membership disappears at their next SSO login.
{% endhint %}

## Phase 2: Configure the SSO connection

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-e48d284ab32007a0779def8c6f48b77017c8f379%2Fsonarqube-cloud-sso-transition-sso-provisioning-settings.png?alt=media" alt="SonarQube Cloud SSO and provisioning settings page, showing how to secure access via SAML or OIDC and manage accounts using SCIM, with options to set up provisioning and map IdP groups."><figcaption></figcaption></figure>

1. Sign in with a DevOps-platform account that has Administer Enterprise.
2. Open the enterprise, then go to **Administration** > **SSO & Provisioning**.
3. Expand **Single sign-on**, select **Set up SSO**, then select **Get Started**. Choose your IdP or protocol. In most cases, you can choose Custom SAML, which is the simplest SAML configuration to set.

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-72acf875c58e116c0b2d5b53596ed62f67ebe28a%2Fsonarqube-cloud-sso-transition-select-idp.png?alt=media" alt="SSO configuration screen prompting the user to select their identity provider, with Okta and OIDC pre-listed, and Custom SAML or Custom OIDC for unlisted providers."><figcaption></figcaption></figure>

4. Configure the SonarQube Cloud application in the IdP using the values the assistant displays:
   * Service-provider identifier or entity ID.
   * Assertion consumer service or single sign-on URL.
   * Metadata URL or certificate.
   * Required user attributes: name, login, email, and groups.

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-b136ad63fb37d950b63c7795559d13f5e91b9e7c%2Fsonarqube-cloud-sso-transition-configure-connection.png?alt=media" alt="SAML SSO Configure Connection section with the Automatic tab selected, showing the Metadata URL input field and the navigation steps for SSO setup."><figcaption></figcaption></figure>

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-e046d90cde3086f3ee71a395927eb483f30291f2%2Fsonarqube-cloud-sso-transition-attribute-mapping.png?alt=media" alt="Attribute Mapping section of a Single Sign-On configuration, mapping the required Email, Groups, Login, and Name attributes to their corresponding values."><figcaption></figcaption></figure>

5. Configure the group claim. It's required for automatic group synchronization, whether you use SCIM or JIT.
6. Assign the test user or test group to the IdP application.
7. In the SonarQube Cloud assistant, run **Test Connection** and validate the returned attributes:
   * Email.
   * Login or unique identifier.
   * Name.
   * Groups.

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-7f354b466e7463c3d960e8321123c4cccd5a19df%2Fsonarqube-cloud-sso-transition-test-connection-success.png?alt=media" alt="Successful test of a Single Sign-On configuration. The Test SSO section shows a successful test and a JSON object with the returned user attributes, including user_id, email, name, and groups."><figcaption></figcaption></figure>

8. Enable the connection only after the test confirms the correct user and group values.

## Phase 3: Configure provisioning and domain verification

1. Choose one provisioning method:
   * (RECOMMENDED) Configure SCIM if you need centralized provisioning and deprovisioning.
   * Otherwise, use JIT provisioning and confirm that all matching groups already exist in SonarQube Cloud. Users must connect at least once to be created.
2. Verify your corporate email domain in the SSO assistant. This avoids one-time email verification for users who sign in with SSO, especially if the user is a service account.
3. Configure the enterprise recovery account after SSO is working. We strongly recommend this step to preserve enterprise access if the IdP or SSO configuration becomes unavailable.

<figure><img src="https://2223713658-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB4UT2GNiZKjtxFtcFAL7%2Fuploads%2Fgit-blob-187738ef839d4f6daa745b90b6b0be2f732c8611%2Fsonarqube-cloud-sso-transition-scim-flow.png?alt=media" alt="Integration between an identity provider and SonarQube Cloud for SSO with SCIM, showing how user accounts and groups are provisioned, deprovisioned, and synchronized between the IdP and SonarQube Cloud, granting user access within the organization."><figcaption><p>SCIM handles user and group provisioning, deprovisioning, and membership sync.</p></figcaption></figure>

## Phase 4: Pilot migration

1. Retrieve the enterprise SSO login URL from **Administration** > **SSO & Provisioning** > **Single sign-on** > **Invite users to sign in**.
2. Send the URL to a small number of test users only.
3. Ask each pilot user to:
   * Sign in through the enterprise SSO URL.
   * Confirm access to the expected organization or organizations.
   * Verify their expected project permissions.
   * Create new analysis tokens under the SSO account, if you use personal tokens.

## Phase 5: Roll out to all users

1. Communicate the enterprise SSO URL and the migration date to all users.
2. Tell users they must start login from SonarQube Cloud using the supplied URL or go to **Administration** > **SSO & Provisioning** > **Single sign-on** > **Configure one-click access** to get a URL for one-click SSO login.

## Rollback approach

If access or group synchronization is incorrect:

1. Don't remove the retained DevOps-platform administrator accounts.
2. Use the DevOps-platform enterprise administrator account to correct:
   * IdP application assignment.
   * Group claim mapping.
   * Exact group-name matching.
   * SonarQube Cloud group permissions.
   * Recovery-account configuration.
   * IdP group mapping to organizations (SCIM).
3. Retest with the pilot user before inviting more users.
4. Don't delete the SSO configuration as a first troubleshooting step. Keeping DevOps-platform authentication active during rollout gives you a safer recovery path.

## Completion checklist

* [ ] IdP groups match SonarQube Cloud groups exactly.
* [ ] SonarQube Cloud group permissions are validated for every organization.
* [ ] The SSO connection test returns the correct identity and group claims.
* [ ] The corporate domain is verified.
* [ ] Test users have validated organization, project, and administration access.
* [ ] SSO admins have Administer Enterprise.
* [ ] The recovery account is configured and documented.
* [ ] CI analysis tokens and integrations are validated.
* [ ] DevOps-platform fallback admins and service accounts are retained.
* [ ] End-user DevOps-platform memberships are removed only after validation.

## Related pages

* [Set up SSO](/sonarqube-cloud/administering-sonarcloud/enterprise-security/sso-and-provisioning/set-up-sso.md)
* [Set up SCIM](/sonarqube-cloud/administering-sonarcloud/enterprise-security/sso-and-provisioning/set-up-scim.md)
* [Recovery account for SSO](/sonarqube-cloud/administering-sonarcloud/enterprise-security/sso-and-provisioning/recovery-account.md)
* [Editing or deleting SSO configuration](/sonarqube-cloud/administering-sonarcloud/enterprise-security/sso-and-provisioning/edit-or-delete-sso-setup.md)
* [Troubleshooting SSO and provisioning](/sonarqube-cloud/administering-sonarcloud/enterprise-security/sso-and-provisioning/troubleshooting.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-cloud/quickstart-guides/transition-from-devops-platform-authentication-to-sso.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.