This version of the SonarQube documentation is no longer maintained. It relates to a version of SonarQube that is not active.

See latest version
Start Free
9.8 | Instance administration | Authentication | SAML | How to set up Keycloak

How to set up Keycloak

On this page

The following content may be useful if you're using Keycloak as a SAML identity provider.

To integrate Keycloak (the identity provider) with SonarQube (the service provider), both sides need to be configured.

Keycloak server configuration

Create a new SAML client

Step 1: Create your Client ID. Define it as something like sonarqube. It must not contain whitespace.

Step 2: Define your Client Protocol as saml.

Step 3: The Client SAML Endpoint can be left empty.

Configure the new SAML client

Step 1: Under Settings:

    1. Client Signature Required: ON (only if request signature is active in the SonarQube SAML configuration).
    2. Encrypt Assertions: ON (if the responses from the IdP are to be encrypted).
    3. Valid Redirect URLs: <Your SonarQube URL>/oauth2/callback/saml. For example,  https://sonarqube.mycompany.com/oauth2/callback/saml.

Step 2: Under Keys:

    1. Signing Key (optional): Add the service provider private key and the certificate if the signature of the requests is enabled on the SonarQube side (Keycloak generated keys can be used). This private key will have to be provided in PKCS8 format in SonarQube.
    2. Encryption Key (optional): Add the service provider certificate if you want to activate the encryption of Keycloak responses. If a request signature is used, you must use the same certificate for the encryption.

Step 3: 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)

Step 4: Under Mappers, create a mapper for each user attribute:

    1. Create a mapper for the login:
      1. Name: Login
      2. Mapper TypeUser property.
      3. Property: Username (Note that this value should not contain any special characters other than .-_@, to meet SonarQube restrictions.)
      4. SAML Attribute Name: login
    2. Create a mapper for the name:
      1. Name: Name
      2. Mapper TypeUser property.
      3. Property: Username (This can also be another attribute that you previously specified for the users.)
      4. SAML Attribute Name: name
    3. (Optional) Create a mapper for the email:
      1. Name: Email
      2. Mapper TypeUser property.
      3. Property: Email
      4. 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 TypeRole list.
      3. Role Attribute Name: groups
      4. Single Role AttributeON
    5. If you rely on a list of groups defined in "Groups":
      1. Name: Groups
      2. Mapper TypeGroup list.
      3. Role Attribute Name: groups
      4. Single Role AttributeON
      5. Full Group PathOFF

Step 5: In Realm Settings > General > Endpoints, click on SAML 2.0 Identify Provider Metadata to obtain the XML configuration file from Keycloak.

SonarQube configuration

Configure the SAML authentication: Administration > Configuration > General Settings > Authentication > SAML:

  • Application ID: The value of the Client ID you set in Keycloak (for example, sonarqube)
  • Provider ID: The value of the EntityDescriptor > entityID attribute in the XML configuration file (for example, http://keycloak:8080/auth/realms/sonarqube).
  • SAML login URL: The value of SingleSignOnService > Location attribute in the XML configuration file (for example, http://keycloak:8080/auth/realms/sonarqube/protocol/saml).
  • Identity provider certificate: The value you get from Realm Settings > Keys > RS256. Click on Certificate.
  • SAML user login attribute: login (or whatever you configured above when doing the mapping)
  • SAML user name attribute: name (or whatever you configured above when doing the mapping)
  • (Optional) SAML user email attribute: email (or whatever you configured above when doing the mapping)
  • (Optional) SAML group attribute groups (or whatever you configured above when doing the mapping)
  • Sign requests: Set to true to activate the signature of the SAML requests. It needs both the service provider private key and certificate to be set.
  • Service provider private key: The service provider private key shared with the identity provider. This key is required for both request signature and response encryption, which can be activated individually. The key should be provided for SonarQube in PKCS8 format without password protection.
  • Service provider certificate: The service provider certificate shared with the identity provider in order to activate the request signature.

You can find some instructions to convert different key formats here.

In the login form, the new button Log in with SAML allows users to connect with their SAML account.

Enabling and testing SAML authentication

Step 1: In the SonarQube SAML settings, enable SAML by selecting Enabled

Where to enable SAML for Keycloak from the SonarQube SAML settings.

Before enabling the SAML authentication on SonarQube, you can verify that the configuration is correct by selecting Test Configuration as shown in the image above. A SAML login will be initiated and useful information about the SAML response obtained from the Identity provider will be returned.


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