Merge pull request #72448 from MicrosoftDocs/master

4/08 PM Publish

Author: huypub

.openpublishing.redirection.json

@@ -30546,6 +30546,11 @@
       "redirect_url": "/azure/active-directory/saas-apps/ms-confluence-jira-plugin-adminguide",
       "redirect_document_id": false
     },
+    {
+      "source_path": "articles/active-directory/saas-apps/alibaba-cloud-service-(role-based-sso)-tutorial.md",
+      "redirect_url": "/azure/active-directory/saas-apps/alibaba-cloud-service-role-based-sso-tutorial",
+      "redirect_document_id": false
+    },
     {
       "source_path": "articles/active-directory/saas-apps/index.md",
       "redirect_url": "/azure/active-directory/saas-apps/tutorial-list",

articles/active-directory/conditional-access/app-protection-based-conditional-access.md

@@ -46,7 +46,7 @@ You can combine app-protection-based conditional access policies with other poli
 
 ## Benefits of app protection-based conditional access requirement
 
-Similar to compliance being reported by Intune for iOS and Android for managed device, Intune now reports to Azure AD if app protection policy is applied so that conditional access can use this as an access check. This new conditional access policy **App protection policy** increases security by protects admin errors such as:
+Similar to compliance being reported by Intune for iOS and Android for managed device, Intune now reports to Azure AD if app protection policy is applied so that conditional access can use this as an access check. This new conditional access policy **App protection policy** increases security by protecting against admin errors such as:
 
 - users that do not have an Intune license
 - users that cannot receive an Intune app protection policy

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

@@ -145,7 +145,7 @@ Microsoft identities can authenticate in a variety of ways, which may be relevan
 
 ## Validating tokens
 
-To validate an id_token or an access_token, your app should validate both the token's signature and the claims. In order to validate access tokens, your app should also validate the issuer, the audience and the signing tokens. These need to be validated against the values in the OpenID discovery document. For example, the tenant independent version of the document is located at [https://login.microsoftonline.com/common/.well-known/openid-configuration](https://login.microsoftonline.com/common/.well-known/openid-configuration). 
+To validate an id_token or an access_token, your app should validate both the token's signature and the claims. In order to validate access tokens, your app should also validate the issuer, the audience and the signing tokens. These need to be validated against the values in the OpenID discovery document. For example, the tenant-independent version of the document is located at [https://login.microsoftonline.com/common/.well-known/openid-configuration](https://login.microsoftonline.com/common/.well-known/openid-configuration). 
 
 The Azure AD middleware has built-in capabilities for validating access tokens, and you can browse through our [samples](https://docs.microsoft.com/azure/active-directory/active-directory-code-samples) to find one in the language of your choice. For more information on how to explicitly validate a JWT token, see the [manual JWT validation sample](https://github.com/Azure-Samples/active-directory-dotnet-webapi-manual-jwt-validation). 
 
@@ -170,14 +170,14 @@ 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 your app 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.
 
-You can acquire the signing key data necessary to validate the signature by using the OpenID Connect metadata document located at:
+You can 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:
 
 ```
-https://login.microsoftonline.com/common/.well-known/openid-configuration
+https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration
 ```
 
 > [!TIP]
-> Try this [URL](https://login.microsoftonline.com/common/.well-known/openid-configuration) in a browser!
+> Try this [URL](https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration) in a browser!
 
 This metadata document:
 
@@ -187,7 +187,9 @@ This metadata document:
 > [!NOTE]
 > The v1.0 endpoint returns both the `x5t` and `kid` claims, while the v2.0 endpoint responds with only the `kid` claim. Going forward, we recommend using the `kid` claim to validate your token.
 
-Performing signature validation is outside the scope of this document - there are many open source libraries available for helping you do so if necessary.
+Performing signature validation is outside the scope of this document - there are many open source libraries available for helping you do so if necessary.  However, the Microsoft Identity platform has one token signing extension to the standards - custom signing keys.  
+
+If your app has custom signing keys as a result of using the [claims-mapping](active-directory-claims-mapping.md) feature, you must append an `appid` query parameter containing the app ID in order to get a `jwks_uri` pointing to your app's signing key information, which should be used for validation. For example: `https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e` contains a `jwks_uri` of `https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e`.
 
 ### Claims based authorization
 

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

@@ -410,7 +410,7 @@ Based on the method chosen, a set of inputs and outputs is expected. Define the
 
 ### Custom signing key
 
-A custom signing key must be assigned to the service principal object for a claims mapping policy to take effect. All tokens issued that have been impacted by the policy are signed with the custom signing key, and applications must be configured to accept tokens signed with the signing key. This ensures acknowledgment that tokens have been modified by the creator of the claims mapping policy and protects applications from claims mapping policies created by malicious actors.
+A custom signing key must be assigned to the service principal object for a claims mapping policy to take effect. This ensures acknowledgment that tokens have been modified by the creator of the claims mapping policy and protects applications from claims mapping policies created by malicious actors.  Apps that have claims mapping enabled must check a special URI for 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).  
 
 ### Cross-tenant scenarios
 

articles/active-directory/develop/active-directory-v2-protocols.md

@@ -37,10 +37,11 @@ In nearly all OAuth 2.0 and OpenID Connect flows, there are four parties involve
 * The **Authorization Server** is the v2.0 endpoint and responsible for ensuring the user's identity, granting and revoking access to resources, and issuing tokens. The authorization server also known as the identity provider - it securely handles anything to do with the user's information, their access, and the trust relationships between parties in a flow.
 * The **Resource Owner** is typically the end user. It's the party that owns the data and has the power to allow third parties to access that data or resource.
 * The **OAuth Client** is your app, identified by its application ID. The OAuth client is usually the party that the end user interacts with, and it requests tokens from the authorization server. The client must be granted permission to access the resource by the resource owner.
-* The **Resource Server** is where the resource or data resides. It trusts the Authorization Server to securely authenticate and authorize the OAuth Client, and uses Bearer access_tokens to ensure that access to a resource can be granted.
+* The **Resource Server** is where the resource or data resides. It trusts the Authorization Server to securely authenticate and authorize the OAuth Client, and uses Bearer access tokens to ensure that access to a resource can be granted.
 
 ## App Registration
-Every app that uses the v2.0 endpoint must be registered in [apps.dev.microsoft.com](https://apps.dev.microsoft.com/?referrer=https://azure.microsoft.com/documentation/articles&deeplink=/appList) or through the new **App registrations (Preview)** experience in the [Azure portal](https://portal.azure.com/?Microsoft_AAD_RegisteredApps=true#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) before it can interact using OAuth or OpenID Connect. The app registration process will collect and assign a few values to your app:
+
+Every app that wants to accept both personal and work or school accounts must be registered through the new **App registrations (Preview)** experience in the [Azure portal](https://portal.azure.com/?Microsoft_AAD_RegisteredApps=true#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) before it can sign these users in using OAuth 2.0 or OpenID Connect. The app registration process will collect and assign a few values to your app:
 
 * An **Application ID** that uniquely identifies your app
 * A **Redirect URI** or **Package Identifier** that can be used to direct responses back to your app
@@ -68,6 +69,9 @@ Where the `{tenant}` can take one of four different values:
 
 To learn how to interact with these endpoints, choose a particular app type in the [Protocols](#protocols) section and follow the links for more info.
 
+> [!TIP]
+> Any app registered in Azure AD can use the v2.0 endpoint, even if they don't sign in personal accounts.  This way, you can migrate existing applications to v2.0 and [MSAL](reference-v2-libraries.md) without re-creating your application.  
+
 ## Tokens
 
 The v2.0 implementation of OAuth 2.0 and OpenID Connect make extensive use of bearer tokens, including bearer tokens represented as JWTs. A bearer token is a lightweight security token that grants the “bearer” access to a protected resource. In this sense, the “bearer” is any party that can present the token. Though a party must first authenticate with Azure AD to receive the bearer token, if the required steps are not taken to secure the token in transmission and storage, it can be intercepted and used by an unintended party. While some security tokens have a built-in mechanism for preventing unauthorized parties from using them, bearer tokens do not have this mechanism and must be transported in a secure channel such as transport layer security (HTTPS). If a bearer token is transmitted in the clear, a malicious party can use a man-in-the-middle attack to acquire the token and use it for unauthorized access to a protected resource. The same security principles apply when storing or caching bearer tokens for later use. Always ensure that your app transmits and stores bearer tokens in a secure manner. For more security considerations on bearer tokens, see [RFC 6750 Section 5](https://tools.ietf.org/html/rfc6750).

articles/active-directory/develop/v1-protocols-openid-connect-code.md

@@ -43,12 +43,12 @@ OpenID Connect describes a metadata document that contains most of the informati
 ```
 https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration
 ```
-The metadata is a simple JavaScript Object Notation (JSON) document. See the following snippet for an example. The snippet's contents are fully described in the [OpenID Connect specification](https://openid.net). Note that providing tenant rather than `common` in place of {tenant} above will result in tenant-specific URIs in the JSON object returned.
+The metadata is a simple JavaScript Object Notation (JSON) document. See the following snippet for an example. The snippet's contents are fully described in the [OpenID Connect specification](https://openid.net). Note that providing a tenant ID rather than `common` in place of {tenant} above will result in tenant-specific URIs in the JSON object returned.
 
 ```
 {
-    "authorization_endpoint": "https://login.microsoftonline.com/common/oauth2/authorize",
-    "token_endpoint": "https://login.microsoftonline.com/common/oauth2/token",
+    "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
+    "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
     "token_endpoint_auth_methods_supported":
     [
         "client_secret_post",
@@ -61,6 +61,8 @@ The metadata is a simple JavaScript Object Notation (JSON) document. See the fol
 }
 ```
 
+If your app has custom signing keys as a result of using the [claims-mapping](active-directory-claims-mapping.md) feature, you must append an `appid` query parameter containing the app ID in order to get a `jwks_uri` pointing to your app's signing key information. For example: `https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e` contains a `jwks_uri` of `https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e`.
+
 ## Send the sign-in request
 
 When your web application needs to authenticate the user, it must direct the user to the `/authorize` endpoint. This request is similar to the first leg of the [OAuth 2.0 Authorization Code Flow](v1-protocols-oauth-code.md), with a few important distinctions:
@@ -87,7 +89,7 @@ client_id=6731de76-14a6-49ae-97bc-6eba6914391e
 | Parameter |  | Description |
 | --- | --- | --- |
 | tenant |required |The `{tenant}` value in the path of the request can be used to control who can sign into the application. The allowed values are tenant identifiers, for example, `8eaef023-2b34-4da1-9baa-8bc8c9d6a490` or `contoso.onmicrosoft.com` or `common` for tenant-independent tokens |
-| client_id |required |The Application Id assigned to your app when you registered it with Azure AD. You can find this in the Azure Portal. Click **Azure Active Directory**, click **App Registrations**, choose the application and locate the Application Id on the application page. |
+| client_id |required |The Application ID assigned to your app when you registered it with Azure AD. You can find this in the Azure portal. Click **Azure Active Directory**, click **App Registrations**, choose the application and locate the Application ID on the application page. |
 | response_type |required |Must include `id_token` for OpenID Connect sign-in. It may also include other response_types, such as `code` or `token`. |
 | scope | recommended | The OpenID Connect specification requires the scope `openid`, which translates to the "Sign you in" permission in the consent UI. This and other OIDC scopes are ignored on the v1.0 endpoint, but is still a best practice for standards-compliant clients. |
 | nonce |required |A value included in the request, generated by the app, that is included in the resulting `id_token` as a claim. The app can then verify this value to mitigate token replay attacks. The value is typically a randomized, unique string or GUID that can be used to identify the origin of the request. |
@@ -175,13 +177,13 @@ post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
 
 | Parameter |  | Description |
 | --- | --- | --- |
-| post_logout_redirect_uri |recommended |The URL that the user should be redirected to after successful logout. If not included, the user is shown a generic message. |
+| post_logout_redirect_uri |recommended |The URL that the user should be redirected to after successful sign out. If not included, the user is shown a generic message. |
 
 ## Single sign-out
 
 When you redirect the user to the `end_session_endpoint`, Azure AD clears the user's session from the browser. However, the user may still be signed in to other applications that use Azure AD for authentication. To enable those applications to sign the user out simultaneously, Azure AD sends an HTTP GET request to the registered `LogoutUrl` of all the applications that the user is currently signed in to. Applications must respond to this request by clearing any session that identifies the user and returning a `200` response. If you wish to support single sign out in your application, you must implement such a `LogoutUrl` in your application's code. You can set the `LogoutUrl` from the Azure portal:
 
-1. Navigate to the [Azure Portal](https://portal.azure.com).
+1. Navigate to the [Azure portal](https://portal.azure.com).
 2. Choose your Active Directory by clicking on your account in the top right corner of the page.
 3. From the left hand navigation panel, choose **Azure Active Directory**, then choose **App registrations** and select your application.
 4. Click on **Settings**, then **Properties** and find the **Logout URL** text box. 
@@ -196,7 +198,7 @@ To acquire access tokens, you need to modify the sign-in request from above:
 // Line breaks for legibility only
 
 GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
-client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application Id
+client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
 &response_type=id_token+code
 &redirect_uri=http%3A%2F%2Flocalhost%3a12345          // Your registered Redirect Uri, url encoded
 &response_mode=form_post                              // `form_post' or 'fragment'