Synchronize data between IDM and Azure Active Directory

Azure Active Directory (Azure AD) is Microsoft’s cloud-based identity and access management service that lets users sign in and access resources. This sample uses the Microsoft Graph API connector to synchronize IDM managed users and Azure AD users.

Prepare the sample

Before you can run this sample, you must register an application with Azure. You need a Microsoft Azure subscription to complete this procedure:

Log in to the MS Azure portal as an administrative user.
Under Azure services , select App registrations.
On the Register an application page, enter a name for the application; for example, FR-Connector.
Select the supported account types, and enter a Redirect URI.

The redirect URI is the IDM URI that Azure should redirect to after successful authentication; for example, https://idm.example.com:8443/.
On the new registration page for your application, make a note of the Application (client) ID and the Directory (tenant) ID. You will need these to configure the connector:
Generate a client secret:
1. Select Certificates & secrets > New client secret .
2. Enter a description, select an expiration date, and click Add.
3. Copy the client secret Value:
You will not be able to retrieve the client secret in cleartext after you exit this screen.
Set the API permissions:
1. Select API permissions, click Microsoft Graph, and then click Application permissions.
2. From the User item, select the following permissions:
  - User.Export.All
  - User.ManageIdentities.All
  - User.Read.All
  - User.ReadWrite.All
3. From the Group item, select the following permissions:
  - Group.Create
  - Group.Read.All
  - Group.ReadWrite.All
4. From the Directory item, select the following permissions:
  - Directory.Read.All
  - Directory.ReadWrite.All
5. Click Add permissions .
Grant admin consent for the API permissions:

On the Configured permissions page, Grant admin consent for org-name, then click Yes.

Configure the MS Graph API connector

This procedure uses the admin UI to configure the connector. You can also edit the samples/sync-with-azuread/conf/provisioner.openicf-azuread.json file directly.

Start IDM with the configuration for the AzureAD sample:

cd /path/to/openidm/
./startup.sh -p samples/sync-with-azuread

Log in to the admin UI at the URL https://localhost:8443/admin as the default administrative user (openidm-admin) with password openidm-admin.

This URL reflects the host on which IDM is installed, and must be the same as the Redirect URI that you set when you registered your Azure application.
Select Configure > Connectors, and click the Azuread connector.
Under General Details, select Enabled.
Under Base Connector Details, enter at least the Tenant, ClientID, and Client Secret that you obtained when you prepared the sample, and then click Save.

After you click Save, IDM validates the connector configuration. If you do not see an error, your connector is configured correctly.

Run the sample

This procedure uses create, read, update, and delete (CRUD) operations on the Azure AD resource, to verify that the connector is working as expected. The procedure uses a combination of REST commands, to manage users and groups in Azure AD, and the admin UI, to manage IDM users and reconcile objects between the Azure AD and IDM.

The sample configuration has two mappings: one from Azure AD to the managed user repository, and one from the managed user repository to the users in Azure AD.

Before you can synchronize accounts between the two data stores, you must update the second mapping with your tenant name:

In the admin UI, select Configure > Mappings.
Click on mapping 2 (managedUser_systemAzureadUser).
On the Properties tab, under the Attributes grid, click the userName to userPrincipalName mapping.
On the Transformation Script tab, replace <my tenant> with the name of your tenant. For example:
```
source +'@example.onmicrosoft.com'
```
Click Save.

All of the commands shown here assume that your domain is example.com. Adjust the examples to match your domain.

Manage users in Azure AD

Create a user entry in Azure AD, over REST. This command creates an entry for user Sam Carter:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--header "content-type: application/json" \
--data '{
  "surname": "Carter",
  "displayName": "Sam Carter",
  "givenName": "Sam",
  "userType": "Member",
  "accountEnabled": true,
  "mail": "scarter@example.com",
  "country": "US",
  "mailNickname": "scarter",
  "userPrincipalName": "scarter@example.onmicrosoft.com",
  "__PASSWORD__": "MyPassw0rd"
}' \
"http://localhost:8080/openidm/system/azuread/user?_action=create"
{
  "_id": "be14f228-1d3a-4f31-aeee-ba6e8419b1b0",
  "accountEnabled": true,
  "memberOf": [],
  "userPrincipalName": "scarter@example.onmicrosoft.com",
  "mailNickname": "scarter",
  "givenName": "Sam",
  "proxyAddresses": [
    "SMTP:scarter@example.com"
  ],
  "createdDateTime": "2021-03-31T13:47:59Z",
  "onPremisesExtensionAttributes": {
    ...
  },
  "surname": "Carter",
  "imAddresses": [],
  "userType": "Member",
  "manager": null,
  "country": "US",
  "licenses": [],
  "id": "be14f228-1d3a-4f31-aeee-ba6e8419b1b0",
  "mail": "scarter@example.com",
  "displayName": "Sam Carter",
  "identities": [
    {
      "signInType": "userPrincipalName",
      "issuerAssignedId": "scarter@example.onmicrosoft.com",
      "issuer": "example.onmicrosoft.com"
    }
  ],
  "__NAME__": "scarter@example.onmicrosoft.com",
  "businessPhones": []
}

Take note of the ID of the new user (be14f228-1d3a-4f31-aeee-ba6e8419b1b0 in this example). You will need this ID for additional commands in this example.

Reconcile the Azure AD resource with the managed user repository.

This step should create the new user, Sam Carter (and any other users in your Azure AD resource) in the managed user repository:
1. In the admin UI, select Configure > Mappings.
2. On mapping 1 (systemAzureadUser_managedUser ), click Reconcile.
3. Select Manage > User, and verify that the user Sam Carter exists in the repository.
Update Sam Carter’s country property in IDM:
1. Select Manage > User, and click Sam Carter's entry.
2. Change his Country property from US to FR, and click Save.
As a result of implicit synchronization, Sam Carter’s country should be updated automatically in the Azure AD resource.

Read the value of Sam Carter’s country attribute in your Azure AD, specifying the ID you retrieved when you created the user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/azuread/user/be14f228-1d3a-4f31-aeee-ba6e8419b1b0?_fields=country"
{
  "_id": "be14f228-1d3a-4f31-aeee-ba6e8419b1b0",
  "country": "FR"
}

Manage groups in Azure AD

Create a basic group entry in Azure AD:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "description": "Group used for Azure AD sample.",
  "displayName": "AzureAD Test Group",
  "mailNickname": "ExampleTestGroup",
  "mailEnabled": false,
  "securityEnabled": true
}' \
"http://localhost:8080/openidm/system/azuread/group?_action=create"
{
  "_id": "c628713f-e6c8-43a4-8c5d-9c9ee437d950",
  "description": "Group used for Azure AD sample.",
  "mailNickname": "ExampleTestGroup",
  "groupTypes": [],
  "displayName": "AzureAD Test Group",
  "securityIdentifier": "S-1-12-1-3324539199-1134880456-2661047692-1356412900",
  "proxyAddresses": [],
  "mailEnabled": false,
  "createdDateTime": "2021-04-01T12:40:22Z",
  "securityEnabled": true,
  "members": [],
  "__NAME__": "AzureAD Test Group",
  "creationOptions": []
}

Add Sam Carter to the AzureAD Test Group that you have just created. Choose one of the following methods:

Update Sam Carter’s memberOf property with the group ID

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request PUT \
--header "If-Match:*" \
--header "content-type: application/json" \
--data '{
  "memberOf": ["c628713f-e6c8-43a4-8c5d-9c9ee437d950"]
}' \
"http://localhost:8080/openidm/system/azuread/user/be14f228-1d3a-4f31-aeee-ba6e8419b1b0"
{
  "_id": "be14f228-1d3a-4f31-aeee-ba6e8419b1b0",
  "manager": null,
  "userPrincipalName": "scarter@example.onmicrosoft.com",
  "userType": "Member",
  "country": "FR",
  "createdDateTime": "2021-03-31T13:47:59Z",
  "givenName": "Sam",
  "__NAME__": "scarter@example.onmicrosoft.com",
  "onPremisesExtensionAttributes": {
    ...
  },
  "mailNickname": "scarter",
  "licenses": [],
  "businessPhones": [],
  "displayName": "Sam Carter",
  "imAddresses": [],
  "id": "be14f228-1d3a-4f31-aeee-ba6e8419b1b0",
  "mail": "scarter@example.com",
  "proxyAddresses": [
    "smtp:scarter@example.onmicrosoft.com",
    "SMTP:scarter@example.com"
  ],
  "accountEnabled": true,
  "memberOf": [
    "c628713f-e6c8-43a4-8c5d-9c9ee437d950"
  ],
  "identities": [
    {
      "signInType": "userPrincipalName",
      "issuerAssignedId": "scarter@example.onmicrosoft.com",
      "issuer": "example.onmicrosoft.com"
    }
  ],
  "surname": "Carter"
}

Update the group’s members property with the user ID

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--header "If-Match:*" \
--data '{
  "members": ["be14f228-1d3a-4f31-aeee-ba6e8419b1b0"]
}' \
"http://localhost:8080/openidm/system/azuread/group/c628713f-e6c8-43a4-8c5d-9c9ee437d950"
{
  "_id": "c628713f-e6c8-43a4-8c5d-9c9ee437d950",
  "description": "Group used for Azure AD sample.",
  "mailNickname": "ExampleTestGroup",
  "groupTypes": [],
  "displayName": "AzureAD Test Group",
  "securityIdentifier": "S-1-12-1-3324539199-1134880456-2661047692-1356412900",
  "proxyAddresses": [],
  "mailEnabled": false,
  "createdDateTime": "2021-04-01T12:40:22Z",
  "securityEnabled": true,
  "members": [
    "be14f228-1d3a-4f31-aeee-ba6e8419b1b0"
  ],
  "__NAME__": "AzureAD Test Group",
  "creationOptions": []
}

Read the group entry’s members property to verify that the Sam Carter has been added:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/azuread/group/c628713f-e6c8-43a4-8c5d-9c9ee437d950?_fields=members"
{
  "_id": "c628713f-e6c8-43a4-8c5d-9c9ee437d950",
  "members": [
    "be14f228-1d3a-4f31-aeee-ba6e8419b1b0"
  ]
}

Delete the group entry:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/system/azuread/group/c628713f-e6c8-43a4-8c5d-9c9ee437d950"
{
  "_id": "c628713f-e6c8-43a4-8c5d-9c9ee437d950",
  "description": "Group used for Azure AD sample.",
  "mailNickname": "ExampleTestGroup",
  "groupTypes": [],
  "displayName": "AzureAD Test Group",
  "securityIdentifier": "S-1-12-1-3324539199-1134880456-2661047692-1356412900",
  "proxyAddresses": [],
  "mailEnabled": false,
  "createdDateTime": "2021-04-01T12:40:22Z",
  "securityEnabled": true,
  "members": [
    "be14f228-1d3a-4f31-aeee-ba6e8419b1b0"
  ],
  "__NAME__": "AzureAD Test Group",
  "creationOptions": []
}

Delete user Sam Carter, to return your Azure AD resource to its original state:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/system/azuread/user/be14f228-1d3a-4f31-aeee-ba6e8419b1b0"
{
  "_id": "be14f228-1d3a-4f31-aeee-ba6e8419b1b0",
  "manager": null,
  "userPrincipalName": "scarter@example.onmicrosoft.com",
  "userType": "Member",
  "country": "FR",
  "createdDateTime": "2021-03-31T13:47:59Z",
  "givenName": "Sam",
  "__NAME__": "scarter@example.onmicrosoft.com",
  "onPremisesExtensionAttributes": {
    ...
  },
  "mailNickname": "scarter",
  "licenses": [],
  "businessPhones": [],
  "displayName": "Sam Carter",
  "imAddresses": [],
  "id": "be14f228-1d3a-4f31-aeee-ba6e8419b1b0",
  "mail": "scarter@example.com",
  "proxyAddresses": [
    "smtp:scarter@example.onmicrosoft.com",
    "SMTP:scarter@example.com"
  ],
  "accountEnabled": true,
  "memberOf": [],
  "identities": [
    {
      "signInType": "userPrincipalName",
      "issuerAssignedId": "scarter@example.onmicrosoft.com",
      "issuer": "example.onmicrosoft.com"
    }
  ],
  "surname": "Carter"
}

In this sample, you used the MS Graph API connector to add and delete user and group objects in your Azure AD tenant and to reconcile users between Azure AD and IDM. You can expand on this sample by customizing the connector configuration to provide additional synchronization functionality between IDM and Azure AD. For information about configuring connectors, refer to Connector reference.

PingIDM 7.5.0