Merge pull request #232027 from MicrosoftDocs/repo_sync_working_branch

Confirm merge from repo_sync_working_branch to main to sync with https://github.com/MicrosoftDocs/azure-docs (branch main)

Author: rmca14

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

@@ -242,45 +242,34 @@ If the application has custom signing keys as a result of using the [claims-mapp
 
 ### Claims based authorization
 
-The business logic of the application dictates claims based authorization. Some common authorization methods are listed below.
+The business logic of an application determines how authorization should be handled. The general approach to authorization based on token claims, and which claims should be used, is described below.
 
-#### Validate the token
+After a token is validated with the correct `aud` claim, the token tenant, subject, actor must be authorized.
 
-Use the `aud` claim to ensure that the user intended to call the application. If the identifier of the resource isn't in the `aud` claim, reject it.
+#### Tenant
 
-#### Validate user permission
+First, always check that the `tid` in a token matches the tenant ID used to store data with the application. When information is stored for an application in the context of a tenant, it should only be accessed again later in the same tenant. Never allow data in one tenant to be accessed from another tenant.
 
-Use the `roles` and `wids` claims to validate that the user has authorization to call the API.  For example, an administrator may have permission to write to the API, but not a normal user. Check that the `tid` inside the token matches the tenant ID used to store the data in the API.
+#### Subject
 
-When a user stores data in the API from one tenant, they must sign into that tenant again to access that data. Never allow data in one tenant to be accessed from another tenant.
+Next, to determine if the token subject, such as the user (or app itself in the case of an app-only token), is authorized, either check for specific `sub` or `oid` claims, or check that the subject belongs to an appropriate role or group with the `roles`, `groups`, `wids` claims.
 
-Use the `amr` claim to verify the user has performed MFA. The enforcement of MFA is done using [Conditional Access](../conditional-access/overview.md). If `roles` or `groups` claims are requested in the access token, verify that the user is in the group allowed to do this action.
+For example, use the immutable claim values `tid` and `oid` as a combined key for application data and determining whether a user should be granted access.
 
-For tokens retrieved using the implicit flow, query the [Microsoft Graph](https://developer.microsoft.com/graph/) for this data, as it's often too large to fit in the token.
+The `roles`, `groups` or `wids` claims can also be used to determine if the subject has authorization to perform an operation. For example, an administrator may have permission to write to an API, but not a normal user, or the user may be in a group allowed to do some action.
 
-Don't use `email` or `upn` claim values to determine whether the user in an access token should have access to data. Mutable claim values like these can change over time, making them insecure and unreliable for authorization.
+> [!WARNING]
+> Never use `email` or `upn` claim values to store or determine whether the user in an access token should have access to data. Mutable claim values like these can change over time, making them insecure and unreliable for authorization.
 
-Use immutable claim values `tid` and `sub` or `oid` as a combined key for uniquely identifying the API's data and determining whether a user should be granted access to that data.
+#### Actor
 
-- Good: `tid` + `sub`
-- Better: `tid` + `oid` - the `oid` is consistent across applications, so an ecosystem of applications can audit user access to data.
+Lastly, when an app is acting for a user, this client app (the actor), must also be authorized. Use the `scp` claim (scope) to validate that the app has permission to perform an operation.
 
-Don't use mutable, human-readable identifiers like `email` or `upn` for uniquely identifying data.
+Scopes are defined by the application, and the absence of `scp` claim means full actor permissions.	
 
-#### Validate application sign-in
-
-* Use the `scp` claim to validate that the user has granted the calling app permission to call your API.
-* Ensure the calling client is allowed to call your API using the `appid` claim (for v1.0 tokens) or the `azp` claim (for v2.0 tokens).
-    * You only need to validate these claims (`appid`, `azp`) if you want to restrict your web API to be called only by pre-determined applications (e.g., line-of-business applications or web APIs called by well-known frontends). APIs intended to allow access from any calling application do not need to validate these claims.
-
-## User and application tokens
-
-An application may receive tokens for a user or directly from an application through the client credentials flow. These app-only tokens indicate that this call is coming from an application and doesn't have a user backing it. These tokens are handled largely the same:
-
-- Use `roles` to see permissions that have been granted to the subject of the token.
-- Use `oid` or `sub` to validate that the calling service principal is the expected one.
+> [!NOTE]
+> An application may handle app-only tokens (requests from applications without users, such as daemon apps) and want to authorize a specific application across multiple tenants, rather than individual service principal IDs. In that case, check for an app-only token using the `idtyp` optional claim and use the `appid` claim (for v1.0 tokens) or the `azp` claim (for v2.0 tokens) along with `tid` to determine authorization based on tenant and application ID.
 
-If the application needs to distinguish between app-only access tokens and access tokens for users, use the `idtyp` [optional claim](active-directory-optional-claims.md). To detect app-only access tokens, add the `idtyp` claim to the `accessToken` field, and check for the value `app`. ID tokens and access tokens for users won't have the `idtyp` claim included.
 
 ## Token revocation
 

articles/active-directory/develop/active-directory-schema-extensions.md

@@ -27,11 +27,11 @@ The identifier for a directory extension attribute is of the form *extension_xxx
 ## Registering and using directory extensions
 Directory extension attributes can be registered and populated in one of two ways:
 
-- By configuring AD Connect to create them and to sync data into them from on-premises AD. See [Azure AD Connect Sync Directory Extensions](../hybrid/how-to-connect-sync-feature-directory-extensions.md).
+- By configuring Azure AD Connect to create them and to sync data into them from on-premises AD. See [Azure AD Connect Sync Directory Extensions](../hybrid/how-to-connect-sync-feature-directory-extensions.md).
 - By using Microsoft Graph to register, set the values of, and read from [directory extensions](/graph/extensibility-overview#directory-azure-ad-extensions). [PowerShell cmdlets](/powershell/azure/active-directory/using-extension-attributes-sample) are also available.
 
-### Emitting claims with data from directory extension attributes created with AD Connect
-Directory extension attributes created and synced using AD Connect are always associated with the application ID used by AD Connect. They can be used as a source for claims both by configuring them as claims in the **Enterprise Applications** configuration in the Portal UI for SAML applications registered using the Gallery or the non-Gallery application configuration experience under **Enterprise Applications**, and via a claims-mapping policy for applications registered via the Application registration experience.  Once a directory extension attribute created via AD Connect is in the directory, it will show in the SAML SSO claims configuration UI.
+### Emitting claims with data from directory extension attributes created with Azure AD Connect
+Directory extension attributes created and synced using Azure AD Connect are always associated with the application ID used by Azure AD Connect. These attributes can be used as a source for claims both by configuring them as claims in the **Enterprise Applications** configuration in the Portal UI for SAML applications registered using the Gallery or the non-Gallery application configuration experience under **Enterprise Applications**, and via a claims-mapping policy for applications registered via the Application registration experience.  Once a directory extension attribute created via AD Connect is in the directory, it will show in the SAML SSO claims configuration UI.
 
 ### Emitting claims with data from directory extension attributes created for an application using Graph or PowerShell
 If a directory extension attribute is registered for an application using Microsoft Graph or PowerShell (via an applications initial setup or provisioning step for instance), the same application can be configured in Azure Active Directory to receive data in that attribute from a user object in a claim when the user signs in.  The application can be configured to receive data in directory extensions that are registered on that same application using [optional claims](active-directory-optional-claims.md#configuring-directory-extension-optional-claims).  These can be set in the application manifest.  This enables a multi-tenant application to register directory extension attributes for its own use. When the application is provisioned into a tenant the associated directory extensions become available to be set on users in that tenant, and to be consumed.  Once it's configured in the tenant and consent granted, it can be used to store and retrieve data via graph and to map to claims in tokens the Microsoft identity platform emits to applications.

articles/active-directory/identity-protection/howto-identity-protection-simulate-risk.md

@@ -63,8 +63,8 @@ Completing the following procedure requires you to use a user account that has:
 
 **To simulate a sign-in from an unfamiliar location, perform the following steps**:
 
-1. When signing in with your test account, fail the multifactor authentication (MFA) challenge by not passing the MFA challenge.
-2. Using your new VPN, navigate to [https://myapps.microsoft.com](https://myapps.microsoft.com) and enter the credentials of your test account.
+1. Using your new VPN, navigate to [https://myapps.microsoft.com](https://myapps.microsoft.com) and enter the credentials of your test account.
+2. When signing in with your test account, fail the multifactor authentication (MFA) challenge by not passing the MFA challenge.
 
 The sign-in shows up on the Identity Protection dashboard within 10 - 15 minutes.
 

articles/azure-maps/tutorial-create-store-locator.md

@@ -2,8 +2,8 @@
 title: 'Tutorial: Use Microsoft Azure Maps to create store locator web applications'
 titleSuffix: Microsoft Azure Maps
 description: Tutorial on how to use Microsoft Azure Maps to create store locator web applications.
-author: eriklindeman
-ms.author: eriklind
+author: sinnypan
+ms.author: sipa
 ms.date: 01/03/2022
 ms.topic: tutorial
 ms.service: azure-maps
@@ -42,12 +42,12 @@ In this tutorial, you'll learn how to:
 
 In this tutorial, you'll create a store locator for a fictional company named *Contoso Coffee*. Also, this tutorial includes some tips to help you learn about extending the store locator with other optional functionality.
 
-To see a live sample of what you will create in this tutorial, see [Simple Store Locator] on the **Azure Maps Code Samples** site.
+To see a live sample of what you're creating in this tutorial, see [Simple Store Locator] on the **Azure Maps Code Samples** site.
 
-To more easily follow and engage this tutorial, you'll need to download the following resources:
+To more easily follow and engage this tutorial, download the following resources:
 
-* Full source code for the [Simple Store Locator](https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/master/Samples/Tutorials/Simple%20Store%20Locator) on GitHub.
-* [Store location data](https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/master/Samples/Tutorials/Simple%20Store%20Locator/data) that you'll import into the store locator dataset.
+* [Simple Store Locator] source code.
+* [Store location data] used to import into the store locator dataset.
 * The [Map images].
 
 ## Store locator features
@@ -213,7 +213,7 @@ To create the HTML:
     </main>
     ```
 
-After you finish, *index.html* should look like [Simple Store Locator.html].
+After you finish, *index.html* should look like _[Simple Store Locator.html]_ in the tutorial sample code.
 
 ## Define the CSS styles
 
@@ -1015,7 +1015,7 @@ In this tutorial, you learned how to create a basic store locator by using Azure
 
 ## Additional information
 
-* For the completed code used in this tutorial, see the [Simple Store Locator](https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/master/Samples/Tutorials/Simple%20Store%20Locator) tutorial on GitHub.
+* For the completed code, see the [Simple Store Locator tutorial on GitHub].
 * To view this sample live, see [Simple Store Locator] on the **Azure Maps Code Samples** site.
 * learn more about the coverage and capabilities of Azure Maps by using [Zoom levels and tile grid].
 * You can also [Use data-driven style expressions] to apply to your business logic.
@@ -1032,21 +1032,24 @@ To see more code examples and an interactive coding experience:
 [Manage authentication in Azure Maps]: how-to-manage-authentication.md
 [Visual Studio Code]: https://code.visualstudio.com
 [Simple Store Locator]: https://samples.azuremaps.com/?sample=simple-store-locator
+[Simple Store Locator tutorial on GitHub]: https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/master/Samples/Tutorials/Simple%20Store%20Locator
+[Simple Store Locator.html]: https://github.com/Azure-Samples/AzureMapsCodeSamples/blob/master/Samples/Tutorials/Simple%20Store%20Locator/Simple%20Store%20Locator.html
+
 [data]: https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/master/Samples/Tutorials/Simple%20Store%20Locator/data
 [Search service]: /rest/api/maps/search
 [Spherical Mercator projection]: glossary.md#spherical-mercator-projection
 [EPSG:3857]: https://epsg.io/3857
 [EPSG:4326]: https://epsg.io/4326
 [ContosoCoffee.xlsx]: https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/master/Samples/Tutorials/Simple%20Store%20Locator/data
 [Map images]: https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/master/Samples/Tutorials/Simple%20Store%20Locator/images
-[Simple Store Locator.html]: https://github.com/Azure-Samples/AzureMapsCodeSamples/blob/master/Samples/Tutorials/Simple%20Store%20Locator/Simple%20Store%20Locator.html
 [event listener]: /javascript/api/azure-maps-control/atlas.map#events
-[suggestions as you type]: (https://samples.azuremaps.com/?sample=search-autosuggest-and-jquery-ui
-[support for multiple languages]: (https://samples.azuremaps.com/?sample=map-localization
-[filter locations along a route]: (https://samples.azuremaps.com/?sample=filter-data-along-route
-[set filters]: (https://samples.azuremaps.com/?sample=filter-symbols-by-property
+[suggestions as you type]: https://samples.azuremaps.com/?sample=search-autosuggest-and-jquery-ui
+[support for multiple languages]: https://samples.azuremaps.com/?sample=map-localization
+[filter locations along a route]: https://samples.azuremaps.com/?sample=filter-data-along-route
+[set filters]: https://samples.azuremaps.com/?sample=filter-symbols-by-property
 [Azure App Service Web App]: ../app-service/quickstart-html.md
 [SQL Server spatial data types overview]: /sql/relational-databases/spatial/spatial-data-types-overview?preserve-view=true&view=sql-server-2017
 [Query spatial data for the nearest neighbor]: /sql/relational-databases/spatial/query-spatial-data-for-nearest-neighbor?preserve-view=true&view=sql-server-2017
 [Zoom levels and tile grid]: zoom-levels-and-tile-grid.md
 [Use data-driven style expressions]: data-driven-style-expressions-web-sdk.md
+[Store location data]: https://github.com/Azure-Samples/AzureMapsCodeSamples/tree/master/Samples/Tutorials/Simple%20Store%20Locator/data