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

[sharadregoti]

User description

Summary

• Adds a Keycloak (OAuth Token via OpenID Connect) worked example to api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx, alongside the existing GitHub and LDAP examples, implementing the GenerateOAuthTokenForClient TIB action with SocialProvider/openid-connect.
• Clarifies two field descriptions in the same page's "Issuing OAuth Tokens" reference table: APIListenPath (must have no leading/trailing slash) and NoRedirect (should always be set explicitly).
• Cross-links tyk-identity-broker/sso-keycloak.mdx's intro to also point at "Issuing Tokens via TIB", since its Keycloak client setup steps are now reused by the new worked example.

Context

Jira: DX-2014 (Zendesk 22155). The customer's application currently handles SSO redirection itself before calling their API; they want to offload that redirect/token flow to Tyk, using Tyk's OAuth 2.0 Authorization Code Grant as documented at api-management/authentication/oauth-2#using-the-authorization-code-grant. That page already explains the identity server role and links to TIB, but issuing-tokens-via-tib.mdx had no worked example using an OIDC provider like Keycloak, only GitHub (Social) and LDAP.

I confirmed the approach with OEL: Tyk Gateway cannot act as an OIDC Relying Party itself, so TIB acting as the identity server (as already documented) is the correct and only path. I verified the whole flow end-to-end locally (Keycloak → standalone TIB → Tyk Gateway OAuth2 authorization server → protected API), which surfaced two real gaps that are fixed by this PR:

• APIListenPath must be the bare API id/path segment with no leading or trailing slash; copying the listen path verbatim from the API definition produces a malformed URL and the Gateway returns 405.
• NoRedirect should always be set explicitly (even to false); omitting it can cause TIB to fail to process the request (observed on TIB v1.7.3).

Test plan

• Verified locally: Keycloak (quay.io/keycloak/keycloak:23.0) + standalone TIB (tykio/tyk-identity-broker:v1.7.3) + Tyk Gateway/Dashboard (v5.8.13) via tyk-self-managed-trial. Logged in as a Keycloak user through TIB, obtained a Tyk access token via GenerateOAuthTokenForClient, and successfully called the protected API with it (200 from httpbin; 400 without the token).
• Ran scripts/validate_mintlify_docs.py . --check-anchors --links-only locally against the full repo: no broken links, no broken anchor fragments.
• Checked the changed files against the "relative markdown links" and other validate-docs.yml checks manually; all pass.

🤖 Generated with entirely Claude Code assistance, reviewed by Sharad.

---

PR Type

Documentation

---

Description

• Add Keycloak TIB token example

• Clarify APIListenPath slash requirements

• Warn to set NoRedirect explicitly

• Cross-link Keycloak SSO guidance

---

Diagram Walkthrough

flowchart LR
  app["Client application"]
  tib["Tyk Identity Broker"]
  kc["Keycloak OIDC provider"]
  gw["Tyk OAuth gateway"]
  app -- "start auth flow" --> tib
  tib -- "authenticate user" --> kc
  tib -- "request OAuth token" --> gw
  gw -- "return access token" --> tib
  tib -- "redirect with token" --> app

Loading

File Walkthrough

Relevant files

Documentation

issuing-tokens-via-tib.mdx Add Keycloak token flow example                                                    api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx Clarify IdentityHandlerConfig.OAuth.APIListenPath must exclude leading and trailing slashes. Document that malformed APIListenPath values can produce Gateway 405 errors. Clarify IdentityHandlerConfig.OAuth.NoRedirect should always be set explicitly. Add a full Keycloak OpenID Connect worked example for issuing OAuth tokens via TIB. +68/-2    sso-keycloak.mdx Cross-link Keycloak docs to TIB                                                    tyk-identity-broker/sso-keycloak.mdx Update the introduction to link Keycloak setup guidance to Issuing Tokens via TIB. Expand the list of prerequisite guides for choosing the correct ActionType and profile fields. +1/-1

---

[probelabs]

This PR adds a detailed worked example for using Keycloak as an OpenID Connect (OIDC) provider to issue Tyk OAuth 2.0 tokens via the Tyk Identity Broker (TIB). It addresses a documented customer need by providing a step-by-step guide for this common integration pattern. The PR also clarifies two important TIB configuration fields (APIListenPath and NoRedirect) based on end-to-end testing and improves documentation discoverability by cross-linking related guides.

Files Changed Analysis

• api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx: This is the primary file changed. It introduces the new Keycloak worked example, including client setup, TIB profile configuration, and testing steps. It also adds crucial clarifications for the APIListenPath and NoRedirect configuration fields to prevent common errors.
• tyk-identity-broker/sso-keycloak.mdx: This file has a minor but important update, adding a cross-link from the existing Keycloak SSO guide to the new token issuance example. This improves the user journey by connecting related use cases.

Architecture & Impact Assessment

• What this PR accomplishes
  The PR provides a clear, validated guide for integrating an external OIDC identity provider (Keycloak) with Tyk's native OAuth 2.0 server using TIB. This helps users offload complex authentication and token exchange flows from their applications to the Tyk stack.

• Key technical changes introduced
  While the changes are purely documentary, they introduce critical technical guidance:

  • A complete TIB profile configuration for using Keycloak via the SocialProvider/openid-connect type.
  • Clarification that APIListenPath must be a bare path segment (e.g., my-api) to avoid 405 errors from the Gateway.
  • A recommendation to always set the NoRedirect field explicitly to prevent TIB from failing to process requests.

• Affected system components
  The documentation describes the interaction between four key components in an OIDC-brokered OAuth 2.0 flow:

  • Client Application: The end-user application initiating the authentication request.
  • Tyk Identity Broker (TIB): Orchestrates the OIDC flow with Keycloak and requests the final access token from the Tyk Gateway.
  • Keycloak: The external OpenID Connect Identity Provider (IdP) that handles user authentication.
  • Tyk Gateway: Acts as the OAuth 2.0 Authorization Server, issuing the final Tyk access token.

• Component Interaction Flow

sequenceDiagram
participant C as Client App
participant TIB as Tyk Identity Broker
participant KC as "Keycloak (OIDC IdP)"
participant GW as "Tyk Gateway (OAuth Server)"

C->>TIB: Start Auth Flow (e.g., /auth/{profile-id}/openid-connect)
TIB->>KC: Redirect user to Keycloak for login
KC-->>C: User authenticates
C->>KC: Submit credentials
KC-->>TIB: Redirect back with authorization code
activate TIB
TIB->>KC: Exchange authorization code for ID token
KC-->>TIB: Return ID token
TIB->>GW: Request Tyk OAuth Token (via GenerateOAuthTokenForClient action)
activate GW
GW-->>TIB: Issue Tyk Access Token
deactivate GW
TIB-->>C: Redirect to client with Tyk Access Token
deactivate TIB

## Scope Discovery & Context Expansion
The author's end-to-end testing has expanded the scope from a simple procedural guide to a validated, production-aware set of instructions. By discovering and documenting non-obvious configuration requirements for `APIListenPath` and `NoRedirect`, the PR proactively addresses common user pitfalls. The cross-linking between the Keycloak SSO guide and this new example correctly identifies that the Keycloak client setup is a shared prerequisite, improving the overall information architecture and user journey through the documentation.


<details>
  <summary>Metadata</summary>

  - Review Effort: 2 / 5
  - Primary Label: documentation


</details>
<!-- visor:section-end id="overview" -->

<!-- visor:thread-end key="TykTechnologies/tyk-docs#2774@6e087bc" -->

---

*Powered by [Visor](https://probelabs.com/visor) from [Probelabs](https://probelabs.com)*

*Last updated: 2026-08-27T05:57:59.636Z | Triggered by: pr_updated | Commit: 6e087bc*

💡 **TIP:** You can chat with Visor using `/visor ask <your question>`
<!-- /visor-comment-id:visor-thread-overview-TykTechnologies/tyk-docs#2774 -->

[probelabs]

Technical-accuracy Issues (3)

Severity	Location	Issue
🟠 Error	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:235-239	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. 💡 Suggestion 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."
🟡 Warning	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:190	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. 💡 Suggestion 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}`.
🟡 Warning	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:223-225	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. 💡 Suggestion 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."

Technical-accuracy Issues (3)

Severity	Location	Issue
🟠 Error	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:235-239	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. 💡 Suggestion 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."
🟡 Warning	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:190	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. 💡 Suggestion 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}`.
🟡 Warning	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:223-225	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. 💡 Suggestion 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."

\n\n ### Security Issues (2)

Severity	Location	Issue
🟠 Error	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:190-238	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. 💡 Suggestion 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.
🟡 Warning	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:235-239	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. 💡 Suggestion 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.

Architecture Issues (3)

Severity	Location	Issue
🟠 Error	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:239-243	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. 💡 Suggestion 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.
🟡 Warning	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:223-225	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. 💡 Suggestion 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.
🟡 Warning	api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx:190-234	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. 💡 Suggestion 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.

✅ Performance Check Passed

No performance issues found – changes LGTM.

✅ Quality Check Passed

No quality issues found – changes LGTM.

---

Powered by Visor from Probelabs

Last updated: 2026-08-27T05:57:52.557Z | Triggered by: pr_updated | Commit: 6e087bc

💡 TIP: You can chat with Visor using /visor ask <your question>

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Misleading outcome This worked example does not pin IdentityHandlerConfig.OAuth.ResponseType, but the test step says a successful login redirects with #access_token=.... That is only true for the token response type. If a reader follows the shared template with authorization_code, TIB will return an authorization code instead, so the documented verification step is wrong for that valid configuration. 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

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Clarify response type outcome This outcome is only correct when IdentityHandlerConfig.OAuth.ResponseType is token. Call that out explicitly here, or document the authorization_code result as an alternative, otherwise readers can configure a valid flow that does not return #access_token=... and think the example is broken. api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx [235] -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: +Log in with a Keycloak user. If `IdentityHandlerConfig.OAuth.ResponseType` is set to `token` for this example, TIB redirects the browser to the `RedirectURI` configured in the profile with the Tyk access token appended as a URL fragment. If you use `ResponseType: authorization_code` instead, expect an authorization code response rather than `#access_token=...`: Suggestion importance[1-10]: 6 __ Why: This is a valid documentation issue: the described result at RedirectURI only matches IdentityHandlerConfig.OAuth.ResponseType: token, while authorization_code behaves differently. Clarifying that prevents readers from misinterpreting a correct configuration as a broken flow.	Low
	Align redirect behavior note The test steps below assume IdentityHandlerConfig.OAuth.NoRedirect is false; if a reader follows this note and sets it to true, there will be no browser redirect at all. Mention that dependency here so the documented verification path matches the configuration being recommended. api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx [223-225] <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. +Set `IdentityHandlerConfig.OAuth.NoRedirect` explicitly in the `IdentityHandlerConfig` block shown in the [OAuth token flow](#issuing-oauth-tokens) template above. For the browser-based flow in this example, keep it `false`; if you set it to `true`, TIB returns the token as JSON in the response body instead of redirecting. Omitting the field entirely can cause TIB to fail to process the request. </Note> Suggestion importance[1-10]: 6 __ Why: This correctly points out that the note about IdentityHandlerConfig.OAuth.NoRedirect can conflict with the browser-redirect test steps that follow. Adding the false requirement for this example would make the configuration guidance consistent with the documented verification path.	Low
Security	Use public HTTPS endpoints Using http:// in a token-issuing example is unsafe outside local development and can also cause redirect mismatches when TIB is behind TLS termination. Show the externally reachable https:// URL that the browser uses, not TIB's internal address, so the callback configuration works in real deployments. api-management/access-control/sessions-and-keys/issuing-tokens-via-tib.mdx [190-209] -http://{tib-host}/auth/{profile-id}/openid-connect/callback +https://{public-tib-host}/auth/{profile-id}/openid-connect/callback ... - "CallbackBaseURL": "http://{tib-host}", - "FailureRedirect": "http://{app-domain}/login?fail=true", + "CallbackBaseURL": "https://{public-tib-host}", + "FailureRedirect": "https://{app-domain}/login?fail=true", Suggestion importance[1-10]: 5 __ Why: This is a reasonable improvement because CallbackBaseURL and the callback URI often need to match the externally reachable URL, especially behind TLS termination. However, it is more of a deployment and documentation best-practice improvement than a definite bug in the PR text.	Low