Skip to main content

​
Introduction

Keycloak 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 or Portal 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. Create Client
  2. Click Create client, set the Client type to OpenID Connect, enter a Client ID, and click Next. Set Client Type and ID
  3. Enable Client authentication and click Next, then Save. Enable Client Auth
  4. From the client’s Credentials tab, copy the Client Secret. Retrieve 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
Keycloak discovery endpoint

​
TIB Profile

The Keycloak-specific configuration goes in the ProviderConfig block of the TIB profile. Set ProviderName to SocialProvider and Type to redirect. 
{
  "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:
FieldDescription
CallbackBaseURLThe base URL of your TIB instance. TIB appends the callback path automatically.
FailureRedirectURL to redirect the user to on authentication failure.
UseProviders.NameMust be openid-connect. This value routes TIB to the OpenID Connect provider implementation.
UseProviders.KeyThe Keycloak Client ID.
UseProviders.SecretThe Keycloak Client Secret.
UseProviders.ScopesOAuth scopes to request. openid and email are required.
UseProviders.DiscoverURLThe 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: 
{
  "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
{
  "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 for full details.TIB profileThe TIB profile is created via the Tyk Identity Broker API or the Tyk Dashboard UI.
{
  "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 Dashboard credentials
Keycloak redirect URIEnsure 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 URLThis 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 for details on session behavior, permissions, and user group mapping.