# With Keycloak

## Keycloak <a href="#generate-private-key" id="generate-private-key"></a>

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

## Set up Keycloak <a href="#keycloak-server-configuration" id="keycloak-server-configuration"></a>

Before starting the setup in Keycloak, make sure:

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

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

{% step %}

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

<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:
   1. Verify the user groups in SonarQube.
   2. 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 %}

For more information about JIT provisioning, see [#justintime-provisioning](https://docs.sonarsource.com/sonarqube-server/2026.1/instance-administration/overview#justintime-provisioning "mention").

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

1. In your SonarQube 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</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 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<sup>1</sup>.</p><p><strong>Example</strong>: <code>groups</code></p></td></tr></tbody></table>
{% endstep %}
{% endstepper %}

1\) See [#justintime-provisioning](https://docs.sonarsource.com/sonarqube-server/2026.1/instance-administration/overview#justintime-provisioning "mention").

## 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. Once you have registered the SonarQube in Keycloak, you can set up the following security features:

* The encryption of SAML assertions emitted by Keycloak for SonarQube.
* The signing of the SAML requests from SonarQube 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

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

**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, 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, 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 %}

## Related pages

* [overview](https://docs.sonarsource.com/sonarqube-server/2026.1/instance-administration/authentication/overview "mention")
* [overview](https://docs.sonarsource.com/sonarqube-server/2026.1/instance-administration/authentication/saml/overview "mention")


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-server/2026.1/instance-administration/authentication/saml/how-to-set-up-keycloak.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.