# Keycloak SSO

{% stepper %}
{% step %}
**Create a new SAML application client in Keycloak**

* Go to **Clients**
* Click **Create**
* Fill in the details: see the table below.
* Click **Save**

<table><thead><tr><th width="271">Setting</th><th>Value</th></tr></thead><tbody><tr><td>Client ID</td><td>Use the <strong>base.url</strong> of the Lenses installation e.g. <strong>https://lenses-dev.example.com</strong></td></tr><tr><td>Client Protocol</td><td>Set it to saml</td></tr><tr><td>Client Saml Endpoint</td><td>This is the Lenses API point for Keycloak to call back. Set it to <strong>[BASE_URL]/api/v2/auth/saml/callback?client_name=SAML2Client. e.g. https://lenses-dev.example.com/api/v2/auth/saml/callback?client_name=SAML2Client</strong></td></tr></tbody></table>
{% endstep %}

{% step %}
**Update Client Settings**

Change the settings on client you just created to:

<table><thead><tr><th width="274">Setting</th><th>Value</th></tr></thead><tbody><tr><td>Name</td><td>Lenses</td></tr><tr><td>Description</td><td>(Optional) Add a description to your app.</td></tr><tr><td>SAML Signature Name</td><td>KEY_ID</td></tr><tr><td>Client Signature Required</td><td>OFF</td></tr><tr><td>Force POST Binding</td><td>ON</td></tr><tr><td>Front Channel Logout</td><td>OFF</td></tr><tr><td>Force Name ID Format</td><td>ON</td></tr><tr><td>Name ID Format</td><td>email</td></tr><tr><td>Root URL</td><td>Use the <strong>base.url</strong> of the Lenses installation e.g. https://lenses-dev.example.com</td></tr><tr><td>Valid Redirect URIs</td><td>Use the <strong>base.url</strong> of the Lenses installation e.g. <strong>https://lenses-dev.example.com</strong></td></tr></tbody></table>
{% endstep %}

{% step %}
**Map users to groups**

Configure Keycloak to communicate groups to Lenses. Head to the **Mappers** (under Client scope tab) section.

1. Click Create
2. Fill in the details: see table below.
3. Click Save

| Setting                | Value                   |
| ---------------------- | ----------------------- |
| Name                   | Groups                  |
| Mapper Type            | Group list              |
| Group attribute name   | groups (case-sensitive) |
| Single Group Attribute | ON                      |
| Full group path        | OFF                     |
| {% endstep %}          |                         |

{% step %}
**Download SAML Certificates**

Download the Federation Metadata XML file with the Keycloak IdP details.
{% endstep %}

{% step %}
**Configure SAML in HQ**

SAML configuration is set in HQ's **config.yaml** file. See [here ](https://docs.lenses.io/latest/deployment/hq#samlconfig)for more details.
{% endstep %}
{% endstepper %}


---

# 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.lenses.io/latest/deployment/configuration/authentication/sso-and-saml/keycloak-sso.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.