Document flow extension attribute access and supported flows

[KD23243]

Purpose

Documents the changes introduced by wso2/carbon-identity-framework#8221 and wso2/identity-apps#10567, and brings the flow extension docs in line with wso2/identity-apps#10537.

Three statements in the existing docs were no longer accurate:

• Flow extensions were documented as supported only in the Self Registration flow. The Flow Extension step is now available in the password recovery and ask password flow builders as well.
• Identity attributes (http://wso2.org/claims/identity/*) were documented as impossible for an extension to modify. That restriction has been removed, and these attributes are now listed in the claim picker and support both read and write.
• Nothing described why certain fields cannot be marked as writable, or that the set of such fields is now resolved from server configuration rather than from each claim's userstore read-only marking.

Steps 1 and 4 of the configuration guide also rendered with broken media on the IS next site, because three assets referenced by the shared include existed only in the Asgardeo tree.

Related Issue

• N/A

Implementation

Supported flows

flow-extensions/index.md replaces the Self-Registration-only note with a Supported flows table covering Self Registration, Password Recovery, and Invited User Registration, along with the flow type each one sends. A new What an extension can read and write section establishes the read and write access model once, and notes that a reused extension can receive a smaller payload in one flow than in another.

flow-extension-configuration.md Step 5 now states the three flows and that the procedure is identical in each, then keeps the Self Registration walkthrough as the worked example.

Attribute access levels

flow-extension-configuration.md Step 3 gains an Attribute access levels section: a table covering fields that accept read only, the username, and identity attributes, plus the error returned when a read-only path is marked as writable through the Flow Extension Management API. The read-only row is identified by the Read-Only badge shown in the Console rather than by specific attributes, since the list is resolved from server configuration.

flow-extension-external-service.md describes the same rules from the endpoint author's side: the intro notes one service can back more than one flow, flowType lists its three values, the allowedOperations guidance explains that the whitelist reflects the current flow, and the operation validation list drops the identity attribute clause in favour of the current rules.

Configuration reference

configuration_catalog.yaml adds an actions.types.flow_extension section documenting non_modifiable_paths, alongside the existing actions section and tagged configure-actions. This is IS-only, so the property is documented in a file that Asgardeo does not render; the configuration guide carries a single gated pointer to it.

API contracts

Both copies of flow-extension-action-v1.yaml gain a flowType enum of the three flow types and note that the username is sent only in the registration flow. The Flow Extension Management API documents that non-modifiable paths on accessConfig.modify are rejected.

Media

Copies flow-extension-encryption-certificate.mp4, flow-extension-encryption-settings.png, and flow-extension-encryption-toggles.png into the IS next asset tree, matching the existing convention where each product tree carries its own identical copy. Removes the stale TODO next to the encryption toggles image, which the image already satisfies; the certificate management TODO is left in place, as that screenshot shows the upload state rather than a configured certificate.

Verification

• mkdocs build for both en/identity-server/next and en/asgardeo completes with no errors.
• The IS-only configuration note renders on IS and is absent from Asgardeo, with no unrendered template syntax on either.
• All 32 asset references across en/includes/guides/flows/ resolve in both trees, and a scan of the built IS next site reports no broken asset references on any Flows page.
• All four images and the video on the configuration page decode in the browser at their source dimensions.
• Vale reports no errors, warnings, or suggestions on the changed pages.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Flow extension API schemas now support three flow types. Configuration and guides document protected write paths, attribute access behavior, reusable external service endpoints, and operation validation rules.

Flow extension updates

Layer / File(s)	Summary
Expand flow extension API contracts en/asgardeo/docs/references/.../flow-extension-action-v1.yaml, en/identity-server/next/docs/references/.../flow-extension-action-v1.yaml, en/includes/guides/flows/flow-extensions/index.md	The API definitions and guide now identify REGISTRATION, PASSWORD_RECOVERY, and INVITED_USER_REGISTRATION as supported flow types.
Document access controls and protected paths en/asgardeo/docs/apis/restapis/flow-extension-management.yaml, en/identity-server/next/docs/_data/configuration_catalog.yaml, en/includes/guides/flows/flow-extensions/index.md, en/includes/guides/flows/flow-extension-configuration.md	Access declarations, protected non-modifiable paths, read/write enforcement, attribute exceptions, and the related configuration property are documented.
Clarify external service routing and validation en/includes/guides/flows/flow-extension-external-service.md	The guide explains routing multiple flows through one endpoint and separates attribute write restrictions from claim URI validation issues.

Suggested labels: Team/Authentication & registration, Team/Identity Server Core

Suggested reviewers: pavindulakshan

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: documenting flow extension attribute access and supported flows.
Description check	✅ Passed	Mostly complete with Purpose, Implementation, and Verification, but Related PRs, Test environment, and Security checks sections are missing.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@en/asgardeo/docs/apis/restapis/flow-extension-management.yaml`:
- Around line 584-588: Update the modify property description in the
flow-extension management API schema to clarify that configuring a
non-modifiable path is rejected with a 400 response, while runtime response
operations targeting such paths are skipped and remaining operations continue.

In `@en/includes/guides/flows/flow-extension-configuration.md`:
- Around line 85-91: Update the introductory sentence before the access table to
avoid calling all listed rows “exceptions.” Use wording that accurately covers
unavailable controls alongside attributes with flow-specific behavior or usage
guidance, while leaving the table entries unchanged.
- Around line 95-97: Update the note associated with
actions.types.flow_extension.non_modifiable_paths to use active voice and state
precisely that this property defines the paths that cannot be modified, rather
than saying it sets read-only attributes. Preserve the existing
configuration-catalog reference.

In `@en/includes/guides/flows/flow-extensions/index.md`:
- Line 37: Update the sentence in the flow extensions guide to replace the vague
phrase “a small number of attributes” with “some attributes” or the contract’s
exact attribute count, while leaving the surrounding explanation and link
unchanged.

🪄 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 Plus

Run ID: 49a01d61-c5d7-4969-bd3e-eff92b76f856

📥 Commits

Reviewing files that changed from the base of the PR and between 7d073b0 and bdffed6.

⛔ Files ignored due to path filters (3)

• en/identity-server/next/docs/assets/img/guides/flows/flow-extension-encryption-certificate.mp4 is excluded by !**/*.mp4
• en/identity-server/next/docs/assets/img/guides/flows/flow-extension-encryption-settings.png is excluded by !**/*.png
• en/identity-server/next/docs/assets/img/guides/flows/flow-extension-encryption-toggles.png is excluded by !**/*.png

📒 Files selected for processing (7)

• en/asgardeo/docs/apis/restapis/flow-extension-management.yaml
• en/asgardeo/docs/references/service-extensions/in-flow-extensions/flow-extension/api/flow-extension-action-v1.yaml
• en/identity-server/next/docs/_data/configuration_catalog.yaml
• en/identity-server/next/docs/references/service-extensions/in-flow-extensions/flow-extension/api/flow-extension-action-v1.yaml
• en/includes/guides/flows/flow-extension-configuration.md
• en/includes/guides/flows/flow-extension-external-service.md
• en/includes/guides/flows/flow-extensions/index.md