Add cert expired issue as a note in token exchange grant

[mpmadhavig]

Purpose

$subject

Summary by CodeRabbit

• Documentation
  • Added a cautionary note titled "Using product tokens as issuer" to the token exchange guide explaining signature failures when a product-issued token's signing certificate has expired.
  • Clarifies that renewing the issuing certificate in both the Key Store and Trust Store prevents validation errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

Walkthrough

Added a cautionary note to the token exchange configuration docs explaining that using a product-issued token as the subject token can cause signature validation to fail if the issuer's public certificate has expired, and instructing renewal of the issuing certificate in both the Key Store and the Trust Store.

Changes

Cohort / File(s)	Summary
Documentation en/includes/guides/authentication/configure-token-exchange.md	Inserted a caution titled "Using {{ product_name }} tokens as issuer" immediately after the issuer details block under "Register a trusted token issuer", explaining signature validation failure when issuer public certificates expire and instructing renewal in Key Store and Trust Store.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 I nudge a note into the fold,
Of expiring certs and tokens old,
Renew the keys, both store and trust,
So signatures stay fair and just,
Hooray — no more surprises bold! 🎋

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is incomplete and largely unfilled. Only the Purpose section header is present with a placeholder '$subject' instead of actual content, and all other required sections (Related PRs, Test environment, Security checks) are entirely missing.	Complete the Purpose section with actual details about the certificate expiration issue, and fill in the Related PRs, Test environment, and Security checks sections as required by the template.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a note about certificate expiration issues to token exchange grant documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into master

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@en/includes/guides/authentication/configure-token-exchange.md`:
- Around line 39-40: The note titled "Using Identity Server tokens as issuer" is
misleading: update the text to state that expired tokens are not fixed by
updating the signing certificate and that certificate/JWKS updates are only
necessary when the issuer rotates its signing key (or when using a static PEM
certificate rather than automatic JWKS refresh); also replace the literal
"Identity Server" with the product-agnostic {{ product_name }} variable. Edit
the note content to clearly say: token expiry is normal and must be resolved by
re-issuing a fresh token, while updating the public certificate or JWKS is only
required if the issuer rotated its signing key or if you rely on a static PEM,
and include a brief remediation sentence advising to request a new token or
configure automatic JWKS refresh.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

cat -n en/includes/guides/authentication/configure-token-exchange.md | sed -n '35,45p'

Repository: wso2/docs-is

Length of output: 936

---

🌐 Web query:

WSO2 Identity Server token exchange subject token validation JWKS certificate rotation

💡 Result:

In WSO2 Identity Server Token Exchange (grant_type=urn:ietf:params:oauth:grant-type:token-exchange), the subject_token (JWT) is validated against the Trusted Token Issuer you configure. You have two practical options for handling certificate/key rotation:

1) Recommended: Validate via the issuer’s JWKS endpoint

1. Register the third-party issuer as a Trusted Token Issuer and choose JWKS endpoint, providing the issuer’s jwks_uri. WSO2 IS will use that JWKS to validate the subject_token signature. [1]
2. Ensure the JWKS HTTP client is enabled (and tune timeouts if needed) via deployment.toml:

[oauth.jwks_endpoint]
enable = true
connection_timeout = 1000
read_timeout = 1000
size_limit_bytes = 51200

[2]

What happens during rotation (key rollover)

• WSO2 IS caches JWKS per jwks_uri and validates JWTs by matching the JWT header kid to a key in the cached JWKS. [3]
• If the issuer rotates keys and a new JWT arrives with a kid not found in the cached JWKS, WSO2 IS re-fetches the latest JWKS from the endpoint and retries validation with the matching key. This is the built-in mechanism that makes rotation work without manual cert updates (as long as the issuer publishes the new key via JWKS). [3]

Operational best practice: during rotation, the issuer should publish both old and new keys in JWKS for an overlap window so previously issued tokens keep validating until they expire (this is generally how smooth rollover is achieved with JWKS). [3]

2) If you validate via a static PEM certificate (manual rotation)

If, when registering the Trusted Token Issuer, you choose Use PEM certificate, then rotation is not automatic—you must update the uploaded/pasted public certificate in WSO2 IS whenever the issuer rotates its signing cert/key. [1]

Sources: WSO2 IS token exchange trusted token issuer config [1], enabling JWKS endpoint + rollover note [2], JWKS caching + refresh-on-kid-miss behavior [3].

---

Clarify the cause and remediation: token expiry is not fixed by certificate updates.

The note incorrectly suggests that updating the public certificate remediates an expired token. Token expiry is expected behavior; certificate updates are only necessary when the signing certificate or key is rotated by the issuer. The current wording may mislead users into rotating certificates to fix token expiry, which is incorrect. Additionally, the note uses "Identity Server" while the surrounding content uses {{ product_name }} for product-agnostic language.

Reword to clarify that certificate/JWKS updates are relevant only when the issuer rotates its signing key or when using the static PEM certificate method (as opposed to automatic JWKS refresh). For example:

Suggested rewording

-    !!! note "Using Identity Server tokens as issuer"
-        If you use a token issued from Identity Server itself as the subject token, in the cases where the token is expired, update the public certificate of the Identity Server used to issue the token to avoid issues.
+    !!! note "Using {{ product_name }} tokens as issuer"
+        If you use a token issued by {{ product_name }} as the subject token and the issuer rotates its signing certificate or key, update the trusted token issuer's public certificate or JWKS configuration to validate newly issued tokens. Use the JWKS endpoint method when available, as it automatically handles certificate rotation.

🤖 Prompt for AI Agents

In `@en/includes/guides/authentication/configure-token-exchange.md` around lines
39 - 40, The note titled "Using Identity Server tokens as issuer" is misleading:
update the text to state that expired tokens are not fixed by updating the
signing certificate and that certificate/JWKS updates are only necessary when
the issuer rotates its signing key (or when using a static PEM certificate
rather than automatic JWKS refresh); also replace the literal "Identity Server"
with the product-agnostic {{ product_name }} variable. Edit the note content to
clearly say: token expiry is normal and must be resolved by re-issuing a fresh
token, while updating the public certificate or JWKS is only required if the
issuer rotated its signing key or if you rely on a static PEM, and include a
brief remediation sentence advising to request a new token or configure
automatic JWKS refresh.