Review feedback and minor changes

Author: yoelhor

articles/active-directory/develop/TOC.yml

@@ -72,7 +72,7 @@
     - name: Custom Authentication Extensions
       displayName: Custom Authentication Extensions
       items:
-        - name: Custom extensions
+        - name: Overview
           href: custom-extension-overview.md
         - name: Custom claims provider
           href: custom-claims-provider-overview.md

articles/active-directory/develop/custom-claims-provider-overview.md

@@ -17,9 +17,9 @@ ms.custom: aaddev
 #Customer intent: As a developer, I want to learn about custom claims provider so that I can augment tokens with claims from an external identity system or role management system.
 ---
 
-# Custom claims provider
+# Custom claims provider (preview)
 
-This article provides an overview to the custom claims provider, as part of [custom authentication extensions](./custom-extension-overview.md). 
+This article provides an overview to the Azure Active Directory (Azure AD) custom claims provider. 
 When a user authenticates to an application, a custom claims provider can be used to add  claims into the token. A custom claims provider is made up of a custom extension that calls an external REST API, to fetch claims from external systems. A custom claims provider can be assigned to one or many applications in your directory.
 
 Key data about a user is often stored in systems external to Azure AD. For example, secondary email, billing tier, or sensitive information. Some applications may rely on these attributes for the application to function as designed. For example, the application may block access to certain features based on a claim in the token.
@@ -31,9 +31,9 @@ Use a custom claims provider for the following scenarios:
 
 ## Token issuance start event listener
 
-A custom claims provider allows mapping claims from an external source into the token when the user signs into an application. It uses a custom extension to fetch attributes from an external REST API. The custom extension uses the **token issuance start** event listener, which causes it to be triggered when a token is about to be issued by Azure AD. The trigger event is configured within the custom extension, by using the **token issuance start** event type.
+An event listener is a procedure that waits for an event to occur. The custom extension uses the **token issuance start** event listener. The  event is triggered when a token is about to be issued to your application. When the event is triggered the custom extension REST API is called to fetch attributes from external systems.
 
-For an example using a custom claims provider with the **token issuance start**, check out the [get started with custom claims providers](custom-extension-get-started.md) article.
+For an example using a custom claims provider with the **token issuance start** event listener, check out the [get started with custom claims providers](custom-extension-get-started.md) article.
 
 ## Next steps
 

articles/active-directory/develop/custom-claims-provider-reference.md

@@ -19,7 +19,7 @@ ms.custom: aaddev
 
 # Custom claims providers
 
-In this reference article, you can learn about the REST API schema and Claims mapping policy structure for custom claim provider events.
+In this reference article, you can learn about the REST API schema and claims mapping policy structure for custom claim provider events.
 
 ## Token issuance start event
 

articles/active-directory/develop/custom-extension-get-started.md

@@ -1,7 +1,7 @@
 ---
 title: Get started with custom claims providers (preview)
 titleSuffix: Microsoft identity platform
-description: Use a custom authentication extension to augment tokens with claims from an external identity system. Learn how to create and deploy a custom authentication extension REST API. The REST API receives HTTP requests, or events, from the Azure AD event service and return attributes from an external data store. Learn how to register the custom authentication extensions so the Azure AD event service sends an HTTP request, or event, to your custom authentication extensionsAPI endpoint.
+description: Learn how to develop and register an Azure Active Directory custom extensions REST API. The custom extension allows you to source claims from a data store that is external to Azure Active Directory.  
 services: active-directory
 author: yoelhor
 manager: CelesteDG
@@ -19,7 +19,7 @@ ms.reviewer: JasSuri
 
 # Configure a custom claim provider token issuance event (preview)
 
-This article describes how to configure and setup a custom authentication extension with the [token issuance start event](custom-claims-provider-overview.md#token-issuance-start-event-listener) type. This event is triggered right before the token is issued, and allows you to call a REST API to add claims to the token. 
+This article describes how to configure and setup a custom claims provider with the [token issuance start event](custom-claims-provider-overview.md#token-issuance-start-event-listener) type. This event is triggered right before the token is issued, and allows you to call a REST API to add claims to the token. 
 
 This how-to guide demonstrates the token issuance start event with a REST API running in Azure Functions and a sample OpenID Connect application.
 
@@ -194,11 +194,11 @@ Create an Application Registration to authenticate your custom extension to your
 1. Paste the URL: `https://graph.microsoft.com/v1.0/applications`
 1. Select **Request Body** and paste the following JSON:
 
-```json
-{
-  "displayName": "authenticationeventsAPI"
-}
-```
+    ```json
+    {
+      "displayName": "authenticationeventsAPI"
+    }
+    ```
 
 1. Select **Run Query** to submit the request.
 
@@ -210,11 +210,11 @@ Create a service principal in the tenant for the authenticationeventsAPI app reg
 1. Paste the URL: `https://graph.microsoft.com/v1.0/servicePrincipals`
 1. Select **Request Body** and paste the following JSON:
 
-```json
-{
-    "appId": "{authenticationeventsAPI_AppId}"
-}
-```
+    ```json
+    {
+        "appId": "{authenticationeventsAPI_AppId}"
+    }
+    ```
 
 1. Select **Run Query** to submit the request.
 
@@ -226,37 +226,37 @@ Update the newly created application to set the application ID URI value, the ac
 1. Paste the URL: `https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}`
 1. Select **Request Body** and paste the following JSON:
 
-Set the application ID URI value in the *identifierUris* property. Replace `{Function_Url_Hostname}` with the hostname of the `{Function_Url}` you recorded earlier. 
-
-Set the `{authenticationeventsAPI_AppId}` value with the App ID generated from the app registration created in the previous step.
-
-An example value would be `api://authenticationeventsAPI.azurewebsites.net/f4a70782-3191-45b4-b7e5-dd415885dd80`. Take note of this value as it is used in following steps and is referenced as `{functionApp_IdentifierUri}`.
-
-```json
-{
-    "identifierUris": [
-        "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
-    ],    
-    "api": {
-        "requestedAccessTokenVersion": 2,
-        "acceptMappedClaims": null,
-        "knownClientApplications": [],
-        "oauth2PermissionScopes": [],
-        "preAuthorizedApplications": []
-    },
-    "requiredResourceAccess": [
-        {
-            "resourceAppId": "00000003-0000-0000-c000-000000000000",
-            "resourceAccess": [
-                {
-                    "id": "214e810f-fda8-4fd7-a475-29461495eb00",
-                    "type": "Role"
-                }
-            ]
-        }
-    ]
-}
-```
+    Set the application ID URI value in the *identifierUris* property. Replace `{Function_Url_Hostname}` with the hostname of the `{Function_Url}` you recorded earlier. 
+    
+    Set the `{authenticationeventsAPI_AppId}` value with the App ID generated from the app registration created in the previous step.
+    
+    An example value would be `api://authenticationeventsAPI.azurewebsites.net/f4a70782-3191-45b4-b7e5-dd415885dd80`. Take note of this value as it is used in following steps and is referenced as `{functionApp_IdentifierUri}`.
+    
+    ```json
+    {
+        "identifierUris": [
+            "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
+        ],    
+        "api": {
+            "requestedAccessTokenVersion": 2,
+            "acceptMappedClaims": null,
+            "knownClientApplications": [],
+            "oauth2PermissionScopes": [],
+            "preAuthorizedApplications": []
+        },
+        "requiredResourceAccess": [
+            {
+                "resourceAppId": "00000003-0000-0000-c000-000000000000",
+                "resourceAccess": [
+                    {
+                        "id": "214e810f-fda8-4fd7-a475-29461495eb00",
+                        "type": "Role"
+                    }
+                ]
+            }
+        ]
+    }
+    ```
 
 1. Select **Run Query** to submit the request.
 
@@ -268,35 +268,35 @@ Next, you register the custom extension. You register the custom extension by as
 1. Paste the URL: `https://graph.microsoft.com/beta/identity/customAuthenticationExtensions`
 1. Select **Request Body** and paste the following JSON:
 
-Replace `{Function_Url}` with the hostname of your Azure Function app. Replace `{functionApp_IdentifierUri}` with the identifierUri used in the previous step.
-
-```json
-{
-    "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtension",
-    "displayName": "onTokenIssuanceStartCustomExtension",
-    "description": "Fetch additional claims from custom user store",
-    "endpointConfiguration": {
-        "@odata.type": "#microsoft.graph.httpRequestEndpoint",
-        "targetUrl": "{Function_Url}"
-    },
-    "authenticationConfiguration": {
-        "@odata.type": "#microsoft.graph.azureAdTokenAuthentication",
-        "resourceId": "{functionApp_IdentifierUri}"
-    },
-    "clientConfiguration": {
-        "timeoutInMilliseconds": 2000,
-        "maximumRetries": 1
-    },
-    "claimsForTokenConfiguration": [
-        {
-            "claimIdInApiResponse": "DateOfBirth"
+    Replace `{Function_Url}` with the hostname of your Azure Function app. Replace `{functionApp_IdentifierUri}` with the identifierUri used in the previous step.
+    
+    ```json
+    {
+        "@odata.type": "#microsoft.graph.onTokenIssuanceStartCustomExtension",
+        "displayName": "onTokenIssuanceStartCustomExtension",
+        "description": "Fetch additional claims from custom user store",
+        "endpointConfiguration": {
+            "@odata.type": "#microsoft.graph.httpRequestEndpoint",
+            "targetUrl": "{Function_Url}"
         },
-        {
-            "claimIdInApiResponse": "CustomRoles"
-        }
-    ]
-}
-```
+        "authenticationConfiguration": {
+            "@odata.type": "#microsoft.graph.azureAdTokenAuthentication",
+            "resourceId": "{functionApp_IdentifierUri}"
+        },
+        "clientConfiguration": {
+            "timeoutInMilliseconds": 2000,
+            "maximumRetries": 1
+        },
+        "claimsForTokenConfiguration": [
+            {
+                "claimIdInApiResponse": "DateOfBirth"
+            },
+            {
+                "claimIdInApiResponse": "CustomRoles"
+            }
+        ]
+    }
+    ```
 
 1. Select **Run Query** to submit the request.
 
@@ -444,15 +444,15 @@ Next, create the claims mapping policy, which describes which claims can be issu
 1. Paste the URL: `https://graph.microsoft.com/v1.0/policies/claimsmappingpolicies`
 1. Select **Request Body** and paste the following JSON:
 
-```json
-{
-    "definition": [
-        "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"CustomClaimsProvider\",\"ID\":\"DateOfBirth\",\"JwtClaimType\":\"dob\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CustomRoles\",\"JwtClaimType\":\"my_roles\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CorrelationId\",\"JwtClaimType\":\"correlationId\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"ApiVersion\",\"JwtClaimType\":\"apiVersion \"},{\"Value\":\"tokenaug_V2\",\"JwtClaimType\":\"policy_version\"}]}}"
-    ],
-    "displayName": "MyClaimsMappingPolicy",
-    "isOrganizationDefault": false
-}
-```
+    ```json
+    {
+        "definition": [
+            "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"CustomClaimsProvider\",\"ID\":\"DateOfBirth\",\"JwtClaimType\":\"dob\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CustomRoles\",\"JwtClaimType\":\"my_roles\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"CorrelationId\",\"JwtClaimType\":\"correlationId\"},{\"Source\":\"CustomClaimsProvider\",\"ID\":\"ApiVersion\",\"JwtClaimType\":\"apiVersion \"},{\"Value\":\"tokenaug_V2\",\"JwtClaimType\":\"policy_version\"}]}}"
+        ],
+        "displayName": "MyClaimsMappingPolicy",
+        "isOrganizationDefault": false
+    }
+    ```
 
 1. Record the `ID` generated in the response, later it's referred to as `{claims_mapping_policy_ID}`.
 1. Select **Run Query** to submit the request.
@@ -469,11 +469,11 @@ Assign the claims mapping policy to the `servicePrincipal` of *My Test Applicati
 1. Paste the URL: `https://graph.microsoft.com/v1.0/servicePrincipals/{test_App_Service_Principal_ObjectId}/claimsMappingPolicies/$ref`
 1. Select **Request Body** and paste the following JSON:
 
-```json
-{
-    "@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/{claims_mapping_policy_ID}"
-}
-```
+    ```json
+    {
+        "@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/{claims_mapping_policy_ID}"
+    }
+    ```
 
 1. Select **Run Query** to submit the request.
 
@@ -497,7 +497,7 @@ To protect your Azure function, follow these steps to integrate Azure AD authent
 1. Unselect the **Token store** option.
 1. Select **Add** to add authentication to your Azure Function.
 
-    :::image type="content" border="false"  source="media/custom-extension-get-started/configure-auth-function-app.png" alt-text="Screenshot that shows how to add authentication to your function app." lightbox="media/custom-extension-get-started/configure-auth-function-app.png":::
+    :::image type="content" border="true"  source="media/custom-extension-get-started/configure-auth-function-app.png" alt-text="Screenshot that shows how to add authentication to your function app." lightbox="media/custom-extension-get-started/configure-auth-function-app.png":::
 
 ### 5.1 Using OpenID Connect identity provider
 

articles/active-directory/develop/custom-extension-overview.md

@@ -1,7 +1,7 @@
 ---
 title: Custom authentication extension 
 titleSuffix: Microsoft identity platform
-description: Use a custom authentication extension to augment tokens with claims from an external identity system or role management system. Custom authentication extensions can be used to migrate from AD FS or legacy systems.  You can also integrate with data stores external to your Azure AD directory or keep sensitive information stored outside of your Azure AD directory.
+description: Use Azure Active Directory custom extensions to customize your user's sign-in experience by using REST APIs or outbound webhooks.
 services: active-directory
 author: yoelhor
 manager: CelesteDG
@@ -33,8 +33,6 @@ The following diagram depicts the sign-in flow integrated with a custom extensio
 1. The Azure AD **custom extension** processes the response and customizes the authentication based on the event type and the HTTP response payload.
 1. A **token** is returned to the **app**.
 
-Depending on the custom extension, it could be integrated in different authentication journeys, for example self-service sign-up.
-
 ## Custom extension REST API endpoint
 
 When an event fires, Azure AD calls a REST API endpoint you own. The request to the REST API contains information about the event, the user profile, authentication request data, and other context information.

articles/active-directory/develop/custom-extension-troubleshoot.md

@@ -175,7 +175,7 @@ To test your API directly from the Postman, follow these steps:
 One of the most common issues is that your custom claims provider API doesn't respond within the two-seconds timeout. If your REST API doesn't respond in subsequent retries, then the authentication fails. To improve the performance of your REST API, follow the below suggestions:
 
 1. If your API accesses any downstream APIs, cache the access token used to call these APIs, so a new token doesn't have to be acquired on every execution.
-1. Performance issues are often been in a downstream service. Add logging, which records the process time to call to any downstream services. 
+1. Performance issues are often related to downstream services. Add logging, which records the process time to call to any downstream services. 
 1. If you use a cloud provider to host your API, use a hosting plan that keeps the API always "warm". For Azure Functions, it can be either [the Premium plan or Dedicated plan](../../azure-functions/functions-scale.md).
 1. [Run automated integration tests](test-automate-integration-testing.md) for your authentications. You can also use Postman or other tools to test just your API performance.