Action needed: Starting July 20, 2026, analyses running with a Java runtime lower than 21 are no longer supported.
Read the scanner requirements page for more details.
Ctrlk
Start FreeLogin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

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.

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.
SAML SSO
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.
OIDC SSO

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.

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.

Don't manually add SSO users to non-IdP groups. That membership disappears at their next SSO login.

Phase 2: Configure the SSO connection

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.

  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.

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.

  1. 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.

SAML SSO Configure Connection section with the Automatic tab selected, showing the Metadata URL input field and the navigation steps for SSO setup.
Attribute Mapping section of a Single Sign-On configuration, mapping the required Email, Groups, Login, and Name attributes to their corresponding values.

  1. Configure the group claim. It's required for automatic group synchronization, whether you use SCIM or JIT.

  2. Assign the test user or test group to the IdP application.

  3. In the SonarQube Cloud assistant, run Test Connection and validate the returned attributes:

    • Email.

    • Login or unique identifier.

    • Name.

    • Groups.

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.

  1. 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.

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.
SCIM handles user and group provisioning, deprovisioning, and membership sync.

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

Related pages

PreviousQuickstart guide for Enterprises
NextGetting started with SonarQube Cloud

Last updated

Was this helpful?