SSO with Keycloak

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, pick the guide for your use case: Dashboard SSO, Portal SSO, or Issuing Tokens via TIB. Each page explains the ActionType, ReturnURL, and IdentityHandlerConfig fields for that use case. This page covers the Keycloak-specific configuration only.

Configure Keycloak

In your Keycloak Admin Console, navigate to the realm you want to use and select Clients.
Click Create client, set the Client type to OpenID Connect, enter a Client ID, and click Next.
Enable Client authentication and click Next, then Save.
From the client’s Credentials tab, copy the Client Secret.
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.
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.

{
  "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:

{
  "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.

Dashboard SSO
Portal 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

{
  "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.

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 configurationEnable embedded TIB in the Portal configuration:

{
  "TIB": {
    "Enable": true
  }
}

TIB profileThe TIB profile is created via the Tyk Developer Portal UI under Settings > SSO Profiles.

{
  "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 used to authenticate with the Portal’s management API

http://portal.example.com:3001/auth/keycloak-portal-oidc/openid-connect/callback

Login URLThis 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.

Overview

Govern APIs

Dashboard Analytics

User Management

Tyk Identity Broker (TIB)

Guides

Reference

Introduction

Configure Keycloak

TIB Profile

JSON Web Encryption (JWE)

Worked Examples

​Introduction

​Configure Keycloak

​TIB Profile

​JSON Web Encryption (JWE)

​Worked Examples

Introduction

Configure Keycloak

TIB Profile

JSON Web Encryption (JWE)

Worked Examples