With Keycloak

Setting up SAML authentication with Keycloak in your SonarQube Server instance.

To integrate Keycloak (the identity provider) with SonarQube Server (the service provider), both sides need to be configured, first in Keycloak, then in SonarQube Server. In addition, you may want to set up security features.

Set up Keycloak

Prerequisites

You have created in Keycloak a realm that you want to use with SonarQube.

The SonarQube Server URL is correctly set in SonarQube Server. See Server base URL.

1

Create a new SAML client

1. Sign in to your Keycloak administration console.

2. Select the realm to be used to interact with SonarQube.

3. In the left navigation panel, select Clients.

[A]: The current realm must be the realm you want to use to interact with SonarQube.

1. Select the Create client button.

1. In General settings, set the following parameters and click Next.

   • Client type: SAML

   • Client ID: Identifier of the SonarQube application in Keycloak. Any name can be used but it must not contain whitespace, e.g. sonarqube.

2. In Login settings, set the following parameter:

   • Valid redirect URIs: Must be in the format: <SonarQubeBaseURL>/oauth2/callback/saml Example: https://sonarqube.mycompany.com/oauth2/callback/saml

3. Select Save. The client is created.

The client signature is enabled by default. Disable this setting if you are not using advanced security features (see Set up security features below): In the Keys tab of the SAML client used for SonarQube, disable Client signature required.

2

Set up mappers

1. In the left navigation panel, select the Clients menu. Then select the client you created earlier.

2. Select Client scopes, then <nameOfYourClient>-dedicated.

3. Create different mappers as described in the table below. To create a mapper, select Configure a new mapper or Add mapper > By configuration.

Purpose	Mapper type	Name	Property	SAML attribute name	Mandatory for SonarQube
Login	User Property	Login	username Note: This value should not contain any special characters other than ., -, _, and @, to meet SonarQube restrictions.	login	x
Name	User Property	Name	username or another attribute that you previously specified for the users.)	name	x
email	User Property	Email	email	email

1. If you use Just-in-Time provisioning with the group synchronization feature:

2. Verify the user groups in SonarQube Server. For more information, see Just-in-Time provisioning.

3. Select Add mapper > By Configuration and add a groups mapper by using one of the two options described below.

Option	Mapper type	Name	Group / Role attribute name	Single role attribute	Full Group Path
If you rely on a list of groups defined in Groups.	Group list	Groups	groups	ON	OFF
If you rely on a list of roles defined in Roles of the realm, not in Roles of the client.	Role list	Groups	groups	ON	n/a

Set up SonarQube Server

1

Open the IdP metadata file from Keycloak

1. Sign in to your Keycloak administration console.

2. Select the realm you use to interact with SonarQube.

3. In the left navigation panel, select Realm settings.

4. At the bottom of the General tab, you should see a SAML 2.0 Identity Provider Metadata endpoint. Select the link to open a new tab with the metadata or right-click to download it.

2

Configure SonarQube Server

1. In your SonarQube Server instance, go to Administration > Configuration > General Settings > Authentication> SAML.

2. Select Create Configuration.

3. Fill in the fields as explained in the table below.

Field in SonarQube Server	Description
Application ID	The value of the Client ID you set in Keycloak. Example: sonarqube
Provider name	Name of the Identity Provider displayed on the SonarQube Server login page when SAML authentication is active.
Provider ID	The value of the EntityDescriptor > entityID attribute in the IdP metadata file. This can be found in Keycloak in Your realm > Realm settings > General > SAML 2.0 Identity Provider Metadata. Example: http://keycloak:8080/realms/sonarqube
SAML login URL	The value of SingleSignOnService > Location attribute in the IdP metadata file. This can be found in Keycloak in Your realm > Realm settings > General > SAML 2.0 Identity Provider Metadata. Example: http://<SonarQubeBaseUrl>/realms/SonarQube2025/protocol/saml
Identity provider certificate	Copy-paste the realm’s certificate. It can be found in Keycloak: In Your realm > Realm settings > General > SAML 2.0 Identity Provider Metadata. or in Your realm > Realm Settings > Keys > RS256 and select Certificate.
SAML user login attribute	The SAML attribute name configured for the login attribute. Example: login
SAML user name attribute	The SAML attribute name configured for the name attribute. Example: name
SAML user email attribute	Optional. The SAML attribute name configured for the email attribute. Example: email
SAML group attribute	Optional. The SAML attribute name configured for the groups attribute if you use the Just-in-Time provisioning group synchronization feature. For more information, see Just-in-Time provisioning. Example: groups

Set up security features

To improve security, you can enable the encryption of SAML assertions sent by Keycloak and the signing of SAML requests sent by SonarQube Server. Once you have registered the SonarQube Server in Keycloak, you can set up the following security features:

• The encryption of SAML assertions emitted by Keycloak for SonarQube Server.

• The signing of the SAML requests from SonarQube Server to Keycloak.

To enable the encryption of SAML assertions or the signing of SAML requests, you need to provide two things (the same key pair is used for both security features) :

• Service provider private key: PKCS8-stored private key.

• Service provider certificate: X.509 certificate.

1

Configure the security features in Keycloak

You can enable the signing of SAML requests and/or the encryption of SAML assertions. To enalbe the assertion encryption, follow the steps below. To enable the signed requests, nothing needs to be done in this step.

To enable in Keycloak the encrytpion of SAML assertions:

1. In Keycloak, go to the Clients section and select the SAML client used for SonarQube.

2. In the Keys tab of the SAML client, disable Signing key config if not already done and enable Encrypt assertions in Encryption keys config. A dialog opens to generate a paired private key and certificate.

3. Select the Generate button. A pop-up indicates that the key pair and certificate have been successfully generated (if it's not the case, make sure pop-ups are not blocked on your browser): the private.key file has been downloaded to your local folder.

4. Select Confirm. The dialog closes.

2

Convert the private key to PKCS#8 format

You have to convert the Keycloak private.key into a pkcs8.key, which is SonarQube compatible. To do so, use a shell script based on the example below. In this example, the private.key downloaded from Keycloak is located in the same folder as where the script is run. Modify the script as needed.

#!/bin/zsh
echo -e "-----BEGIN RSA PRIVATE KEY-----\n$(cat private.key)\n-----END RSA PRIVATE KEY-----" > newprivate.key
openssl pkcs8 -topk8 -in newprivate.key -out pkcs8.key -nocrypt
tr -d "\n\r" < pkcs8.key

The resulting file should look like this:

-----BEGIN PRIVATE KEY-----MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQC3qfa8mtiJVCg1RkDFOxfuqk0Gd/R5ULalxC/8fUcDPyGzH0LXD8TYRpPj0b067rqSa0Exg77ZtgDzoz/H9nUaKEwz4C0Cg7U31F2UOgA0IsGQYzJk4YyKmWBbcbkRRnJi9FS672ZIsQQR82XkLplWVw4BIYGXl/Zkb5bMh3AUAOQUMCej5SBqxOxeYRI4l0A0MhnnIwkkIEALjkzbI9LrxWxj3hi7FYLObNOMxSzKr6Zpttv7tO/6QBcCK0ux2WAjKz0oCvzSEq/qXFodKifHFIdlrpldbjBP0gsUU9xOe1X6PqBynnqdNy9s8WZu5TeGFaK3aEOZD93KrMKAWUrnAgMBAAECggEALwEIHQ/SEB9iJPREWlW708Bw8xFbF3sxK25wy4EyXeHX2ZRMEmc+PQ2fBsSkVcNIK3XYmvf5LZW3W6MxjRcFtDqQ+gvK6SRVCiNHCcroR2+Hs1C30nqo8cW8E9sgfovVdX7LeoYPWtY20PNGZeYJJ0AjXOW62VWyYNTwNosJA40hq5jsd/ktmwd5o1zKPbaMplrWtVlt3UKii3YfeTodOIE/FSHtVL14PcyeYZxgCxJp2gGHvqMjOmBgs89kwkP7+vtYg1Rn8Cj3CzkVDnsHiuDaaSuScntgRXMywhEH6oBs/aFzvA3zhiMW17146TB1eAtKAnVNk8kcC58b5In7qQKBgQDk18Snz10obdw8U9IxY9LtvsKEx6uti7ROtScAi8wJOquYUhx2kTbT0xkfgNhqe+cpPvTx50Av1Fi9x8y5yTCtSocagQHMF0WyAKoBTRi+wgshsgmVNn+UQmUMuTMsU+1TkOC0iw8WuyYvuYqnZh3stwt/mYt//bMH0eKH66y0fwKBgQDNdamkV0+CZeMdNIxGOUUTbmo/QfGFLUB/1Qf1UAsu6iuIQHn9NoDLACrhI0noQKhoODyQjT/3HDXE4CnEKu9ooUrQ3scklj9FYxMKudQRS+mTtE0ZXe9uD0+rht4Ev9cPAqmZEGa6ZoZ6o84ors/vtBDYL7kX/r7N8pNVvy0VmQKBgQCaezHNGoXHsgn3S5pcLwgH6DuFyQiSufl5HH78tmKBZHLL+7otLDA35IxUIPV3RLcyt8ZAupww7YcObh88150djm8PrEDbVmZ9GEerYzEuLO24zGf9q3GKUxvF8Aukg+909xtJpYoFDUdk9jqscJoI3zRK6gsq1seRotTqbmUC3wKBgQCRXuky0Fv/ZVu2dFGz9h17zCn8rAnZMtVqHS7OUV44SZOXihdGI+QoveuY9ED8xZLierfPh0F09E7PB9RFaiOOomCvPJEmv+/whlMYybbUriOMUIwkoKQh+U9ji79XGO1vP3EETeiBhr0r1O6vNlEFxyAL9mg+JA6Y5UN97hBWMQKBgQCLH/9epJo01mGe+9h0Q1zoBpTGllJXtiOwKAf0JzqKEkVwFtuzgzC3WD1Ru0X85X6pbgyignKe60ZmFa8+nKmgF4IUKtNQmw7+poUzruw9BdOlpdnFrMU05k7hV0s1frwd+L/GLtBP62fw9QSLoWHE25X5Uq8OvI77wV6NwYS/PA==-----END PRIVATE KEY----

3

Configure the security features in SonarQube Server

To configure both the SAML request signing and the SAML assertion encryption features

1. In Keycloak, retrieve the SAML client used for SonarQube and go to the Keys tab.

2. Copy the certificate value in Encryption keys config.

3. In SonarQube Server, go to Administration > Configuration > General Settings > Authentication > SAML.

4. In SAML Configuration > SAML, select Edit. The Edit SAML configuration dialog opens.

5. In Service provider certificate, paste the certificate value copied from Keycloak.

6. Open your pkcs8.key file and copy its content. Remember that pkcs8.key contents are all on one line as shown in 2. Convert the private key to PKCS#8 format above.

7. In SonarQube Server, paste this value in Service provider private key.

8. To enable the signing of the SAML requests, enable the Sign requests toggle.

9. Select Save configuration.

10. Select Test Configuration to verify.

To configure the SAML assertion encryption feature only

1. Follow the steps above, but ensure you the Sign requests toggle is disabled.

2. Both Service provider private key and Service provider certificate should be set (should not be not empty).