Merge pull request #209407 from mmacy/msid-content-health-oidc-ado-2009832

[msid][health] refresh v2-protocols-oidc.md (ADO-2009832)

Author: PMEds28

articles/active-directory/develop/access-tokens.md

@@ -219,7 +219,7 @@ The `alg` claim indicates the algorithm that was used to sign the token, while t
 
 At any given point in time, Azure AD may sign an ID token using any one of a certain set of public-private key pairs. Azure AD rotates the possible set of keys on a periodic basis, so the application should be written to handle those key changes automatically. A reasonable frequency to check for updates to the public keys used by Azure AD is every 24 hours.
 
-Acquire the signing key data necessary to validate the signature by using the [OpenID Connect metadata document](v2-protocols-oidc.md#fetch-the-openid-connect-metadata-document) located at:
+Acquire the signing key data necessary to validate the signature by using the [OpenID Connect metadata document](v2-protocols-oidc.md#fetch-the-openid-configuration-document) located at:
 
 ```
 https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

articles/active-directory/develop/active-directory-claims-mapping.md

@@ -402,7 +402,7 @@ else
 ```
 
 #### Validate token signing key
-Apps that have claims mapping enabled must validate their token signing keys by appending `appid={client_id}` to their [OpenID Connect metadata requests](v2-protocols-oidc.md#fetch-the-openid-connect-metadata-document). Below is the format of the OpenID Connect metadata document you should use:
+Apps that have claims mapping enabled must validate their token signing keys by appending `appid={client_id}` to their [OpenID Connect metadata requests](v2-protocols-oidc.md#fetch-the-openid-configuration-document). Below is the format of the OpenID Connect metadata document you should use:
 
 ```
 https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

articles/active-directory/develop/userinfo.md

@@ -9,54 +9,54 @@ ms.service: active-directory
 ms.subservice: develop
 ms.workload: identity
 ms.topic: conceptual
-ms.date: 09/21/2020
+ms.date: 08/26/2022
 ms.author: ludwignick
 ms.reviewer: ludwignick
 ms.custom: aaddev
 ---
 
 # Microsoft identity platform UserInfo endpoint
 
-The UserInfo endpoint is part of the [OpenID Connect standard](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) (OIDC), designed to return claims about the user that authenticated.  For the Microsoft identity platform, the UserInfo endpoint is hosted on Microsoft Graph (https://graph.microsoft.com/oidc/userinfo). 
+Part of the OpenID Connect (OIDC) standard, the [UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) is returns information about an authenticated user. In the Microsoft identity platform, the UserInfo endpoint is hosted by Microsoft Graph at https://graph.microsoft.com/oidc/userinfo. 
 
 ## Find the .well-known configuration endpoint
 
-You can programmatically discover the UserInfo endpoint using the OpenID Connect discovery document, at `https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration`. It’s listed in the `userinfo_endpoint` field, and this pattern can be used across clouds to help point to the right endpoint.  We do not recommend hard-coding the UserInfo endpoint in your app – use the OIDC discovery document to find this endpoint at runtime instead.
+You can find the UserInfo endpoint programmatically by reading the `userinfo_endpoint` field of the OpenID configuration document at `https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration`. We don't recommend hard-coding the UserInfo endpoint in your applications. Instead, use the OIDC configuration document to find the endpoint at runtime.
 
-As part of the OpenID Connect specification, the UserInfo endpoint is often automatically called by [OIDC compliant libraries](https://openid.net/developers/certified/)  to get information about the user.  Without hosting such an endpoint, the Microsoft identity platform would not be standards compliant and some libraries would fail.  From the [list of claims identified in the OIDC standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) we produce the name claims, subject claim, and email when available and consented for.  
+The UserInfo endpoint is typically called automatically by [OIDC-compliant libraries](https://openid.net/developers/certified/) to get information about the user.From the [list of claims identified in the OIDC standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims), the Microsoft identity platform produces the name claims, subject claim, and email when available and consented to. 
 
-## Consider: Use an ID Token instead
+## Consider using an ID token instead
 
-The information available in the ID token that your app can receive is a superset of the information it can get from the UserInfo endpoint.  Because you can get an ID token at the same time you get a token to call the UserInfo endpoint, we suggest that you use that ID token to get information about the user instead of calling the UserInfo endpoint.  Using the ID token will eliminate one to two network requests from your application launch, reducing latency in your application.
+The information in an ID token is a superset of the information available on UserInfo endpoint. Because you can get an ID token at the same time you get a token to call the UserInfo endpoint, we suggest getting the user's information from the token instead calling the UserInfo endpoint. Using the ID token instead of calling the UserInfo endpoint eliminates up to two network requests, reducing latency in your application.
 
-If you require more details about the user, you should call the [Microsoft Graph `/user` API](/graph/api/user-get) to get information like office number or job title.   You can also use [optional claims](active-directory-optional-claims.md) to include additional user information in your ID and access tokens.
+If you require more details about the user like manager or job title, call the [Microsoft Graph `/user` API](/graph/api/user-get). You can also use [optional claims](active-directory-optional-claims.md) to include additional user information in your ID and access tokens.
 
 ## Calling the UserInfo endpoint
 
-UserInfo is a standard OAuth Bearer token API, called like any other Microsoft Graph API using the access token received when getting a token for Microsoft Graph. It returns a JSON response containing claims about the user.
+UserInfo is a standard OAuth bearer token API hosted by Microsoft Graph. Call the UserInfo endpoint as you would any Microsoft Graph API by using the access token your application received when it requested access to Microsoft Graph. The UserInfo endpoint returns a JSON response containing claims about the user.
 
 ### Permissions
 
-Use the following [OIDC permissions](v2-permissions-and-consent.md#openid-connect-scopes) to call the UserInfo API. `openid` is required, and the `profile` and `email` scopes ensure that additional information is provided in the response.
+Use the following [OIDC permissions](v2-permissions-and-consent.md#openid-connect-scopes) to call the UserInfo API. The `openid` claim is required, and the `profile` and `email` scopes ensure that additional information is provided in the response.
 
-|Permission type      | Permissions    |
-|:--------------------|:---------------------------------------------------------|
-|Delegated (work or school account) | openid (required), profile, email |
-|Delegated (personal Microsoft account) | openid (required), profile, email |
-|Application | Not applicable |
+| Permission type                        | Permissions                       |
+|:---------------------------------------|:----------------------------------|
+| Delegated (work or school account)     | `openid` (required), `profile`, `email` |
+| Delegated (personal Microsoft account) | `openid` (required), `profile`, `email` |
+| Application                            | Not applicable                    |
 
 > [!TIP]
-> Copy this URL in your browser to get a token for the UserInfo endpoint as well as an [ID token](id-tokens.md) and replace the client ID and redirect URI with your own. Note that it only requests scopes for OpenID or Graph scopes, and nothing else.  This is required, since you cannot request permissions for two different resources in the same token request.
+> Copy this URL in your browser to get an access token for the UserInfo endpoint and an [ID token](id-tokens.md). Replace the client ID and redirect URI with values from an app registration.
 >
 > `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<yourClientID>&response_type=token+id_token&redirect_uri=<YourRedirectUri>&scope=user.read+openid+profile+email&response_mode=fragment&state=12345&nonce=678910`
 >
-> You can use this access token in the next section.
+> You can use the access token that's returned in the query in the next section.
 
-As with any other Microsoft Graph token, the token you receive here may not be a JWT. If you signed in a Microsoft account user, it will be an encrypted token format. This is because Microsoft Graph has a special token issuance pattern. This does not impact your ability to use the access token to call the UserInfo endpoint.
+Microsoft Graph uses a special token issuance pattern that may impact your app's ability to read or validate it. As with any other Microsoft Graph token, the token you receive here may not be a JWT and your app should consider it opaque. If you signed in a Microsoft account user, it will be an encrypted token format. None of these factors, however, impact your app's ability to use the access token in a request to the UserInfo endpoint.
 
 ### Calling the API
 
-The UserInfo API supports both GET and POST, per the OIDC spec.
+The UserInfo API supports both GET and POST requests.
 
 ```http
 GET or POST /oidc/userinfo HTTP/1.1
@@ -77,16 +77,16 @@ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6Il…
 }
 ```
 
-The claims listed here are all of the claims that the UserInfo endpoint can return.  These are the same values that the app would see in the [ID token](id-tokens.md) issued to the app.  
+The claims shown in the response are all those that the UserInfo endpoint can return. These values are the same values included in an [ID token](id-tokens.md). 
 
 ## Notes and caveats on the UserInfo endpoint
 
-* If you want to call this UserInfo endpoint you must use the v2.0 endpoint.  If you use the v1.0 endpoint you will get a token for the v1.0 UserInfo endpoint, hosted on login.microsoftonline.com.  We recommend that all OIDC compliant apps and libraries use the v2.0 endpoint to ensure compatibility.
-* The response from the UserInfo endpoint cannot be customized.  If you’d like to customize claims, please use [claims mapping]( active-directory-claims-mapping.md) to edit the information returned in the tokens.
-* The response from the UserInfo endpoint cannot be added to.  If you’d like to get additional claims about the user, please use [optional claims]( active-directory-optional-claims.md) to add new claims to the tokens.
+You can't add to or customize the information returned by the UserInfo endpoint.
+
+To customize the information returned by the identity platform during authentication and authorization, use [claims mapping]( active-directory-claims-mapping.md) and [optional claims]( active-directory-optional-claims.md) to modify security token configuration.
 
 ## Next Steps
 
-* [Review the contents of ID tokens](id-tokens.md)
-* [Customize the contents of an ID token using optional claims](active-directory-optional-claims.md)
-* [Request an access token and ID token using the OAuth2 protocol](v2-protocols-oidc.md)
+* [Review the contents of ID tokens](id-tokens.md).
+* [Customize the contents of an ID token using optional claims](active-directory-optional-claims.md).
+* [Request an access token and ID token using the OAuth 2 protocol](v2-protocols-oidc.md).