Fix: Add comprehensive documentation for explicit federated user associations for all affected versions (Product IS issue #26288) #5757
Conversation
…ciations for all affected versions (product-is#26288) - Added detailed guide on managing explicit federated user associations via APIs - Documented the idp and federatedUserId parameters with clear examples - Explained how federatedUserId maps to sub claim (OIDC) and NameID (SAML) - Added instructions for custom subject attribute mapping configuration - Documented the deployment.toml config: enable_configured_idp_sub_for_federated_user_association - Included bulk API documentation for IS 7.2+ - Applied changes to versions: 7.0.0, 7.1.0, 7.2.0, and next 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
|
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. |
WalkthroughThis PR adds comprehensive documentation for managing federated user associations across multiple WSO2 Identity Server versions (7.0.0, 7.1.0, 7.2.0, and next). It introduces a shared template pattern with includes and updates navigation configuration files for each version, supplemented by broader user management organizational changes in the next version. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (9)
en/identity-server/7.0.0/docs/guides/users/manage-federated-user-associations.md (1)
1-2: Include looks correct; consider setting a version flag here.Path resolves from this depth. To hide the 7.2+ bulk section for 7.0.0, set a flag before the include.
{% set product_name = "WSO2 Identity Server" %} +{% set has_bulk_association_api = false %} {% include "../../../../../includes/guides/users/manage-federated-user-associations.md" %}en/includes/guides/users/manage-federated-user-associations.md (5)
122-154: Gate the bulk API section by version, not by product name.This section says “IS 7.2.0 introduces…”, but the include is rendered for 7.0.0/7.1.0 too, causing a broken link if that API isn’t present in older docs. Introduce a boolean flag and default it to false in this include; set it true only in 7.2.0 and next pages.
Apply in this include:
+{% if has_bulk_association_api is not defined %}{% set has_bulk_association_api = false %}{% endif %} -{% if product_name == "WSO2 Identity Server" %} +{% if has_bulk_association_api %} ### Create bulk associations (IS 7.2+) @@ -Learn more about the [federated user association bulk API]({{base_path}}/apis/organization-apis/org-association-rest-api/). +Learn more about the [federated user association bulk API]({{base_path}}/apis/organization-apis/org-association-rest-api/). {% endif %}Then in version pages:
- 7.2.0 and next:
{% set has_bulk_association_api = true %}- 7.0.0 and 7.1.0:
{% set has_bulk_association_api = false %}(or omit).Confirm the link slug exists in each version. As per coding guidelines, …
239-244: Ensure referenced API slugs exist in each version; align link formats (.md vs folder).Some links use trailing slash paths (e.g.,
{{base_path}}/apis/association-rest-api/) while nav files list.mdpages. Standardize to avoid 404s after build.
- Replace with exact slugs used in nav, or confirm MkDocs redirects/aliases are configured for both forms across 7.0.0–7.2.0.
- Quick check recommended after
mkdocs build.
223-236: Deletion uses the end‑user API; mention admin deletion too.Add the admin API variant to delete another user’s association, or clarify this is only for the current user.
57-65: Minor editorial tweak for clarity.Rephrase to avoid split infinitive and keep tone consistent.
-The `federatedUserId` corresponds to the subject identifier that the external IdP uses to uniquely identify a user: +The `federatedUserId` corresponds to the subject identifier the external IdP uses to identify a user:
176-181: Style nit: avoid repeated “For example, if you want to …”.Tighten phrasing for variety.
-For example, if you want to use the user's email address: +For example, to use the user's email address:en/identity-server/7.2.0/docs/guides/users/manage-federated-user-associations.md (1)
1-2: Set the bulk API flag for 7.2.0.Enable rendering of the 7.2+ bulk section for this version.
{% set product_name = "WSO2 Identity Server" %} +{% set has_bulk_association_api = true %} {% include "../../../../../includes/guides/users/manage-federated-user-associations.md" %}en/identity-server/next/docs/guides/users/manage-federated-user-associations.md (1)
1-2: Enable bulk API section for “next”.Next should include 7.2+ features.
{% set product_name = "WSO2 Identity Server" %} +{% set has_bulk_association_api = true %} {% include "../../../../../includes/guides/users/manage-federated-user-associations.md" %}en/identity-server/7.1.0/docs/guides/users/manage-federated-user-associations.md (1)
1-2: Include is fine; explicitly disable bulk section for 7.1.0.Prevents showing a 7.2+ feature on 7.1.0 pages.
{% set product_name = "WSO2 Identity Server" %} +{% set has_bulk_association_api = false %} {% include "../../../../../includes/guides/users/manage-federated-user-associations.md" %}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
en/identity-server/7.0.0/docs/guides/users/manage-federated-user-associations.md(1 hunks)en/identity-server/7.0.0/mkdocs.yml(1 hunks)en/identity-server/7.1.0/docs/guides/users/manage-federated-user-associations.md(1 hunks)en/identity-server/7.1.0/mkdocs.yml(1 hunks)en/identity-server/7.2.0/docs/guides/users/manage-federated-user-associations.md(1 hunks)en/identity-server/7.2.0/mkdocs.yml(1 hunks)en/identity-server/next/docs/guides/users/manage-federated-user-associations.md(1 hunks)en/identity-server/next/mkdocs.yml(1 hunks)en/includes/guides/users/manage-federated-user-associations.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
en/includes/guides/users/manage-federated-user-associations.md
[style] ~59-~59: Try moving the adverb to make the sentence clearer.
Context: ...ubject identifier that the external IdP uses to uniquely identify a user: For OIDC connections: The `feder...
(SPLIT_INFINITIVE)
[style] ~178-~178: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ct identifier. For example, if you want to use the user's email address: - For...
(REP_WANT_TO_VB)
🔇 Additional comments (5)
en/identity-server/7.0.0/mkdocs.yml (1)
608-608: Nav entry LGTM; run a quick link check.The page exists; please run the docs link checker to catch regressions after build.
en/identity-server/7.2.0/mkdocs.yml (1)
653-657: Nav addition under “Users” looks good.Item points to the correct guide. Please verify the nesting renders as intended in the built sidebar.
en/identity-server/7.1.0/mkdocs.yml (1)
633-634: Nav entry LGTM; verify after build.Path matches the added page; please run a local build to confirm no broken anchors in this section.
en/identity-server/next/mkdocs.yml (2)
653-656: Navigation restructuring introduces new "Users:" subsection.Lines 653–656 refactor the User management navigation by creating a nested "Users:" subsection that groups "Onboard users", "Manage users", and the new "Manage federated user associations" entry. This is a logical organizational change that improves navigation hierarchy.
656-656: No action required. The referenced documentation file exists aten/identity-server/next/docs/guides/users/manage-federated-user-associations.md, and the navigation entry has been consistently applied across all relevant version files (7.0.0, 7.1.0, and 7.2.0).
| ### Create a single association | ||
|
|
||
| To create a single federated user association for a specific local user: | ||
|
|
||
| 1. Obtain the local user's unique identifier (user ID) in {{ product_name }}. | ||
|
|
||
| 2. Use the following API request: | ||
|
|
||
| ```bash | ||
| curl -X POST \ | ||
| 'https://<hostname>/api/users/v1/me/federated-associations' \ | ||
| -H 'Authorization: Bearer <access_token>' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "idp": "GoogleIdP", | ||
| "federatedUserId": "1234567890" | ||
| }' | ||
| ``` | ||
|
|
||
| Replace the following: | ||
| - `<hostname>` - Your {{ product_name }} hostname | ||
| - `<access_token>` - A valid access token with appropriate permissions | ||
| - `GoogleIdP` - The name of your external IdP connection | ||
| - `1234567890` - The federated user's unique identifier | ||
|
|
||
| 3. If successful, the API returns a `201 Created` response, confirming that the association was created. |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
WSO2 Identity Server federated associations API create endpoint scopes documentation
💡 Result:
The create (POST) endpoints for account associations (including federated associations) require the scope mapped to the "create" permission: internal_identity_mgt_create (permission: /permission/admin/manage/identity/identitymgt/create). See the Associations API docs and the REST‑API scopes mapping. [1][2]
Sources:
[1] WSO2 Identity Server — User Account Associations API (Associated accounts API).
[2] WSO2 Identity Server — Scopes Corresponding to Permissions Required to Invoke REST API Calls (scopes mapping).
🌐 Web query:
WSO2 Identity Server "/api/users/v1/me/federated-associations" OR "/api/server/v1/users" federated associations endpoint
💡 Result:
Short answer: WSO2 IS exposes a "User Account Associations" (federated-associations) REST API — e.g. GET/POST/DELETE under the /me/federated-association(s) resource (commonly exposed as /api/users/v1/me/federated-associations or tenant-scoped /t/{tenant}/api/users/v1/me/federated-associations). Use the association API to list a user’s federated associations, create (link) one, or remove one. See WSO2 docs and community examples for request/response shapes and available operations. [1][2]
Sources:
- WSO2 Identity Server — Associated accounts / Association REST API (API operations: /me/federated-association, /{user-id}/federated-association). [1]
- WSO2 docs / examples and community posts showing usage such as /t/{tenant}/api/users/v1/me/federated-associations (Asgardeo/WSO2 examples). [2]
Address ambiguity between "specific local user" wording and the "/me" endpoint, which only applies to the authenticated user.
The current text states "for a specific local user" and "obtain the local user's unique identifier," but the code sample uses /api/users/v1/me/federated-associations, which only manages the caller's own associations, ignoring any target user ID.
Reword the introduction to: "To create a federated user association for the currently authenticated user:" This aligns the prose with the actual /me endpoint behavior. If the documentation should also cover admin-initiated associations for other users, add a separate section for that use case with the appropriate admin endpoint pattern (/{user-id}/federated-association), an admin-scoped access token, and the internal_identity_mgt_create scope requirement.
🤖 Prompt for AI Agents
en/includes/guides/users/manage-federated-user-associations.md lines 95-120: The
wording says "for a specific local user" and instructs obtaining a local user ID
but the example uses the /api/users/v1/me/federated-associations endpoint which
only operates on the authenticated user; update the introduction to "To create a
federated user association for the currently authenticated user:" to match the
/me endpoint, and add a new, separate section showing the admin flow for other
users that uses the admin endpoint pattern (/{user-id}/federated-association),
notes the need for an admin-scoped access token, and mentions the
internal_identity_mgt_create scope requirement.
This PR was automatically generated by Claude AI.
Issue: wso2/product-is#26288
Type: Documentation (missing documentation)
Summary: Added comprehensive documentation for managing explicit federated user associations via APIs, addressing the lack of documentation reported in product-is#26288. This includes detailed explanations of API parameters, custom subject attribute mapping configuration, and the deployment.toml setting.
Affected Versions:
Changes Made:
Created new guide: "Manage explicit federated user associations" explaining:
idpandfederatedUserId)federatedUserIdmaps tosubclaim in OIDC andNameIDin SAMLenable_configured_idp_sub_for_federated_user_associationdeployment.toml configurationUpdated mkdocs.yml in all affected versions to include the new documentation page
Style Scope Verification: Microsoft Style Guidelines have been applied to all newly created content. No modifications were made to existing documentation style.
Verification: All mkdocs.yml files validated successfully with Python YAML parser.
Related Documentation:
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.