> ## Documentation Index
> Fetch the complete documentation index at: https://tyk.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO with Keycloak

> Learn how to configure Single Sign-On (SSO) for Tyk Dashboard or Tyk Developer Portal using Keycloak via OpenID Connect (OIDC), with worked examples for Dashboard and Portal.

## Introduction

[Keycloak](https://www.keycloak.org/) is an open-source identity provider that supports OpenID Connect. TIB connects to Keycloak using `SocialProvider` with the `openid-connect` provider type.

Before configuring your IdP and TIB profile, pick the guide for your use case: [Dashboard SSO](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md), [Portal SSO](https://tyk.io/docs/tyk-stack/tyk-developer-portal/enterprise-developer-portal/managing-access/enable-sso.md), or [Issuing Tokens via TIB](https://tyk.io/docs/api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.md). Each page explains the `ActionType`, `ReturnURL`, and `IdentityHandlerConfig` fields for that use case.

This page covers the Keycloak-specific configuration only.

## Configure Keycloak

1. In your Keycloak Admin Console, navigate to the realm you want to use and select **Clients**.

   ![Create Client](https://mintcdn.com/tyk/IjX3R2JMsyaApv0U/img/keycloak-sso/create-client.png?fit=max\&auto=format\&n=IjX3R2JMsyaApv0U\&q=85\&s=40a6e4e1dcb203f21bed7b4b0984a5da)

2. Click **Create client**, set the **Client type** to **OpenID Connect**, enter a **Client ID**, and click **Next**.

   ![Set Client Type and ID](https://mintcdn.com/tyk/IjX3R2JMsyaApv0U/img/keycloak-sso/create-client2.png?fit=max\&auto=format\&n=IjX3R2JMsyaApv0U\&q=85\&s=55d36d345a9a815ddcdf6c114e3cba85)

3. Enable **Client authentication** and click **Next**, then **Save**.

   ![Enable Client Auth](https://mintcdn.com/tyk/IjX3R2JMsyaApv0U/img/keycloak-sso/enable-client-auth.png?fit=max\&auto=format\&n=IjX3R2JMsyaApv0U\&q=85\&s=bf10dce5176a5ae87fbc4802522f5c63)

4. From the client's **Credentials** tab, copy the **Client Secret**.

   ![Retrieve Client Secret](https://mintcdn.com/tyk/IjX3R2JMsyaApv0U/img/keycloak-sso/retrieve-client-secret.png?fit=max\&auto=format\&n=IjX3R2JMsyaApv0U\&q=85\&s=6aacddd46e88de7abecc283eb35dc537)

5. From the client's **Settings** tab, add the TIB callback URL to **Valid redirect URIs**:
   ```
   http://{tib-host}/auth/{profile-id}/openid-connect/callback
   ```
   Replace `{tib-host}` with the hostname of your TIB instance and `{profile-id}` with the ID you will assign to the TIB profile.

6. Click **Save**.

The Keycloak OIDC discovery URL for your realm is accessible from **Realm Settings > General > OpenID Endpoint Configuration**:

```
https://{keycloak-host}/realms/{realm-name}/.well-known/openid-configuration
```

![Keycloak discovery endpoint](https://mintcdn.com/tyk/IjX3R2JMsyaApv0U/img/keycloak-sso/realm-discovery-endpoint.png?fit=max\&auto=format\&n=IjX3R2JMsyaApv0U\&q=85\&s=4b92203b3341bdbbd3a41145b7bce75f)

## TIB Profile

The Keycloak-specific configuration goes in the `ProviderConfig` block of the TIB profile. Set `ProviderName` to `SocialProvider` and `Type` to `redirect`.

```json expandable theme={null}
{
  "ProviderName": "SocialProvider",
  "Type": "redirect",
  "ProviderConfig": {
    "CallbackBaseURL": "http://{tib-host}",
    "FailureRedirect": "http://{failure-redirect-url}",
    "UseProviders": [
      {
        "Name": "openid-connect",
        "Key": "{keycloak-client-id}",
        "Secret": "{keycloak-client-secret}",
        "Scopes": ["openid", "email", "profile"],
        "DiscoverURL": "https://{keycloak-host}/realms/{realm-name}/.well-known/openid-configuration"
      }
    ]
  }
}
```

The Keycloak-specific `ProviderConfig` fields are:

| Field | Description |
| - | - |
| `CallbackBaseURL` | The base URL of your TIB instance. TIB appends the callback path automatically. |
| `FailureRedirect` | URL to redirect the user to on authentication failure. |
| `UseProviders.Name` | Must be `openid-connect`. This value routes TIB to the OpenID Connect provider implementation. |
| `UseProviders.Key` | The Keycloak Client ID. |
| `UseProviders.Secret` | The Keycloak Client Secret. |
| `UseProviders.Scopes` | OAuth scopes to request. `openid` and `email` are required. |
| `UseProviders.DiscoverURL` | The Keycloak OIDC discovery URL for your realm. |

### JSON Web Encryption (JWE)

If Keycloak is configured to encrypt ID tokens, TIB can decrypt them using JWE. Add a `JWE` block to `ProviderConfig` to enable this:

```json theme={null}
{
  "ProviderConfig": {
    "UseProviders": [...],
    "JWE": {
      "Enabled": true,
      "PrivateKeyLocation": "{certificate-id-or-path}"
    }
  }
}
```

For embedded TIB in Tyk Dashboard, set `PrivateKeyLocation` to the certificate ID from the Tyk Dashboard certificate manager. For standalone TIB, set it to the file path of a PEM file containing the private key. The key must correspond to the public key registered with Keycloak for token encryption.

Requires Tyk Identity Broker v1.6.1+ and Tyk Dashboard v5.7.0+.

## Worked Examples

These examples use embedded TIB, so the `CallbackBaseURL` is the same as the Dashboard or Portal respectively; TIB handles requests on the same host and port.

> [tab] Dashboard SSO
>
> In this example, Tyk Dashboard is running at `http://dashboard.example.com` on port `3000`; replace the example values with your own.
>
> **Tyk Dashboard configuration**
>
> ```json theme={null}
> {
>   "sso_enable_user_lookup": true,
>   "sso_permission_defaults": {
>     "apis": "write",
>     "keys": "write",
>     "policies": "write"
>   },
>   "sso_default_group_id": "{tyk-user-group-id}"
> }
> ```
>
> With this configuration, registered users (with a Tyk Dashboard user account) get their own permissions; unregistered users fall back to the group specified in `sso_default_group_id`. See [Dashboard SSO](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md) for full details.
>
> **TIB profile**
>
> The TIB profile is created via the [Tyk Identity Broker API](https://tyk.io/docs/tyk-identity-broker/tib-rest-api.md) or the [Tyk Dashboard UI](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md#create-a-tib-profile-using-dashboard-ui).
>
> ```json expandable theme={null}
> {
>   "ID": "keycloak-dashboard-oidc",
>   "Name": "Keycloak Dashboard SSO",
>   "OrgID": "{tyk-org-id}",
>   "ActionType": "GenerateOrLoginUserProfile",
>   "Type": "redirect",
>   "ProviderName": "SocialProvider",
>   "ReturnURL": "http://dashboard.example.com:3000/tap",
>   "IdentityHandlerConfig": {
>     "DashboardCredential": "{tib-service-user-api-key}"
>   },
>   "ProviderConfig": {
>     "CallbackBaseURL": "http://dashboard.example.com:3000",
>     "FailureRedirect": "http://dashboard.example.com:3000/?fail=true",
>     "UseProviders": [
>       {
>         "Name": "openid-connect",
>         "Key": "{keycloak-client-id}",
>         "Secret": "{keycloak-client-secret}",
>         "Scopes": ["openid", "email", "profile"],
>         "DiscoverURL": "https://{keycloak-host}/realms/{realm-name}/.well-known/openid-configuration"
>       }
>     ]
>   }
> }
> ```
>
> * set `Key` to the Keycloak **Client ID**
> * set `Secret` to the Keycloak **Client Secret**
> * set `DashboardCredential` to the [TIB service account's](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md#tib-service-account) Dashboard credentials
>
> **Keycloak redirect URI**
>
> Ensure the following URL is listed in **Valid redirect URIs** in your Keycloak client settings. The `ID` in the registered URL must exactly match the `ID` in your TIB profile; a mismatch will result in a `400 Bad Request` error:
>
> ```
> http://dashboard.example.com:3000/auth/keycloak-dashboard-oidc/openid-connect/callback
> ```
>
> **Login URL**
>
> This URL initiates the SSO login flow:
>
> ```
> http://dashboard.example.com:3000/auth/keycloak-dashboard-oidc/openid-connect
> ```
>
> In production, present this as a "Log in with Keycloak" button or link on a custom login page, rather than expecting users to navigate to it directly.
>
> See [Dashboard SSO](https://tyk.io/docs/tyk-identity-broker/dashboard-sso.md) for details on session behavior, permissions, and user group mapping.

> [tab] Portal SSO
>
> In this example, Tyk Developer Portal is running at `http://portal.example.com` on port `3001`; replace the example values with your own.
>
> **Tyk Developer Portal configuration**
>
> Enable embedded TIB in the Portal configuration:
>
> ```json theme={null}
> {
>   "TIB": {
>     "Enable": true
>   }
> }
> ```
>
> **TIB profile**
>
> The TIB profile is created via the Tyk Developer Portal UI under **Settings > SSO Profiles**.
>
> ```json expandable theme={null}
> {
>   "ID": "keycloak-portal-oidc",
>   "Name": "Keycloak Portal SSO",
>   "OrgID": "{tyk-org-id}",
>   "ActionType": "GenerateOrLoginDeveloperProfile",
>   "Type": "redirect",
>   "ProviderName": "SocialProvider",
>   "ReturnURL": "http://portal.example.com:3001/sso",
>   "IdentityHandlerConfig": {
>     "DashboardCredential": "{portal-api-secret}"
>   },
>   "ProviderConfig": {
>     "CallbackBaseURL": "http://portal.example.com:3001",
>     "FailureRedirect": "http://portal.example.com:3001/?fail=true",
>     "UseProviders": [
>       {
>         "Name": "openid-connect",
>         "Key": "{keycloak-client-id}",
>         "Secret": "{keycloak-client-secret}",
>         "Scopes": ["openid", "email", "profile"],
>         "DiscoverURL": "https://{keycloak-host}/realms/{realm-name}/.well-known/openid-configuration"
>       }
>     ]
>   }
> }
> ```
>
> * set `ActionType` and `OrgID` based on the audience:
>   * Admin Portal (API owners): `ActionType: "GenerateOrLoginUserProfile"`, `OrgID: "0"`
>   * Live Portal (API consumers): `ActionType: "GenerateOrLoginDeveloperProfile"`, `OrgID` is not required
> * set `Key` to the Keycloak **Client ID**
> * set `Secret` to the Keycloak **Client Secret**
> * set `DashboardCredential` to the [PORTAL\_API\_SECRET](https://tyk.io/docs/product-stack/tyk-enterprise-developer-portal/deploy/configuration.md#portal_api_secret) used to authenticate with the Portal's management API
>
> **Keycloak redirect URI**
>
> Ensure the following URL is listed in **Valid redirect URIs** in your Keycloak client settings. The `ID` in the registered URL must exactly match the `ID` in your TIB profile; a mismatch will result in a `400 Bad Request` error:
>
> ```
> http://portal.example.com:3001/auth/keycloak-portal-oidc/openid-connect/callback
> ```
>
> **Login URL**
>
> This URL initiates the SSO login flow:
>
> ```
> http://portal.example.com:3001/auth/keycloak-portal-oidc/openid-connect
> ```
>
> In production, present this as a "Log in with Keycloak" button or link on the Portal login page.
>
> For details on user group mapping and admin vs developer profiles, see [Portal SSO](https://tyk.io/docs/tyk-stack/tyk-developer-portal/enterprise-developer-portal/managing-access/enable-sso.md).