Overview

You can delegate authentication to a SAML 2.0 identity provider using SAML authentication. SonarQube uses the Service Provider (SP) initiated SAML.

You can delegate authentication to a SAML 2.0 identity provider using SAML authentication. SonarQube uses the Service Provider (SP) initiated SAML.

With this configured, you can also configure Overview to automatically provision users and groups to SonarQube.

SAML authentication flow

1. The user triggers SonarQube to initiate the SAML authentication process.

2. SonarQube creates a SAML request for the configured identity provider and sends it back to the user’s browser.

3. The user’s browser automatically relays the SAML request to the identity provider.

4. The identity provider authenticates the user and creates a SAML assertion containing the user information and privilege. Optionally, the identity provider can encrypt this assertion with the SonarQube certificate.

5. The identity provider sends a SAML assertion back to the web browser.

6. The user’s browser then relays the SAML assertion to SonarQube to authenticate and authorize the user.

7. SonarQube responds with the originally requested resource.

During the process, certificates are used to authenticate the identity provider and, optionally, SonarQube. The identity provider public certificate is necessary to ensure that the SAML assertion is genuine. The SonarQube certificate is optional, but ensures that only SonarQube can use the assertion provided.

Settings

Property	UI Name	Description	Required
sonar.auth.saml.enabled	Enabled	Controls whether SAML authentication is enabled on SonarQube.	Yes
sonar.auth.saml.applicationId	Application ID	The ID under which SonarQube is known to the identity provider.	Yes
sonar.auth.saml.providerName	Provider Name	The name of the identity provider displayed in the login page when SAML authentication is active.	Yes
sonar.auth.saml.providerId	Provider ID	The ID of the identity provider.	Yes
sonar.auth.saml.loginUrl	SAML login url	The URL at which the identity provider expects to receive SAML requests.	Yes
sonar.auth.saml.certificate.secured	Identity provider certificate	The public X.509 certificate used by the identity provider to authenticate SAML messages.	Yes
sonar.auth.saml.user.login	SAML user login attribute	The name of the attribute that the identity provider will use to store the authenticated user login.	Yes
sonar.auth.saml.user.name	SAML user name attribute	The name of the attribute that the identity provider will use to store the authenticated user name.	Yes
sonar.auth.saml.user.email	SAML user email attribute	The name of the attribute that the identity provider will use to store the authenticated user email.	No
sonar.auth.saml.group.name	SAML group attribute	The attribute defining the user group in SAML. If this attribute is not defined, users are associated with the default group. See the Overview for more details about group behavior.	No
sonar.auth.saml.signature.enabled	Sign requests	Controls whether SonarQube is expected to sign the SAML requests. If enabled, both the service provider’s private key and certificate must be provided.	No
sonar.auth.saml.sp.privateKey.secured	Service provider private key	The PKCS8 private key without password used by SonarQube to sign SAML requests and to decrypt encrypted SAML responses.	This is only required if sonar.auth.saml.signature.enabled is set to true or the Identity Provider sends encrypted SAML responses.
sonar.auth.saml.sp.certificate.secured	Service provider certificate	The public key part of the previously provided private key.	This is only required if sonar.auth.saml.signature.enabled is set to true.

Testing

After all the mandatory settings are filled, the SAML integration with the identity provider can be tested by clicking the Test configuration button. A new tab will open with more information regarding the success of the integration, attributes received from the identity provider, and any warnings or errors that occur.

SAML configuration related information and limitations

• SAML and reverse proxy configuration: When using SAML, make sure your reverse proxy is properly configured. See Operating the server for more information.

• Migrating from LDAP to SAML as Identity Provider: A guide on how to perform this migration is available here.

• Identity Provider initiated authentication is not supported: This is a known limitation of SonarQube when using SAML as the authentication mechanism. Only service provider-initiated authentication is fully supported.

• SAML Single Sign Out is not supported: Logging off from SonarQube when SAML authentication is enabled, will not result in a disconnection from the other services linked to the same identity provider.

SAML group synchronization

Group synchronization can be enabled for any SAML provider including Azure, Keycloak and Okta, and also any SAML endpoint. To enable the SAML group attribute, navigate to Administration > Configuration > General Settings > Authentication > SAML > Configuration.

See the Group synchronization section on the Overview for more details about this feature’s general behavior.

When group synchronization is configured, the delegated authentication source becomes the only place to manage group membership, and the user’s groups are re-fetched with each login. It is not possible to use both manual group memberships and group synchronization (via your ALM integration) for the same user.