Setting up SAML with Keycloak

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

To integrate Keycloak (the identity provider) with SonarQube Server (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 Server SAML configuration).
2. Encrypt Assertions: ON (if the responses from the IdP are to be encrypted).
3. Valid Redirect URLs: <Your SonarQube Server 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 Server side (Keycloak generated keys can be used). This private key will have to be provided in PKCS8 format in SonarQube Server.
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 Type: User property.
   3. Property: Username (Note that this value should not contain any special characters other than .-_@, to meet SonarQube Server restrictions.)
   4. SAML Attribute Name: login
2. Create a mapper for the name:
   1. Name: Name
   2. Mapper Type: User 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 Type: User 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 Type: Role list.
   3. Role Attribute Name: groups
   4. Single Role Attribute: ON
5. 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

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

SonarQube Server configuration

Navigate to Administration > Authentication > SAML and click Create configuration, it will open a popup window with all the fields that you need to provide. 

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)
• 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 Server 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.

Enabling and testing SAML authentication

Step 1: Save the SAML configuration by clicking Save configuration.

Step 2: Before enabling the SAML authentication on SonarQube Server, you can verify that the configuration is correct by clicking Test Configuration. This will initiate a SAML login and return useful information about the SAML response obtained from the identity provider.

Step 3: Click Enable configuration.

Step 4: In the login form, the new button Log in with Keycloak (or a custom name specified in the Provider Name field) allows users to connect with their SAML account.

Group synchronization

While configuring Keycloak, you configured a groups attribute (see the Keycloak server configuration section). You can now use it in SonarQube Server to enable group synchronization. To do this, under SAML > Provisioning,  enter groups, or whatever name you gave to this attribute, in the SAML group attribute field. If no value is entered in this field, users are assigned to the default sonar-users group only.

Group synchronization is only compatible with the Just-in-Time user and group provisioning (default) option.