Merge pull request #245758 from cmmdesai/quick-start-ps

API-driven provisioning with PowerShell

Author: American-Dipper

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

@@ -101,12 +101,13 @@ Depending on the app you selected, use one of the following sections to complete
 ## Start accepting provisioning requests
 
 1. Open the provisioning application's **Provisioning** -> **Overview** page. 
+      :::image type="content" source="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png" alt-text="Screenshot of Provisioning API endpoint." lightbox="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png":::
 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. 
+     - **Provision on demand** control button – This feature is not supported for API-driven inbound provisioning. 
      - **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. 
 

articles/active-directory/app-provisioning/inbound-provisioning-api-curl-tutorial.md

@@ -21,16 +21,16 @@ ms.reviewer: cmmdesai
 ## Pre-requisites
 
 * You have configured [API-driven inbound provisioning app](inbound-provisioning-api-configure-app.md). 
-* You have [configured a service principal and it has access](inbound-provisioning-api-grant-access.md) to the inbound provisioning API.
+* You have [configured a service principal and it has access](inbound-provisioning-api-grant-access.md) to the inbound provisioning API. Make note of the `ClientId` and `ClientSecret` of your service principal app for use in this tutorial. 
 
-## Upload user data to the inbound provisioning API using cURL
+## Upload user data to the inbound provisioning API
 
 1. Retrieve the **client_id** and **client_secret** of the service principal that has access to the inbound provisioning API. 
 1. Use OAuth **client_credentials** grant flow to get an access token. Replace the variables `[yourClientId]`, `[yourClientSecret]` and `[yourTenantId]` with values applicable to your setup and run the following cURL command. Copy the access token value generated 
      ```
      curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=[yourClientId]&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=[yourClientSecret]&grant_type=client_credentials" "https://login.microsoftonline.com/[yourTenantId]/oauth2/v2.0/token"
      ```
-1. Copy the bulk request payload from the example [Bulk upload using SCIM core user and enterprise user schema](/graph/api/synchronization-synchronizationjob-post-bulkupload#example-1-bulk-upload-using-scim-core-user-and-enterprise-user-schema) and save the contents in a file called scim-bulk-upload-users.json.
+1. Copy the [bulk request with SCIM Enterprise User Schema](#bulk-request-with-scim-enterprise-user-schema) and save the contents in a file called scim-bulk-upload-users.json.
 1. Replace the variable `[InboundProvisioningAPIEndpoint]` with the provisioning API endpoint associated with your provisioning app. Use the `[AccessToken]` value from the previous step and run the following curl command to upload the bulk request to the provisioning API endpoint. 
      ```
      curl -v "[InboundProvisioningAPIEndpoint]" -d @scim-bulk-upload-users.json -H "Authorization: Bearer [AccessToken]" -H "Content-Type: application/scim+json"
@@ -57,6 +57,152 @@ ms.reviewer: cmmdesai
       * The **Provision User** step calls out the final processing step and changes applied to the user account.
       * Use the **Modified properties** tab to view attribute updates.
 
+## Appendix
+
+### Bulk request with SCIM Enterprise User Schema
+The bulk request shown below uses the SCIM standard Core User and Enterprise User schema. 
+
+**Request body**
+# [HTTP](#tab/http)
+<!-- {
+  "blockType": "request",
+  "name": "Quick_start_with_curl"
+}-->
+```http
+{
+    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
+    "Operations": [
+    {
+        "method": "POST",
+        "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",
+        "path": "/Users",
+        "data": {
+            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
+            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
+            "externalId": "701984",
+            "userName": "[email protected]",
+            "name": {
+                "formatted": "Ms. Barbara J Jensen, III",
+                "familyName": "Jensen",
+                "givenName": "Barbara",
+                "middleName": "Jane",
+                "honorificPrefix": "Ms.",
+                "honorificSuffix": "III"
+            },
+            "displayName": "Babs Jensen",
+            "nickName": "Babs",
+            "emails": [
+            {
+              "value": "[email protected]",
+              "type": "work",
+              "primary": true
+            }
+            ],
+            "addresses": [
+            {
+              "type": "work",
+              "streetAddress": "100 Universal City Plaza",
+              "locality": "Hollywood",
+              "region": "CA",
+              "postalCode": "91608",
+              "country": "USA",
+              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
+              "primary": true
+            }
+            ],
+            "phoneNumbers": [
+            {
+              "value": "555-555-5555",
+              "type": "work"
+            }
+            ],
+            "userType": "Employee",
+            "title": "Tour Guide",
+            "preferredLanguage": "en-US",
+            "locale": "en-US",
+            "timezone": "America/Los_Angeles",
+            "active":true,
+            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
+                 "employeeNumber": "701984",
+                 "costCenter": "4130",
+                 "organization": "Universal Studios",
+                 "division": "Theme Park",
+                 "department": "Tour Operations",
+                 "manager": {
+                     "value": "89607",
+                     "displayName": "John Smith"
+                 }
+            }
+        }
+    },
+    {
+        "method": "POST",
+        "bulkId": "897401c2-2de4-4b87-a97f-c02de3bcfc61",
+        "path": "/Users",
+        "data": {
+            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
+            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
+            "externalId": "701985",
+            "userName": "[email protected]",
+            "name": {
+                "formatted": "Ms. Kathy J Jensen, III",
+                "familyName": "Jensen",
+                "givenName": "Kathy",
+                "middleName": "Jane",
+                "honorificPrefix": "Ms.",
+                "honorificSuffix": "III"
+            },
+            "displayName": "Kathy Jensen",
+            "nickName": "Kathy",
+            "emails": [
+            {
+              "value": "[email protected]",
+              "type": "work",
+              "primary": true
+            }
+            ],
+            "addresses": [
+            {
+              "type": "work",
+              "streetAddress": "100 Oracle City Plaza",
+              "locality": "Hollywood",
+              "region": "CA",
+              "postalCode": "91618",
+              "country": "USA",
+              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
+              "primary": true
+            }
+            ],
+            "phoneNumbers": [
+            {
+              "value": "555-555-5545",
+              "type": "work"
+            }
+            ],
+            "userType": "Employee",
+            "title": "Tour Lead",
+            "preferredLanguage": "en-US",
+            "locale": "en-US",
+            "timezone": "America/Los_Angeles",
+            "active":true,
+            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
+                 "employeeNumber": "701985",
+                 "costCenter": "4130",
+                 "organization": "Universal Studios",
+                 "division": "Theme Park",
+                 "department": "Tour Operations",
+                 "manager": {
+                     "value": "701984",
+                     "displayName": "Barbara Jensen"
+                 }
+            }
+        }
+    }
+],
+    "failOnErrors": null
+}
+```
+
 ## Next steps
 - [Troubleshoot issues with the inbound provisioning API](inbound-provisioning-api-issues.md)
 - [API-driven inbound provisioning concepts](inbound-provisioning-api-concepts.md)

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

@@ -48,8 +48,11 @@ Yes, the provisioning API supports on-premises AD domains as a target.
 
 ## How do we get the /bulkUpload API endpoint for our provisioning app?
 
-The /bulkUpload API is available only for apps of the type: "API-driven inbound provisioning to Azure AD" and "API-driven inbound provisioning to on-premises Active Directory". You can retrieve the unique API endpoint for each provisioning app from the Provisioning blade home page.  In **Statistics to date** > **View technical information**,copy the **Provisioning API Endpoint** URL. It has the format:
+The /bulkUpload API is available only for apps of the type: "API-driven inbound provisioning to Azure AD" and "API-driven inbound provisioning to on-premises Active Directory". You can retrieve the unique API endpoint for each provisioning app from the Provisioning blade home page.  In **Statistics to date** > **View technical information**,copy the **Provisioning API Endpoint** URL. 
 
+  :::image type="content" source="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png" alt-text="Screenshot of Provisioning API endpoint." lightbox="media/inbound-provisioning-api-configure-app/provisioning-api-endpoint.png":::
+
+It has the format:
 ```http
 https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
 ```
@@ -145,11 +148,15 @@ If the attribute is set to **true**, the default mapping rule enables the accoun
 
 ## Can we soft-delete a user in Azure AD using /bulkUpload provisioning API?
 
-No. Currently the provisioning service only supports enabling or disabling an account in Azure AD/on-premises AD.
+Yes, you can soft-delete a user by using the **DELETE** method in the bulk request operation. Refer to the [bulkUpload](/graph/api/synchronization-synchronizationjob-post-bulkupload) API spec doc for an example request. 
 
 ## How can we prevent accidental disabling/deletion of users?
 
-You can enable accidental deletion prevention. See [Enable accidental deletions prevention in the Azure AD provisioning service](accidental-deletions.md)
+To prevent and recover from accidental deletions, we recommend [configuring accidental deletion threshold](accidental-deletions.md) in the provisioning app and [enabling the on-premises Active Directory recycle bin](../hybrid/connect/how-to-connect-sync-recycle-bin.md). In your provisioning app's **Attribute Mapping** blade, under **Target object actions** disable the **Delete** operation.  
+
+**Recovering deleted accounts**
+* If the target directory for the operation is Azure AD, then the matched user is soft-deleted. The user can be seen on the Microsoft Azure portal **Deleted users** page for the next 30 days and can be restored during that time.
+* If the target directory for the operation is on-premises Active Directory, then the matched user is hard-deleted. If the **Active Directory Recycle Bin** is enabled, you can restore the deleted on-premises AD user object.
 
 ## Do we need to send all users from the HR system in every request?
 

articles/active-directory/app-provisioning/inbound-provisioning-api-grant-access.md

@@ -43,7 +43,8 @@ This configuration registers an app in Azure AD that represents the external API
 1. Search and select permission **AuditLog.Read.All** and **SynchronizationData-User.Upload**.
 1. Click on **Grant admin consent** on the next screen to complete the permission assignment. Click Yes on the confirmation dialog. Your app should have the following permission sets.
       [![Screenshot of app permissions.](media/inbound-provisioning-api-grant-access/api-client-permissions.png)](media/inbound-provisioning-api-grant-access/api-client-permissions.png#lightbox)  
-1. You're now ready to use the service principal with your API client. 
+1. You're now ready to use the service principal with your API client.
+1. For production workloads, we recommend using [client certificate-based authentication](../develop/howto-authenticate-service-principal-powershell.md) with the service principal or managed identities. 
 
 ## Configure a managed identity