Refine wording on permissions and scopes in OIDC doc - #1999
Open
Nicolas Lykke Iversen (nlykkei) wants to merge 1 commit into
Open
Refine wording on permissions and scopes in OIDC doc#1999Nicolas Lykke Iversen (nlykkei) wants to merge 1 commit into
Nicolas Lykke Iversen (nlykkei) wants to merge 1 commit into
Conversation
Corrected phrasing for clarity regarding permission definitions and scopes. Scopes are not permission sets, but permissions.
Contributor
|
Nicolas Lykke Iversen (@nlykkei) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refines terminology in the OIDC scopes documentation to reduce confusion between “permissions” and “scopes” in the Microsoft identity platform.
Changes:
- Rewords the explanation of fine-grained access control to refer to permissions (rather than “permission sets”).
- Updates the OAuth 2.0 paragraph to frame scopes as permission strings and align terminology with the
scopeparameter usage. - Fixes indentation so the explanatory paragraphs render as normal prose (instead of appearing indented like a code block).
| Because of these permission definitions, the resource has fine-grained control over its data and how API functionality is exposed. A third-party app can request these permissions from users and administrators, who must approve the request before the app can access data or act on a user's behalf. | ||
|
|
||
| When a resource's functionality is chunked into small permission sets, third-party apps can be built to request only the permissions that they need to perform their function. Users and administrators can know what data the app can access. And they can be more confident that the app isn't behaving with malicious intent. Developers should always abide by the principle of least privilege, asking for only the permissions they need for their applications to function. | ||
| When a resource's functionality is chunked by fine-grained permissions, third-party apps can be built to request only the permissions that they need to perform their function. Users and administrators can know what data the app can access. And they can be more confident that the app isn't behaving with malicious intent. Developers should always abide by the principle of least privilege, asking for only the permissions they need for their applications to function. |
| When a resource's functionality is chunked by fine-grained permissions, third-party apps can be built to request only the permissions that they need to perform their function. Users and administrators can know what data the app can access. And they can be more confident that the app isn't behaving with malicious intent. Developers should always abide by the principle of least privilege, asking for only the permissions they need for their applications to function. | ||
|
|
||
| In OAuth 2.0, these types of permission sets are called *scopes*. They're also often referred to as *permissions*. In the Microsoft identity platform, a permission is represented as a string value. An app requests the permissions it needs by specifying the permission in the `scope` query parameter. Identity platform supports several well-defined [OpenID Connect scopes](#openid-connect-scopes) and resource-based permissions (each permission is indicated by appending the permission value to the resource's identifier or application ID URI). For example, the permission string `https://graph.microsoft.com/Calendars.Read` is used to request permission to read users calendars in Microsoft Graph. | ||
| In OAuth 2.0, these permissions are called *scopes*. They're also often referred to as *permissions*. In the Microsoft identity platform, a permission is represented as a string value. An app requests the permissions it needs by specifying the permission in the `scope` query parameter. Identity platform supports several well-defined [OpenID Connect scopes](#openid-connect-scopes) and resource-based permissions (each permission is indicated by appending the permission value to the resource's identifier or application ID URI). For example, the permission string `https://graph.microsoft.com/Calendars.Read` is used to request permission to read users calendars in Microsoft Graph. |
Contributor
|
Jackline Omondi (@omondiatieno) Can you review the proposed changes? IMPORTANT: When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
Contributor
|
Learn Build status updates of commit 209e412:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/identity-platform/tutorial-desktop-app-maui-sign-in-sign-out.md | Details | ||
| docs/identity-platform/tutorial-mobile-app-maui-sign-in-sign-out.md | Details | ||
| docs/identity-platform/scopes-oidc.md | ✅Succeeded |
docs/identity-platform/tutorial-desktop-app-maui-sign-in-sign-out.md
- Line 50, Column 4: [Warning: invalid-code]
The code snippet "~/../ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/MainView.xaml" could not be found. - Line 69, Column 4: [Warning: invalid-code]
The code snippet "~/../ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/MainView.xaml.cs" could not be found. - Line 86, Column 4: [Warning: invalid-code]
The code snippet "~/../ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/ClaimsView.xaml" could not be found. - Line 100, Column 4: [Warning: invalid-code]
The code snippet "~/../ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/ClaimsView.xaml.cs" could not be found.
docs/identity-platform/tutorial-mobile-app-maui-sign-in-sign-out.md
- Line 50, Column 4: [Warning: invalid-code]
The code snippet "~/../ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/MainView.xaml" could not be found. - Line 69, Column 4: [Warning: invalid-code]
The code snippet "~/../ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/MainView.xaml.cs" could not be found. - Line 86, Column 4: [Warning: invalid-code]
The code snippet "~/../ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/ClaimsView.xaml" could not be found. - Line 100, Column 4: [Warning: invalid-code]
The code snippet "~/../ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/ClaimsView.xaml.cs" could not be found.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
Contributor
|
Nicolas Lykke Iversen (@nlykkei), thank you for your contribution. Kindly commit the copilot suggestions and also resolve the invalid code block errors. Jackson Woods (MSFT) (@Jackson-Woods), are you still the PM for this feature and can you help us review the updates for technical accuracy? |
Contributor
|
Nicolas Lykke Iversen (@nlykkei) Can you respond to the requested changes or let us know if you would like us to commit them? Jackson Woods (MSFT) (@Jackson-Woods) Jackline Omondi (@omondiatieno) - When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
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
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.
Corrected phrasing for clarity regarding permission definitions and scopes.
Scopes are not permission sets, but permissions.
The documentation is very confusing and doesn't use consistent terminology.