Skip to end of metadata
Go to start of metadata

Description

This plugin lets you delegate authentication to a SAML 2.0 Identity Provider. Optionally, group membership can be obtained for users logging in.

Configuration

Property

Name

Description

Mandatory

Default valueExample
sonar.auth.saml.enabled
Enabled

Enable SAML 2.0 authentication.
Value is ignored if other required parameters are not defined.

Yes

false
sonar.auth.saml.applicationId
Application IDIdentifier of the application

Yes

sonarqube
sonar.auth.saml.providerName
Provider name

Name displayed for the provider in the login page

Yes

SAML
sonar.auth.saml.providerId
Provider IDIdentifier (URI) of the identity provider, the entity that provides SAML authentication

Yes


http://localhost:8080/auth/realms/sonarqube
sonar.auth.saml.certificate.secured
Provider certificate

X.509 certificate for the identity provider


Yes


MIICoTCCAYkCBgFksusMzTANBgkqhki...
sonar.auth.saml.loginUrl
SAML login urlSAML login URL for the identity providerYes
http://localhost:8080/auth/realms/sonarqube/protocol/saml
sonar.auth.saml.user.login
SAML user login attributeAttribute defining the user identifier in SAMLYes
login
sonar.auth.saml.user.name
SAML user name attributeAttribute defining the user name in SAMLYes
name
sonar.auth.saml.user.email
SAML user email attributeAttribute defining the user email in SAMLNo
email
sonar.auth.saml.group.name
SAML groups attributeAttribute defining the user groups in SAML.

No
groups

Group Mapping

When using group mapping (sonar.auth.saml.group.name configured):

  • membership in Identity Provider will override any membership locally configured in SonarQube
  • membership to a group in Identity Provider is synched only if a group exists in Sonarqube with the same name
  • membership to the default group sonar-users remains (this is a built-in group)


Example of configuration using Keycloak as a SAML Identity Provider

Please note that if you're not using Keycloak your settings are likely to be different.

In the Keycloak server, create a new SAML client:

  1. Go to "Clients" → create a client
    • "Client ID" is something like "sonarqube" (no space allowed)
    • "Client Protocol" must be set to "saml"
    • "Client SAML Endpoint" can be left empty
  2. Go to "Clients" → select the created client
    1. In "Settings":
      1. Set "Client Signature Required" to "OFF"
      2. Set "Valid Redirect URIs" to "<SonarQube URL>/oauth2/callback/*", for example "https://sonarqube.mycompany.com/oauth2/callback/saml"

    2. In "Client Scopes" → "Default Client Scopes", remove "role_list" from "Assigned Default Client Scopes" (to prevent the error "com.onelogin.saml2.exception.ValidationError: Found an Attribute element with duplicated Name" during authentication)

    3. In "Mappers", create a mapper for each user attribute (Note that values provided below for Name, SAML Attribute Name, Role Attribute Name are only example values) : 

      1. Create a mapper for the login: 

        • Name: Login
        • Mapper Type: User Property
        • Property: Username
          Note that the login should not contain any special character except than .-_@ to fit with SonarQube restrictions.
        • SAML Attribute Name: login
      2. Create a mapper for the name: 
        • Name: Name
        • Mapper Type: User Property
        • User Attribute: Username
          It can also be another attribute you would previously have specified for the users
        • SAML Attribute Name: name
      3. (Optional) Create a mapper for the email :
        • Name: Email
        • Mapper Type: User Property
        • Property: Email
        • SAML Attribute Name: email
      4. (Optional) Create a mapper for the groups :
        If you rely on a list of roles defined in "Roles" of the Realm (not in "Roles" of the client):
        1. Name: Groups
        2. Mapper Type: Role list
        3. Role Attribute Name: groups
        4. Single Role Attribute: ON
        If you rely on a list of groups defined in "Groups":
        1. Name: Groups
        2. Mapper Type: Group list
        3. Role Attribute Name: groups
        4. Single Role Attribute: ON
        5. Full Group Path: OFF
    4. Download the XML configuration file in Installations > Format Option > SAML Metadata IDPSSODescriptor

In SonarQube settings, configure SAML authentication

  1. Go to Administration > Configuration > General Settings > SAML > Authentication
    • "Enabled" should be set to true
    • "Application ID" is the value of the "Client ID" (for example "sonarqube")
    • "Provider ID" is the value of the "EntityDescriptor" → "entityID" attribute in the XML configuration file (for example "http://keycloak:8080/auth/realms/sonarqube" where sonarqube is the name of the realm)
    • "SAML login url" is the value of "SingleSignOnService" → "Location" attribute in the XML configuration file (for example "http://keycloak:8080/auth/realms/sonarqube/protocol/saml")
    • "Provider certificate" is the value of "dsig:X509Certificate" node in the XML configuration file
    • "SAML user login attribute" is the value set in the login mapper in "SAML Attribute Name"
    • "SAML user name attribute" is the value set in the name mapper in "SAML Attribute Name"
    • (Optional) "SAML user email attribute" is the value set in the email mapper in "SAML Attribute Name"
    • (Optional) "SAML group attribute" is the value set in the groups mapper in "Role/Group Attribute Name"
  2. In the login form, the new button "Log in with SAML" allows users to connect with their SAML account.

Limitations

  • SAML requests are not signed. Client signature validation should be disabled in the Identity Provider.
  • SAML encrypted responses are not supported. SAML encryption should be disabled in the Identity Provider.
  • No labels