Overview of SAML support

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

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

SAML authentication flow

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

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

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’s information and privileges. Optionally, the identity provider can encrypt this assertion with SonarQube Server’s certificate. Note that in that case, the SAML response, which contains the encrypted assertion, must be signed.

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

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

7. SonarQube Server 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 Server.	Yes
sonar.auth.saml.applicationId	Application ID	The ID under which SonarQube Server 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 Server 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 Server 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 or if the SAML assertions emitted by the Identity Provider are encrypted.

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 Securing behind a proxy 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 Server 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 Server 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 in Just-in-Time provisioning 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.

Related pages

• With SCIM provisioning