2.1 Preparing for Installation

This section provides the prerequisites, considerations, and system setup needed to install the driver:

2.1.1 Prerequisites for the Driver

The driver requires the following applications:

  • Identity Manager 4.6 or later

  • Identity Manager Designer 4.6 or later

  • Identity Manager REST driver 1.0.0.1 or later

2.1.2 Prerequisites for Identity Manager Exchange Service

  • Microsoft Windows Server 2008 R2, Microsoft Windows Server 2012, Microsoft Windows Server 2012 R2, Microsoft Windows Server 2016, or Microsoft Windows Server 2019

  • Microsoft Windows Management Framework 4.0 (required for Windows Server 2008 R2)

  • Microsoft Visual C++ 2017 Redistributable packages for Visual Studio

    Download the packages from the Microsoft Downloads website.

  • Microsoft Online Services Sign-In Assistant for IT Professionals RTW

    Download the packages from the Microsoft Download Center website.

  • Windows Azure AD Module for Windows PowerShell on the computer where you will install Windows Powershell service.

    Perform the following steps to upgrade PowerShell to the latest version:

    1. Open a Windows PowerShell console.

    2. Run the following Install-Module cmdlet or Install-Script cmdlet:

      • If it is a module: Install-Module -Name <moduleName> -RequiredVersion <version>

        For example, Install-Module -Name MSOnline -RequiredVersion 1.1.166.0

      • If it is a script: Install-Script -Name <scriptName> -RequiredVersion <version>

Identity Manager Exchange Service can be run on a user configured port. However, the service cannot be used with any other REST client tools.

2.1.3 Prerequisites for OAuth 2.0

The driver uses OAuth 2.0 protocol to authenticate to Azure AD. To support this protocol for authentication, you need to have a proxy application for the Azure AD driver on Azure AD. The Client ID and Client Secret allotted to the application will be later used in the Azure AD driver configuration. For more information about Azure Active Directory Application Proxy, see Microsoft Azure documentation.

Creating a Proxy Application on Azure AD

A proxy application is created in the Azure Portal. Creating a proxy application involves the following steps:

  1. Registering an application and obtaining a client ID. For more information see, Registering an Application.

  2. Generating an application password or the client secret. For more information see, Certificates and Secrets.

  3. Configuring API permissions (Delegated and Application permissions). Set the delegated and application permissions as shown in the following image. For more information see, Add permissions to access web APIs.

The Client ID and Client Secret can now be used for driver configurations or any other REST clients.

Assigning the Rights to the Application

  1. Log in to PowerShell and connect to the Office 365 Exchange Online service by using the following command:

    Connect-MSolService
  2. To obtain the Client ID for your application, replace <AppPrincipalId> with the Client ID that you obtained from Creating a Proxy Application on Azure AD and run the following commands in PowerShell.

    Get-MsolServicePrincipal | ft DisplayName, <AppPrincipalId> -AutoSize
    
    $ClientIdWebApp = ’<AppPrincipalId>’
    
    $webApp = Get-MsolServicePrincipal –AppPrincipalId $ClientIdWebApp
  3. Assign the Company Administrator rights to your application using the Client ID obtained in Step 2 by running the following command:

    Add-MsolRoleMember -RoleName "Company Administrator" -RoleMemberType ServicePrincipal -RoleMemberObjectId $webApp.ObjectID

    The Company Administrator role will give you rights to delete the directory objects.

Ensure that the account used by the driver to connect to the Exchange Online service has the correct roles to load and execute the following cmdlets:

  • New-Mailbox

  • Set-Mailbox

  • Get-Mailbox

  • Remove-Mailbox

  • New-MailUser

  • Set-MailUser

  • Get-MailUser

  • Remove-MailUser

  • Set-User

  • Get-User

  • New-DistributionGroup

  • Set-DistributionGroup

  • Set-Group

  • Get-DistributionGroup

  • Get-Group

  • Remove-DistributionGroup

  • Add-DistributionGroupMember

  • Remove-DistributionGroupMember

  • Get-DistributionGroupMember

  • Add-RoleGroupMember

  • Remove-RoleGroupMember

  • Get-RoleGroupMember

  • New-UnifiedGroup

  • Get-UnifiedGroup

  • Set-UnifiedGroup

  • Remove-UnifiedGroup

  • Add-UnifiedGroupLinks

  • Remove-UnifiedGroupLinks

  • Get-UnifiedGroupLinks

Absence of the required roles prevents the driver from executing the cmdlets that require those roles.

2.1.4 Prerequisites for Support of Modern Authentication

As Microsoft Office 365 is deprecating the Basic authentication, you must now configure the driver with modern authentication method. You must also ensure to have the earlier mentioned prerequisites (Prerequisites for the Driver, Prerequisites for Identity Manager Exchange Service, and Prerequisites for OAuth 2.0) met, and then proceed with the following prerequisites.

The following prerequisites are specific to modern authentication. It is highly recommended to upgrade the driver version 5.1.x to 5.1.3 to support modern authentication.

Installing the Microsoft Exchange Online PowerShell V2 (EXO V2)

For Azure AD 5.1.3, you must mandatorily install the Microsoft Exchange Online PowerShell V2 module to support the new API’s. For more information on EXO V2 module, see About the Exchange Online PowerShell V2 module.

Configuring Azure AD Proxy Application for Modern Authentication Methods

IMPORTANT: This configuration is applicable for Azure AD Driver 5.1.3 and later versions only. It is highly recommended that you upgrade your driver instance to version 5.1.3 or later.

You must upgrade the Azure AD driver version to 5.1.3 as Microsoft Office 365 is deprecating the Basic authentication support. This deprecation enforces the driver to be configured with advance authentication method. It is mandatory to upgrade the existing driver version 5.1.x to 5.1.3 to support modern authentication.

If you are setting up the Azure AD driver 5.1.3 version, you must enable the permission in the Azure portal to access Microsoft Office 365 with modern authentication.

The procedure to set the permission is shown below:

  1. Login to the Azure AD Portal.

  2. Select Azure Active Directory.

  3. Navigate to App Registration > find and select your application in the list (for example: <MySample_Azure_Appln>) > Authentication > Advanced Settings.

  4. Set Treat Application as a Public Client permission to Yes.

    IMPORTANT:The multi-factor authentication (MFA) must be disabled for the Azure account which is used with the driver.