Quickstart API-driven inbound provisioning with Postman (Public preview)

Article
11/15/2023

This tutorial describes how you can quickly test API-driven inbound provisioning with Postman.

Pre-requisites

You have configured API-driven inbound provisioning app.
You have configured a service principal and it has access to the inbound provisioning API. Make note of the TenantId, ClientId and ClientSecret of your service principal app for use in this tutorial.

Upload user data to the inbound provisioning API

In this step, you'll configure the Postman app and invoke the API using the configured service account.

Download and install the Postman app.
Open the Postman desktop app.
From the Workspaces menu, select Create Workspace to create a new Workspace called Microsoft Entra provisioning API.
Download the following Postman collections and save it in your local directory.
- Microsoft Entra Inbound Provisioning.postman_collection.json (Request collection)
- Test-API2AAD.postman_environment.json (Environment collection for API-driven provisioning to Microsoft Entra ID)-
- Test-API2AD.postman_environment.json (Environment collection for API-driven provisioning to on-premises AD)
Use the Import option in Postman to import both of these files into your Workspace.
Click the Environments menu and open the Test-API2AAD environment.
Retrieve the values of client_id, client_secret, and token_endpoint from your registered app.
Paste the values in the table for each variable under the column Initial value and Current value.
Open your provisioning app landing page and copy-paste the value of Job ID for the jobId variable and the value of Provisioning API endpoint for the bulk_upload_endpoint variable
Leave the value of ms_graph_resource_id unchanged and save the environment collection. Make sure that both Initial value and Current value columns are populated.
Next, open the collection Microsoft Entra Inbound Provisioning.
From the Environment dropdown, select Test-API2AAD.
Select the Authorization tab associated with the collection.
Make sure that authorization is configured to use OAuth settings.
The Advanced options section should show the following configuration:
Click on Get New Access Token to initiate the process to procure an access token.
Select the option Use Token to use the access token with all requests in this collection.

Note

The OAuth access token generated using client_credentials grant type is valid for one hour. You can decode the token using https://jwt.ms and check when it expires. Requests fail after the token expires. If your access token has expired, click Get New Access Token in Postman to get a new access token. The token is automatically copied into the Current token section of the Authorization tab. You can now use the token to make API calls. Let's start with the first call in this collection.
Open the request SCIM bulk request upload.
Under the Authorization tab, make sure that type is set to Inherit auth from parent.
Change to the Request body tab, to view and edit the sample SCIM bulk request. When you're done editing, click Send.

If the API invocation is successful, you see the message 202 Accepted. Under Headers, the Location attribute points to the provisioning logs API endpoint.

Verify processing of bulk request payload

You can verify the processing either from the Microsoft Entra admin center or using Postman.

Verify processing from Microsoft Entra admin center

Log in to Microsoft Entra admin center with at least Application Administrator level credentials.
Browse to Microsoft Entra ID -> Applications -> Enterprise applications.
Under all applications, use the search filter text box to find and open your API-driven provisioning application.
Open the Provisioning blade. The landing page displays the status of the last run.
Click on View provisioning logs to open the provisioning logs blade. Alternatively, you can click on the menu option Monitor -> Provisioning logs.
Click on any record in the provisioning logs to view additional processing details.
The provisioning log details screen displays all the steps executed for a specific user.
- Under the Import from API step, see details of user data extracted from the bulk request.
- The Match user step shows details of any user match based on the matching identifier. If a user match happens, then the provisioning service performs an update operation. If there is no user match, then the provisioning service performs a create operation.
- The Determine if User is in scope step shows details of scoping filter evaluation. By default, all users are processed. If you have set a scoping filter (example, process only users belonging to the Sales department), the evaluation details of the scoping filter displays in this step.
- 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.

Verify processing using provisioning logs API in Postman

This section shows how you can query provisioning logs in Postman using the same service account (service principal) that you configured.

Open the workspace Microsoft Entra provisioning API in your Postman desktop app.
The collection Microsoft Entra Inbound Provisioning contains three sample requests that enable you to query the provisioning logs.
You can open any of these predefined requests.
If you don't have a valid access token or you're not sure if the access token is still valid, go to the collection object's root Authorization tab and use the option Get New Access Token to get a fresh token.
Click Send to get provisioning log records. Upon successful execution, you'll get a 200 HTTP response from the server along with the provisioning log records.

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

{
    "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": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "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": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "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
}