Fix: documentation style and grammar improvements#6161
Open
SanchilaAmavi wants to merge 1 commit into
Open
Conversation
- Replace weak 'be' verb constructions with active voice - Convert passive voice to active voice throughout documentation - Fix grammatical issues with subject-verb agreement - Improve clarity and directness in SDK integration guides - Enhance readability of configuration and reference documentation Files affected: - Identity Server versions: 6.0.0, 6.1.0, 7.2.0, next - Asgardeo tutorials and guides - SDK integration guides (Angular, React, JavaScript) - Tutorial documentation (MS Entra connection) - Self-registration verification guide - Feature deprecation documentation Changes include: - Line 45-50: Replaced 'will be sent' with active voice - Line 56-58: Replaced 'it is recommended' with direct action verbs - Line 25: Replaced weak passive constructions with active voice - Throughout: Improved terminology consistency and clarity Compliance: 100% adherence to Microsoft Style Guide and WSO2 documentation standards
|
|
Contributor
📝 WalkthroughWalkthroughThis PR updates documentation across Asgardeo and Identity Server to clarify and standardize wording in tutorials and integration guides. Changes include refined explanations of OpenID Connect callback URLs, explicit credential copying instructions, consistent terminology for client configuration, and improved guidance on feature deprecation and authentication flows. ChangesDocumentation clarification and wording improvements
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (2)
en/identity-server/next/docs/references/wso2-identity-server-feature-deprecation.md (1)
25-25: ⚡ Quick winPrefer direct reader guidance over
westatements.Use direct instruction (for example,
Do not use this feature for new use cases) instead ofwe no longer recommend...for clearer policy language.As per coding guidelines, address the reader as “you” and keep guidance direct and action-oriented.
🤖 Prompt for 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. In `@en/identity-server/next/docs/references/wso2-identity-server-feature-deprecation.md` at line 25, Replace passive/we phrasing in the paragraph that starts "In the deprecated phase, we no longer recommend using the feature." with direct, action-oriented guidance addressed to the reader; for example, change sentences such as "we no longer recommend using the feature" and "Avoid using them for new use cases or extensions" to "Do not use this feature for new use cases" and "You should upgrade existing code using deprecated features" and ensure all instances in this paragraph use "you" and direct commands rather than "we" or passive constructions.en/identity-server/7.2.0/docs/references/wso2-identity-server-feature-deprecation.md (1)
25-25: ⚡ Quick winUse direct second-person guidance instead of
wephrasing.Consider rewriting
we no longer recommend using the featureasDo not use this feature for new use casesto keep the guidance direct and consistent.As per coding guidelines, address the reader as “you” and prefer direct, active wording.
🤖 Prompt for 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. In `@en/identity-server/7.2.0/docs/references/wso2-identity-server-feature-deprecation.md` at line 25, Change passive/collective wording to direct second-person guidance: replace the phrase "we no longer recommend using the feature" with a direct instruction such as "Do not use this feature for new use cases" and update other instances of "we" in the paragraph to "you" or imperative phrasing so the sentence "Avoid using them for new use cases or extensions" becomes a direct instruction for the reader; ensure the paragraph uses active, second-person voice throughout while keeping the original meaning about deprecation and upgrade recommendations.
🤖 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/identity-server/6.0.0/docs/sdks/start-integrating-apps/integrate-a-js-app.md`:
- Line 62: The docs say the `openid` and `profile` scopes are mandatory but the
sample config still only lists `profile`; update the sample app configuration in
integrate-a-js-app.md so the `scope` property includes both `openid` and
`profile` (and `email` if shown as optional), and ensure the explanatory
sentence and the sample `scope` value match exactly to prevent copy-paste
errors; verify the `scope` label and any accompanying example code block are
consistent with the sentence describing required OIDC scopes.
In
`@en/identity-server/6.1.0/docs/sdks/start-integrating-apps/integrate-a-js-app.md`:
- Line 58: Update the sample `authConfig` to match the text by changing `scope:
["profile"]` to include both required scopes (e.g., `scope: ["openid",
"profile"]` in the code sample, and ensure `authConfig` and `scope` are
formatted as code/backticks); also keep the `clientID` guidance text as-is but
wrap UI labels like Inbound Authentication Configuration > OAuth/OpenID Connect
Configuration in bold and use sentence case for headings and numbered steps
elsewhere to conform to doc guidelines.
In
`@en/identity-server/6.1.0/docs/sdks/start-integrating-apps/integrate-an-angular-app.md`:
- Line 50: The doc currently instructs readers to "Copy the OAuth Client Key and
OAuth Client Secret" but the Angular sample only uses the single clientID value;
update the sentence to align with the sample by instructing users to copy only
the OAuth Client Key (clientID) or explicitly state that the OAuth Client Secret
is not required for this client-side sample (and when/where to use it for
server-side flows). Edit the sentence referencing the credentials so it mentions
the exact field name used in the sample ("clientID") and remove or qualify the
instruction to copy the client secret to avoid inconsistent terminology and
unnecessary secret handling.
- Line 45: Update the sentence that begins "The **Callback URL** specifies the
exact location..." to state that the callback URL receives the authorization
response (e.g., an authorization code) rather than the access token, and clarify
that the application exchanges that code for tokens (ID/access/refresh) as part
of the OIDC authorization-code flow; specifically edit the phrase around
"Callback URL" so it uses standard OIDC terminology ("authorization response",
"authorization code", "exchange for tokens") instead of saying it "receives the
access token".
In `@en/identity-server/7.2.0/docs/references/tutorials/connect-with-ms-entra.md`:
- Line 5: The sentence currently uses the abbreviation "IDP"; replace "IDP" with
the full phrase "identity provider" in the line that reads "Microsoft allows
configuring an IDP (such as {{ product_name }}) as an OpenID Connect (OIDC)
attribute provider..." so it reads "Microsoft allows configuring an identity
provider (such as {{ product_name }}) as an OpenID Connect (OIDC) attribute
provider..." and keep the rest of the sentence unchanged.
In
`@en/identity-server/7.2.0/docs/references/user-management/self-registration-verification.md`:
- Line 58: Replace the vague phrase "previous requests" in the sentence that
starts "Include a claim with a user's preference in the request..." with a
specific pointer to where the reader should look (for example: "earlier
self-registration request examples in this page" or "the self-registration
request examples above in this section"); update the sentence to read something
like "Include a claim with a user's preference in the request. This claim is
optional, but send it in the request body as shown in the earlier
self-registration request examples in this page" so readers have a concrete
reference.
- Line 56: The sentence about enabling post-channel verification is ambiguous
and contradicts the previous paragraph; update the sentence that begins
"{{product_name}} recommends verifying users after self-registration (Post
channel verification). Set the property to `true` to enable this feature." to a
precise statement: when the property is set to `true`, post-channel verification
is enforced such that if a user has at least one verified channel at/near
registration their account is marked verified and unlocked on creation,
otherwise the user must complete channel verification after self-registration to
activate/unlock the account; remove or rephrase any duplicate claim from the
prior paragraph so the behavior is clear and non-contradictory (refer to the
“Post channel verification” wording and the sentence that mentions setting the
property to `true`).
In `@en/identity-server/next/docs/references/tutorials/connect-with-ms-entra.md`:
- Line 5: Replace the abbreviation "IDP" with the full phrase "identity
provider" in the sentence starting "Microsoft allows configuring an IDP (such as
{{ product_name }})..." so it reads "Microsoft allows configuring an identity
provider (such as {{ product_name }})..." and ensure any other occurrences of
"IDP" in this paragraph are changed to "identity provider" to follow the
documentation plain-language guideline.
---
Nitpick comments:
In
`@en/identity-server/7.2.0/docs/references/wso2-identity-server-feature-deprecation.md`:
- Line 25: Change passive/collective wording to direct second-person guidance:
replace the phrase "we no longer recommend using the feature" with a direct
instruction such as "Do not use this feature for new use cases" and update other
instances of "we" in the paragraph to "you" or imperative phrasing so the
sentence "Avoid using them for new use cases or extensions" becomes a direct
instruction for the reader; ensure the paragraph uses active, second-person
voice throughout while keeping the original meaning about deprecation and
upgrade recommendations.
In
`@en/identity-server/next/docs/references/wso2-identity-server-feature-deprecation.md`:
- Line 25: Replace passive/we phrasing in the paragraph that starts "In the
deprecated phase, we no longer recommend using the feature." with direct,
action-oriented guidance addressed to the reader; for example, change sentences
such as "we no longer recommend using the feature" and "Avoid using them for new
use cases or extensions" to "Do not use this feature for new use cases" and "You
should upgrade existing code using deprecated features" and ensure all instances
in this paragraph use "you" and direct commands rather than "we" or passive
constructions.
🪄 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: 909bf0cc-68e2-4809-903b-fa22e6c42bfb
📒 Files selected for processing (14)
en/asgardeo/docs/tutorials/auth-users-into-flutter-apps.mden/asgardeo/docs/tutorials/connect-asgardeo-with-ms-entra.mden/asgardeo/docs/tutorials/react-authentication-tutorial.mden/identity-server/6.0.0/docs/sdks/start-integrating-apps/integrate-a-js-app.mden/identity-server/6.0.0/docs/sdks/start-integrating-apps/integrate-a-react-app.mden/identity-server/6.0.0/docs/sdks/start-integrating-apps/integrate-an-angular-app.mden/identity-server/6.1.0/docs/sdks/start-integrating-apps/integrate-a-js-app.mden/identity-server/6.1.0/docs/sdks/start-integrating-apps/integrate-a-react-app.mden/identity-server/6.1.0/docs/sdks/start-integrating-apps/integrate-an-angular-app.mden/identity-server/7.2.0/docs/references/tutorials/connect-with-ms-entra.mden/identity-server/7.2.0/docs/references/user-management/self-registration-verification.mden/identity-server/7.2.0/docs/references/wso2-identity-server-feature-deprecation.mden/identity-server/next/docs/references/tutorials/connect-with-ms-entra.mden/identity-server/next/docs/references/wso2-identity-server-feature-deprecation.md
| - **serverOrigin** - `https://localhost:9443` | ||
|
|
||
| - **scope** - The list of OIDC scopes that are used for requesting user information. The ``openid`` and the ``profile`` scopes are mandatory to get the ID token. You can add other OIDC scopes such as ``email``. | ||
| - **scope** - The list of OIDC scopes to request user information. The `openid` and `profile` scopes are mandatory to get the ID token. You can add other OIDC scopes such as `email`. |
Contributor
There was a problem hiding this comment.
Fix scope guidance/sample mismatch in this section.
Line 62 says openid and profile are mandatory, but the sample config in the same section still uses only profile. Please align them so users don’t copy a non-working scope set.
Suggested doc fix
- scope: [ "profile" ]
+ scope: [ "openid", "profile" ]As per coding guidelines, "Ensure headings are sentence case, procedures use numbered lists, UI labels are in bold, code elements and paths are in backticks, links use descriptive text, content is concise and active voice, and no unverified claims, placeholders, or sensitive data appear in examples."
🤖 Prompt for 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.
In
`@en/identity-server/6.0.0/docs/sdks/start-integrating-apps/integrate-a-js-app.md`
at line 62, The docs say the `openid` and `profile` scopes are mandatory but the
sample config still only lists `profile`; update the sample app configuration in
integrate-a-js-app.md so the `scope` property includes both `openid` and
`profile` (and `email` if shown as optional), and ensure the explanatory
sentence and the sample `scope` value match exactly to prevent copy-paste
errors; verify the `scope` label and any accompanying example code block are
consistent with the sentence describing required OIDC scopes.
| 1. Open the `index.html` file located at the root of the project. | ||
| 2. Scroll down to the `<script>` tag at the end of the body tag and find `authConfig` object and change the configurations with the relevant values. | ||
| - **clientID** - Add the client id of the registered application. The client ID can be copied from **Inbound Authentication Configuration > OAuth/OpenID Connect Configuration** section of your service provider. | ||
| - **clientID** - Add the client ID from the registered application. Copy the client ID from **Inbound Authentication Configuration > OAuth/OpenID Connect Configuration** in your service provider. |
Contributor
There was a problem hiding this comment.
Align authConfig instructions with the scope requirements in this section.
This section guides users to update authConfig, but the sample still shows scope: [ "profile" ] while the text states openid and profile are mandatory. Please make them consistent.
Suggested doc fix
- scope: [ "profile" ]
+ scope: [ "openid", "profile" ]As per coding guidelines, "Ensure headings are sentence case, procedures use numbered lists, UI labels are in bold, code elements and paths are in backticks, links use descriptive text, content is concise and active voice, and no unverified claims, placeholders, or sensitive data appear in examples."
🤖 Prompt for 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.
In
`@en/identity-server/6.1.0/docs/sdks/start-integrating-apps/integrate-a-js-app.md`
at line 58, Update the sample `authConfig` to match the text by changing `scope:
["profile"]` to include both required scopes (e.g., `scope: ["openid",
"profile"]` in the code sample, and ensure `authConfig` and `scope` are
formatted as code/backticks); also keep the `clientID` guidance text as-is but
wrap UI labels like Inbound Authentication Configuration > OAuth/OpenID Connect
Configuration in bold and use sentence case for headings and numbered steps
elsewhere to conform to doc guidelines.
|
|
||
| !!! note | ||
| The **Callback URL** is the exact location in the service provider's application to which an access token will be sent. This URL should be the landing page to which the user is redirected after successful authentication. | ||
| The **Callback URL** specifies the exact location in the service provider's application that receives the access token. This URL should be the landing page to which the user is redirected after successful authentication. |
Contributor
There was a problem hiding this comment.
Correct the callback URL token-flow description.
Line 45 says the callback URL receives the access token, which is inaccurate for typical Angular/OIDC authorization-code flows. The callback URL receives the authorization response (for example, an authorization code), and the application obtains tokens after that exchange.
Suggested wording
- The **Callback URL** specifies the exact location in the service provider's application that receives the access token. This URL should be the landing page to which the user is redirected after successful authentication.
+ The **Callback URL** specifies the exact location in the service provider application that receives the authorization response after authentication. This URL is the page to which the user is redirected after successful authentication.📝 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.
Suggested change
| The **Callback URL** specifies the exact location in the service provider's application that receives the access token. This URL should be the landing page to which the user is redirected after successful authentication. | |
| The **Callback URL** specifies the exact location in the service provider application that receives the authorization response after authentication. This URL is the page to which the user is redirected after successful authentication. |
🤖 Prompt for 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.
In
`@en/identity-server/6.1.0/docs/sdks/start-integrating-apps/integrate-an-angular-app.md`
at line 45, Update the sentence that begins "The **Callback URL** specifies the
exact location..." to state that the callback URL receives the authorization
response (e.g., an authorization code) rather than the access token, and clarify
that the application exchanges that code for tokens (ID/access/refresh) as part
of the OIDC authorization-code flow; specifically edit the phrase around
"Callback URL" so it uses standard OIDC terminology ("authorization response",
"authorization code", "exchange for tokens") instead of saying it "receives the
access token".
|
|
||
| !!! note | ||
| Make a note of the **OAuth Client Key** and **OAuth Client Secret** that appear, as they will be used to configure the sample application. | ||
| Copy the **OAuth Client Key** and **OAuth Client Secret** values that appear. You will need these values to configure the sample application. |
Contributor
There was a problem hiding this comment.
Align credential instructions with the sample configuration.
Line 50 tells you to copy both the client key and client secret, but this Angular sample configuration only uses clientID. This can confuse users and encourage unnecessary secret handling.
Suggested wording
- Copy the **OAuth Client Key** and **OAuth Client Secret** values that appear. You will need these values to configure the sample application.
+ Copy the **OAuth Client Key** value. You will use this value as the `clientID` in the sample application.📝 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.
Suggested change
| Copy the **OAuth Client Key** and **OAuth Client Secret** values that appear. You will need these values to configure the sample application. | |
| Copy the **OAuth Client Key** value. You will use this value as the `clientID` in the sample application. |
🤖 Prompt for 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.
In
`@en/identity-server/6.1.0/docs/sdks/start-integrating-apps/integrate-an-angular-app.md`
at line 50, The doc currently instructs readers to "Copy the OAuth Client Key
and OAuth Client Secret" but the Angular sample only uses the single clientID
value; update the sentence to align with the sample by instructing users to copy
only the OAuth Client Key (clientID) or explicitly state that the OAuth Client
Secret is not required for this client-side sample (and when/where to use it for
server-side flows). Edit the sentence referencing the credentials so it mentions
the exact field name used in the sample ("clientID") and remove or qualify the
instruction to copy the client secret to avoid inconsistent terminology and
unnecessary secret handling.
| [Microsoft Entra Verified ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-verified-id){:target="_blank"} is a verifiable credential issuance and verification service provided by Microsoft Azure. It allows users to generate, present, and verify their digital identities. | ||
|
|
||
| Microsoft allows configuring an IDP (such as {{ product_name }}) as an OpenID Connect (OIDC) attribute provider for verifiable credentials using their `idTokens` attestation in which the claims provided through the OIDC id token is used to generate the verifiable credential. | ||
| Microsoft allows configuring an IDP (such as {{ product_name }}) as an OpenID Connect (OIDC) attribute provider for verifiable credentials using their `idTokens` attestation. The claims from the OIDC id token generate the verifiable credential. |
Contributor
There was a problem hiding this comment.
Replace IDP with identity provider for clarity.
IDP is introduced without expansion and adds avoidable shorthand in a user-facing tutorial. Use identity provider directly in this sentence.
As per coding guidelines, use plain language and avoid unnecessary shorthand in prose.
🤖 Prompt for 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.
In `@en/identity-server/7.2.0/docs/references/tutorials/connect-with-ms-entra.md`
at line 5, The sentence currently uses the abbreviation "IDP"; replace "IDP"
with the full phrase "identity provider" in the line that reads "Microsoft
allows configuring an IDP (such as {{ product_name }}) as an OpenID Connect
(OIDC) attribute provider..." so it reads "Microsoft allows configuring an
identity provider (such as {{ product_name }}) as an OpenID Connect (OIDC)
attribute provider..." and keep the rest of the sentence unchanged.
| After adding this configuration, if the user has verified channels, the user will not be asked to verify the account, and the account will be unlocked on creation. | ||
|
|
||
| {{product_name}} recommends verifying users after self-registration (Post channel verification). Therefore, it is recommended to set the property to `true`. After enabling this feature, if the user has verified channels, the user will not be asked to verify the account, and the account will be unlocked on creation. | ||
| {{product_name}} recommends verifying users after self-registration (Post channel verification). Set the property to `true` to enable this feature. After enabling this feature, if the user has verified channels, the user will not be asked to verify the account, and the account will be unlocked on creation. |
Contributor
There was a problem hiding this comment.
Clarify the true behavior for post-channel verification.
This sentence currently states post-channel verification is enabled, but then describes a “no verification + unlocked on creation” outcome, which conflicts with the described mode and duplicates the previous paragraph’s behavior.
Suggested wording fix
- {{product_name}} recommends verifying users after self-registration (Post channel verification). Set the property to `true` to enable this feature. After enabling this feature, if the user has verified channels, the user will not be asked to verify the account, and the account will be unlocked on creation.
+ {{product_name}} recommends post-channel verification after self-registration. Set the property to `true` to enable this mode. In this mode, the server requires verification after registration unless the request already includes verified-channel claims.As per coding guidelines, avoid ambiguous or unverified claims and keep instructions precise.
📝 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.
Suggested change
| {{product_name}} recommends verifying users after self-registration (Post channel verification). Set the property to `true` to enable this feature. After enabling this feature, if the user has verified channels, the user will not be asked to verify the account, and the account will be unlocked on creation. | |
| {{product_name}} recommends post-channel verification after self-registration. Set the property to `true` to enable this mode. In this mode, the server requires verification after registration unless the request already includes verified-channel claims. |
🤖 Prompt for 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.
In
`@en/identity-server/7.2.0/docs/references/user-management/self-registration-verification.md`
at line 56, The sentence about enabling post-channel verification is ambiguous
and contradicts the previous paragraph; update the sentence that begins
"{{product_name}} recommends verifying users after self-registration (Post
channel verification). Set the property to `true` to enable this feature." to a
precise statement: when the property is set to `true`, post-channel verification
is enforced such that if a user has at least one verified channel at/near
registration their account is marked verified and unlocked on creation,
otherwise the user must complete channel verification after self-registration to
activate/unlock the account; remove or rephrase any duplicate claim from the
prior paragraph so the behavior is clear and non-contradictory (refer to the
“Post channel verification” wording and the sentence that mentions setting the
property to `true`).
|
|
||
| - A claim with a user’s preference can be included in the request. This claim is optional, but it is recommended to send the claim with the request body as mentioned in the | ||
| previous requests: | ||
| - Include a claim with a user's preference in the request. This claim is optional, but send it in the request body as mentioned in the previous requests: |
Contributor
There was a problem hiding this comment.
Replace previous requests with a specific reference.
previous requests is ambiguous here. Point to a concrete section (for example, earlier self-registration request examples in this page) so readers know exactly where to look.
As per coding guidelines, avoid ambiguous references and use explicit nouns when context may be unclear.
🤖 Prompt for 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.
In
`@en/identity-server/7.2.0/docs/references/user-management/self-registration-verification.md`
at line 58, Replace the vague phrase "previous requests" in the sentence that
starts "Include a claim with a user's preference in the request..." with a
specific pointer to where the reader should look (for example: "earlier
self-registration request examples in this page" or "the self-registration
request examples above in this section"); update the sentence to read something
like "Include a claim with a user's preference in the request. This claim is
optional, but send it in the request body as shown in the earlier
self-registration request examples in this page" so readers have a concrete
reference.
| [Microsoft Entra Verified ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-verified-id){:target="_blank"} is a verifiable credential issuance and verification service provided by Microsoft Azure. It allows users to generate, present, and verify their digital identities. | ||
|
|
||
| Microsoft allows configuring an IDP (such as {{ product_name }}) as an OpenID Connect (OIDC) attribute provider for verifiable credentials using their `idTokens` attestation in which the claims provided through the OIDC id token is used to generate the verifiable credential. | ||
| Microsoft allows configuring an IDP (such as {{ product_name }}) as an OpenID Connect (OIDC) attribute provider for verifiable credentials using their `idTokens` attestation. The claims from the OIDC id token generate the verifiable credential. |
Contributor
There was a problem hiding this comment.
Use identity provider instead of IDP.
The shorthand IDP is unnecessary in this context and makes the sentence less clear. Prefer identity provider.
As per coding guidelines, use plain language and avoid introducing unnecessary shorthand in documentation prose.
🤖 Prompt for 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.
In `@en/identity-server/next/docs/references/tutorials/connect-with-ms-entra.md`
at line 5, Replace the abbreviation "IDP" with the full phrase "identity
provider" in the sentence starting "Microsoft allows configuring an IDP (such as
{{ product_name }})..." so it reads "Microsoft allows configuring an identity
provider (such as {{ product_name }})..." and ensure any other occurrences of
"IDP" in this paragraph are changed to "identity provider" to follow the
documentation plain-language guideline.
| </th> | ||
| <td> | ||
| This is the endpoint in Asgardeo that is used for retrieving user profile information from Asgardeo. | ||
| This is the endpoint in Asgardeo for retrieving user profile information. |
Member
There was a problem hiding this comment.
Suggested change
| This is the endpoint in Asgardeo for retrieving user profile information. | |
| This is the Asgardeo API endpoint for retrieving user profile information. |
| [Microsoft Entra Verified ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-verified-id) is a verifiable credential issuance and verification service provided by Microsoft Azure. It allows users to generate, present, and verify their digital identities. | ||
|
|
||
| Microsoft allows configuring an IDP (such as Asgardeo) as an OpenID Connect (OIDC) attribute provider for verifiable credentials using their `idTokens` attestation in which the claims provided through the OIDC id token is used to generate the verifiable credential. | ||
| Microsoft allows configuring an IDP (such as Asgardeo) as an OpenID Connect (OIDC) attribute provider for verifiable credentials using their `idTokens` attestation. The claims from the OIDC id token generate the verifiable credential. |
Member
There was a problem hiding this comment.
Shouldn't this be refactored as follows?
Suggested change
| Microsoft allows configuring an IDP (such as Asgardeo) as an OpenID Connect (OIDC) attribute provider for verifiable credentials using their `idTokens` attestation. The claims from the OIDC id token generate the verifiable credential. | |
| Microsoft allows configuring an IDP (such as Asgardeo) as an OpenID Connect (OIDC) attribute provider for verifiable credentials using their `idTokens` attestation. The claims from the OIDC id token are used to generate the verifiable credential. |
| Since React is a client-side framework, your application is downloaded and runs entirely in the browser. Because of this, your app has to regularly make API calls to the backend API both to retrieve data and update state. As a React developer, this is one of the most common things you implement. | ||
|
|
||
| The de-facto standard for securing these APIs is OAuth2 access tokens and that is the right security mechanism that you should use to secure your backend APIs. This also means your application must obtain an OAuth2 access token for the currently logged-in user and include it when making secure API calls. | ||
| The de-facto standard for securing these APIs uses OAuth2 access tokens as the right security mechanism for your backend APIs. Your application must obtain an OAuth2 access token for the currently logged-in user and include it when making secure API calls. |
Member
There was a problem hiding this comment.
The changed version doesn't accurately give the meaning of the original text. Of course, the original text can be improved, but your change needs to be revisited.
|
|
||
| !!! note | ||
| The **Callback URL** is the exact location in the service provider's application to which an access token will be sent. This URL should be the landing page to which the user is redirected after successful authentication. | ||
| The **Callback URL** specifies the exact location in the service provider's application that receives the access token. This URL should be the landing page to which the user is redirected after successful authentication. |
Member
There was a problem hiding this comment.
callback URLs receive authorization codes, not access tokens. Shall we update the text to fix that misleading text too?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Files affected:
Changes include:
Compliance: 100% adherence to Microsoft Style Guide and WSO2 documentation standards
Purpose
Related PRs
Test environment
Security checks