Fix: Add crucial requirement for custom attributes in OIDC scope for access token inclusion (Product IS issue #27542)

[wso2-engineering-bot]

This PR was automatically generated by Claude AI.

• Fixes Doc Update: Clarify requirement to add custom attributes to OIDC scope for Access Token inclusion product-is#27542
• Type: Documentation / Suggestion
• Summary: Added critical clarification that custom attributes must be explicitly mapped to OIDC scopes to appear in access tokens. This requirement was missing from the documentation, causing potential confusion for users.

Changes Made

• Added a warning note in the "Access Token Attributes" section explaining the requirement to map custom attributes to OIDC scopes
• Included guidance on how to configure scope settings to properly associate custom attributes
• Updated the common include file that is shared across multiple versions

Affected Versions

This fix applies to the following Identity Server versions:

• 7.1.0 (explicitly mentioned in the issue)
• 7.2.0 (labeled in the issue)
• All versions after 7.0.0 that use the Access Token Attributes feature

Note: Version 7.0.0 does not include the Access Token Attributes feature, so this fix does not apply to that version.

Style Scope Verification

Microsoft Style Guidelines have been applied to the newly added content:

• Used active voice and present tense
• Applied sentence case for the warning heading
• Formatted UI labels in bold (e.g., Access Token Attributes)
• Used clear, concise language
• Structured content for easy readability

Verification

The markdown syntax has been validated and follows repository conventions. The changes use proper MkDocs admonition syntax and maintain consistency with existing documentation style.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ pavinduLakshan
❌ wso2-engineering-bot

---

wso2-engineering-bot seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: de99af37-11e8-4bb6-9426-ccd4eba9268a

📥 Commits

Reviewing files that changed from the base of the PR and between e26e462 and 5c50f4a.

📒 Files selected for processing (1)

• en/includes/guides/fragments/manage-app/oidc-settings/access-token.md

✅ Files skipped from review due to trivial changes (1)

• en/includes/guides/fragments/manage-app/oidc-settings/access-token.md

---

📝 Walkthrough

Walkthrough

Added a warning to the Access Token Attributes documentation clarifying that custom attributes are included in JWT access tokens only when they are explicitly mapped to an OIDC scope and the application requests that scope; without such mapping, custom attributes are not present in the JWT.

Changes

Cohort / File(s)	Summary
OIDC Access Token Documentation en/includes/guides/fragments/manage-app/oidc-settings/access-token.md	Inserted a warning under "Access Token Attributes" stating custom attributes are not automatically included in JWT access tokens and must be explicitly mapped to an OIDC scope and requested by the application to appear in the token.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a crucial requirement for custom attributes in OIDC scope for access token inclusion, with explicit issue reference.
Description check	✅ Passed	The PR description provides a comprehensive overview with purpose, changes made, affected versions, and style verification, though it does not follow the exact template structure with Security checks section.
Linked Issues check	✅ Passed	The PR successfully addresses all requirements from issue #27542: documents the custom attribute to OIDC scope mapping requirement, updates the Access Token Attributes documentation, targets relevant versions, and references the related product issue.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issue requirements. The documentation update focuses solely on clarifying the custom attribute mapping requirement with no unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fixing-product-is-issue-27542-1775841390

---

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

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

en/includes/guides/fragments/manage-app/oidc-settings/access-token.md (1)

57-58: ⚠️ Potential issue | 🔴 Critical

Fix: Add blank line before heading to resolve pipeline failure.

The Markdown linter requires a blank line above headings. The pipeline is currently failing with MD022 error at line 58.

📝 Proposed fix

 {% endif %}
+
 #### Access Token Attributes

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@en/includes/guides/fragments/manage-app/oidc-settings/access-token.md` around
lines 57 - 58, Add a blank line immediately before the conditional heading block
that renders "#### Access Token Attributes" so the Markdown linter rule MD022 is
satisfied; specifically, update the template around the expression {% if
product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and
is_version != "7.0.0") %} to ensure there is an empty line preceding the "####
Access Token Attributes" heading when it is rendered.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@en/includes/guides/fragments/manage-app/oidc-settings/access-token.md`:
- Line 67: Remove the trailing whitespace on the blank line in access-token.md
(the blank line reported by the linter) so the line contains no spaces; simply
delete the extra spaces at the end of that empty line to satisfy MD009.

---

Outside diff comments:
In `@en/includes/guides/fragments/manage-app/oidc-settings/access-token.md`:
- Around line 57-58: Add a blank line immediately before the conditional heading
block that renders "#### Access Token Attributes" so the Markdown linter rule
MD022 is satisfied; specifically, update the template around the expression {%
if product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and
is_version != "7.0.0") %} to ensure there is an empty line preceding the "####
Access Token Attributes" heading when it is rendered.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 91c910ec-27b4-42bd-a818-c16efc99283b

📥 Commits

Reviewing files that changed from the base of the PR and between c976863 and a4d2287.

📒 Files selected for processing (1)

• en/includes/guides/fragments/manage-app/oidc-settings/access-token.md