Microsoft Identity Manager connector for Microsoft Graph

Summary

The Microsoft Identity Manager connector for Microsoft Graph enables additional integration scenarios for Azure AD Premium customers. It surfaces in the MIM sync metaverse additional objects obtained from the Microsoft Graph API v1 and beta.

Scenarios covered

B2B account lifecycle management

The initial scenario for the Microsoft Identity Manager connector for Microsoft Graph is as a connector to help automate AD DS account lifecycle management for external users. In this scenario, an organization is synchronizing employees to Azure AD from AD DS using Azure AD Connect, and has also invited guests into their Azure AD directory. Inviting a guest results in an external user object being in that organization's Azure AD directory, which is not in that organization's AD DS. Then the organization wishes to give those guests access to on-premises Windows Integrated Authentication or Kerberos-based applications, via the Azure AD application proxy or other gateway mechanisms. The Azure AD application proxy requires each user to have their own AD DS account, for identification and delegation purposes.

To learn how to configure MIM sync to automatically create and maintain AD DS accounts for guests, after reading the instructions in this article, continue reading in the article Azure AD business-to-business (B2B) collaboration with MIM 2016 SP1 with Azure Application Proxy. That article illustrates the sync rules needed for the connector.

Other identity management scenarios

The connector can be used for other specific identity management scenarios involving create, read, update and delete of user, group and contact objects in Azure AD, beyond user and group synchronization to Azure AD. When evaluating potential scenarios, please keep in mind: this connector cannot be operated in a scenario, which would result in a data flow overlap, actual or potential synchronization conflict with an Azure AD Connect deployment. Azure AD Connect is the recommended approach to integrate on-premises directories with Azure AD, by synchronizing users and groups from on-premises directories to Azure AD. Azure AD Connect has many more synchronization features and enables scenarios such as password and device writeback, which are not possible for objects created by MIM. If data is being brought into AD DS, for example, ensure that it is excluded from Azure AD Connect attempting to match those objects back to the Azure AD directory. Nor can this connector be used to make changes to Azure AD objects, which were created by Azure AD Connect.

Preparing to use the Connector for Microsoft Graph

Authorizing the connector to retrieve or manage objects in your Azure AD directory

  1. The connector requires a Web app / API application to be created in Azure AD, so that it can be authorized with appropriate permissions to operate on Azure AD objects through Microsoft Graph.

Picture 1. New application registration

  1. In the Azure portal, open the created application, and save the Application ID, as a Client ID to use later on the MA’s connectivity page:

Picture 2. Application ID

  1. Generate new Client Secret by opening All settings -> Keys. Set some Key description and select needful Duration. Save changes. A secret value will not be available after leaving the page.

Picture 3. New Client Secret

  1. Add “Microsoft Graph API” to the application by opening “Required permissions.”

Picture 4. Add new API

The following permission should be added to the application to allow it to use the “Microsoft Graph API”, depending on the scenario:

Operation with object Permission required Permission type
Import Group Group.Read.All or Group.ReadWrite.All Application
Import User User.Read.All, User.ReadWrite.All, Directory.Read.All or Directory.ReadWrite.All Application

More details about required permissions could be found here.

  1. Grant the application the required permissions.

Installing the connector

  1. Before you install the Connector, make sure you have the following on the synchronization server:
  • Microsoft .NET 4.5.2 Framework or later
  • Microsoft Identity Manager 2016 SP1, and must use hotfix 4.4.1642.0 KB4021562 or later.
  1. The connector for Microsoft Graph, in addition to other connectors for Microsoft Identity Manager 2016 SP1, is available as a download from the Microsoft Download Center.

  2. Restart MIM Synchronization Service.

Connector configuration

  1. In the Synchronization Service Manager UI, select Connectors and Create. Select Graph (Microsoft) , create a connector and give it a descriptive name.

  1. In the MIM synchronization service UI, specify the Application ID and generated Client Secret. Each management agent configured in MIM Sync should have its own application in Azure AD to avoid running import in parallel for the same application.

Picture 5. Connectivity page

The connectivity page (Picture 5) contains the Graph API version that is used and tenant name. The Client ID and Client Secret represent the Application ID and Key value of the WebAPI application that must be created in Azure AD.

  1. Make any necessary changes on the Global Parameters page:

Picture 6. Global Parameters page

Global parameters page contains the following settings:

  • DateTime format – format that is used for any attribute with Edm.DateTimeOffset type. All dates are converted to string by using that format during the import. Set format is applied for any attribute, which saves date.

  • HTTP timeout (seconds) – timeout in seconds that will be used during each HTTP call to WebAPI application.

  • Force change password for created user at next sign – this option is used for new user that will be created during the export. If option is enabled, then forceChangePasswordNextSignIn property will be set to true, otherwise it will be false.

Configuring the connector schema and operations

  1. Configure the schema. The connector supports the following list of object types:
  • User

    • Full/Delta Import

    • Export (Add, Update, Delete)

  • Group

    • Full/Delta Import

    • Export (Add, Update, Delete)

The list of attribute types that are supported:

  • Edm.Boolean

  • Edm.String

  • Edm.DateTimeOffset (string in connector space)

  • microsoft.graph.directoryObject (reference in connector space to any of the supported objects)

  • microsoft.graph.contact

Multivalued attributes (Collection) are also supported for any of a type from the list above.

The connector uses the ‘id’ attribute for anchor and DN for all objects. Therefore, rename is not needed, because Graph API does not allow an object to change its ‘id’ attribute.

Access token lifetime

A Graph application requires an access token for accessing the Graph API. A connector will request a new access token for each import iteration (import iteration depends on page size). For example:

  • Azure AD contains 10000 objects

  • Page size configured in connector is 5000

In this case there will be two iterations during the import, each of them will return 5000 objects to Sync. So, a new access token will be request twice.

During the export a new access token will be requested for each object that must be added/updated/deleted.

Troubleshooting

Enable logs

If there are any issues in Graph, then logs could be used to localize the problem. So, traces could be enabled in the same way like for Generic connectors. Or just by adding the following to miiserver.exe.config (inside system.diagnostics/sources section):

<source name="ConnectorsLog" switchValue="Verbose">

<listeners>

<add initializeData="ConnectorsLog" type="System.Diagnostics.EventLogTraceListener, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="ConnectorsLogListener" traceOutputOptions="LogicalOperationStack, DateTime, Timestamp, Call stack" />

<remove name="Default" />

</listeners>

</source>

Note

If ‘Run this management agent in a separate process’ is enabled, then dllhost.exe.config should be used instead of miiserver.exe.config.

Access token expired error

Connector might return HTTP error 401 Unauthorized, message “Access token has expired.”:

Picture 7. “Access token has expired.” Error

The cause of this issue might be configuration of access token lifetime from the Azure side. By default, the access token expires after 1 hour. To increase expiration time, please see this article.

Example of this using Azure AD PowerShell Module Public Preview release

New-AzureADPolicy -Definition @('{"TokenLifetimePolicy":{"Version":1, "AccessTokenLifetime":"5:00:00"}}') -DisplayName "OrganizationDefaultPolicyScenario" -IsOrganizationDefault $true -Type "TokenLifetimePolicy"

Next steps

Scenario-specific guides

MIM B2B End to End Deployment