Merge pull request #223326 from csmulligan/csmulligan-exid-sssu-approvals

[EXID] Content freshness update for self-service-sign-up-add-approvals (ADO-59225)

Author: Maggiemouse1

articles/active-directory/external-identities/media/self-service-sign-up-add-approvals/api-connectors-user-flow-api.png

@@ -4,14 +4,16 @@ description: Add API connectors for custom approval workflows in External Identi
 services: active-directory
 ms.service: active-directory
 ms.subservice: B2B
-ms.topic: article
-ms.date: 07/13/2021
+ms.topic: how-to
+ms.date: 01/09/2023
 
 ms.author: mimart
 author: msmimart
 manager: celestedg
 ms.custom: "it-pro"
-ms.collection: M365-identity-device-management
+ms.collection: engagement-fy23, M365-identity-device-management
+
+# Customer intent: As a tenant administrator, I want to add API connectors for custom approval workflows in self-service sign-up.
 ---
 
 # Add a custom approval workflow to self-service sign-up
@@ -36,25 +38,22 @@ You need to register your approval system as an application in your Azure AD ten
 2. Under **Azure services**, select **Azure Active Directory**.
 3. In the left menu, select **App registrations**, and then select **New registration**.
 4. Enter a **Name** for the application, for example, _Sign-up Approvals_.
-
-   <!-- ![Register an application for the approval system](./self-service-sign-up-add-approvals/approvals/register-an-approvals-application.png) -->
-
 5. Select **Register**. You can leave other fields at their defaults.
 
-   ![Screenshot that highlights the Register button.](media/self-service-sign-up-add-approvals/register-approvals-app.png)
+:::image type="content" source="media/self-service-sign-up-add-approvals/register-approvals-app.png" alt-text="Screenshot that highlights the Register button.":::
 
 6. Under **Manage** in the left menu, select **API permissions**, and then select **Add a permission**.
 7. On the **Request API permissions** page, select **Microsoft Graph**, and then select **Application permissions**.
 8. Under **Select permissions**, expand **User**, and then select the **User.ReadWrite.All** check box. This permission allows the approval system to create the user upon approval. Then select **Add permissions**.
 
-   ![Register an application page](media/self-service-sign-up-add-approvals/request-api-permissions.png)
+:::image type="content" source="media/self-service-sign-up-add-approvals/request-api-permissions.png" alt-text="Screenshot of requesting API permissions.":::
 
 9. On the **API permissions** page, select **Grant admin consent for (your tenant name)**, and then select **Yes**.
 10. Under **Manage** in the left menu, select **Certificates & secrets**, and then select **New client secret**.
 11. Enter a **Description** for the secret, for example _Approvals client secret_, and select the duration for when the client secret **Expires**. Then select **Add**.
-12. Copy the value of the client secret.
+12. Copy the value of the client secret. Client secret values can be viewed only immediately after creation. Make sure to save the secret when created, before leaving the page.
 
-    ![Copy the client secret for use in the approval system](media/self-service-sign-up-add-approvals/client-secret-value-copy.png)
+:::image type="content" source="media/self-service-sign-up-add-approvals/client-secret-value-copy.png" alt-text="Screenshot of copying the client secret. ":::
 
 13. Configure your approval system to use the **Application ID** as the client ID and the **client secret** you generated to authenticate with Azure AD.
 
@@ -64,11 +63,11 @@ Next you'll [create the API connectors](self-service-sign-up-add-api-connector.m
 
 - **Check approval status**. Send a call to the approval system immediately after a user signs-in with an identity provider to check if the user has an existing approval request or has already been denied. If your approval system only does automatic approval decisions, this API connector may not be needed. Example of a "Check approval status" API connector.
 
-  ![Check approval status  API connector configuration](./media/self-service-sign-up-add-approvals/check-approval-status-api-connector-config-alt.png)
+:::image type="content" source="media/self-service-sign-up-add-approvals/check-approval-status-api-connector-config-alt.png" alt-text="Screenshot of check approval status API connector configuration.":::
 
 - **Request approval** - Send a call to the approval system after a user completes the attribute collection page, but before the user account is created, to request approval. The approval request can be automatically granted or manually reviewed. Example of a "Request approval" API connector. 
 
-  ![Request approval API connector configuration](./media/self-service-sign-up-add-approvals/create-approval-request-api-connector-config-alt.png)
+:::image type="content" source="media/self-service-sign-up-add-approvals/create-approval-request-api-connector-config-alt.png" alt-text="Screenshot of request approval API connector configuration.":::
 
 To create these connectors, follow the steps in [create an API connector](self-service-sign-up-add-api-connector.md#create-an-api-connector).
 
@@ -85,13 +84,14 @@ Now you'll add the API connectors to a self-service sign-up user flow with these
    - **After federating with an identity provider during sign-up**: Select your approval status API connector, for example _Check approval status_.
    - **Before creating the user**: Select your approval request API connector, for example _Request approval_.
 
-   ![Add APIs to the user flow](./media/self-service-sign-up-add-approvals/api-connectors-user-flow-api.png)
+:::image type="content" source="media/self-service-sign-up-add-approvals/api-connectors-user-flow-api.png" alt-text="Screenshot of API connector in a user flow.":::
+
 
 6. Select **Save**.
 
 ## Control the sign-up flow with API responses
 
-Your approval system can use its responses when called to control the sign up flow. 
+Your approval system can use its responses when called to control the sign-up flow. 
 
 ### Request and responses for the "Check approval status" API connector
 
@@ -117,13 +117,13 @@ Content-type: application/json
 }
 ```
 
-The exact claims sent to the API depends on which information is provided by the identity provider. 'email' is always sent.
+The exact claims sent to the API depend on which information is provided by the identity provider. 'email' is always sent.
 
 #### Continuation response for "Check approval status"
 
 The **Check approval status** API endpoint should return a continuation response if:
 
-- The user has not previously requested an approval.
+- The user hasn't previously requested an approval.
 
 Example of the continuation response:
 
@@ -200,7 +200,7 @@ Content-type: application/json
 }
 ```
 
-The exact claims sent to the API depends on which information is collected from the user or is provided by the identity provider.
+The exact claims sent to the API depend on which information is collected from the user or is provided by the identity provider.
 
 #### Continuation response for "Request approval"
 
@@ -385,5 +385,7 @@ Content-type: application/json
 
 ## Next steps
 
-- Get started with our [Azure Function quickstart samples](code-samples-self-service-sign-up.md#api-connector-azure-function-quickstarts).
-- Checkout the [self-service sign-up for guest users with manual approval sample](code-samples-self-service-sign-up.md#custom-approval-workflows).
+- [Add a self-service sign-up user flow](self-service-sign-up-user-flow.md)
+- [Add an API connector](self-service-sign-up-add-api-connector.md)
+- [Secure your API connector](self-service-sign-up-secure-api-connector.md)
+- [self-service sign-up for guest users with manual approval sample](code-samples-self-service-sign-up.md#custom-approval-workflows).

articles/active-directory/external-identities/media/self-service-sign-up-add-approvals/check-approval-status-api-connector-config-alt.png

@@ -5,18 +5,21 @@ services: active-directory
 ms.service: active-directory
 ms.subservice: B2B
 ms.topic: how-to
-ms.date: 10/12/2022
+ms.date: 01/06/2023
 
 ms.author: mimart
 author: msmimart
 manager: CelesteDG
 ms.custom: "it-pro"
-ms.collection: M365-identity-device-management
+ms.collection: engagement-fy23, M365-identity-device-management
+
+# Customer intent: As a tenant administrator, I want to set up user flows that allow a user to sign up for an app and create a new guest account. 
+
 ---
 
 # Add a self-service sign-up user flow to an app
 
-For applications you build, you can create user flows that allow a user to sign up for an app and create a new guest account. A self-service sign-up user flow defines the series of steps the user will follow during sign-up, the identity providers you'll allow them to use, and the user attributes you want to collect. You can associate one or more applications with a single user flow.
+For applications you build, you can create user flows that allow a user to sign up for an app and create a new guest account. A self-service sign-up user flow defines the series of steps the user will follow during sign-up, the [identity providers](identity-providers.md) you'll allow them to use, and the user attributes you want to collect. You can associate one or more applications with a single user flow.
 
 > [!NOTE]
 > You can associate user flows with apps built by your organization. User flows can't be used for Microsoft apps, like SharePoint or Teams.
@@ -25,12 +28,12 @@ For applications you build, you can create user flows that allow a user to sign
 
 ### Add identity providers (optional)
 
-Azure AD is the default identity provider for self-service sign-up. This means that users are able to sign up by default with an Azure AD account. In your self-service sign-up user flows, you can also include social identity providers like Google and Facebook, Microsoft Account, and Email One-time Passcode. For more information, see these articles:
+Azure AD is the default identity provider for self-service sign-up. This means that users are able to sign up by default with an Azure AD account. In your self-service sign-up user flows, you can also include social identity providers like Google and Facebook, Microsoft Account, and the email one-time passcode feature. For more information, see these articles:
 
-- [Microsoft Account identity provider](microsoft-account.md)
-- [Email one-time passcode authentication](one-time-passcode.md)
-- [Add Facebook to your list of social identity providers](facebook-federation.md)
 - [Add Google to your list of social identity providers](google-federation.md)
+- [Add Facebook to your list of social identity providers](facebook-federation.md)
+- [Add Microsoft account as an identity provider](microsoft-account.md)
+- [Email one-time passcode authentication](one-time-passcode.md)
 
 ### Define custom attributes (optional)
 
@@ -45,8 +48,9 @@ Before you can add a self-service sign-up user flow to your applications, you ne
 
 1. Sign in to the [Azure portal](https://portal.azure.com) as an Azure AD administrator.
 2. Under **Azure services**, select **Azure Active Directory**.
-3. Select **User settings**, and then under **External users**, select **Manage external collaboration settings**.
-4. Set the **Enable guest self-service sign up via user flows** toggle to **Yes**.
+1. Under **Manage** in the left menu, select **Users**.
+1. Select **User settings**, and then under **External users**, select **Manage external collaboration settings**.
+1. Set the **Enable guest self-service sign up via user flows** toggle to **Yes**.
 
    ![Enable guest self-service sign-up](media/self-service-sign-up-user-flow/enable-self-service-sign-up.png)
 5. Select **Save**.