Start Free
9.9 | Instance administration | Authentication | SAML | Overview

Overview

On this page

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

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

PropertyUI NameDescriptionRequired
sonar.auth.saml.enabledEnabledControls whether SAML authentication is enabled on SonarQube.Yes
sonar.auth.saml.applicationIdApplication IDThe ID under which SonarQube is known to the identity provider.Yes
sonar.auth.saml.providerNameProvider NameThe name of the identity provider displayed in the login page when SAML authentication is active.Yes
sonar.auth.saml.providerIdProvider IDThe ID of the identity provider.Yes
sonar.auth.saml.loginUrlSAML login urlThe URL at which the identity provider expects to receive SAML requests.Yes
sonar.auth.saml.certificate.securedIdentity provider certificateThe public X.509 certificate used by the identity provider to authenticate SAML messages.Yes
sonar.auth.saml.user.loginSAML user login attributeThe name of the attribute that the identity provider will use to store the authenticated user login.Yes
sonar.auth.saml.user.nameSAML user name attributeThe name of the attribute that the identity provider will use to store the authenticated user name.Yes
sonar.auth.saml.user.emailSAML user email attributeThe name of the attribute that the identity provider will use to store the authenticated user email.No
sonar.auth.saml.group.nameSAML group attributeThe 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.enabledSign requestsControls 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.securedService provider private keyThe 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.securedService provider certificateThe 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 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 and define your attribute value. 

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



Was this page helpful?

© 2008-2024 SonarSource SA. All rights reserved. SONAR, SONARSOURCE, SONARLINT, SONARQUBE, SONARCLOUD, and CLEAN AS YOU CODE are trademarks of SonarSource SA.

Creative Commons License