Untitled :: ICF 1.5.20.21

Install and configure the MS Graph API connector

Microsoft Azure requirements

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

You can download any connector from Backstage, but some come bundled with Identity Cloud, IDM, or RCS by default. When using a bundled connector, you can skip installing it and move directly to configuration.

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

Download the connector .jar file from Backstage.

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.20.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.20.
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 connector

One simple method for testing the connector configuration is using the test action on the openidm/system endpoint:

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.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.msgraphapi-connector",
    "connectorName": "org.forgerock.openicf.connectors.msgraphapi.MSGraphAPIConnector"
  },
  "displayName": "MSGraphAPI Connector",
  "objectTypes": [
    "servicePrincipal",
    "__GROUP__",
    "roleEligibilitySchedule",
    "roleEligibilityScheduleInstance",
    "__ALL__",
    "roleEligibilityScheduleRequest",
    "directoryRole",
    "team",
    "roleAssignmentSchedule",
    "roleDefinition",
    "servicePlan",
    "directoryRoleTemplate",
    "application",
    "roleAssignmentScheduleRequest",
    "roleAssignmentScheduleInstance",
    "subscribedSku",
    "__ACCOUNT__",
    "roleAssignment"
  ],
  "ok": true (1)
}

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

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
Defines throttling for read operations either per seconds ("30/sec") or per minute ("100/min").
`writeRateLimit`	`String`	`null`		No
Defines throttling for write operations (create/update/delete) either per second ("30/sec") or per minute ("100/min").
`licenseCacheExpiryTime`	`Long`	`null`		No
Defines the expiry time for cached license information (in minutes).

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

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

writeRateLimit

String

null

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

licenseCacheExpiryTime

Long

null

Defines the expiry time for cached license information (in minutes).

⁽¹⁾ 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.