Set up SSO

How to set up Single Sign-On (SSO) in your enterprise by using the SonarQube Cloud setup assistant.

This feature requires the SonarQube Cloud Enterprise license.

For more information about SSO, see SSO and provisioning.

To set up SSO through Okta’s Express Configuration, see Using Okta Express Configuration.

To set up SSO in your enteprise, you must be the administrator of the enterprise in SonarQube Cloud.

If you don't intend to use SCIM provisioning, you must first manage the user groups and permissions in your organizations as described in If using JIT provisioning (Verify groups and permissions) below.

Start the SSO setup assistant

1. In SonarQube Cloud, retrieve your enterprise. See Retrieving and viewing your enterprise for more details.

2. Go to Administration > SSO & Provisioning. The SSO & Provisioning page opens.

1. Expand the Single sign-on section and select Set up SSO. A new page opens.

2. In the bottom-right corner, select Get Started. The Configure Your Connection page opens.

1. Select Single Sign-On. The SSO setup assistant opens.

1. Select your identity provider or protocol, and select Next.

The SSO setup assistant opens. Follow the instructions below depending on your selection:

• Okta OIDC

• Custom SAML

Okta OIDC

1

Create application

1. In Okta, go to Applications > Applications and select Create App Integration.

1. In the dialog:

   1. In Sign-in method, select OIDC - OpenID Connect. The Application type section shows up.

   2. In Application type, select Web application.

2. Select Next.

3. Fill in the fields and options as described below.

   • General settings:

     • App integration name: the SonarQube Cloud application name.

       Example: SonarQube Cloud.

   • Sign-in redirect URIs: Copy-paste the Callback URL field value from the setup assistant.

   • Assignments Select the following options:

     • Controlled access > Allow everyone in your organization to access

     • Enable immediate access > Enable immediate access with Federation Broker Mode

4. Select Save.

5. In the setup assistant, select Next to go to the step 2. Configure Connection.

2

Configure connection

1. In Okta’s SonarQube Cloud application, go to General > Client Credentials.

2. Copy the value of the Client ID field.

1. Paste the copied value to the Client ID field in the setup assistant page.

2. Go back to your Okta's SonarQube Cloud application and copy the client secret.

1. Paste the copied value to the Client Secret field in the setup assistant page.

2. Go back to Okta and select your account / name in the top-right corner.

3. Copy your Okta organization URL / domain.

1. Paste the copied value to the Okta Domain field in the setup assistant.

1. In the bottom right corner of the assistant, select Create Connection and then Proceed. SonarQube Cloud is trying to connect to your Identity Provider. If the connection is established, the assistant moves to step 3. Claims Mapping.

3

Claims Mapping

1. In your Okta’s SonarQube Cloud application, go to Sign On.

2. Go down to the Token claims section and open the Show legacy configuration panel.

3. Select Edit.

4. Set the fields as follows:

   • Groups claim type: Filter

   • Groups claim filter:

     • First field: groups

     • Second field: Select Matches regex and set the value to .*

1. Select Save.

2. In the SonarQube Cloud's setup assistant, select Next to go to the step 4. Assign Access.

4

Assign Access

1. In your Okta’s SonarQube Cloud application, go to Assignments.

2. Select Assign, then Assign to Groups.

3. Select the groups to assign to the application.

4. Select Done.

5. In the SonarQube Cloud's setup assistant, select Next to go to the step 5. Test SSO.

5

Test SSO

1. Select the Test Connection button. The test is started and the results are displayed on the page.

2. Verify the JSON response. In particular, verify that the email and groups attributes are correct. If the test was successful, select Enable Connection and Proceed.

3. If you want to set up SCIM provisioning, select Provisioning to open the SCIM provisioning setup assistant. See Set up SCIM for more details. Otherwise, enable the connection by selecting the Enable Connection button in the top-right corner.

6

Terminate

Terminate your SSO setup. See Complete SSO setup.

Custom SAML

1

Create and set up the SonarQube Cloud application in your identity provider

This step depends on your identity provider.

Okta

1. In Okta, under Applications, select Create App Integration.

1. In the dialog, select SAML 2.0.

2. Select Next.

3. Fill in the fields and options as described below.

   • General settings:

     • App name: SonarQube Cloud application name.

       Example: SonarQube Cloud.

     • App visibility: Do not display application icon to users: Select this option. (This is because SonarQube Cloud doesn’t support IdP-initiated SSO)

   • SAML settings:

     • Single sign on URL: Copy-paste the Single Sign-On URL field value from the setup assistant.

     • Audience URI (SP Entity ID): Copy-paste the Service Provider Identity ID field value from the setup assistant.

     • Response: Signed

     • Assertion Signature: Signed

     • Signature Algorithm: RSA-SHA256

   • For assertion encryption:

     • Assertion Encryption: If you want to enable assertion encryption, select Encrypted and fill in the fields below.

     • Encryption Algorithm: Select AES256-GCM for high security.

     • Key Transport Algorithm: RSA-OAEP

     • Encryption Certificate: The public X.509 certificate used by the identity provider to authenticate SAML messages.

Only a single sign-on URL is allowed. Attempting to configure URLs in Other Requestable SSO URLs will lead to errors in your SSO setup.

1. In the Feedback dialog, select Finish to confirm the creation of the SonarQube Cloud application.

2. In the setup assistant, select Next to go to the step 2. Configure Connection.

2. Configure Connection

1. In Okta’s SonarQube Cloud application, go to Sign On > Settings > Sign on methods. Copy the value of the Metadata URL field

1. Paste the copied value to the Metadata URL field in the Automatic tab of the setup assistant page.

1. In the assistant, select Create Connection and Proceed. SonarQube Cloud is trying to connect to your Identity Provider. If the connection is established, the assistant moves to step 3. Attribute Mapping.

3. Attribute Mapping

1. In Okta’s SonarQube Cloud application, go to Sign On.

2. Go down to the Attribute statements section and open the Show legacy configuration panel.

1. Select Edit.

2. In Profile attribute statements, add the attributes for Name, Login, and Email, and in Group Attribute Statements, add the attribute for Groups, as described below.

   • Name attribute:

     • Name: Copy the attribute's Mapping value from the assistant (use the Copy tool).

     • Name format: Unspecified

     • Value: user.firstName

   • Login attribute:

     • Name: Copy the attribute's Mapping value from the assistant (use the Copy tool).

     • Name format: Unspecified

     • Value: user.login

   • Email attribute:

     • Name: Copy the attribute's Mapping value from the assistant (use the Copy tool).

     • Name format: Unspecified

     • Value: user.email

   • Groups attribute:

     • Name: Copy the attribute's Mapping value from the assistant (use the Copy tool).

     • Name format: Unspecified

     • Filter: Select Matches regex and set the value to .*

1. Select Save.

2. In the SonarQube Cloud's setup assistant, select Next to go to the step 4. Test SSO. See Test the SSO connection.

Microsoft Entra ID

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

Proceed as follows:

1. In Microsoft Entra ID, go to Applications > Enterprise applications > All applications.

2. Select New application and then Create your own application.

Make sure you choose Create your own application. Do not select the non-affiliated Sonarqube Microsoft Entra Gallery app, which contains configurations that may prevent proper integration.

1. Fill in the name and select the Integrate any other application you don’t find in the gallery option.

2. Select Create.

3. From the Manage section of the SonarQube Cloud application, go to Single sign-on > SAML.

4. In the Basic SAML Configuration section, select Edit, fill in the Identifier and the Reply URL fields as described below, and save:

   • Identifier (Entity ID): Copy-paste the Service Provider Identity ID field value from the setup assistant.

   • Reply URL (Assertion Consumer Service URL): Copy-paste the Single Sign-On URL field value from the setup assistant.

   • Sign On URL (Optional): Until IdP initiated SSO is available, you can use this URL: https://sonarcloud.io/login/sso?enterprise_key=<enterprise_key>.

Only a single reply URL is allowed. Attempting to configure multiple reply URLs will lead to errors in your SSO setup.

1. In the setup assistant, select Next to go to the step 2. Configure Connection.

2. Configure Connection

1. In your SonarQube Cloud application in Microsoft Entra ID, go to SAML Certificates. Copy the value of the App Federation Metadata Url field and paste it into the Metadata URL field in the Automatic tab of the setup assistant page.

2. In the assistant, select Create Connection and Proceed. SonarQube Cloud is trying to connect to your Identity Provider. If the connection is established, the assistant moves to step 3. Attribute Mapping.

3. Attribute Mapping

1. In Microsoft Entra ID, go to he Attributes & Claims section of your SonarQube Cloud application.

2. Remove the namespaced attributes added by Microsoft Entra ID and listed in the Additional claims section.

3. Select Add new claim and define a claim for the Email attribute. This attribute is used to manage the email of the user.

   • In Name, paste the name copied from the Email's Mapping value in SonarQube Cloud's setup assistant.

   • In Source attribute, select user.mail .

The figure below shows the setup assistant of SonarQube Cloud. Use the copy tool to copy the Mapping value.

1. The same way, define a claim for the Login attribute. This attribute is the unique name used to identify the user in SonarQube Cloud. In Source attribute, select user.userprincipalname.

2. The same way, define a claim for the Name attribute. This attribute is the full name of the user. In Source attribute, select user.givenname or your own user name attribute.

The default list of attributes includes user.givenname (first name) and user.surname (last name). If you prefer to show the full name, you must create a new claim in MS Entra ID.

1. Select Add a group claim to define the Groups attribute. This attribute is used for automatic group synchronization. Set the parameters as follows:

   • Which groups associated with the user should be returned in the claim?: Groups assigned to the application

   • Source attribute: Cloud-only group display names or (if using on-prem Active Directory for group synchronisation) sAMAccountName

   • Emit group name for cloud-only groups option: If you use sAMAccountName, select the option. Otherwise, ignore the option.

The figure below shows a group attribute definition example.

Save. The option to add a group will be unavailable and the group attribute will be listed with the other attributes in the Additional claims section as illustrated below.

1. In the setup assistant, select Next to go to the step 4. Test SSO. See Test the SSO connection.

JumpCloud

1. In JumpCloud, go to SSO Applications and select + Add New Application.

1. Select Custom Application and select Next.

1. Click Next.

2. Select Manage Single Sign-On (SSO) and Configure SSO with SAML, and select Next.

1. Enter a display label and select Save Application. The application is created.

1. Select Configure Application.

2. In the SSO tab, in the Configuration Settings section, set the parameters as described below:

   • IdP Entity ID: Don't change the default value.

   • SP Entity ID: Copy-paste the Single Sign-On URL field value from the setup assistant.

   • ACS URL: Copy-paste the Single Sign-On URL field value from the setup assistant to Default URL.

Only a single ACS URL is allowed. Attempting to configure multiple ACS URLs will lead to errors in your SSO setup.

1. In JumpCloud Metadata in the same section, select the Copy Metadata URL button.

1. In SonarQube Cloud's SAML SSO setup assistant, go the step 2. Configure Connection and paste the copied value to Metadata URL in the Automatic tab.

1. Select Create Connection and then Proceed.

2. In SonarQube Cloud's SAML SSO setup assistant, go the step 3. Attribute Mapping.

3. In the SSO tab of the JumpCloud's application, go to the Attributes > User Attributes section and add three new attributes with the values described below:

   • Name attribute:

     • Service Provider Attribute Name: Paste the name copied from the Mapping value in SonarQube Cloud's setup assistant.

     • JumpCloud Atttribute Name: username

   • Login attribute:

     • Service Provider Attribute Name: Paste the name copied from the Mapping value in SonarQube Cloud's setup assistant.

     • JumpCloud Atttribute Name: displayname

   • Email attribute:

     • Service Provider Attribute Name: Paste the name copied from the Mapping value in SonarQube Cloud's setup assistant.

     • JumpCloud Atttribute Name: email

4. Under the Constant Attributes section, select the Include Group Attribute option. Copy the group attribute name from the assistant and paste it into Groups Attribute Name.

1. Select Save.

2. In SonarQube Cloud's SAML SSO setup assistant, select Next to go to step 4. Test SSO. See Test the SSO connection below.

Other identity providers

1. Create the SonarQube Cloud application in your identity provider.

2. Copy the Service Provider Identity ID field value from the setup assistant and paste it into the corresponding field in your identity provider.

3. Copy the Single Sign-On URL field value from the setup assistant and paste it into the corresponding field in your identity provider.

Only a single sign-on URL is allowed. Attempting to configure multiple sign-on URLs in your identity provider will lead to errors in your SSO setup.

1. In SonarQube Cloud's SSO setup assistant, select Next to go to the step 2. Configure Connection.

2. Configure Connection

The operation is different depending on whether your identity provider supports the SAML metadata URL field (URL used by SonarQube Cloud to access metadata information) or not.

Metadata URL supported

1. In your SonarQube Cloud application in your identity provider, copy the value of the field corresponding to the SAML metadata URL .

2. Paste it into the Metadata URL field in the Automatic tab of the setup assistant page.

1. In the assistant, select Create Connection and Proceed. SonarQube Cloud is trying to connect to your Identity Provider. If the connection is established, the assistant moves to step 3. Attribute Mapping.

Metadata URL not supported

1. In the assistant, select the Manual tab.

1. In your identity provider, copy the value of the SSO login URL field and paste it into Single Sign-On Login URL in the assistant.

2. In your identity provider, download the certificate and upload it to the assistant.

3. In the assistant, select Create Connection and Proceed. SonarQube Cloud is trying to connect to your Identity Provider. If the connection is established, the assistant moves to step 3. Attribute Mapping.

3. Attribute Mapping

1. In your identity provider, create the attributes for Name, Login, Email, and Groups (the group attribute is used for automatic group synchronization). To do so, for each attribute, copy the attribute's Mapping value from the assistant (use the Copy tool) and paste it into the attribute’s name field in your identity provider.

1. In the assistant, select Next to go to step 4. Test SSO. See Test the SSO connection.

2

Test the SSO connection

1. In your identity provider, assign the user groups to the SonarQube Cloud application (to be able to perform the test, at least one group or user must be assigned).

2. In the SonarQube Cloud's setup assistant, select the Test Connection button. The test is started and the results are displayed on the page as illustrated below.

1. If the test was successful, select Enable Connection and Proceed.

2. If you want to set up SCIM provisioning, select Provisioning to open the SCIM provisioning setup assistant and follow the setup instructions. See Set up SCIM for more details. Otherwise enable the connection by selecting the Enable Connection button in the top-right corner.

3

Terminate

Terminate your SSO setup. See Complete SSO setup.

If using JIT provisioning (Verify groups and permissions)

If you don't use SCIM provisioning with SSO, Just-in-Time provisioning will apply. In that case, you must verify your user groups to ensure the automatic group synchronization can take place properly. To do so, verify 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.

Related pages

• Set up SCIM

• Complete SSO setup

• Using Okta Express Configuration

• Editing or deleting SSO configuration

• Troubleshooting SSO and provisioning

Related online learning

• Initial SonarQube Cloud Enterprise set up