Skip to content

[DX-2014] docs: add Keycloak worked example for issuing OAuth tokens via TIB #2774

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sharadregoti wants to merge 8 commits into
base: main
Choose a base branch
from
Open

[DX-2014] docs: add Keycloak worked example for issuing OAuth tokens via TIB #2774

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f45bffb
docs(DX-2014): add Keycloak worked example for issuing OAuth tokens v…
sharadregoti Aug 21, 2026
7e3a4e0
Merge main into docs/DX-2014-oauth2-keycloak-tib-example
probelabs[bot] Aug 21, 2026
1dca2c3
Merge main into docs/DX-2014-oauth2-keycloak-tib-example
probelabs[bot] Aug 25, 2026
1f42375
Merge main into docs/DX-2014-oauth2-keycloak-tib-example
probelabs[bot] Aug 25, 2026
6f85453
Merge main into docs/DX-2014-oauth2-keycloak-tib-example
probelabs[bot] Aug 26, 2026
1aff222
Merge main into docs/DX-2014-oauth2-keycloak-tib-example
probelabs[bot] Aug 27, 2026
4d5bdd7
Merge main into docs/DX-2014-oauth2-keycloak-tib-example
probelabs[bot] Aug 27, 2026
6e087bc
Merge main into docs/DX-2014-oauth2-keycloak-tib-example
probelabs[bot] Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 68 additions & 2 deletions api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,13 +111,13 @@
| `ID` | Required | Unique identifier for this profile. Forms part of the TIB authentication URL; see [Profile](/tyk-identity-broker/overview#profile). |
| `IdentityHandlerConfig.DashboardCredential` | Required | The [TIB service account's](/tyk-identity-broker/dashboard-sso#tib-service-account) Dashboard API key, used to invalidate previous tokens on re-authentication. |
| `IdentityHandlerConfig.DisableOneTokenPerAPI` | Optional | Set to `true` to allow multiple active tokens per user. Defaults to `false`. See [Controlling Concurrent Sessions](#controlling-concurrent-sessions). |
| `IdentityHandlerConfig.OAuth.APIListenPath` | Required | The listen path of the API; TIB uses this to call the OAuth authorize endpoint (`{listen_path}/tyk/oauth/authorize-client/`). |
| `IdentityHandlerConfig.OAuth.APIListenPath` | Required | The listen path of the API, without a leading or trailing slash (for example `my-api`, not `/my-api/`). TIB uses this to call the OAuth authorize endpoint (`{listen_path}/tyk/oauth/authorize-client/`); a leading or trailing slash produces a malformed URL and the Gateway returns `405`. |
| `IdentityHandlerConfig.OAuth.BaseAPIID` | Required | The ID of the API secured with Tyk's built-in OAuth 2.0 authorization server. |
| `IdentityHandlerConfig.OAuth.ClientId` | Required | The client ID of the Tyk OAuth client registered for this API. |
| `IdentityHandlerConfig.OAuth.RedirectURI` | Required | The redirect URI registered for the Tyk OAuth client. The token is returned to the client as a URL fragment at this address. |
| `IdentityHandlerConfig.OAuth.ResponseType` | Required | `token` or `authorization_code`. Use `token` for SPAs and mobile apps. |
| `IdentityHandlerConfig.OAuth.Secret` | Required | The client secret of the Tyk OAuth client. |
| `IdentityHandlerConfig.OAuth.NoRedirect` | Optional | Set to `true` to return the token as JSON in the response body instead of redirecting. Useful for non-browser clients. Defaults to `false`. |
| `IdentityHandlerConfig.OAuth.NoRedirect` | Optional | Set to `true` to return the token as JSON in the response body instead of redirecting. Useful for non-browser clients. Defaults to `false`, but always set this field explicitly; omitting it entirely can cause TIB to fail to process the request. |
| `MatchedPolicyID` | Required | The ID of the policy to apply to the generated OAuth token. |
| `OrgID` | Required | The Tyk Organisation ID. |
| `ProviderConfig` | Required | IdP-specific connection settings. See the [Identity Provider guides](/tyk-identity-broker/overview#what-would-you-like-to-do). |
Expand Down Expand Up @@ -178,6 +178,72 @@
```


### Keycloak (OAuth Token via OpenID Connect)

This example uses [Keycloak](https://www.keycloak.org/) as an OpenID Connect identity provider to issue OAuth 2.0 tokens for API access. It is a working implementation of the *identity server* role described in [Integration with Identity Server](/api-management/authentication/oauth-2#integration-with-identity-server): TIB authenticates the user against Keycloak, then requests the Tyk access token on the client's behalf.

1. Configure the Keycloak Client

Follow the [Configure Keycloak](/tyk-identity-broker/sso-keycloak#configure-keycloak) steps to create an OpenID Connect client with **Client authentication** enabled and the **Standard flow** selected. Set the client's **Valid redirect URIs** to:

```
http://{tib-host}/auth/{profile-id}/openid-connect/callback

Check warning on line 190 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: technical-accuracy

security Issue 

The example configuration for Keycloak integration uses `http://` for sensitive redirect and callback URLs (lines 190, 202, 203, 230). This is insecure as it transmits data, potentially including authorization codes, in cleartext. It can also lead to redirect mismatch errors in environments with TLS termination.
Raw output 
All example URLs that would be user-facing or involve authentication redirects should use `https://` to promote secure best practices. For example, change `http://{tib-host}` to `https://{tib-host}`.
```

Note the **Client ID**, **Client Secret**, and the realm's OIDC discovery URL, available from **Realm Settings > General > OpenID Endpoint Configuration**.

2. Register an OAuth Client in Tyk Dashboard

As with the GitHub example, you need an OAuth client registered in Tyk Dashboard for the target API. See [Client App Registration](/api-management/authentication/oauth-2#client-app-registration) for details.

3. IdP-Specific Profile Configuration

Configure the TIB profile for the [OAuth token flow](#issuing-oauth-tokens) setting `ProviderName` to `SocialProvider` and `Type` to `redirect`. The Keycloak-specific settings go in `ProviderConfig`, using the same fields as [Keycloak SSO](/tyk-identity-broker/sso-keycloak#tib-profile):

Check warning on line 202 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: quality

documentation Issue 

The worked example for Keycloak uses `http://` for several URLs, including the `Valid redirect URIs` (line 190), `CallbackBaseURL` (line 201), and `FailureRedirect` (line 202). Using non-encrypted HTTP for authentication flows is an insecure practice that should not be encouraged, even in documentation examples. It can also lead to practical issues in production environments with TLS termination where redirect URIs must match exactly. The example should use `https://` to promote security best practices.
Raw output 
Replace `http://` with `https://` in all example URLs and update placeholder hostnames like `{tib-host}` to `{public-tib-host}` to imply an externally accessible endpoint, promoting secure configurations.
```json expandable
{
"ProviderName": "SocialProvider",
"Type": "redirect",
"ProviderConfig": {
"CallbackBaseURL": "http://{tib-host}",
"FailureRedirect": "http://{app-domain}/login?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"
}
]
}
}
```

<Note>
Set `IdentityHandlerConfig.OAuth.NoRedirect` explicitly, even to `false`, in the `IdentityHandlerConfig` block shown in the [OAuth token flow](#issuing-oauth-tokens) template above. Omitting it entirely can cause TIB to fail to process the request.
</Note>

Check warning on line 225 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: technical-accuracy

documentation Issue 

The note about `NoRedirect` advises setting it explicitly but doesn't guide the user on what value to use for the current example. The test steps assume a browser redirect (`NoRedirect: false`), but a user could set it to `true` based on the note, which would break the described test flow.
Raw output 
Update the note to explicitly recommend `NoRedirect: false` for this browser-based example, while still explaining the effect of setting it to `true`. For example: "For the browser-based flow in this example, set `IdentityHandlerConfig.OAuth.NoRedirect` to `false`. If you set it to `true`, TIB will return the token as JSON in the response body instead of redirecting. You should always set this field explicitly, as omitting it can cause TIB to fail to process the request."

Check warning on line 225 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: quality

documentation Issue 

The note on line 223 advises setting `IdentityHandlerConfig.OAuth.NoRedirect` explicitly, but the subsequent "Test the Flow" section describes a browser redirect which only occurs if `NoRedirect` is `false`. If a user sets it to `true` based on the option presented, the test steps will not match the actual behavior. The note should guide the user to set it to `false` for this specific browser-based example.
Raw output 
Update the note to recommend setting `NoRedirect` to `false` for the browser-based flow described in the example, while still explaining the effect of setting it to `true`. This makes the example self-consistent.

Check warning on line 225 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: architecture

architecture Issue 

The note advises setting `IdentityHandlerConfig.OAuth.NoRedirect` explicitly but does not guide the user on which value to use for the example. The subsequent "Test the Flow" section is written with the assumption that a browser redirect will happen, which requires `NoRedirect` to be `false`. This can lead to confusion if a user sets it to `true`, as the documented test steps would no longer apply.
Raw output 
Update the note to recommend setting `NoRedirect` to `false` for this specific browser-based example to align with the test instructions. You can also clarify that setting it to `true` would change the behavior from a redirect to a JSON response, which is useful for non-browser clients.

4. Test the Flow

Navigate to the TIB authentication URL to start the flow:

```
http://{tib-host}/auth/{profile-id}/openid-connect
```

Check warning on line 234 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: architecture

architecture Issue 

The worked example consistently uses `http://` for all endpoints, including the TIB callback URL and application redirects. While this may be suitable for local testing, it promotes an insecure architecture for production environments where `https://` is essential for protecting tokens and user data in transit. This can also lead to practical issues with OIDC providers that require HTTPS for redirect URIs.
Raw output 
Modify the example URLs to use `https://` to reflect security best practices for production deployments. A brief note can be added to mention that `http://` may be used for local development if necessary.
Log in with a Keycloak user. On success, TIB redirects the browser to the `RedirectURI` configured in the profile, with the Tyk access token appended as a URL fragment:

```
http://{app-domain}:{port}/{auth-success-path}#access_token=...&expires_in=3600&token_type=bearer

Check failure on line 238 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: security

security Issue 

The documentation example for Keycloak integration consistently uses `http://` for sensitive OAuth/OIDC endpoints, including redirect URIs and callback URLs. This is insecure as it allows for man-in-the-middle attacks to intercept authorization codes or access tokens. All communication involving tokens and codes must be over HTTPS.
Raw output 
Replace all instances of `http://` with `https://` in the Keycloak example. For instance, change `http://{tib-host}` to `https://{tib-host}`. Add a note clarifying that while `http://` might be used for local testing, production deployments must use HTTPS.
```

Check failure on line 239 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: technical-accuracy

documentation Issue 

The documentation for testing the Keycloak flow states that a successful login redirects with an `access_token` in the URL fragment. This is only true if `IdentityHandlerConfig.OAuth.ResponseType` is set to `token`. If `authorization_code` is used, the redirect will contain a code, not a token. The example does not specify which response type to use, making the verification step misleading.
Raw output 
Clarify that the described outcome is for `ResponseType: token`. Either explicitly state that this example requires `ResponseType: token`, or document the alternative outcome for `ResponseType: authorization_code`. For example: "If `IdentityHandlerConfig.OAuth.ResponseType` is set to `token`, TIB redirects... with the Tyk access token... If you use `ResponseType: authorization_code`, the redirect will contain an authorization code that must be exchanged for a token."

Check warning on line 239 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: quality

documentation Issue 

The "Test the Flow" section describes a successful login redirecting with an `#access_token` in the URL fragment. This outcome is only correct if `IdentityHandlerConfig.OAuth.ResponseType` is set to `token`. The documentation allows for `authorization_code` as well, which would result in a different response (a `code` parameter). The example is incomplete as it doesn't clarify the expected outcome for both valid configurations, which could mislead users into thinking a correct `authorization_code` flow has failed.
Raw output 
Explicitly state that the described outcome is for `ResponseType: 'token'`. Briefly mention the different expected outcome for `ResponseType: 'authorization_code'` to prevent user confusion.

Check warning on line 239 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: security

security Issue 

The example's verification step describes the result of an OAuth 2.0 Implicit Grant flow (`ResponseType: token`), where the access token is returned in the URL fragment. This flow is no longer a security best practice due to risks of token leakage. The Authorization Code Grant (`ResponseType: authorization_code`) is more secure and should be the recommended default.
Raw output 
Modify the example to primarily demonstrate the Authorization Code Grant. The `IdentityHandlerConfig.OAuth.ResponseType` is mentioned in the reference table but not set in the example. The example should explicitly recommend and use `authorization_code`, and the verification steps should be updated to describe the code-for-token exchange process. If the Implicit Grant must be shown, it should be as a secondary option with clear security warnings.

Use the `access_token` to call the protected API as described in [Auth Token](/api-management/authentication/bearer-token).

<Note>

Check failure on line 243 in api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx

View check run for this annotation

probelabs / Visor: architecture

architecture Issue 

The example's test instructions describe a redirect containing an `access_token` in the URL fragment, which is the specific outcome of the OAuth `token` response type. However, the documentation does not mandate this `ResponseType` in the configuration, and the referenced general template allows for `authorization_code` as well. This creates a mismatch where a user can follow the guide, use a valid `authorization_code` configuration, and be confused when the test outcome doesn't match the documentation, leading them to believe their setup is faulty.
Raw output 
To ensure the documented architecture is clear and the example is unambiguous, explicitly state that the described test outcome is for when `ResponseType` is set to `token`. Optionally, describe the alternative outcome for `authorization_code` to provide a complete picture.
Keycloak derives its OpenID Connect `issuer` from the hostname used in the inbound request, unless a fixed hostname is configured (`KC_HOSTNAME`). If the browser and TIB reach Keycloak through different hostnames or ports, TIB's token validation fails with an issuer mismatch. Use the same hostname and port for both, or set `KC_HOSTNAME` in Keycloak to a stable value.
</Note>

### OAuth Token via LDAP

This example authenticates the user against LDAP before issuing the OAuth token. It is useful for internal APIs that require valid OAuth tokens but where user identity is managed in an LDAP directory such as Active Directory, rather than a web-based IdP.
Expand Down
2 changes: 1 addition & 1 deletion tyk-identity-broker/sso-keycloak.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ sidebarTitle: "Keycloak"

[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](/tyk-identity-broker/dashboard-sso) or [Portal SSO](/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.
Before configuring your IdP and TIB profile, read [Dashboard SSO](/tyk-identity-broker/dashboard-sso), [Portal SSO](/tyk-stack/tyk-developer-portal/enterprise-developer-portal/managing-access/enable-sso), or [Issuing Tokens via TIB](/api-management/access-control/sessions-and-keys/issuing-tokens-via-tib) to understand the `ActionType`, `ReturnURL`, and `IdentityHandlerConfig` fields required for your use case.

This page covers the Keycloak-specific configuration only.

Expand Down
Loading