# With Keycloak

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 <a href="#keycloak-server-configuration" id="keycloak-server-configuration"></a>

### Prerequisites <a href="#keycloak-server-configuration" id="keycloak-server-configuration"></a>

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](https://docs.sonarsource.com/sonarqube-server/2026.1/instance-administration/server-base-url "mention").

{% stepper %}
{% step %}

#### 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**.

<figure><img src="broken-reference" alt="Make sure the current realm is the realm you want to use to interact with SonarQube."><figcaption></figcaption></figure>

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

4. Select the **Create client** button.

<figure><img src="broken-reference" alt="Set the General settings in the Create client page."><figcaption></figcaption></figure>

5. 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.
6. 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`
7. 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](#set-up-security-features "mention") below): In the **Keys** tab of the SAML client used for SonarQube, disable **Client signature required**.
{% endstep %}

{% step %}

#### Set up mappers <a href="#set-up-mappers" id="set-up-mappers"></a>

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**.

<table><thead><tr><th width="99">Purpose</th><th width="91">Mapper type</th><th width="89">Name</th><th width="218">Property</th><th width="108">SAML attribute name</th><th>Mandatory for SonarQube</th></tr></thead><tbody><tr><td><strong>Login</strong></td><td>User Property</td><td><code>Login</code></td><td><p><code>username</code></p><p><strong>Note</strong>: This value should not contain any special characters other than <code>.</code>, <code>-</code>, <code>_</code>, and <code>@</code>, to meet SonarQube restrictions.</p></td><td><code>login</code></td><td>x</td></tr><tr><td><strong>Name</strong></td><td>User Property</td><td><code>Name</code></td><td><code>username</code> or another attribute that you previously specified for the users.)</td><td><code>name</code></td><td>x</td></tr><tr><td><strong>email</strong></td><td>User Property</td><td><code>Email</code></td><td><code>email</code></td><td><code>email</code></td><td><br></td></tr></tbody></table>

4. If you use Just-in-Time provisioning with the group synchronization feature:
5. Verify the user groups in SonarQube Server. For more information, see [#justintime-provisioning](https://docs.sonarsource.com/sonarqube-server/2026.1/instance-administration/overview#justintime-provisioning "mention").
6. Select **Add mapper** > **By Configuration** and add a groups mapper by using one of the two options described below.

<table><thead><tr><th width="195">Option</th><th width="105">Mapper type</th><th width="89">Name</th><th width="104">Group / Role attribute name</th><th width="105">Single role attribute</th><th width="90">Full Group Path</th></tr></thead><tbody><tr><td>If you rely on a list of groups defined in Groups.</td><td>Group list</td><td>Groups</td><td>groups</td><td>ON</td><td>OFF</td></tr><tr><td>If you rely on a list of roles defined in Roles of the realm, not in Roles of the client.</td><td>Role list</td><td>Groups</td><td>groups</td><td>ON</td><td>n/a</td></tr></tbody></table>
{% endstep %}
{% endstepper %}

## Set up SonarQube Server <a href="#set-up-sonarqube-server" id="set-up-sonarqube-server"></a>

{% stepper %}
{% step %}

#### 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 Metadat**a endpoint. Select the link to open a new tab with the metadata or right-click to download it.
   {% endstep %}

{% step %}

#### 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.

<table><thead><tr><th width="164">Field in SonarQube Server</th><th>Description</th></tr></thead><tbody><tr><td>Application ID</td><td><p>The value of the Client ID you set in Keycloak.</p><p><strong>Example</strong>: <code>sonarqube</code></p></td></tr><tr><td>Provider name</td><td>Name of the Identity Provider displayed on the SonarQube Server login page when SAML authentication is active.</td></tr><tr><td>Provider ID</td><td><p>The value of the <code>EntityDescriptor > entityID</code> attribute in the IdP metadata file. This can be found in Keycloak in <em>Your realm</em> > <strong>Realm settings</strong> > <strong>General</strong> > <strong>SAML 2.0 Identity Provider Metadata</strong>.</p><p><strong>Example</strong>: <code>http://keycloak:8080/realms/sonarqube</code></p></td></tr><tr><td>SAML login URL</td><td><p>The value of <code>SingleSignOnService > Location</code> attribute in the IdP metadata file. This can be found in Keycloak in <em>Your realm</em> > <strong>Realm settings</strong> > <strong>General</strong> > <strong>SAML 2.0 Identity Provider Metadata</strong>.</p><p><strong>Example</strong>: <code>http://&#x3C;SonarQubeBaseUrl>/realms/SonarQube2025/protocol/saml</code></p></td></tr><tr><td>Identity provider certificate</td><td><p>Copy-paste the realm’s certificate. It can be found in Keycloak:</p><ul><li>In <em>Your realm</em> > <strong>Realm settings</strong> > <strong>General</strong> > <strong>SAML 2.0 Identity Provider Metadata</strong>.</li><li>or in <em>Your realm</em> > <strong>Realm Settings</strong> > <strong>Keys</strong> > <strong>RS256 and select Certificate</strong>.</li></ul></td></tr><tr><td>SAML user login attribute</td><td><p>The <strong>SAML attribute name</strong> configured for the login attribute.</p><p><strong>Example</strong>: <code>login</code></p></td></tr><tr><td>SAML user name attribute</td><td><p>The <strong>SAML attribute name</strong> configured for the name attribute.</p><p><strong>Example</strong>: <code>name</code></p></td></tr><tr><td>SAML user email attribute</td><td><p>Optional. The SAML attribute name configured for the email attribute.</p><p><strong>Example</strong>: <code>email</code></p></td></tr><tr><td>SAML group attribute</td><td><p>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 <a data-mention href="../../overview#justintime-provisioning">#justintime-provisioning</a>.</p><p><strong>Example</strong>: <code>groups</code></p></td></tr></tbody></table>
{% endstep %}
{% endstepper %}

## Set up security features <a href="#set-up-security-features" id="set-up-security-features"></a>

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.

{% stepper %}
{% step %}

#### 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.
   {% endstep %}

{% step %}

#### Convert the private key to PKCS#8 format <a href="#convert-to-pkcs8-format" id="convert-to-pkcs8-format"></a>

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.

```bash
#!/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----
```

{% endstep %}

{% step %}

#### 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).
   {% endstep %}
   {% endstepper %}