Before setting up SSO and provisioning

Read this page before setting up Single Sign-On (SSO) in your SonarQube Cloud enterprise.

We recommend that you read About SSO and provisioning before starting the setup.

SSO and provisioning setup overview

The setup steps are as follows:

1. Set up SSO SonarQube Cloud provides a setup assistant to help you configure custom SAML or Okta OIDC. See Set up SSO. If you hold administrative rights for both your Okta tenant and SonarQube Cloud enterprise, you can alternatively use the Okta Express Configuration to set up SSO. See Using Okta Express Configuration.
2. Set up SCIM This step is optional. You can perform it directly after setting up SSO or anytime later. See Set up SCIM. If you don't set up SCIM provisioning, Just-in-Time provisioning will apply. In this case, you have to create first the groups in SonarQube Cloud manually or verify your existing groups. See Managing groups in SonarQube Cloud if using JIT provisioning.
3. Invite users to sign in In this step, you will configure one-click access, invite your users to sign in via SSO, and finalize your SSO setup. See Invite users to sign in.

Important notes

Service Provider (SP) initiated SSO

SonarQube Cloud uses Service Provider (SP) initiated Single Sign-On (SSO). This process involves users attempting to log in to SonarQube Cloud, which then redirects them to your identity provider for authentication.

Identity Provider (IdP) initiated SSO is supported only through the Okta dashboard if you set up SSO with the Okta Express Configuration or by using the one-click access link in the SSO & Provisioning screen.

Group setup is mandatory

Be aware that with SSO, groups are mandatory. Users have access to their SonarQube Cloud organization only if they are members of a group within this organization.

It means that you must assign groups to the SonarQube Cloud application that you will create in your identity provider:​

• ​If you intend to use SCIM provisioning, you'll map groups to organizations during the SCIM setup, and groups will be automatically created in the relevant SonarQube Cloud organizations.
• Otherwise, Just-in-Time provisioning with automatic group synchronization will apply. In that case, you must create the user groups manually in your SonarQube Cloud organizations as described below in Managing groups in SonarQube Cloud if using JIT provisioning.

Regardless of your chosen provisioning method, you must configure the groups attribute in the SAML or OIDC payload. If you use SCIM provisioning, ensuring this value aligns with the data SCIM transmits to SonarQube Cloud is essential.

Managing groups in SonarQube Cloud if using JIT provisioning

If you don't use SCIM provisioning with SSO, Just-in-Time provisioning will apply. In that case, you must create the user groups also in SonarQube Cloud and ensure the automatic group synchronization can take place properly. To do so, make sure that:

• The user groups defined in your IdP service exist in the relevant organizations of your SonarQube Cloud enterprise (i.e. a group with the same (context-sensitive) name exists in the relevant organization(s)).
• The user groups in SonarQube Cloud have the correct permissions.

JIT SSO users' group memberships are reset to match those in your identity provider upon login. If you add a JIT SSO user to a SonarQube Cloud group that doesn't exist in the identity provider, the user will be removed from that group on their next login.

To manage the user groups in SonarQube Cloud, see Managing user groups.

Verify groups

With Okta

The automatic group synchronization of a group applies if the group in Okta and the corresponding group in the SonarQube Cloud organization have the same (case-sensitive) name. Note that the default SonarQube Cloud’s Members group is excluded from the synchronization.

The figure below shows on the left groups defined in Okta and on the right the corresponding groups defined in SonarQube Cloud in two different organizations (OrgA and OrgB). In this example, the SSO users belonging to ENT_ORGA_ADMINS will be automatically added to the corresponding EN_ORG_ADMINS group in SonarQube Cloud. it means that they will have access to OrgA with the permissions defined in SonarQube Cloud.

With Microsoft Entra ID

The automatic group synchronization of a group applies if the group in Microsoft Entra ID and the corresponding group in the SonarQube Cloud organization have the same (case-sensitive) name. Note that the default SonarQube Cloud’s Members group is excluded from the synchronization.

The figure below shows on the left groups defined in Microsoft Entra ID and on the right the corresponding groups defined in SonarQube Cloud in two different organizations (Docs-Team and claudiasonarova 2023). In this example, the SSO users belonging to Communications will be automatically added to the corresponding Communications group in SonarQube Cloud. it means that they will have access to the Docs-Team organization with the permissions defined in SonarQube Cloud.

• Group synchronization doesn’t work with Microsoft Entra ID’s nested groups.
• Microsoft Entra ID’s SAML tokens have a limit regarding the number of groups a user can belong to (see the description of groups in the Claims in SAML Token table). In such cases, you might need to reduce the number of groups the user is in.

Verify group permissions

To verify the group permissions at the enterprise level, see Managing the enterprise-related permissions.

In an organization, you can:

• Verify the groups that can create projects in the organization. See Managing organization permissions for more details.
• Verify the default permissions on new projects. See Using permission templates for more details.