> ## 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, read [Dashboard SSO](/nightly/tyk-identity-broker/dashboard-sso) or [Portal SSO](/nightly/tyk-stack/tyk-developer-portal/enterprise-developer-portal/managing-access/enable-sso) to understand the `ActionType`, `ReturnURL`, and `IdentityHandlerConfig` fields required for your 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**.
2. Click **Create client**, set the **Client type** to **OpenID Connect**, enter a **Client ID**, and click **Next**.
3. Enable **Client authentication** and click **Next**, then **Save**.
4. From the client's **Credentials** tab, copy the **Client Secret**.
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
```
## 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.
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](/nightly/tyk-identity-broker/dashboard-sso) for full details.
**TIB profile**
The TIB profile is created via the [Tyk Identity Broker API](/nightly/tyk-identity-broker/tib-rest-api) or the [Tyk Dashboard UI](/nightly/tyk-identity-broker/dashboard-sso#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](/nightly/tyk-identity-broker/dashboard-sso#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](/nightly/tyk-identity-broker/dashboard-sso) for details on session behavior, permissions, and user group mapping.
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](/nightly/product-stack/tyk-enterprise-developer-portal/deploy/configuration#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](/nightly/tyk-stack/tyk-developer-portal/enterprise-developer-portal/managing-access/enable-sso).