Merge pull request #244582 from MicrosoftDocs/main

Publish to live, Tuesday 4 AM PST, 7/11

Author: ttorble

articles/active-directory/app-provisioning/inbound-provisioning-api-concepts.md

@@ -0,0 +1,80 @@
+---
+title: API-driven inbound provisioning concepts
+description: An overview of API-driven inbound provisioning. 
+services: active-directory
+author: jenniferf-skc
+manager: amycolannino
+ms.service: active-directory
+ms.subservice: app-provisioning
+ms.workload: identity
+ms.topic: reference
+ms.date: 06/22/2023
+ms.author: jfields
+ms.reviewer: chmutali
+---
+
+# API-driven inbound provisioning concepts (Public preview)
+
+This document provides a conceptual overview of the Azure AD API-driven inbound user provisioning.
+
+> [!IMPORTANT]
+> API-driven inbound provisioning is currently in public preview and is governed by [Preview Terms of Use](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
+
+## Introduction
+
+Today enterprises have a variety of authoritative systems of record. To establish end-to-end identity lifecycle, strengthen security posture and stay compliant with regulations, identity data in Azure Active Directory must be kept in sync with workforce data managed in these systems of record. The *system of record* could be an HR app, a payroll app, a spreadsheet or SQL tables in a database hosted either on-premises or in the cloud. 
+
+With API-driven inbound provisioning, the Azure AD provisioning service now supports integration with *any* system of record. Customers and partners can use *any* automation tool of their choice to retrieve workforce data from the system of record and ingest it into Azure AD. The IT admin has full control on how the data is processed and transformed with attribute mappings. Once the workforce data is available in Azure AD, the IT admin can configure appropriate joiner-mover-leaver business processes using [Lifecycle Workflows](../governance/what-are-lifecycle-workflows.md).  
+
+## Supported scenarios
+
+Several inbound user provisioning scenarios are enabled using API-driven inbound provisioning. This diagram demonstrates the most common scenarios.
+
+:::image type="content" source="media/inbound-provisioning-api-concepts/api-workflow-scenarios.png" alt-text="Diagram that shows API scenarios." lightbox="media/inbound-provisioning-api-concepts/api-workflow-scenarios.png":::
+
+### Scenario 1: Enable IT teams to import HR data extracts using any automation tool
+Flat files, CSV files and SQL staging tables are commonly used in enterprise integration scenarios. Employee, contractor and vendor information are periodically exported into one of these formats and an automation tool is used to sync this data with enterprise identity directories. With API-driven inbound provisioning, IT teams can use any automation tool of their choice (example: PowerShell scripts or Azure Logic Apps) to modernize and simplify this integration.   
+
+### Scenario 2: Enable ISVs to build direct integration with Azure AD
+With API-driven inbound provisioning, HR ISVs can ship native synchronization experiences so that changes in the HR system automatically flow into Azure AD and connected on-premises Active Directory domains. For example, an HR app or student information systems app can send data to Azure AD as soon as a transaction is complete or as end-of-day bulk update. 
+
+### Scenario 3: Enable system integrators to build more connectors to systems of record
+Partners can build custom HR connectors to meet different integration requirements around data flow from systems of record to Azure AD. 
+
+In all the above scenarios, the integration is greatly simplified as Azure AD provisioning service takes over the responsibility of performing identity profile comparison, restricting the data sync to scoping logic configured by the IT admin and executing rule-based attribute flow and transformation managed in the Microsoft Entra admin portal.   
+
+## End-to-end flow
+:::image type="content" source="media/inbound-provisioning-api-concepts/end-to-end-workflow.png" alt-text="Diagram of the end-to-end workflow of inbound provisioning." lightbox="media/inbound-provisioning-api-concepts/end-to-end-workflow.png":::
+
+### Steps of the workflow
+
+1. IT Admin configures an API-driven inbound user provisioning app from the Microsoft Entra Enterprise App gallery. 
+2. IT Admin provides endpoint access details to the API developer/partner/system integrator.
+3. The API developer/partner/system integrator builds an API client to send authoritative identity data to Azure AD.
+4. The API client reads identity data from the authoritative source.
+5. The API client sends a POST request to provisioning [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint associated with the provisioning app. 
+     >[!NOTE] 
+     > The API client doesn't need to perform any comparisons between the source attributes and the target attribute values to determine what operation (create/update/enable/disable) to invoke. This is automatically handled by the provisioning service. The API client simply uploads the identity data read from the source system by packaging it as bulk request using SCIM schema constructs. 
+1. If successful, an ```Accepted 202 Status``` is returned. 
+1. The Azure AD Provisioning Service processes the data received, applies the attribute mapping rules and completes user provisioning.
+1. Depending on the provisioning app configured, the user is provisioned either into on-premises Active Directory (for hybrid users) or Azure AD (for cloud-only users).
+1. The API Client then queries the provisioning logs API endpoint for the status of each record sent.
+1. If the processing of any record fails, the API client can check the error details and include records corresponding to the failed operations in the next bulk request (step 5). 
+1. At any time, the IT Admin can check the status of the provisioning job and view events in the provisioning logs.
+
+### Key features of API-driven inbound user provisioning
+
+- Delivered as a provisioning app that that exposes an *asynchronous* Microsoft Graph provisioning [/bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API endpoint accessed using valid OAuth token.
+- Tenant admins must grant API clients interacting with this provisioning app the Graph permission `SynchronizationData-User.Upload`. 
+- The Graph API endpoint accepts valid bulk request payloads using SCIM schema constructs.
+- With SCIM schema extensions, you can send any attribute in the bulk request payload. 
+- The rate limit for the inbound provisioning API is 40 bulk upload requests per second. Each bulk request can contain a maximum of 50 user records, thereby supporting an upload rate of 2000 records per second. 
+- Each API endpoint is associated with a specific provisioning app in Azure AD. You can integrate multiple data sources by creating a provisioning app for each data source. 
+- Incoming bulk request payloads are processed in near real-time.
+- Admins can check provisioning progress by viewing the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md). 
+- API clients can track progress by querying [provisioning logs API](/graph/api/resources/provisioningobjectsummary).
+
+## Next steps
+- [Configure API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md)
+- [Frequently asked questions about API-driven inbound provisioning](inbound-provisioning-api-faqs.md)
+- [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](user-provisioning.md)

articles/active-directory/app-provisioning/inbound-provisioning-api-configure-app.md

@@ -0,0 +1,117 @@
+---
+title: Configure API-driven inbound provisioning app
+description: Learn how to configure API-driven inbound provisioning app.
+services: active-directory
+author: jenniferf-skc
+manager: amycolannino
+ms.service: active-directory
+ms.subservice: app-provisioning
+ms.workload: identity
+ms.topic: how-to
+ms.date: 07/07/2023
+ms.author: jfields
+ms.reviewer: cmmdesai
+---
+
+# Configure API-driven inbound provisioning app (Public preview)
+
+## Introduction
+This tutorial describes how to configure [API-driven inbound user provisioning](inbound-provisioning-api-concepts.md). 
+
+> [!IMPORTANT]
+> API-driven inbound provisioning is currently in public preview and is governed by [Preview Terms of Use](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
+
+This feature is available only when you configure the following Enterprise Gallery apps: 
+* API-driven inbound user provisioning to Azure AD
+* API-driven inbound user provisioning to on-premises AD
+
+## Prerequisites
+To complete the steps in this tutorial, you need access to Microsoft Entra admin portal with the following roles: 
+
+* Global administrator OR
+* Application administrator (if you're configuring inbound user provisioning to Azure AD) OR
+* Application administrator + Hybrid identity administrator (if you're configuring inbound user provisioning to on-premises Active Directory)
+
+If you're configuring inbound user provisioning to on-premises Active Directory, you need access to a Windows Server where you can install the provisioning agent for connecting to your Active Directory domain controller. 
+
+## Create your API-driven provisioning app
+
+1. Log in to the [Microsoft Entra portal](<https://entra.microsoft.com>).
+2. Browse to **Azure Active Directory -> Applications -> Enterprise applications**.
+3. Click on **New application** to create a new provisioning application. 
+     [![Screenshot of Entra Admin Center.](media/inbound-provisioning-api-configure-app/provisioning-entra-admin-center.png)](media/inbound-provisioning-api-configure-app/provisioning-entra-admin-center.png#lightbox)
+4. Enter **API-driven** in the search field, then select the application for your setup:
+     * **API-driven Inbound User Provisioning to On-Premises AD**: Select this app if you're provisioning hybrid identities (identities that need both on-premises AD and Azure AD account) from your system of record. Once these accounts are provisioned in on-premises AD, they are automatically synchronized to your Azure AD tenant using Azure AD Connect or Cloud Sync.
+     * **API-driven Inbound User Provisioning to Azure AD**: Select this app if you're provisioning cloud-only identities (identities that don't require on-premises AD accounts and only need Azure AD account) from your system of record.
+     
+     [![Screenshot of API-driven provisioning apps.](media/inbound-provisioning-api-configure-app/api-driven-inbound-provisioning-apps.png)](media/inbound-provisioning-api-configure-app/api-driven-inbound-provisioning-apps.png#lightbox)
+
+5. In the **Name** field, rename the application to meet your naming requirements, then click **Create**.
+
+     [![Screenshot of create app.](media/inbound-provisioning-api-configure-app/provisioning-create-inbound-provisioning-app.png)](media/inbound-provisioning-api-configure-app/provisioning-create-inbound-provisioning-app.png#lightbox)
+
+     > [!NOTE]
+     > If you plan to ingest data from multiple sources, each with their own sync rules, you can create multiple apps and give each app a descriptive name; for example, Provision-Employees-From-CSV-to-AD or Provision-Contractors-From-SQL-to-AD.
+6. Once the application creation is successful, go to the Provisioning blade and click on **Get started**.
+     [![Screenshot of Get started button.](media/inbound-provisioning-api-configure-app/provisioning-overview-get-started.png)](media/inbound-provisioning-api-configure-app/provisioning-overview-get-started.png#lightbox)
+7. Switch the Provisioning Mode from Manual to **Automatic**.
+
+Depending on the app you selected, use one of the following sections to complete your setup: 
+* [Configure API-driven inbound provisioning to on-premises AD](#configure-api-driven-inbound-provisioning-to-on-premises-ad)
+* [Configure API-driven inbound provisioning to Azure AD](#configure-api-driven-inbound-provisioning-to-azure-ad)
+
+## Configure API-driven inbound provisioning to on-premises AD
+
+1. After setting the Provisioning Mode to **Automatic**, click on **Save** to create the initial configuration of the provisioning job. 
+1. Click on the information banner about the Azure AD Provisioning Agent.
+     [![Screenshot of provisioning agent banner.](media/inbound-provisioning-api-configure-app/provisioning-agent-banner.png)](media/inbound-provisioning-api-configure-app/provisioning-agent-banner.png#lightbox)
+1. Click **Accept terms & download** to download the Azure AD Provisioning Agent.
+1. Refer to the steps documented here to [install and configure the provisioning agent.](https://go.microsoft.com/fwlink/?linkid=2241216). This step registers your on-premises Active Directory domains with your Azure AD tenant.
+1. Once the agent registration is successful, select your domain in the drop-down **Active Directory domain** and specify the distinguished name of the OU where new user accounts are created by default.
+     [![Screenshot of Active Directory domain selected.](media/inbound-provisioning-api-configure-app/provisioning-select-active-directory-domain.png)](media/inbound-provisioning-api-configure-app/provisioning-select-active-directory-domain.png#lightbox)
+     > [!NOTE]
+     > If your AD domain is not visible in the **Active Directory Domain** dropdown list, reload the provisioning app in the browser. Click on **View on-premises agents for your domain** to ensure that your agent status is healthy.
+1. Click on **Test connection** to ensure that Azure AD can connect to the provisioning agent.
+1. Click on **Save** to save your changes.
+1. Once the save operation is successful, you'll see two more expansion panels – one for **Mappings** and one for **Settings**. Before proceeding to the next step, provide a valid notification email ID and save the configuration again.
+     [![Screenshot of the notification email box.](media/inbound-provisioning-api-configure-app/provisioning-notification-email.png)](media/inbound-provisioning-api-configure-app/provisioning-notification-email.png#lightbox)
+     > [!NOTE]
+     > Providing the **Notification Email** in **Settings** is mandatory. If the Notification Email is left empty, then the provisioning goes into quarantine when you start the execution.
+1. Click on hyperlink in the **Mappings** expansion panel to view the default attribute mappings. 
+     > [!NOTE]
+     > The default configuration in the **Attribute Mappings** page maps SCIM Core User and Enterprise User attributes to on-premises AD attributes. We recommend using the default mappings to get started and customizing these mappings later as you get more familiar with the overall data flow.
+1. Complete the configuration by following steps in the section [Start accepting provisioning requests](#start-accepting-provisioning-requests).
+
+
+## Configure API-driven inbound provisioning to Azure AD
+ 
+
+1. After setting the Provisioning Mode to **Automatic**, click on **Save** to create the initial configuration of the provisioning job. 
+1. Once the save operation is successful, you will see two more expansion panels – one for **Mappings** and one for **Settings**. Before proceeding to the next step, make sure you provide a valid notification email id and Save the configuration once more. 
+
+     [![Screenshot of the notification email box.](media/inbound-provisioning-api-configure-app/provisioning-notification-email.png)](media/inbound-provisioning-api-configure-app/provisioning-notification-email.png#lightbox)
+
+     > [!NOTE]
+     > Providing the **Notification Email** in **Settings** is mandatory. If the Notification Email is left empty, then the provisioning goes into quarantine when you start the execution.
+1. Click on hyperlink in the **Mappings** expansion panel to view the default attribute mappings. 
+     > [!NOTE]
+     > The default configuration in the **Attribute Mappings** page maps SCIM Core User and Enterprise User attributes to on-premises AD attributes. We recommend using the default mappings to get started and customizing these mappings later as you get more familiar with the overall data flow.
+1. Complete the configuration by following steps in the section [Start accepting provisioning requests](#start-accepting-provisioning-requests).
+
+## Start accepting provisioning requests
+
+1. Open the provisioning application's **Provisioning** -> **Overview** page. 
+1. On this page, you can take the following actions: 
+     - **Start provisioning** control button – Click on this button to place the provisioning job in **listen mode** to process inbound bulk upload request payloads.  
+     - **Stop provisioning** control button – Use this option to pause/stop the provisioning job. 
+     - **Restart provisioning** control button – Use this option to purge any existing request payloads pending processing and start a new provisioning cycle. 
+     - **Edit provisioning** control button – Use this option to edit the job settings, attribute mappings and to customize the provisioning schema. 
+     - **Provision on demand** control button – This feature is not yet enabled in private preview. 
+     - **Provisioning API Endpoint** URL text – Copy the HTTPS URL value shown and save it in a Notepad or OneNote for use later with the API client.
+1. Expand the **Statistics to date** > **View technical information** panel and copy the **Provisioning API Endpoint** URL. Share this URL with your API developer after [granting access permission](inbound-provisioning-api-grant-access.md) to invoke the API. 
+
+## Next steps
+- [Grant access to the inbound provisioning API](inbound-provisioning-api-grant-access.md)
+- [Frequently asked questions about API-driven inbound provisioning](inbound-provisioning-api-faqs.md)
+- [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](user-provisioning.md)
+