Conversation
WalkthroughAdds documentation, Redoc wrappers, and OpenAPI 3.0.1 specifications for a new "Pre-issue ID token action" service extension, plus sample responses and navigation updates across Asgardeo and Identity Server docs. Changes
Sequence Diagram(s)sequenceDiagram
participant Product
participant IdentityServer
participant ActionService
participant TokenStore
Product->>IdentityServer: Token issuance request (authorization flow)
IdentityServer->>ActionService: POST / (pre-issue ID token event payload)
activate ActionService
ActionService-->>IdentityServer: 200 OK with actionStatus + operations (add/replace/remove)
deactivate ActionService
IdentityServer->>TokenStore: Apply operations to ID token claims / compute expires_in
TokenStore-->>IdentityServer: Updated ID token payload
IdentityServer-->>Product: Issue ID token including modified claims
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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: 2
🤖 Fix all issues with AI agents
In
`@en/asgardeo/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`:
- Around line 116-120: The Request schema currently has its description placed
at the schema level instead of on the additionalParams property; move the
description string from the Request schema down into the additionalParams
property definition (i.e., attach the description to the additionalParams
property object that defines type: array and items: $ref:
'#/components/schemas/RequestParams'), removing the misplaced top-level
description so the Request schema no longer carries that text.
In
`@en/identity-server/next/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`:
- Around line 116-120: The description for the property additionalParams is
currently placed at the Request schema level; move that description string so it
is a child of the additionalParams property (i.e., inside the additionalParams
node alongside type/items) instead of as a sibling to type/properties in the
Request schema; update the YAML under the Request schema so additionalParams
includes the description (leave Request.description blank or a Request-level
description if needed) to ensure the text applies to additionalParams.
🧹 Nitpick comments (2)
en/includes/guides/service-extensions/pre-flow-extensions/pre-issue-id-token-action.md (1)
11-11: Consider clarifying "string type arrays" terminology.The phrase "string type arrays" could be more clearly expressed as "string arrays" or "arrays of strings" for better readability.
📝 Suggested wording improvement
-- Add custom claims. You can use string, number, boolean, and string type arrays. +- Add custom claims. You can use string, number, boolean, and string array types.en/identity-server/next/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml (1)
519-525: BasicAuth scheme allows cleartext credentials over an unencrypted channel.The
BasicAuthsecurity scheme transmits credentials in Base64 (effectively cleartext). While this contract is implemented by an external service (whose transport is outside your control), consider documenting that HTTPS is required when usingBasicAuth. Alternatively, the spec could be tightened by not offeringBasicAuthas a top-level option and favoringBearerAuthorApiKeyAuth.This is flagged by Checkov CKV_OPENAPI_3, and is a reasonable security posture improvement for documentation that will be used as a reference by implementers.
| additionalParams: | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/RequestParams' | ||
| description: Any additional parameters included in the ID token request. These may be custom parameters defined by the client or necessary for specific flows. |
There was a problem hiding this comment.
Same misplaced additionalParams description as in the IS variant.
Same issue as in the IS YAML: line 120's description is at the Request schema level instead of under the additionalParams property.
🔧 Proposed fix
additionalParams:
type: array
+ description: Any additional parameters included in the ID token request. These may be custom parameters defined by the client or necessary for specific flows.
items:
$ref: '#/components/schemas/RequestParams'
- description: Any additional parameters included in the ID token request. These may be custom parameters defined by the client or necessary for specific flows.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| additionalParams: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/RequestParams' | |
| description: Any additional parameters included in the ID token request. These may be custom parameters defined by the client or necessary for specific flows. | |
| additionalParams: | |
| type: array | |
| description: Any additional parameters included in the ID token request. These may be custom parameters defined by the client or necessary for specific flows. | |
| items: | |
| $ref: '#/components/schemas/RequestParams' |
🤖 Prompt for AI Agents
In
`@en/asgardeo/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`
around lines 116 - 120, The Request schema currently has its description placed
at the schema level instead of on the additionalParams property; move the
description string from the Request schema down into the additionalParams
property definition (i.e., attach the description to the additionalParams
property object that defines type: array and items: $ref:
'#/components/schemas/RequestParams'), removing the misplaced top-level
description so the Request schema no longer carries that text.
| additionalParams: | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/RequestParams' | ||
| description: Any additional parameters included in the ID token request. These may be custom parameters defined by the client or necessary for specific flows. |
There was a problem hiding this comment.
Misplaced description — additionalParams description is applied to the Request schema.
The description on line 120 is indented at the Request schema level (sibling of type and properties), so OpenAPI tooling will treat it as the description of the entire Request object rather than the additionalParams property. The text ("Any additional parameters…") clearly belongs to additionalParams.
🔧 Proposed fix
additionalParams:
type: array
+ description: Any additional parameters included in the ID token request. These may be custom parameters defined by the client or necessary for specific flows.
items:
$ref: '#/components/schemas/RequestParams'
- description: Any additional parameters included in the ID token request. These may be custom parameters defined by the client or necessary for specific flows.🤖 Prompt for AI Agents
In
`@en/identity-server/next/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`
around lines 116 - 120, The description for the property additionalParams is
currently placed at the Request schema level; move that description string so it
is a child of the additionalParams property (i.e., inside the additionalParams
node alongside type/items) instead of as a sibling to type/properties in the
Request schema; update the YAML under the Request schema so additionalParams
includes the description (leave Request.description blank or a Request-level
description if needed) to ensure the text applies to additionalParams.
There was a problem hiding this comment.
Pull request overview
This pull request adds comprehensive documentation for the "Pre-issue ID token action" feature to both Asgardeo and Identity Server Next documentation. The documentation helps developers understand how to configure and implement custom logic before ID token issuance.
Changes:
- Added new guide and reference documentation describing the pre-issue ID token action feature, including its purpose, usage, API contract, and sample responses
- Updated navigation files to include the new documentation pages
- Added link in the "Setting up actions" guide to reference the pre-issue ID token action's support for conditional invocation
Reviewed changes
Copilot reviewed 14 out of 18 changed files in this pull request and generated 24 comments.
Show a summary per file
| File | Description |
|---|---|
en/includes/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/sample-success-responses.md |
New sample success responses showing various ID token modification scenarios |
en/includes/guides/service-extensions/pre-flow-extensions/pre-issue-id-token-action.md |
Main guide describing the pre-issue ID token action feature |
en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-issue-id-token-action-v1.x.md |
Version 1.x specific API contract details and implementation guidance |
en/includes/guides/service-extensions/pre-flow-extensions/setting-up-actions.md |
Updated to reference pre-issue ID token action in conditional invocation section |
en/asgardeo/mkdocs.yml |
Navigation updates for Asgardeo docs |
en/identity-server/next/mkdocs.yml |
Navigation updates for Identity Server Next docs |
en/asgardeo/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml |
OpenAPI specification for Asgardeo |
en/identity-server/next/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml |
OpenAPI specification for Identity Server Next |
Multiple .md files in product-specific directories |
Include statements referencing the shared content |
en/asgardeo/docs/assets/img/guides/actions/pre-issue-id-token-action-*.png |
Screenshot images for UI examples |
|
|
||
| When adding a new claim, you need to specify the index where the claim should be inserted. The specified index must not be greater than the number of elements currently in the array. If you want to add the claim to the end of the array, you can use the <code>-</code> character as the index. | ||
|
|
||
| Only string, number, boolean, and string type arrays are allowed to be added to the ID token claims. |
There was a problem hiding this comment.
The word "are" violates the documentation guideline. Change "Only string, number, boolean, and string type arrays are allowed to be added" to "You can add string, number, boolean, and string type arrays".
| </tr> | ||
| </tbody> | ||
| </table> | ||
| <p>OIDC claims are any additional claims configured in the application to be included in the ID token. These claims are based on the OIDC standard and may include user profile information such as email, given_name, or custom claims specific to the application.</p> |
There was a problem hiding this comment.
Avoid the word "are". Change "OIDC claims are any additional claims" to "OIDC claims include any additional claims".
| </tr> | ||
| <tr class="even"> | ||
| <td>event.organization</td> | ||
| <td><p>This property refers to the organization context under which the token is being issued.</p></td> |
There was a problem hiding this comment.
Avoid passive voice with "is being". Change "the token is being issued" to "{{product_name}} issues the token" or use active construction.
| </tr> | ||
| <tr class="odd"> | ||
| <td>event.userStore</td> | ||
| <td><p>This property indicates the user store in which the user's data is being managed.</p></td> |
There was a problem hiding this comment.
Avoid passive voice with "is being". Change "the user's data is being managed" to "{{product_name}} manages the user's data" or use active construction.
|
|
||
| Additionally, your external service can change any OIDC claims incorporated into the ID token. | ||
|
|
||
| Here is the example of an allowedOperations object in a request formatted as a JSON payload: |
There was a problem hiding this comment.
Change "Here is the example" to "Here's an example" to make it more concise and avoid the word "is".
| </tr> | ||
| <tr> | ||
| <td>scopes</td> | ||
| <td>The scopes present in the incoming token request (OAuth2/OIDC hybrid flow). The <code>openid</code> scope must be present to obtain an ID token. Some scopes control what is included in the ID token (for example, <code>profile</code> for profile-related claims and <code>address</code> for address-related claims). Other scopes appear here because they are associated with permissions on the access token issued together with the ID token.</td> |
There was a problem hiding this comment.
Avoid using "are associated". Rewrite the sentence to use active voice. For example: "Other scopes appear here because the access token issued with the ID token uses them for permissions".
|
|
||
| The <code>allowedOperations</code> property in the context of the pre-issue ID token action defines the set of operations that your external service can perform on the ID token's claims. This property specifically relates to the <code>event.idToken</code> property and outlines which attributes let your external service add extra properties, replace values, or remove attributes. The <code>allowedOperations</code> use JSON Patch modification semantics. | ||
|
|
||
| In the context of the pre-issue ID token action, your external service can change certain claims related to the ID token, such as audience (aud), ID token validity (expires_in), and other claims that influence what is included in the token. |
There was a problem hiding this comment.
This sentence exceeds the 25-word limit (33 words). Break it into smaller sentences. For example: "Your external service can change certain claims related to the ID token. These include audience (aud), ID token validity (expires_in), and other claims that influence what the token includes."
| </tr> | ||
| <tr> | ||
| <td>scopes</td> | ||
| <td>The scopes present in the incoming token request (OAuth2/OIDC hybrid flow). The <code>openid</code> scope must be present to obtain an ID token. Some scopes control what is included in the ID token (for example, <code>profile</code> for profile-related claims and <code>address</code> for address-related claims). Other scopes appear here because they are associated with permissions on the access token issued together with the ID token.</td> |
There was a problem hiding this comment.
This description exceeds the 25-word limit (45 words total). Break it into smaller sentences. For example: "The scopes present in the incoming token request (OAuth2/OIDC hybrid flow). The openid scope must be present to obtain an ID token. Some scopes control what the ID token includes. For example, profile controls profile-related claims and address controls address-related claims."
|
|
||
| Configure a pre-issue ID token action with your external service endpoint. | ||
| {{product_name}} calls your service and waits for a response when an ID token is about to be issued. | ||
| Upon receiving the response, {{product_name}} applies any modifications to the ID token as specified in the response and then continues with the flow. |
There was a problem hiding this comment.
This sentence exceeds the 25-word limit (27 words). Break it into smaller sentences. For example: "Upon receiving the response, {{product_name}} applies any modifications to the ID token. It uses the specifications from the response. Then it continues with the flow."
| - equals | ||
| - not equals | ||
|
|
||
| You can combine conditions using logical **AND** and **OR** operators. Conditions in the same group are combined with AND; separate groups are combined with OR. This gives you precise control over when to invoke the pre-issue ID token action. |
There was a problem hiding this comment.
This sentence exceeds the 25-word limit (28 words total). Break it into smaller sentences. For example: "Conditions in the same group use AND logic. Separate groups use OR logic. This gives you precise control over when to invoke the pre-issue ID token action."
There was a problem hiding this comment.
Upload identity server screen shots for IS docs
There was a problem hiding this comment.
This has a black top margin. Better if you can crop that part and re upload the image.
There was a problem hiding this comment.
Actionable comments posted: 11
🤖 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/asgardeo/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`:
- Around line 157-159: The property-level descriptions next to $ref for the
organization properties are ignored by OAS 3.0.1; update each affected property
(the organization properties shown in the diff) to use an allOf wrapper that
contains the $ref and a separate object with the description (i.e. replace
"organization: $ref: '#/components/schemas/Organization' description: ..." with
"organization: allOf: - $ref: '#/components/schemas/Organization' - type: object
description: 'Refers to the organization...'" so the description is preserved by
tooling).
- Around line 280-284: The AllowedOperations example uses an inconsistent path
`/idToken/claims/-`; update the add operation example under AllowedOperations so
its paths entry matches the addOperation schema and request samples by using
`/idToken/claims/` (remove the trailing `-`), ensuring the permission pattern
aligns with the addOperation example; update the example block containing "op:
add" and "paths:" to list `/idToken/claims/` instead of `/idToken/claims/-`.
- Around line 563-566: The OpenAPI spec defines a BasicAuth security scheme
(BasicAuth) but lacks a root-level servers entry enforcing TLS, which triggers
CKV_OPENAPI_3; add a top-level servers array with at least one HTTPS URL (for
example "https://api.example.com" or your real API domain) to make TLS explicit
and satisfy the security check, ensuring the servers block sits at the document
root so the BasicAuth scheme is served only over HTTPS.
In
`@en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-issue-id-token-action-v1.x.md`:
- Line 150: The table cell text "The hash of the state value. Used when the
state parameter present in the authentication request." is missing the verb and
reads awkwardly; update the second sentence to a correct, active phrasing such
as "Used when the state parameter is present in the authentication request."
(locate the fragment "The hash of the state value." / "Used when the state
parameter present in the authentication request." and replace the second
sentence accordingly).
- Around line 422-426: The table row starting with <tr class="even"> for the
"operations" cell has an unclosed <p> and <td>; close both tags before the </tr>
to produce well-formed HTML (i.e., add a closing </p> and </td> for the cell
containing the operations description in the <tr class="even"> row).
- Around line 558-562: Update the two note admonitions to active,
grammatically-correct sentences: replace the first note sentence that currently
reads "The errorMessage and errorDescription ... doesn't directly include in the
error response sent back to the application." with "{{product_name}} does not
map the `errorMessage` and `errorDescription` values from the external service's
`ERROR` response to the error response sent to the application." and replace the
second note sentence "In the OIDC hybrid flow, both `FAILED` and `ERROR`
responses from your external service treated as server errors." with
"{{product_name}} treats both `FAILED` and `ERROR` responses from your external
service as server errors." Ensure you update the two note blocks in
pre-issue-id-token-action-v1.x.md exactly where those admonitions appear.
- Line 70: Replace the grammatically incorrect phrase "The `openid` scope must
present to get an ID token" in the pre-issue-id-token-action-v1.x doc text with
a corrected active-voice sentence such as "The `openid` scope must be present to
obtain an ID token" (or "is required to obtain an ID token"); update the
sentence in the same <td> paragraph that explains OIDC scopes (mentions
`profile`, `address`) so the doc reads clearly and uses "be present" or "is
required" instead of "must present".
In
`@en/includes/guides/service-extensions/pre-flow-extensions/pre-issue-id-token-action.md`:
- Line 11: Update the wording and heading capitalization: change the phrase
"string type array" to "string-type array" in the sentence that lists allowed
claim types, and rename the heading "## How pre-issue id token action works" to
"## How pre-issue ID token action works" so "ID" matches other occurrences;
locate these strings in the pre-issue-id-token-action.md content and apply the
two exact textual edits.
In
`@en/includes/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/sample-success-responses.md`:
- Line 11: The sentence "You can add only string, number, boolean, string type
arrays, and custom objects to the ID token claims." uses "string type arrays"
without the required hyphen; update that phrase to "string-type arrays" so the
compound modifier is correct, leaving the rest of the sentence unchanged and
preserving the list order in the file's sample-success-responses.md.
- Line 133: The phrase "an existing OIDC claims" has an article/noun number
mismatch; update the sentence in the sample success response text to use the
correct plurality by removing the article or making the noun singular—e.g.,
change "You can remove an existing OIDC claims from the ID token." to "You can
remove existing OIDC claims from the ID token." (refer to the sentence
containing "an existing OIDC claims" / "claims" in the sample-success-responses
content).
- Around line 80-94: The example response uses an invalid JSON Patch operation:
change the operation or path so it conforms to RFC 6902; either (A) if this
behavior is a WSO2 extension, add a clarifying note that the guide’s JSON Patch
examples allow using "-" with "replace" (i.e., document the extension) and keep
the line with "op": "replace" and "path": "/idToken/claims/aud/-", or (B) make
the example RFC-compliant by replacing the "-" with a concrete index (e.g.,
change "path": "/idToken/claims/aud/-" to "path": "/idToken/claims/aud/0");
update the surrounding text to match the chosen approach and ensure the JSON
snippet and the earlier RFC 6902 reference are consistent with that decision.
---
Duplicate comments:
In
`@en/asgardeo/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`:
- Around line 116-120: The description text for additionalParams is currently
placed as a sibling to the Request schema fields causing it to apply to the
whole Request; move the description so it is a child of the additionalParams
property (i.e., under additionalParams: ... description: "Any additional
parameters..." ) in the Request schema so the description is scoped to
additionalParams; update the YAML for the Request schema where the
additionalParams property is defined to place the description directly under
additionalParams (referencing the additionalParams property and the Request
schema in the pre-issue-id-token-action-v1.0.yaml).
In
`@en/identity-server/next/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`:
- Around line 116-120: The Request schema's description text is currently
attached to the entire Request object instead of the additionalParams property;
remove the misplaced description from the Request schema and add it as the
description for the additionalParams property (the array under property
additionalParams) so that additionalParams has the description "Any additional
parameters included in the ID token request. These may be custom parameters
defined by the client or necessary for specific flows."; ensure the
additionalParams items still reference RequestParams via $ref to
'#/components/schemas/RequestParams'.
- Around line 280-284: The example for the add operation is inconsistent: change
the paths array entry that reads "/idToken/claims/-" to "/idToken/claims/" so
the "op: add" example under the example block uses "/idToken/claims/" (matching
the addOperation schema example and v1.x guide); update the paths list where
"op: add" and "paths:" appear and ensure the other path entry
"/idToken/claims/aud/" remains unchanged.
- Around line 563-566: Add a top-level servers block to this OpenAPI document to
require HTTPS (so credentials aren’t sent in cleartext); specifically add a
"servers" array (symbol: servers) with an HTTPS URL (e.g. https://{host} with a
host variable or your production hostname) and descriptive variables as needed,
and ensure no plain "http://" server entries remain; keep the existing security
schemes (BasicAuth, BearerAuth) but rely on the new servers block to enforce
TLS.
- Around line 157-159: The schema property descriptions for User.organization
and User.accessingOrganization are ignored because OpenAPI ignores sibling
description when using $ref; update each property to use an allOf wrapper that
contains the $ref plus a local description (e.g., replace the direct "$ref:
'#/components/schemas/Organization'" entries for the User.organization and
User.accessingOrganization properties with an allOf: - first element being the
$ref to '#/components/schemas/Organization' and - second element an inline
object with the desired description) so the description is preserved in the
generated OAS output.
| organization: | ||
| $ref: '#/components/schemas/Organization' | ||
| description: Refers to the organization to which the user belongs. |
There was a problem hiding this comment.
description alongside $ref is silently ignored in OpenAPI 3.0.1.
Per the JSON Reference specification that OAS 3.0 builds on, all sibling properties of $ref SHALL be ignored. The property-level descriptions at line 159 (Refers to the organization to which the user belongs.) and line 170 (Refers to the organization to which the user is accessing.) are dropped by all conforming tooling — consumers will see only the Organization schema's top-level description instead.
Wrap with allOf to attach the description properly:
🔧 Fix for both properties
- organization:
- $ref: '#/components/schemas/Organization'
- description: Refers to the organization to which the user belongs.
+ organization:
+ description: Refers to the organization to which the user belongs.
+ allOf:
+ - $ref: '#/components/schemas/Organization'- accessingOrganization:
- $ref: '#/components/schemas/Organization'
- description: Refers to the organization to which the user is accessing. This is only applicable for `organization_switch` grant type.
+ accessingOrganization:
+ description: Refers to the organization to which the user is accessing. This is only applicable for `organization_switch` grant type.
+ allOf:
+ - $ref: '#/components/schemas/Organization'Also applies to: 168-170
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/asgardeo/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`
around lines 157 - 159, The property-level descriptions next to $ref for the
organization properties are ignored by OAS 3.0.1; update each affected property
(the organization properties shown in the diff) to use an allOf wrapper that
contains the $ref and a separate object with the description (i.e. replace
"organization: $ref: '#/components/schemas/Organization' description: ..." with
"organization: allOf: - $ref: '#/components/schemas/Organization' - type: object
description: 'Refers to the organization...'" so the description is preserved by
tooling).
| example: | ||
| - op: add | ||
| paths: | ||
| - /idToken/claims/- | ||
| - /idToken/claims/aud/ |
There was a problem hiding this comment.
AllowedOperations add-operation example path is inconsistent with the addOperation schema example.
The AllowedOperations example (line 283) lists /idToken/claims/- for the add operation's paths, while the addOperation schema example (lines 314–316) lists /idToken/claims/ (no -). The actual request sample in the v1.x guide also uses /idToken/claims/ without -. Since allowedOperations.paths represent permitted path patterns (not specific index targets), the trailing / without - is the intended form here.
🔧 Fix
example:
- op: add
paths:
- - /idToken/claims/-
+ - /idToken/claims/
- /idToken/claims/aud/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| example: | |
| - op: add | |
| paths: | |
| - /idToken/claims/- | |
| - /idToken/claims/aud/ | |
| example: | |
| - op: add | |
| paths: | |
| - /idToken/claims/ | |
| - /idToken/claims/aud/ |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/asgardeo/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`
around lines 280 - 284, The AllowedOperations example uses an inconsistent path
`/idToken/claims/-`; update the add operation example under AllowedOperations so
its paths entry matches the addOperation schema and request samples by using
`/idToken/claims/` (remove the trailing `-`), ensuring the permission pattern
aligns with the addOperation example; update the example block containing "op:
add" and "paths:" to list `/idToken/claims/` instead of `/idToken/claims/-`.
| BasicAuth: | ||
| type: http | ||
| scheme: basic | ||
| BearerAuth: |
There was a problem hiding this comment.
BasicAuth scheme allows cleartext credentials — no HTTPS server defined.
The BasicAuth scheme transmits credentials as base64 over the wire. Since no servers block is present to mandate HTTPS, Checkov (CKV_OPENAPI_3, high severity) correctly flags this. Add a servers entry with an HTTPS URL to make TLS mandatory explicit in the spec:
🔧 Suggested addition
+servers:
+ - url: https://your-service.example.com
+ description: External service endpoint (HTTPS required)
paths:
/:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/asgardeo/docs/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/api/pre-issue-id-token-action-v1.0.yaml`
around lines 563 - 566, The OpenAPI spec defines a BasicAuth security scheme
(BasicAuth) but lacks a root-level servers entry enforcing TLS, which triggers
CKV_OPENAPI_3; add a top-level servers array with at least one HTTPS URL (for
example "https://api.example.com" or your real API domain) to make TLS explicit
and satisfy the security check, ensuring the servers block sits at the document
root so the BasicAuth scheme is served only over HTTPS.
| </tr> | ||
| <tr> | ||
| <td>scopes</td> | ||
| <td>The scopes present in the incoming token request (OAuth2/OIDC hybrid flow). The <code>openid</code> scope must present to get an ID token. OIDC scopes control the user attributes requested in the ID token (for example, <code>profile</code> for profile-related claims and <code>address</code> for address-related claims). Other OAuth2 scopes appear here because they associate with permissions on the access token issued with the ID token.</td> |
There was a problem hiding this comment.
Grammatically incomplete: "must present."
The phrase "The openid scope must present to get an ID token" is missing a verb. Suggested rewrite using active voice per documentation guidelines:
🔧 Fix
-The <code>openid</code> scope must present to get an ID token. OIDC scopes control the user attributes...
+The <code>openid</code> scope must be present to obtain an ID token. OIDC scopes control the user attributes...📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <td>The scopes present in the incoming token request (OAuth2/OIDC hybrid flow). The <code>openid</code> scope must present to get an ID token. OIDC scopes control the user attributes requested in the ID token (for example, <code>profile</code> for profile-related claims and <code>address</code> for address-related claims). Other OAuth2 scopes appear here because they associate with permissions on the access token issued with the ID token.</td> | |
| <td>The scopes present in the incoming token request (OAuth2/OIDC hybrid flow). The <code>openid</code> scope must be present to obtain an ID token. OIDC scopes control the user attributes requested in the ID token (for example, <code>profile</code> for profile-related claims and <code>address</code> for address-related claims). Other OAuth2 scopes appear here because they associate with permissions on the access token issued with the ID token.</td> |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-issue-id-token-action-v1.x.md`
at line 70, Replace the grammatically incorrect phrase "The `openid` scope must
present to get an ID token" in the pre-issue-id-token-action-v1.x doc text with
a corrected active-voice sentence such as "The `openid` scope must be present to
obtain an ID token" (or "is required to obtain an ID token"); update the
sentence in the same <td> paragraph that explains OIDC scopes (mentions
`profile`, `address`) so the doc reads clearly and uses "be present" or "is
required" instead of "must present".
| </tr> | ||
| <tr> | ||
| <td>s_hash</td> | ||
| <td>The hash of the state value. Used when the state parameter present in the authentication request.</td> |
There was a problem hiding this comment.
Incomplete sentence: "Used when the state parameter present."
Missing the verb "is"; also a passive construction. Suggested fix:
🔧 Fix
-<td>The hash of the state value. Used when the state parameter present in the authentication request.</td>
+<td>The hash of the state value. Included when the authentication request contains the state parameter.</td>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <td>The hash of the state value. Used when the state parameter present in the authentication request.</td> | |
| <td>The hash of the state value. Included when the authentication request contains the state parameter.</td> |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-issue-id-token-action-v1.x.md`
at line 150, The table cell text "The hash of the state value. Used when the
state parameter present in the authentication request." is missing the verb and
reads awkwardly; update the second sentence to a correct, active phrasing such
as "Used when the state parameter is present in the authentication request."
(locate the fragment "The hash of the state value." / "Used when the state
parameter present in the authentication request." and replace the second
sentence accordingly).
| !!! note | ||
| The <code>errorMessage</code> and <code>errorDescription</code> from the external service's <code>ERROR</code> response doesn't directly include in the error response sent back to the application. | ||
|
|
||
| !!! note | ||
| In the OIDC hybrid flow, both <code>FAILED</code> and <code>ERROR</code> responses from your external service treated as server errors. |
There was a problem hiding this comment.
Plural–singular verb mismatch and missing verb in two note admonitions.
- Line 559: "errorMessage and errorDescription" is a plural subject — "doesn't" should be "don't". Additionally, "doesn't directly include in" is grammatically awkward. Rewrite in active voice per documentation guidelines: "{{product_name}} does not map the
errorMessageanderrorDescriptionvalues from the external service'sERRORresponse to the error response sent to the application." - Line 562: "responses from your external service treated as server errors" is missing a main verb and uses passive voice. Active rewrite: "{{product_name}} treats both
FAILEDandERRORresponses from your external service as server errors."
🔧 Fix
- The <code>errorMessage</code> and <code>errorDescription</code> from the external service's <code>ERROR</code> response doesn't directly include in the error response sent back to the application.
+ {{product_name}} does not map the <code>errorMessage</code> and <code>errorDescription</code> from the external service's <code>ERROR</code> response to the error response sent back to the application.- In the OIDC hybrid flow, both <code>FAILED</code> and <code>ERROR</code> responses from your external service treated as server errors.
+ In the OIDC hybrid flow, {{product_name}} treats both <code>FAILED</code> and <code>ERROR</code> responses from your external service as server errors.Based on learnings, documentation should avoid passive voice and auxiliary verbs such as 'are' and 'be'; active constructions with an explicit subject ({{product_name}}) resolve both the grammar errors and the style guidance simultaneously.
🧰 Tools
🪛 LanguageTool
[style] ~560-~560: Using many exclamation marks might seem excessive (in this case: 9 exclamation marks for a text that’s 6350 characters long)
Context: ...response sent back to the application. !!! note In the OIDC hybrid flow, both ...
(EN_EXCESSIVE_EXCLAMATION)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/includes/guides/service-extensions/pre-flow-extensions/action-versions/pre-issue-id-token-action-v1.x.md`
around lines 558 - 562, Update the two note admonitions to active,
grammatically-correct sentences: replace the first note sentence that currently
reads "The errorMessage and errorDescription ... doesn't directly include in the
error response sent back to the application." with "{{product_name}} does not
map the `errorMessage` and `errorDescription` values from the external service's
`ERROR` response to the error response sent to the application." and replace the
second note sentence "In the OIDC hybrid flow, both `FAILED` and `ERROR`
responses from your external service treated as server errors." with
"{{product_name}} treats both `FAILED` and `ERROR` responses from your external
service as server errors." Ensure you update the two note blocks in
pre-issue-id-token-action-v1.x.md exactly where those admonitions appear.
|
|
||
| - Add, change, or remove audience values. | ||
| - Change or remove user attributes incorporated into the ID token. | ||
| - Add custom claims. You can use string, number, boolean, string type array, and custom object. |
There was a problem hiding this comment.
Minor hyphenation and heading capitalization issues.
- Line 11: "string type array" should be "string-type array" (compound modifier before a noun requires a hyphen).
- Line 21: The heading
## How pre-issue id token action worksuses lowercase "id token" — should be "ID token" to match the capitalization used in lines 3, 5, and 14.
🔧 Fix
-You can use string, number, boolean, string type array, and custom object.
+You can use string, number, boolean, string-type array, and custom object.-## How pre-issue id token action works
+## How pre-issue ID token action works📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Add custom claims. You can use string, number, boolean, string type array, and custom object. | |
| - Add custom claims. You can use string, number, boolean, string-type array, and custom object. |
🧰 Tools
🪛 LanguageTool
[grammar] ~11-~11: Use a hyphen to join words.
Context: ... can use string, number, boolean, string type array, and custom object. - Update ...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/includes/guides/service-extensions/pre-flow-extensions/pre-issue-id-token-action.md`
at line 11, Update the wording and heading capitalization: change the phrase
"string type array" to "string-type array" in the sentence that lists allowed
claim types, and rename the heading "## How pre-issue id token action works" to
"## How pre-issue ID token action works" so "ID" matches other occurrences;
locate these strings in the pre-issue-id-token-action.md content and apply the
two exact textual edits.
|
|
||
| When adding a new claim, specify the index where you insert the claim. The specified index must not exceed the number of elements currently in the array. To add the claim to the end of the array, use the <code>-</code> character as the index. | ||
|
|
||
| You can add only string, number, boolean, string type arrays, and custom objects to the ID token claims. |
There was a problem hiding this comment.
"string type arrays" needs a hyphen.
Same issue as in the guide doc. string-type arrays is the correct form for a compound modifier.
🔧 Fix
-You can add only string, number, boolean, string type arrays, and custom objects to the ID token claims.
+You can add only string, number, boolean, string-type arrays, and custom objects to the ID token claims.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| You can add only string, number, boolean, string type arrays, and custom objects to the ID token claims. | |
| You can add only string, number, boolean, string-type arrays, and custom objects to the ID token claims. |
🧰 Tools
🪛 LanguageTool
[grammar] ~11-~11: Use a hyphen to join words.
Context: ...add only string, number, boolean, string type arrays, and custom objects to the I...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/includes/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/sample-success-responses.md`
at line 11, The sentence "You can add only string, number, boolean, string type
arrays, and custom objects to the ID token claims." uses "string type arrays"
without the required hyphen; update that phrase to "string-type arrays" so the
compound modifier is correct, leaving the rest of the sentence unchanged and
preserving the list order in the file's sample-success-responses.md.
| When adding, replacing, or removing an audience value, specify the index where you add, replace, or remove the audience. The specified index must not exceed the number of elements currently in the array. To add, replace, or remove the audience at the end of the array, use the <code>-</code> character as the index. | ||
|
|
||
| Refer to the example response below, which demonstrates modifying audience values: | ||
|
|
||
| ```http | ||
| HTTP/1.1 200 OK | ||
| Content-Type: application/json;charset=UTF-8 | ||
|
|
||
| { | ||
| "actionStatus": "SUCCESS", | ||
| "operations": [ | ||
| { | ||
| "op": "replace", | ||
| "path": "/idToken/claims/aud/-", | ||
| "value": "example.com" |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
RFC 6902 JSON Patch "-" token valid operations add replace remove
💡 Result:
In RFC 6902 JSON Patch, the "-" token is only defined as special when it is the final reference token in a JSON Pointer that targets an array, meaning “the position after the last element”.
Valid uses of "-"
add:path: "/arr/-"appends the"value"to the end of the array. (rfc-editor.org)moveandcopy: their"path"is applied usingaddsemantics, sopath: "/arr/-"also appends the moved/copied value. (rfc-editor.org)
Not valid (will fail)
remove,replace,test: the target location must exist, and"/arr/-"does not refer to an existing element (it refers to “past the end”), so these operations fail if"-"is used that way. (rfc-editor.org)
Note: If the parent is an object, "-" is not special—it’s just a normal member name. (rfc-editor.org)
Citations:
- 1: https://www.rfc-editor.org/rfc/rfc6902.html?utm_source=openai
- 2: https://www.rfc-editor.org/rfc/rfc6902.html?utm_source=openai
- 3: https://www.rfc-editor.org/rfc/rfc6902.html?utm_source=openai
- 4: https://www.rfc-editor.org/rfc/rfc6902.html?utm_source=openai
The example violates RFC 6902 by using - with replace.
According to RFC 6902, the - token is only valid for add, move, and copy operations. For replace and remove, the target location must exist, and - refers to the position past the end of the array (which does not exist). The example at line 93 shows "op": "replace", "path": "/idToken/claims/aud/-", which contradicts the RFC 6902 reference claimed in the v1.x guide (line 424).
Either:
- Qualify the RFC 6902 reference to clarify that this is a custom WSO2 extension (e.g., "follows JSON Patch semantics with an extension that permits
-forreplace"), or - Use a concrete array index in the
replaceexample (e.g.,/idToken/claims/aud/0).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/includes/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/sample-success-responses.md`
around lines 80 - 94, The example response uses an invalid JSON Patch operation:
change the operation or path so it conforms to RFC 6902; either (A) if this
behavior is a WSO2 extension, add a clarifying note that the guide’s JSON Patch
examples allow using "-" with "replace" (i.e., document the extension) and keep
the line with "op": "replace" and "path": "/idToken/claims/aud/-", or (B) make
the example RFC-compliant by replacing the "-" with a concrete index (e.g.,
change "path": "/idToken/claims/aud/-" to "path": "/idToken/claims/aud/0");
update the surrounding text to match the chosen approach and ensure the JSON
snippet and the earlier RFC 6902 reference are consistent with that decision.
|
|
||
| ## Removing an existing OIDC claim | ||
|
|
||
| You can remove an existing OIDC claims from the ID token. For array-type claims such as <code>aud</code>, specify the index of the value to remove. Refer to the example response below, which demonstrates removing a claim: |
There was a problem hiding this comment.
Article–noun mismatch: "an existing OIDC claims."
claims is plural; the indefinite article an applies only to a singular noun. Drop the article.
🔧 Fix
-You can remove an existing OIDC claims from the ID token.
+You can remove existing OIDC claims from the ID token.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| You can remove an existing OIDC claims from the ID token. For array-type claims such as <code>aud</code>, specify the index of the value to remove. Refer to the example response below, which demonstrates removing a claim: | |
| You can remove existing OIDC claims from the ID token. For array-type claims such as <code>aud</code>, specify the index of the value to remove. Refer to the example response below, which demonstrates removing a claim: |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/includes/references/service-extensions/pre-flow-extensions/pre-issue-id-token-action/sample-success-responses.md`
at line 133, The phrase "an existing OIDC claims" has an article/noun number
mismatch; update the sentence in the sample success response text to use the
correct plurality by removing the article or making the noun singular—e.g.,
change "You can remove an existing OIDC claims from the ID token." to "You can
remove existing OIDC claims from the ID token." (refer to the sentence
containing "an existing OIDC claims" / "claims" in the sample-success-responses
content).
2 participants
Related Issues
This pull request adds comprehensive documentation for the "Pre-issue ID token action" feature in both the Asgardeo and Identity Server Next documentation sets. It introduces new guide and reference pages, sample success responses, and updates navigation to help users discover and understand how to use and implement pre-issue ID token actions.
Key changes include:
Documentation Content Additions:
pre-issue-id-token-action.md) describing the purpose, usage, and supported scenarios for the pre-issue ID token action, including details on modifying ID token claims and validity, and notes on applicability and supported grant types.Reference Documentation:
Navigation and Linking Updates:
mkdocs.ymlfiles to include the new guide and reference pages for the pre-issue ID token action, making them accessible from the sidebar. [1] [2] [3] [4]Content Inclusion in Product Docs:
{% include %}statements for content reuse and consistency. [1] [2]These changes collectively provide a clear, discoverable, and thorough documentation experience for users implementing or learning about the pre-issue ID token action feature.
Summary by CodeRabbit
New Features
Documentation