Overview
You can delegate authentication to a SAML 2.0 identity provider using SAML authentication. With this configured, you can also configure SCIM to automatically provision users and groups to SonarQube.
SAML authentication flow
- When a user requests a SonarQube web page and is not already authenticated, SonarQube will start a SAML authentication process.
- SonarQube creates a SAML request for the configured identity provider and sends it back to the user's browser.
- The user's browser automatically relays the SAML request to the identity provider.
- The identity provider authenticates the user and creates a SAML assertion containing the user information and privilege. Optionally, it can encrypt this assertion with the SonarQube certificate.
- The identity provider sends a SAML assertion back to the web browser.
- The user's browser then relays the SAML assertion to SonarQube to authenticate and authorize the user.
- 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 page 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. This option is only available for Just-in-Time user and group provisioning (default). Provide the SAML attribute name in the SAML group attribute field.
See the Group synchronization section on the Overview page 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.
© 2008-2023, SonarSource S.A, Switzerland. Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution-NonCommercial 3.0 United States License. SONARQUBE is a trademark of SonarSource SA. All other trademarks and copyrights are the property of their respective owners.
