Microsoft Graph API Java connector

The Microsoft (MS) Graph API Java connector uses the Microsoft Graph SDK for Java and the Authentication Providers for the Microsoft Graph Java SDK. Unlike the PowerShell connector for Azure, the MS Graph API connector is a Java connector, and does not need .NET RCS to run. As a Java connector, the MS Graph API connector functions like any standard IDM connector.

The MS Graph API connector can read, search, and fetch data from Microsoft Azure, when Azure is the authoritative data source, and can provision to Azure, when IDM is the authoritative data source.

The MS Graph API connector is bundled with IDM and Identity Cloud, and available from the ForgeRock Download Center. The connector bundles all its dependencies.

Before you start

Before you can use the connector, 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.

Install the MS Graph API connector

Some connectors are bundled with Identity Cloud, IDM, or RCS by default. In these cases, you can skip the installation process and move directly to configuring your connector.

Bundle availability
Connector	Identity Cloud	IDM	RCS
Microsoft Graph API Java connector	Yes	Yes	No

Download the connector .jar file from the ForgeRock BackStage download site.

If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:
```
mv ~/Downloads/msgraphapi-connector-1.5.20.15.jar /path/to/openidm/connectors/
```
If you are using a remote connector server (RCS), place it in the /path/to/openicf/connectors directory on the RCS.

Configure the MS Graph API connector

Create a connector configuration using the IDM admin UI:

From the navigation bar, click Configure > Connectors.
On the Connectors page, click New Connector.
On the New Connector page, type a Connector Name.
From the Connector Type drop-down list, select MS Graph API Connector - 1.5.20.15.
Complete the Base Connector Details.

For a list of all configuration properties, refer to MS Graph API Connector Configuration
Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Alternatively, copy the sample connector configuration file from /path/to/openidm/samples/example-configurations/provisioners/provisioner.openicf-azuread.json to your project’s conf/ directory.

Set at least the Azure tenant, clientId and clientSecret in the configurationProperties. For example:

"configurationProperties" : {
    "tenant" : "your tenant ID",
    "clientId" : "your client ID",
    "clientSecret" : "your client secret"
}

MS Graph API remote connector

If you want to run this connector outside of Identity Cloud or IDM, you can configure the MS Graph API connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within Identity Cloud or installed locally on IDM.

You can download the MS Graph API connector from here.

Refer to Remote connectors for configuring the MS Graph API remote connector.

Test the MS Graph API connector

Start IDM, if it is not running. Then use these examples to test that the connector is configured correctly and operating as expected:

Check the Connector Configuration

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system?_action=test"
{
  "name": "azuread",
  "enabled": true,
  "config": "config/provisioner.openicf/azuread",
  "connectorRef": {
    "bundleVersion": "[1.5.19.0,1.6.0.0]",
    "bundleName": "org.forgerock.openicf.connectors.msgraphapi-connector",
    "connectorName": "org.forgerock.openicf.connectors.msgraphapi.MSGraphAPIConnector"
  },
  "displayName": "MSGraphAPI Connector",
  "objectTypes": [
    "subscribedSku",
    "team",
    "user",
    "__ALL__",
    "group"
  ],
  "ok": true
}

A status of "ok": true indicates that the connector is configured correctly.

List User Entries

This command retrieves a list of users in your Azure tenant. You can also use any system-enabled filter, such as those described in Construct Queries:

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?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "c48be8cc-5846-4059-95e8-a7acbf6aec31"
    },
    {
      "_id": "c7fe57e2-3159-45e1-b67a-435232fd88d9"
    },
    {
      "_id": "9e714b5c-345a-430c-93f5-d8c6f9a2f225"
    },
    ...
  ],
  ...
}

Return a User Entry

This command retrieves a specific user entry from your Azure tenant:

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/c48be8cc-5846-4059-95e8-a7acbf6aec31"
{
  "_id": "c48be8cc-5846-4059-95e8-a7acbf6aec31",
  "surname": "Jensen",
  "displayName": "Babs Jensen",
  "memberOf": [
    "036f288c-6f71-41ae-9d09-6a68c8ba315b"
  ],
  "mail": "babs.jensen@example.onmicrosoft.com",
  "onPremisesExtensionAttributes": {
    ...
  },
  "usageLocation": "FR",
  "userType": "Member",
  "identities": [
    {
      "signInType": "userPrincipalName",
      "issuerAssignedId": "00991235@example.onmicrosoft.com",
      "issuer": "example.onmicrosoft.com"
    }
  ],
  "businessPhones": [],
  "createdDateTime": "2020-11-20T11:09:15Z",
  "accountEnabled": true,
  "userPrincipalName": "00991235@example.onmicrosoft.com",
  "proxyAddresses": [
    "smtp:00991235@example.onmicrosoft.com",
    "SMTP:babs.jensen@example.onmicrosoft.com"
  ],
  "imAddresses": [],
  "passwordPolicies": "None",
  "mailNickname": "00991235",
  "givenName": "Babs",
  "__NAME__": "00991235@example.onmicrosoft.com"
}

Create Users or Groups

This command creates a new user in your Azure tenant:

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": "Steve Carter",
  "givenName": "Steve",
  "userType": "Member",
  "accountEnabled": true,
  "mailNickname": "00654321",
  "userPrincipalName": "00654321@forgedemo.onmicrosoft.com",
  "__PASSWORD__": "MyPassw0rd"
}' \
"http://localhost:8080/openidm/system/azuread/user?_action=create"
{
  "_id": "9fa6c765-0872-45f6-8714-1dcd1ed94859",
  "surname": "Carter",
  "displayName": "Steve Carter",
  "memberOf": [],
  "onPremisesExtensionAttributes": {
    "extensionAttribute14": null,
    ...
  },
  "userType": "Member",
  "identities": [
    {
      "signInType": "userPrincipalName",
      "issuerAssignedId": "00654321@example.onmicrosoft.com",
      "issuer": "example.onmicrosoft.com"
    }
  ],
  "businessPhones": [],
  "createdDateTime": "2020-12-18T13:23:58Z",
  "accountEnabled": true,
  "userPrincipalName": "00654321@example.onmicrosoft.com",
  "proxyAddresses": [],
  "imAddresses": [],
  "mailNickname": "00654321",
  "givenName": "Steve",
  "__NAME__": "00654321@example.onmicrosoft.com"
}

Update Entries

This command changes the password for the user created previously:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request PATCH \
--header "content-type: application/json" \
--data '[ {
  "operation": "replace",
  "field": "__PASSWORD__",
  "value": "MyNewPassw0rd"
} ]' \
"http://localhost:8080/openidm/system/azuread/user/9fa6c765-0872-45f6-8714-1dcd1ed94859"
{
  "_id": "9fa6c765-0872-45f6-8714-1dcd1ed94859",
  "surname": "Carter",
  "displayName": "Steve Carter",
  "memberOf": [],
  "onPremisesExtensionAttributes": {
    "extensionAttribute14": null,
    ...
  },
  "userType": "Member",
  "identities": [
    {
      "signInType": "userPrincipalName",
      "issuerAssignedId": "00654321@forgedemo.onmicrosoft.com",
      "issuer": "forgedemo.onmicrosoft.com"
    }
  ],
  "businessPhones": [],
  "createdDateTime": "2020-12-18T13:23:58Z",
  "accountEnabled": true,
  "userPrincipalName": "00654321@forgedemo.onmicrosoft.com",
  "proxyAddresses": [],
  "imAddresses": [],
  "mailNickname": "00654321",
  "givenName": "Steve",
  "__NAME__": "00654321@forgedemo.onmicrosoft.com"
}

Delete Users and Groups

This command deletes the user created previously:

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/9fa6c765-0872-45f6-8714-1dcd1ed94859"
{
  "_id": "9fa6c765-0872-45f6-8714-1dcd1ed94859",
  "surname": "Carter",
  "displayName": "Steve Carter",
  "memberOf": [],
  "onPremisesExtensionAttributes": {
    "extensionAttribute14": null,
    ...
  },
  "userType": "Member",
  "identities": [
    {
      "signInType": "userPrincipalName",
      "issuerAssignedId": "00654321@forgedemo.onmicrosoft.com",
      "issuer": "forgedemo.onmicrosoft.com"
    }
  ],
  "businessPhones": [],
  "createdDateTime": "2020-12-18T13:23:58Z",
  "accountEnabled": true,
  "userPrincipalName": "00654321@forgedemo.onmicrosoft.com",
  "proxyAddresses": [],
  "imAddresses": [],
  "mailNickname": "00654321",
  "givenName": "Steve",
  "__NAME__": "00654321@forgedemo.onmicrosoft.com"
}

Manage user licenses

The MS Graph API connector lets you list the available licenses in your Azure data source, and manage those licenses for specific users:

List available licenses in Azure

This command lists the values of the read-only subscribedSku object. For more information about this object class, refer to the corresponding Microsoft documentation:

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/subscribedSku?_queryFilter=true"
{
  "result": [
    {
      "_id": "5ee8xxxx-xxxx-xxxx-xxxx-76dc2c2c30bc_f245ecc8-xxxx-xxxx-xxxx-xxxx114de5f3",
      "prepaidUnits": {
        "warning": 0,
        "enabled": 1,
        "suspended": 0
      },
      "skuId": "f245ecc8-xxxx-xxxx-xxxx-xxxx114de5f3",
      "skuPartNumber": "O365_BUSINESS_PREMIUM",
      "capabilityStatus": "Enabled",
      "appliesTo": "User",
      "consumedUnits": 1,
      "__NAME__": "O365_BUSINESS_PREMIUM",
      "servicePlans": [
        {
          "servicePlanName": "RMS_S_BASIC",
          "provisioningStatus": "PendingProvisioning",
          "appliesTo": "Company",
          "servicePlanId": "31cxxxxxxxxxxxxxxxxxxxxxxxxxxx122"
        },
        {
          "servicePlanName": "POWER_VIRTUAL_AGENTS_O365_P2",
          "provisioningStatus": "PendingProvisioning",
          "appliesTo": "User",
          "servicePlanId": "041xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxaee"
        },
        {
          "servicePlanName": "CDS_O365_P2",
          "provisioningStatus": "PendingProvisioning",
          "appliesTo": "User",
          "servicePlanId": "95bxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx95a"
        },
        ...
      ]
    }
  ],
  ...
}

List a user’s licenses

Each user object can include a read-only licenses property that contains an array of objects (maps).

This command lists a specific user’s licenses:

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/c48be8cc-5846-4059-95e8-a7acbf6aec31?_fields=licenses"
{
    "_id": "c48be8cc-5846-4059-95e8-a7acbf6aec31",
    "licenses": [
        {
            "skuPartNumber": "O365_BUSINESS_PREMIUM",
            "servicePlans": [
                {
                    "servicePlanName": "RMS_S_BASIC",
                    "provisioningStatus": "PendingProvisioning",
                    "appliesTo": "Company",
                    "servicePlanId": "31cxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx122"
                },
                {
                    "servicePlanName": "POWER_VIRTUAL_AGENTS_O365_P2",
                    "provisioningStatus": "PendingProvisioning",
                    "appliesTo": "Company",
                    "servicePlanId": "041xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxaee"
                },
                {
                    "servicePlanName": "CDS_O365_P2",
                    "provisioningStatus": "PendingProvisioning",
                    "appliesTo": "Company",
                    "servicePlanId": "95bxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx95a"
                },
                ...
            ],
            "id": "c8noxxxxsEqoxxxxLCwwxxxxRfKvxxxxth8nxxxx5fM",
            "skuId": "f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3"
        }
    ]
}

Add and remove a user’s licenses

You cannot manipulate a user’s licenses property directly, because it is read-only. To add or remove licenses for a user, set the addLicenses or removeLicenses properties when you create or update the user.

The connector does not currently support PATCH add or PATCH remove operations. PATCH replace is supported because it is the equivalent of a PUT operation.

This command updates an existing user entry to add a license with the `skuId`f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3:

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" \
--header "If-None-Match: *" \
--request PUT \
--data '{
  "addLicenses": [
    {
      "skuId": "f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3"
    }
  ]
}' \
"http://localhost:8080/openidm/system/azuread/user/c48be8cc-5846-4059-95e8-a7acbf6aec31"

This command updates the user entry to remove the license with `skuId`f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3:

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" \
--header "If-Match: *" \
--request PUT \
--data '{
  "removeLicenses": "f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3"
}' \
"http://localhost:8080/openidm/system/azuread/user/c48be8cc-5846-4059-95e8-a7acbf6aec31"

Contacts

A contact is a resource type in Microsoft Outlook used to organize and store information about an associated object. Contacts use the /user endpoint. For more information, see the Microsoft Graph documentation.

The MS Graph API connector offers limited support for contacts and includes the following write-only attributes:

{
  "type": "array",
  "items": {
    "type": "object",
    "nativeType": "object"
  },
  "nativeName": "__addContacts__",
  "nativeType": "object",
  "flags": [
    "NOT_READABLE",
    "NOT_RETURNED_BY_DEFAULT"
  ]
},
{
  "type": "array",
  "items": {
    "type": "string",
    "nativeType": "string"
  },
  "nativeName": "__removeContacts__",
  "nativeType": "string",
  "flags": [
    "NOT_READABLE",
    "NOT_RETURNED_BY_DEFAULT"
  ]
},
{
  "type": "array",
  "items": {
    "type": "object",
    "nativeType": "object"
  },
  "nativeName": "__updateContacts__",
  "nativeType": "object",
  "flags": [
    "NOT_READABLE",
    "NOT_RETURNED_BY_DEFAULT"
  ]
}

Add contacts to a user

Contacts must be added to an existing user.

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" \
--header "If-Match: *" \
--request PUT \
--data '{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "__addContacts__": {
    "givenName": "Test-Contact",
    "businessAddress": {
      "city": "exampleCity",
      "state": "exampleState",
      "postalCode": "99999",
      "street": "example st",
      "countryOrRegion": "United States"
    }
  }
}' \
"http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7"

Return a user entry with contacts

Request

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 GET \
'http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7?_fields="_id,contacts"'

Response

{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "contacts": [
    {
      "id": "{CONTACT-ID}",
      "givenName": "Test-Contact",
      "businessAddress": {
        "city": "exampleCity",
        "state": "exampleState",
        "postalCode": "99999",
        "street": "example st",
        "countryOrRegion": "United States"
      }
    }
  ]
}

Update a user’s contacts

Request

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" \
--header "If-Match: *" \
--request PUT \
--data '{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "__updateContacts__": {
    "id": "{CONTACT-ID}",
    "givenName": "Test-Contact-Updated",
    "businessAddress": {
      "city": "exampleCity",
      "state": "exampleState",
      "postalCode": "99999",
      "street": "example st",
      "countryOrRegion": "United States"
    }
  }
}' \
"http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7"

After updating the user’s contacts, a subsequent read on the user with the contacts field returns the updated contacts:

Request

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 GET \
'http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7?_fields="_id,contacts"'

Response

{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "contacts": [
    {
      "id": "{CONTACT-ID}",
      "givenName": "Test-Contact-Updated",
      "businessAddress": {
        "city": "exampleCity",
        "state": "exampleState",
        "postalCode": "99999",
        "street": "example st",
        "countryOrRegion": "United States"
      }
    }
  ]
}

Remove a user’s contacts

Request

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" \
--header "If-Match: *" \
--request PUT \
--data '{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "__removeContacts__": [
    "{CONTACT-ID}"
  ]
}' \
"http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7"

After removing the user’s contacts, a subsequent read on the user with the contacts field returns an empty contacts array:

Request

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 GET \
'http://localhost:8080/openidm/system/azuread/user/671fa173-ad81-41c3-89bf-af939426eee7?_fields="_id,contacts"'

Response

{
  "_id": "671fa173-ad81-41c3-89bf-af939426eee7",
  "contacts": []
}

Role eligibility schedules

The MS Graph API connector lets you read and manage role eligibility schedules.

Create a role eligibility schedule request

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 '{
  "action": "adminAssign",
  "justification": "Justification is required",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "directoryScopeId": "/",
  "principalId": "2588c7f0-776e-407e-a1dc-f3a77a28e4fe",
  "scheduleInfo": {
    "startDateTime": "2022-04-10T00:00:00Z",
    "expiration": {
      "type": "noExpiration"
    }
  }
}' \
"http://localhost:8080/openidm/system/azuread/roleEligibilityScheduleRequest"
{
  "_id": "0d8a7bbe-e4ab-4798-8539-728c410ac7b7",
  "isValidationOnly": false,
  "targetScheduleId": "0d8a7bbe-e4ab-4798-8539-728c410ac7b7",
  "createdDateTime": "2023-02-15T23:59:45.143Z",
  "__NAME__": "0d8a7bbe-e4ab-4798-8539-728c410ac7b7",
  "directoryScopeId": "/",
  "principalId": "2588c7f0-776e-407e-a1dc-f3a77a28e4fe",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "action": "adminAssign",
  "ticketInfo": {},
  "completedDateTime": "2023-02-15T23:59:45.167Z",
  "justification": "Justification is required",
  "status": "Provisioned",
  "scheduleInfo": {
    "startDateTime": "2023-02-15T23:59:45.168101400Z",
    "expiration": {
      "type": "noExpiration"
    }
  },
  "createdBy": {
    "user": {
      "id": "f516bdc4-0171-42ba-823a-4cbdff160d0f"
    }
  }
}

Read a role eligibility schedule request

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/roleEligibilityScheduleRequest/0d8a7bbe-e4ab-4798-8539-728c410ac7b7"
{
  "_id": "0d8a7bbe-e4ab-4798-8539-728c410ac7b7",
  "isValidationOnly": false,
  "targetScheduleId": "0d8a7bbe-e4ab-4798-8539-728c410ac7b7",
  "createdDateTime": "2023-02-15T23:59:45.143Z",
  "__NAME__": "0d8a7bbe-e4ab-4798-8539-728c410ac7b7",
  "directoryScopeId": "/",
  "principalId": "2588c7f0-776e-407e-a1dc-f3a77a28e4fe",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "action": "adminAssign",
  "ticketInfo": {},
  "completedDateTime": "2023-02-15T23:59:45.167Z",
  "justification": "Justification is required",
  "status": "Provisioned",
  "scheduleInfo": {
    "startDateTime": "2023-02-15T23:59:45.168101400Z",
    "expiration": {
      "type": "noExpiration"
    }
  },
  "createdBy": {
    "user": {
      "id": "f516bdc4-0171-42ba-823a-4cbdff160d0f"
    }
  }
}

Get role eligibility schedules for a 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/roleEligibilitySchedule?_queryFilter=principalId%20eq%20'2588c7f0-776e-407e-a1dc-f3a77a28e4fe'"
{
  "result": [
    {
      "_id": "0d8a7bbe-e4ab-4798-8539-728c410ac7b7",
      "modifiedDateTime": "0001-01-01T08:00Z",
      "createdDateTime": "2023-02-15T23:59:45.450Z",
      "principalId": "2588c7f0-776e-407e-a1dc-f3a77a28e4fe",
      "scheduleInfo": {
        "startDateTime": "2023-02-15T23:59:45.450Z",
        "expiration": {
          "type": "noExpiration"
        }
      },
      "createdUsing": "0d8a7bbe-e4ab-4798-8539-728c410ac7b7",
      "status": "Provisioned",
      "directoryScopeId": "/",
      "__NAME__": "0d8a7bbe-e4ab-4798-8539-728c410ac7b7",
      "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
      "memberType": "Direct"
    }
  ],
  ...
}

Get role eligibility schedule instance

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/roleEligibilityScheduleInstance?_queryFilter=principalId+eq+'2588c7f0-776e-407e-a1dc-f3a77a28e4fe'"
{
  "result": [
    {
      "_id": "UX6spHTVBkG5_Zv86oJthH0ZIKwfxAZIp1uoOmyPt1I-1-e",
      "roleDefinitionId": "a4ac7e51-d574-4106-b9fd-9bfcea826d84",
      "directoryScopeId": "/",
      "roleEligibilityScheduleId": "1248840c-f57d-4168-9e2c-1e0d0e9a46f4",
      "__NAME__": "UX6spHTVBkG5_Zv86oJthH0ZIKwfxAZIp1uoOmyPt1I-1-e",
      "principalId": "2588c7f0-776e-407e-a1dc-f3a77a28e4fe",
      "startDateTime": "2023-02-03T21:29:03.217Z",
      "memberType": "Direct"
    }
  ],
  ...
}

Role assignment schedules

The MS Graph API connector lets you read and manage role assignment schedules.

Create a role assignment schedule request

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 '{
  "action": "adminAssign",
  "justification": "Justification is required",
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "directoryScopeId": "/",
  "principalId": "a4375665-cba5-4208-a4f2-12a0d2fc0e85",
  "scheduleInfo": {
    "startDateTime": "2022-04-10T00:00:00Z",
    "expiration": {
      "type": "noExpiration"
    }
  }
}' \
"http://localhost:8080/openidm/system/azuread/roleAssignmentScheduleRequest"
{
  "_id": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
  "scheduleInfo": {
    "startDateTime": "2023-02-16T22:21:04.079921Z",
    "expiration": {
      "type": "noExpiration"
    }
  },
  "isValidationOnly": false,
  "createdBy": {
    "user": {
      "id": "f516bdc4-0171-42ba-823a-4cbdff160d0f"
    }
  },
  "ticketInfo": {},
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "principalId": "f96413e8-1366-426e-ab24-4d9380f11e2e",
  "__NAME__": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
  "completedDateTime": "2023-02-16T22:21:04.080Z",
  "targetScheduleId": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
  "action": "adminAssign",
  "directoryScopeId": "/",
  "status": "Provisioned",
  "createdDateTime": "2023-02-16T22:21:04.070Z",
  "justification": "Justification is required"
}

Read a role assignment schedule request

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/roleAssignmentScheduleRequest/4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0"
{
  "_id": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
  "scheduleInfo": {
    "startDateTime": "2023-02-16T22:21:04.079921Z",
    "expiration": {
      "type": "noExpiration"
    }
  },
  "isValidationOnly": false,
  "createdBy": {
    "user": {
      "id": "f516bdc4-0171-42ba-823a-4cbdff160d0f"
    }
  },
  "ticketInfo": {},
  "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
  "principalId": "f96413e8-1366-426e-ab24-4d9380f11e2e",
  "__NAME__": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
  "completedDateTime": "2023-02-16T22:21:04.080Z",
  "targetScheduleId": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
  "action": "adminAssign",
  "directoryScopeId": "/",
  "status": "Provisioned",
  "createdDateTime": "2023-02-16T22:21:04.070Z",
  "justification": "Justification is required"
}

Get role assignment schedules for a 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/roleAssignmentSchedule?_queryFilter=principalId%20eq%20’f96413e8-1366-426e-ab24-4d9380f11e2e'"
{
  "result": [
    {
      "_id": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
      "__NAME__": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
      "status": "Provisioned",
      "memberType": "Direct",
      "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
      "principalId": "f96413e8-1366-426e-ab24-4d9380f11e2e",
      "createdDateTime": "2023-02-16T22:21:07.727Z",
      "assignmentType": "Assigned",
      "directoryScopeId": "/",
      "createdUsing": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
      "scheduleInfo": {
        "startDateTime": "2023-02-16T22:21:07.727Z",
        "expiration": {
          "type": "noExpiration"
        }
      }
    }
  ],
  ...
}

Get role assignment schedule instance

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/roleAssignmentScheduleInstance?_queryFilter=principalId+eq+'f96413e8-1366-426e-ab24-4d9380f11e2e'"
{
  "result": [
    {
      "_id": "UafX_Qu2SkSYTAJlL-j6HOgTZPlmE25CqyRNk4DxHi4-1",
      "assignmentType": "Assigned",
      "memberType": "Direct",
      "principalId": "f96413e8-1366-426e-ab24-4d9380f11e2e",
      "startDateTime": "2023-02-16T22:21:07.727Z",
      "__NAME__": "UafX_Qu2SkSYTAJlL-j6HOgTZPlmE25CqyRNk4DxHi4-1",
      "roleAssignmentScheduleId": "4b49df1e-4b59-4a93-a7c7-ad3b13ad98b0",
      "directoryScopeId": "/",
      "roleDefinitionId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
      "roleAssignmentOriginId": "UafX_Qu2SkSYTAJlL-j6HOgTZPlmE25CqyRNk4DxHi4-1"
    }
  ],
  ...
}

Applications

The MS Graph API connector lets you read and manage applications.

Query all applications

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/application?_queryFilter=true"

Read an application

Request

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/application/e2dcfa77-5222-4715-a043-98baac00683d"

Response

{
  "_id": "e2dcfa77-5222-4715-a043-98baac00683d",
  "tags": [],
  "spa": {
    "redirectUris": []
  },
  "parentalControlSettings": {
    "legalAgeGroupRule": "Allow",
    "countriesBlockedForMinors": []
  },
  "api": {
    "requestedAccessTokenVersion": 2,
    "knownClientApplications": [],
    "oauth2PermissionScopes": [],
    "preAuthorizedApplications": []
  },
  "passwordCredentials": [],
  "info": {},
  "addIns": [],
  "keyCredentials": [],
  "publicClient": {
    "redirectUris": []
  },
  "verifiedPublisher": {},
  "identifierUris": [],
  "web": {
    "implicitGrantSettings": {
      "enableAccessTokenIssuance": false,
      "enableIdTokenIssuance": false
    },
    "redirectUris": []
  },
  "publisherDomain": "example.com",
  "createdDateTime": "2023-05-05T20:40:02Z",
  "displayName": "Test-Application",
  "appRoles": [],
  "isDeviceOnlyAuthSupported": false,
  "appId": "bc146d82-be72-4e16-814d-76e977ad198e",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "resourceAccess": [
        {
          "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "type": "Scope"
        }
      ]
    }
  ]
}

Create an application

Request

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 '{
  "displayName": "Test-Application",
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "resourceAccess": [
        {
          "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "type": "Scope"
        }
      ]
    }
  ]
}' \
"http://localhost:8080/openidm/system/azuread/application"

Response

{
  "_id": "e2dcfa77-5222-4715-a043-98baac00683d",
  "tags": [],
  "spa": {
    "redirectUris": []
  },
  "parentalControlSettings": {
    "legalAgeGroupRule": "Allow",
    "countriesBlockedForMinors": []
  },
  "api": {
    "requestedAccessTokenVersion": 2,
    "knownClientApplications": [],
    "oauth2PermissionScopes": [],
    "preAuthorizedApplications": []
  },
  "passwordCredentials": [],
  "info": {},
  "addIns": [],
  "keyCredentials": [],
  "publicClient": {
    "redirectUris": []
  },
  "verifiedPublisher": {},
  "identifierUris": [],
  "web": {
    "implicitGrantSettings": {
      "enableAccessTokenIssuance": false,
      "enableIdTokenIssuance": false
    },
    "redirectUris": []
  },
  "publisherDomain": "example.com",
  "createdDateTime": "2023-05-05T20:40:02Z",
  "displayName": "Test-Application",
  "appRoles": [],
  "isDeviceOnlyAuthSupported": false,
  "appId": "bc146d82-be72-4e16-814d-76e977ad198e",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "resourceAccess": [
        {
          "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "type": "Scope"
        }
      ]
    }
  ]
}

Add a password (client secret) to an application

Adding passwordCredential when creating applications is not supported. You must use the addPassword method to add passwords or secrets to an application.

Some actions require more than a UUID on return and have no object to follow up with a subsequent read. In this instance, you can use the scriptOnConnector action, which requires at least the builtinAction parameter. Adding client secrets using this method requires the parameter builtinAction=addPassword. You can learn more about the other required parameter applicationId and optional parameters in the Microsoft Graph documentation.

The above also requires a dummy system action. For example:

{
  "scriptId": "addPassword",
  "actions": [
    {
      "systemType": ".*MSGraphAPIConnector",
      "actionSource": "return;",
      "actionType": "Groovy"
    }
  ]
}

The actionSource is ignored for these builtIn requests, but still required to invoke the scriptOnConnector action.

Request

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 \
"http://localhost:8080/openidm/system/azuread/?_action=script&scriptId=addPassword&displayName=TestSecretGenesis&applicationId=f619a0ac-0548-4e90-9314-84d967088d2b&builtinAction=addPassword"

Response

{
  "actions": [
    {
      "result": {
        "secretText": "{GENERATED-CLIENT-SECRET}",
        "startDateTime": {
          "dateTime": {
            "date": {
              "month": 5,
              "year": 2023,
              "day": 5
            },
            "time": {
              "hour": 20,
              "nano": 771787000,
              "minute": 40,
              "second": 27
            }
          },
          "offset": {
            "totalSeconds": 0
          }
        },
        "displayName": "TestSecretGenesis",
        "hint": "LS8",
        "keyId": "8f48fb5e-a295-4969-b988-a723a02f2f28",
        "endDateTime": {
          "dateTime": {
            "date": {
              "month": 5,
              "year": 2025,
              "day": 5
            },
            "time": {
              "hour": 20,
              "nano": 771787000,
              "minute": 40,
              "second": 27
            }
          },
          "offset": {
            "totalSeconds": 0
          }
        }
      }
    }
  ]
}

Update an application

Request

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 PATCH \
--data '[
  {
    "operation": "replace",
    "field": "/displayName",
    "value": "Test-Application-Updated"
  }
]' \
"http://localhost:8080/openidm/system/azuread/application/4eff1242-bd95-463b-9c8c-f221ec489ba1"

Response

{
  "_id": "4eff1242-bd95-463b-9c8c-f221ec489ba1",
  "tags": [],
  "spa": {
    "redirectUris": []
  },
  "parentalControlSettings": {
    "legalAgeGroupRule": "Allow",
    "countriesBlockedForMinors": []
  },
  "api": {
    "requestedAccessTokenVersion": 2,
    "knownClientApplications": [],
    "oauth2PermissionScopes": [],
    "preAuthorizedApplications": []
  },
  "passwordCredentials": [],
  "info": {},
  "addIns": [],
  "keyCredentials": [],
  "publicClient": {
    "redirectUris": []
  },
  "verifiedPublisher": {},
  "identifierUris": [],
  "web": {
    "implicitGrantSettings": {
      "enableAccessTokenIssuance": false,
      "enableIdTokenIssuance": false
    },
    "redirectUris": []
  },
  "publisherDomain": "example.com",
  "createdDateTime": "2023-05-05T20:40:11Z",
  "displayName": "Test-Application-Updated",
  "appRoles": [],
  "appId": "68e06ad2-569f-407d-b117-6cc1d9f5d787",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "requiredResourceAccess": []
}

Delete an application

Request

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" \
--header "If-Match: *" \
--request DELETE \
"http://localhost:8080/openidm/system/azuread/application/579d5781-6e39-4b94-b741-1748d1e14199"

Response

{
  "_id": "579d5781-6e39-4b94-b741-1748d1e14199",
  "tags": [],
  "spa": {
    "redirectUris": []
  },
  "parentalControlSettings": {
    "legalAgeGroupRule": "Allow",
    "countriesBlockedForMinors": []
  },
  "api": {
    "requestedAccessTokenVersion": 2,
    "knownClientApplications": [],
    "oauth2PermissionScopes": [],
    "preAuthorizedApplications": []
  },
  "passwordCredentials": [],
  "info": {},
  "addIns": [],
  "keyCredentials": [],
  "publicClient": {
    "redirectUris": []
  },
  "verifiedPublisher": {},
  "identifierUris": [],
  "web": {
    "implicitGrantSettings": {
      "enableAccessTokenIssuance": false,
      "enableIdTokenIssuance": false
    },
    "redirectUris": []
  },
  "publisherDomain": "example.com",
  "createdDateTime": "2023-05-05T20:40:18Z",
  "displayName": "Test-Application",
  "appRoles": [],
  "appId": "6e26b7a3-53ef-45ea-8492-fed30f1dd2ad",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "requiredResourceAccess": []
}

`servicePrincipal`

The servicePrincipal resource type represents an instance of an application in a directory. For more information, refer to the Microsoft Graph documentation.

Query all servicePrincipal objects

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/servicePrincipal?_queryFilter=true"

Read a servicePrincipal

Request

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/servicePrincipal/1c696b95-7f68-4018-b627-6c9601faa80b"

Response

{
  "_id": "1c696b95-7f68-4018-b627-6c9601faa80b",
  "addIns": [],
  "replyUrls": [],
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "displayName": "Test-Application",
  "appRoleAssignments": [],
  "alternativeNames": [],
  "resourceSpecificApplicationPermissions": [],
  "appDisplayName": "Test-Application",
  "accountEnabled": true,
  "appOwnerOrganizationId": "9e91bf24-7a08-433e-b111-5542416b4f20",
  "passwordCredentials": [],
  "servicePrincipalNames": [
    "a293dbaf-ba5d-4692-8898-521a1da51bac"
  ],
  "appId": "a293dbaf-ba5d-4692-8898-521a1da51bac",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "notificationEmailAddresses": [],
  "servicePrincipalType": "Application",
  "tags": [],
  "appRoleAssignedTo": [],
  "info": {},
  "appRoles": [],
  "appRoleAssignmentRequired": false
}

Create a servicePrincipal

A servicePrincipal requires an appId.

Request

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 '{
  "appId": "0b9179f4-f617-4ab8-9c33-18a870c76722"
}' \
"http://localhost:8080/openidm/system/azuread/servicePrincipal"

Response

{
  "_id": "7d164d58-6210-4c25-84db-d3dfce1171b4",
  "addIns": [],
  "replyUrls": [],
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "displayName": "Test-Application",
  "appRoleAssignments": [],
  "alternativeNames": [],
  "resourceSpecificApplicationPermissions": [],
  "appDisplayName": "Test-Application",
  "accountEnabled": true,
  "appOwnerOrganizationId": "9e91bf24-7a08-433e-b111-5542416b4f20",
  "passwordCredentials": [],
  "servicePrincipalNames": [
    "0b9179f4-f617-4ab8-9c33-18a870c76722"
  ],
  "appId": "0b9179f4-f617-4ab8-9c33-18a870c76722",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "notificationEmailAddresses": [],
  "servicePrincipalType": "Application",
  "tags": [],
  "appRoleAssignedTo": [],
  "info": {},
  "appRoles": [],
  "appRoleAssignmentRequired": false
}

Add a password (client secret) to a servicePrincipal

Adding passwordCredential when creating a servicePrincipal is not supported. You must use the addPassword method to add passwords or secrets to a servicePrincipal.

Request

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 \
"http://localhost:8080/openidm/system/azuread/?_action=script&scriptId=addPassword&displayName=TestSecretGenesis&servicePrincipalId=32e18e7a-cb23-4453-b5f4-286bc1a629b8&builtinAction=addPassword"

Response

{
  "actions": [
    {
      "result": {
        "secretText": "{GENERATED-CLIENT-SECRET}",
        "startDateTime": {
          "dateTime": {
            "date": {
              "month": 5,
              "year": 2023,
              "day": 5
            },
            "time": {
              "hour": 20,
              "nano": 91094000,
              "minute": 41,
              "second": 8
            }
          },
          "offset": {
            "totalSeconds": 0
          }
        },
        "displayName": "TestSecretGenesis",
        "hint": "rJn",
        "keyId": "862c0883-45ac-4e13-8adc-ce9bf3036570",
        "endDateTime": {
          "dateTime": {
            "date": {
              "month": 5,
              "year": 2025,
              "day": 5
            },
            "time": {
              "hour": 20,
              "nano": 91094000,
              "minute": 41,
              "second": 8
            }
          },
          "offset": {
            "totalSeconds": 0
          }
        }
      }
    }
  ]
}

Update a servicePrincipal

Request

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 PATCH \
--data '[
  {
    "operation": "replace",
    "field": "/appRoleAssignmentRequired",
    "value": true
  }
]' \
"http://localhost:8080/openidm/system/azuread/servicePrincipal/7d164d58-6210-4c25-84db-d3dfce1171b4"

Response

{
  "_id": "7d164d58-6210-4c25-84db-d3dfce1171b4",
  "addIns": [],
  "replyUrls": [],
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "displayName": "Test-Application",
  "appRoleAssignments": [],
  "alternativeNames": [],
  "resourceSpecificApplicationPermissions": [],
  "appDisplayName": "Test-Application",
  "accountEnabled": true,
  "appOwnerOrganizationId": "9e91bf24-7a08-433e-b111-5542416b4f20",
  "passwordCredentials": [],
  "servicePrincipalNames": [
    "0b9179f4-f617-4ab8-9c33-18a870c76722"
  ],
  "appId": "0b9179f4-f617-4ab8-9c33-18a870c76722",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "notificationEmailAddresses": [],
  "servicePrincipalType": "Application",
  "tags": [],
  "appRoleAssignedTo": [],
  "info": {},
  "appRoles": [],
  "appRoleAssignmentRequired": true
}

Delete a servicePrincipal

Request

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" \
--header "If-Match: *" \
--request DELETE \
"http://localhost:8080/openidm/system/azuread/servicePrincipal/1df34a52-3491-4b3a-8ec7-51d77ab50860"

Response

{
  "_id": "1df34a52-3491-4b3a-8ec7-51d77ab50860",
  "addIns": [],
  "replyUrls": [],
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "displayName": "Test-Application",
  "appRoleAssignments": [],
  "alternativeNames": [],
  "resourceSpecificApplicationPermissions": [],
  "appDisplayName": "Test-Application",
  "accountEnabled": true,
  "appOwnerOrganizationId": "9e91bf24-7a08-433e-b111-5542416b4f20",
  "passwordCredentials": [],
  "servicePrincipalNames": [
    "a2179b48-33f0-4933-8c59-39639469bb13"
  ],
  "appId": "a2179b48-33f0-4933-8c59-39639469bb13",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "notificationEmailAddresses": [],
  "servicePrincipalType": "Application",
  "tags": [],
  "appRoleAssignedTo": [],
  "info": {},
  "appRoles": [],
  "appRoleAssignmentRequired": false
}

Application permissions

Application permissions are also known as app roles or app role assignments. You can grant application permissions directly by adding an app role assignment to an object, such as user, group, or servicePrincipal. For more information about app role assignments, refer to the Microsoft Graph documentation.

The following table displays what the different id’s involved in app role assignment represent:

principalId

The id of a user, group, or client servicePrincipal. Depends on the type of object receiving the app role assignment.

resourceId

The object id of the servicePrincipal containing the appRole.

appRoleId

The id of the appRole.

Special schema definitions for app role assignments

The following schema definitions are special attributes in the connector, not real, readable properties of a servicePrincipal or other directory objects. They allow the connector to add and remove the respective app role assignments that appear in their related relationship fields.

For example, __addAppRoleAssignments__ stores a list of object data to populate the actual attribute appRoleAssignments.

__addAppRoleAssignments__

{
  "type": "array",
  "items": {
    "type": "object",
    "nativeType": "object"
  },
  "nativeName": "__addAppRoleAssignments__",
  "nativeType": "object"
}

__removeAppRoleAssignments__

{
  "type": "array",
  "items": {
    "type": "string",
    "nativeType": "string"
  },
  "nativeName": "__removeAppRoleAssignments__",
  "nativeType": "string"
}

__addAppRoleAssignedTo__

{
  "type": "array",
  "items": {
    "type": "object",
    "nativeType": "object"
  },
  "nativeName": "__addAppRoleAssignedTo__",
  "nativeType": "object"
}

__removeAppRoleAssignedTo__

{
  "type": "array",
  "items": {
    "type": "string",
    "nativeType": "string"
  },
  "nativeName": "__removeAppRoleAssignedTo__",
  "nativeType": "string"
}

Add an app role assignment to a servicePrincipal

This process is identical for users and groups.

Request

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" \
--header "If-Match: *" \
--request PUT \
--data '{
  "__addAppRoleAssignments__": {
    "principalId": "05b49121-0bf5-479e-8a4e-140212648879",
    "resourceId": "b3e4e58e-16fa-4b3d-a7b5-f134b7387e62",
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214"
  }
}' \
"http://localhost:8080/openidm/system/azuread/servicePrincipal/05b49121-0bf5-479e-8a4e-140212648879"

Response

{
  "_id": "05b49121-0bf5-479e-8a4e-140212648879",
  "addIns": [],
  "replyUrls": [],
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "displayName": "Test-Application",
  "appRoleAssignments": [
    {
      "resourceDisplayName": "Microsoft Graph",
      "resourceId": "b3e4e58e-16fa-4b3d-a7b5-f134b7387e62",
      "principalDisplayName": "Test-Application",
      "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
      "createdDateTime": "2023-05-05T20:41:15.373168300Z",
      "principalId": "05b49121-0bf5-479e-8a4e-140212648879",
      "id": "IZG0BfULnkeKThQCEmSIeS7n5ay2n99BiFNwyj97w8Y",
      "principalType": "ServicePrincipal"
    }
  ],
  "alternativeNames": [],
  "resourceSpecificApplicationPermissions": [],
  "appDisplayName": "Test-Application",
  "accountEnabled": true,
  "appOwnerOrganizationId": "9e91bf24-7a08-433e-b111-5542416b4f20",
  "passwordCredentials": [],
  "servicePrincipalNames": [
    "93dd36a4-61ca-4a1d-89cf-eac96587de35"
  ],
  "appId": "93dd36a4-61ca-4a1d-89cf-eac96587de35",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "notificationEmailAddresses": [],
  "servicePrincipalType": "Application",
  "tags": [],
  "appRoleAssignedTo": [],
  "info": {},
  "appRoles": [],
  "appRoleAssignmentRequired": false
}

Remove an app role assignment from a servicePrincipal

This process is identical for users and groups.

Request

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" \
--header "If-Match: *" \
--request PUT \
--data '{
  "__removeAppRoleAssignments__": "IZG0BfULnkeKThQCEmSIeS7n5ay2n99BiFNwyj97w8Y"
}' \
"http://localhost:8080/openidm/system/azuread/servicePrincipal/05b49121-0bf5-479e-8a4e-140212648879"

Response

{
  "_id": "05b49121-0bf5-479e-8a4e-140212648879",
  "addIns": [],
  "replyUrls": [],
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "displayName": "Test-Application",
  "appRoleAssignments": [],
  "alternativeNames": [],
  "resourceSpecificApplicationPermissions": [],
  "appDisplayName": "Test-Application",
  "accountEnabled": true,
  "appOwnerOrganizationId": "9e91bf24-7a08-433e-b111-5542416b4f20",
  "passwordCredentials": [],
  "servicePrincipalNames": [
    "93dd36a4-61ca-4a1d-89cf-eac96587de35"
  ],
  "appId": "93dd36a4-61ca-4a1d-89cf-eac96587de35",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "notificationEmailAddresses": [],
  "servicePrincipalType": "Application",
  "tags": [],
  "appRoleAssignedTo": [],
  "info": {},
  "appRoles": [],
  "appRoleAssignmentRequired": false
}

Add an app role to a principal (user/group/servicePrincipal) via a servicePrincipal

Request

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" \
--header "If-Match: *" \
--request PUT \
--data '{
  "__addAppRoleAssignedTo__": {
    "principalId": "87f5b3f8-6a8c-4e50-8fd6-0467d5e97e0c",
    "resourceId": "bf960539-a1d8-4eab-a46e-e9ce0b3f15c8",
    "appRoleId": "00000000-0000-0000-0000-000000000000"
  }
}' \
"http://localhost:8080/openidm/system/azuread/servicePrincipal/bf960539-a1d8-4eab-a46e-e9ce0b3f15c8"

Response

{
  "_id": "bf960539-a1d8-4eab-a46e-e9ce0b3f15c8",
  "addIns": [],
  "replyUrls": [],
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "displayName": "Test-Application",
  "appRoleAssignments": [],
  "alternativeNames": [],
  "resourceSpecificApplicationPermissions": [],
  "appDisplayName": "Test-Application",
  "accountEnabled": true,
  "appOwnerOrganizationId": "9e91bf24-7a08-433e-b111-5542416b4f20",
  "passwordCredentials": [],
  "servicePrincipalNames": [
    "62212657-8f49-40b3-874b-9d1c25cb4388"
  ],
  "appId": "62212657-8f49-40b3-874b-9d1c25cb4388",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "notificationEmailAddresses": [],
  "servicePrincipalType": "Application",
  "tags": [],
  "appRoleAssignedTo": [
    {
      "resourceDisplayName": "Test-Application",
      "resourceId": "bf960539-a1d8-4eab-a46e-e9ce0b3f15c8",
      "principalDisplayName": "qcmozfwwygkebie",
      "appRoleId": "00000000-0000-0000-0000-000000000000",
      "createdDateTime": "2023-05-05T20:41:25.405071800Z",
      "principalId": "87f5b3f8-6a8c-4e50-8fd6-0467d5e97e0c",
      "id": "-LP1h4xqUE6P1gRn1el-DCzqXtqJH6NBt0Fr0lT0g2g",
      "principalType": "User"
    }
  ],
  "info": {},
  "appRoles": [],
  "appRoleAssignmentRequired": false
}

Remove an app role from a principal (user/group/servicePrincipal) via a servicePrincipal

Request

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" \
--header "If-Match: *" \
--request PUT \
--data '{
  "__removeAppRoleAssignedTo__": "-LP1h4xqUE6P1gRn1el-DCzqXtqJH6NBt0Fr0lT0g2g"
}' \
"http://localhost:8080/openidm/system/azuread/servicePrincipal/bf960539-a1d8-4eab-a46e-e9ce0b3f15c8"

Response

{
  "_id": "bf960539-a1d8-4eab-a46e-e9ce0b3f15c8",
  "addIns": [],
  "replyUrls": [],
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "displayName": "Test-Application",
  "appRoleAssignments": [],
  "alternativeNames": [],
  "resourceSpecificApplicationPermissions": [],
  "appDisplayName": "Test-Application",
  "accountEnabled": true,
  "appOwnerOrganizationId": "9e91bf24-7a08-433e-b111-5542416b4f20",
  "passwordCredentials": [],
  "servicePrincipalNames": [
    "62212657-8f49-40b3-874b-9d1c25cb4388"
  ],
  "appId": "62212657-8f49-40b3-874b-9d1c25cb4388",
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "notificationEmailAddresses": [],
  "servicePrincipalType": "Application",
  "tags": [],
  "appRoleAssignedTo": [],
  "info": {},
  "appRoles": [],
  "appRoleAssignmentRequired": false
}

Synchronize accounts between IDM and Azure

To use the MS Graph API connector to synchronize accounts between IDM and Azure, set up a mapping between the two data stores.

You can use the sample configuration file at /path/to/openidm/samples/sync-with-azuread/conf/sync.json as a starting point.

OpenICF Interfaces Implemented by the MSGraphAPI Connector

The MSGraphAPI Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:

Authenticate

Provides simple authentication with two parameters, presumed to be a user name and password.

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector.

Any script that runs on the connector has the following characteristics:

The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.
The script has access to any script arguments passed in by the application.

Search

Searches the target resource for all objects that match the specified object class and filter.

Sync

Polls the target resource for synchronization events, that is, native changes to objects on the target resource.

Test

Tests the connector configuration.

Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

MSGraphAPI Connector Configuration

The MSGraphAPI Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Encrypted⁽¹⁾	Required⁽²⁾
`tenant`	`String`	`null`		Yes
The Azure AD tenant name or id
`clientId`	`String`	`null`		Yes
The clientID used by the connector during the OAuth flow
`clientSecret`	`GuardedString`	`null`	Yes	No
The client secret used by the connector during the OAuth flow
`httpProxyHost`	`String`	`null`		No
The Http proxy host
`httpProxyPort`	`Integer`	`null`		No
The Http proxy port
`httpProxyUsername`	`String`	`null`		No
The Http proxy user name
`httpProxyPassword`	`GuardedString`	`null`	Yes	No
The Http proxy user password
`performHardDelete`	`boolean`	`false`		No
If set to true, the Azure object will be deleted permanently on delete operation.
`readRateLimit`	`String`	`null`		No
Define throttling for read operations either per seconds ("30/sec") or per minute ("100/min").
`writeRateLimit`	`String`	`null`		No
Define throttling for write operations (create/update/delete) either per second ("30/sec") or per minute ("100/min").

tenant

String

null

Yes

The Azure AD tenant name or id

clientId

String

null

Yes

The clientID used by the connector during the OAuth flow

clientSecret

GuardedString

null

Yes

The client secret used by the connector during the OAuth flow

httpProxyHost

String

null

The Http proxy host

httpProxyPort

Integer

null

The Http proxy port

httpProxyUsername

String

null

The Http proxy user name

httpProxyPassword

GuardedString

null

Yes

The Http proxy user password

performHardDelete

boolean

false

If set to true, the Azure object will be deleted permanently on delete operation.

readRateLimit

String

null

Define throttling for read operations either per seconds ("30/sec") or per minute ("100/min").

writeRateLimit

String

null

Define throttling for write operations (create/update/delete) either per second ("30/sec") or per minute ("100/min").

⁽¹⁾ Whether the property value is considered confidential, and is therefore encrypted in IDM.

⁽²⁾ A list of operations in this column indicates that the property is required for those operations.

ICF 1.5.20.15

Microsoft Graph API Java connector

Before you start

Install the MS Graph API connector

Configure the MS Graph API connector

MS Graph API remote connector

Test the MS Graph API connector

Manage user licenses

Contacts

Role eligibility schedules

Role assignment schedules

Applications

servicePrincipal

Application permissions

Synchronize accounts between IDM and Azure

OpenICF Interfaces Implemented by the MSGraphAPI Connector

MSGraphAPI Connector Configuration

Basic Configuration Properties

`servicePrincipal`