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 MS Graph API Java 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 expiry date, and click Add.
3. Copy the client secret Value:
  Important
  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, 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
Executing ./startup.sh...
Using OPENIDM_HOME:   /path/to/openidm
Using PROJECT_HOME:   /path/to/openidm/samples/sync-with-azuread/
Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/samples/sync-with-azuread/conf/logging.properties
Using boot properties at /path/to/openidm/resolver/boot.properties
-> OpenIDM ready

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 on 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, then click Save.
IDM validates the connector configuration when you click Save so if you do not see an error here, 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 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.

Note

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": []
}

Note

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 has been created in the repository.
Update Sam Carter's country property in IDM:
1. Select Manage > User, then click on 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, see Overview.

Synchronize Data Between IDM and Azure Active Directory

Prepare the Sample

Important

Configure the MS Graph API Connector

Run the Sample

Note

Note