5.2 Installing the Driver Files

You can install the Azure AD driver on the Identity Manager server or with the Remote Loader.

5.2.1 Preparing for Installation

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

Prerequisites for the Driver

The driver requires the following applications:

  • Identity Manager 4.7 or later

  • Identity Manager Designer 4.7 or later

  • Identity Manager REST driver 1.0.0.1 or later

Prerequisites for the User Account Configured in the Driver

You must ensure that the user account you are configuring in the driver has the following Roles or Permissions in the Azure application:

  • At a minimum, the user account must have the following roles:

    • User Administrator

    • Exchange Service Administrator

    • Privileged Role Administrator

  • The multi-factor authentication for the user account is disabled.

  • A user account has conditional access. For more information on providing conditional access, see What is Conditional Access.

Prerequisites for Identity Manager Exchange Service

  • Microsoft Windows Server 2016, or Microsoft Windows Server 2019

  • Microsoft Windows Management Framework 4.0

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

    Download the packages from the Microsoft Downloads 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>

    3. Install the Exchange Online Management tool and execute the below command:

      Install-Module -Name ExchangeOnlineManagement

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

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 table. For more information see, Add permissions to access web APIs.

    API/Permission Name

    Type

    Description

    Admin consent required

    Azure Active Directory Graph (5)

     

     

     

    Device.ReadWrite.All

    Application

    Read and write devices

    Yes

    Directory.Read.All

    Application

    Read directory data

    Yes

    Directory.ReadWrite.All

    Application

    Read and write directory data

    Yes

    Domain.ReadWrite.All

    Application

    Read and write domains

    Yes

    Microsoft Graph (1)

     

     

     

    User.Read

    Delegated

    Sign in and read user profile

    No

NOTE:You may need to provide additional permissions based on their requirement.

As a minimal requirement, the user account used in Azure AD Driver configuration should have the following Roles:

  • User Administrator

  • Exchange Administrator

    NOTE:You may need to provide additional roles based on their requirement.

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. In the server where you have installed the exchange service, login to PowerShell and connect to the Office 365 Exchange Online service, 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.

    IMPORTANT:The Company Administrator role in Identity Manager is mapped to the Global Administrator role in Azure AD.

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.

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)

You must 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

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.

5.2.2 Installing the Driver and the Identity Manager Exchange Service

The driver installation program guides you through the driver and the Identity Manager Exchange Service installation.

Perform the following actions to install and configure the Exchange Service:

  1. Copy Exchange Service from [ISO]:\products\IDM\windows\setup\drivers\azuread\ExchangeService to any local drive on the server you intend to run this service.

  2. Navigate to the directory where you copied the ExchServerHost.exe in the first step.

    For example, C:\ExchangeService

  3. Run the following command to install the Exchange Service:

    <location of InstallUtil>\InstallUtil.exe ExchServerHost.exe

    For example:

    C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe ExchServerHost.exe

    where, C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe is the location where InstallUtil.exe is located.

  4. Ensure the server certificate is available in iManager. To create the server certificate, see Securing Communication with Identity Manager Exchange Service

  5. Open cmd prompt, and navigate to the local drive location where the ExchangeService is saved, as mentioned in Step 1 (\products\IDM\windows\setup\drivers\azuread\ExchangeService\), and execute the command configureExchService.bat <port> <certificate_name>.

    For example: configureExchService.bat 9001 azuread. Where 9001 is the port number and azuread is the nickname of the certificate that was created in iManager.

  6. To start the service, navigate to Control Panel > Administrative Tools > Services.

  7. Right-click the IDMExchangeOnline service and select Start.

NOTE:To uninstall the service, open a .NET command prompt and issue the InstallUtil /u ExchServerHost.exe command.

NetIQ recommends you to use TLS 1.1 and TLS 1.2 protocols with the Identity Manager Exchange Service. If you are using ciphers and protocols such as RC4 and Triple DES, or SSLv2/v3 on a server running Identity Manager Exchange Service, you must disable them using the disableWeakCiphers.reg file provided in the Exchange Service installation directory. You can either execute the registry file or import the file into Windows Registry. After the changes are made, restart the server. For more information about restricting the use of certain cryptographic algorithms and protocols on Windows servers, see Microsoft Support Site.

5.2.3 Verifying and Starting the Identity Manager Exchange Service

After finishing the installation of Identity Manager Exchange Service, verify that the service is properly installed.

NOTE:Ensure that SSL is configured for the Identity Manager Exchange Service before starting the service. This is a mandatory step before running the service. For more information, see Securing Communication with Identity Manager Exchange Service.

  1. From the Start menu, type regedit.

  2. On the Registry Editor page, locate the service at HKEY_LOCAL_MACHINE > Software > Novell > ExchServer and verify that the Port and CertificateFriendlyName have the correct values.

    The CertificateFriendlyName must be the same as Certificate Alias that you specified in Step 1 of the Securing Communication with Identity Manager Exchange Service.

  3. Navigate to the services that are running on your server and start the IDMExchangeOnline service.

5.2.4 Verifying the Provisioning of Exchange Mailbox

To verify the provisioned mailboxes for users, follow the procedure provided in the Microsoft Exchange Admin Center.