3.1 Preparing for Installation

3.1.1 Prerequisites

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.8.4 or later
Identity Manager Designer 4.8.4 or later
Identity Manager REST driver 1.1.2.0400 or later

Prerequisites for the User Account to be 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 Administrator
- Privileged Role Administrator
- Teams 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.

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

Prerequisites for Identity Manager Exchange Service

Microsoft Windows Server 2016, or Microsoft Windows Server 2019.
Install .NET Framework 4.7.2 or later.
Microsoft Visual C++ 2017 Redistributable packages for Visual Studio.

Download the packages from the Microsoft Downloads website.
Upgrade to PowerShell 5.1 or later.
Update PowerShellGet to the latest version using Install-Module PowerShellGet -Force-5
Install the ExchangeOnlineManagement and Microsoft Graph modules by executing the below commands in PowerShell:
- Install-Module -Name ExchangeOnlineManagement
- Install-Module Microsoft.Graph -Scope AllUsers
NOTE:If you get “Unable to resolve package source” error, then run [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 command before running the Install-Module commands.
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. Refer to www.powershellgallery.com
  - 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.

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:

Registering an application and obtaining a client ID. For more information see, Registering an Application.
Generating an application password or the client secret. For more information see, Certificates and Secrets.

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.

Table 3-1 List of Application type of APIs

API	Type	Description	Admin Consent
Application.Read.All	Application	Read all applications	Grant Admin Consent
Application.ReadWrite.All	Application	Read and write all applications	Grant Admin Consent
AuditLog.Read.All	Application	Read all audit log data	Grant Admin Consent
Channel.Create	Application	Create channels	Grant Admin Consent
Channel.Delete.All	Application	Delete channels	Grant Admin Consent
Channel.ReadBasic.All	Application	Read the names and descriptions of all channels	Grant Admin Consent
ChannelMember.Read.All	Application	Read the members of all channels	Grant Admin Consent
ChannelMember.ReadWrite.All	Application	Add and remove members from all channels	Grant Admin Consent
ChannelSettings.Read.All	Application	Read the names, descriptions, and settings of all channels	Grant Admin Consent
ChannelSettings.ReadWrite.All	Application	Read and write the names, descriptions, and settings of all channels	Grant Admin Consent
Device.Read.All	Application	Read all devices	Grant Admin Consent
Device.ReadWrite.All	Application	Read and write devices	Grant Admin Consent
Directory.Read.All	Application	Read directory data	Grant Admin Consent
Directory.ReadWrite.All	Application	Read and write directory data	Grant Admin Consent
Domain.ReadWrite.All	Application	Read and write domains	Grant Admin Consent
Group.Create	Application	Create groups	Grant Admin Consent
Group.Read.All	Application	Read all groups	Grant Admin Consent
Group.ReadWrite.All	Application	Read and write all groups	Grant Admin Consent
GroupMember.Read.All	Application	Read all group memberships	Grant Admin Consent
GroupMember.ReadWrite.All	Application	Read and write all group memberships	Grant Admin Consent
Team.Create	Application	Create teams	Grant Admin Consent
Team.ReadBasic.All	Application	Get a list of all teams	Grant Admin Consent
TeamMember.Read.All	Application	Read the members of all teams	Grant Admin Consent
TeamMember.ReadWrite.All	Application	Add and remove members from all teams	Grant Admin Consent
TeamMember.ReadWriteNonOwnerRole.All	Application	Add and remove members with non-owner role for all teams	Grant Admin Consent
TeamSettings.Read.All	Application	Read all teams' settings	Grant Admin Consent
TeamSettings.ReadWrite.All	Application	Read and change all teams' settings	Grant Admin Consent
User.Read.All	Application	Read all users	Grant Admin Consent
User.ReadWrite.All	Application	Read and write all users' full profiles	Grant Admin Consent
UserAuthenticationMethod.Read.All	Application	Read all user authentication methods	Grant Admin Consent
UserAuthenticationMethod.ReadWrite.All	Application	Read and write all users authentication methods	Grant Admin Consent

Table 3-2 List of Delegated type of APIs

API	Type	Description	Admin Consent
AuditLog.Read.All	Delegated	Read audit log data	Grant Admin Consent
Directory.AccessAsUser.All	Delegated	Access directory as the signed in user	Grant Admin Consent
Directory.Read.All	Delegated	Read directory data	Grant Admin Consent
Directory.ReadWrite.All	Delegated	Read and write directory data	Grant Admin Consent
Group.Read.All	Delegated	Read all groups	Grant Admin Consent
Group.ReadWrite.All	Delegated	Read and write all groups	Grant Admin Consent
GroupMember.Read.All	Delegated	Read group memberships	Grant Admin Consent
GroupMember.ReadWrite.All	Delegated	Read and write group memberships	Grant Admin Consent
RoleManagement.Read.All	Delegated	Read role management data for all RBAC providers	Grant Admin Consent
RoleManagement.Read.Directory	Delegated	Read directory RBAC settings	Grant Admin Consent
UserAuthenticationMethod.Read	Delegated	Read user authentication methods	Grant Admin Consent
UserAuthenticationMethod.Read.All	Delegated	Read all user’s authentication methods	Grant Admin Consent
UserAuthenticationMethod.ReadWrite	Delegated	Read and write user authentication methods	Grant Admin Consent
UserAuthenticationMethod.ReadWrite.All	Delegated	Read and write all user authentication methods	Grant Admin Consent
User.Read	Delegated	Sign in and read user profile	Grant Admin Consent
User.Read.All	Delegated	Read all users' full profiles	Grant Admin Consent
User.ReadBasic.All	Delegated	Read all users' basic profiles	Grant Admin Consent
User.ReadWrite	Delegated	Read and write access to user profile	Grant Admin Consent
User.ReadWrite.All	Delegated	Read and write all users' full profiles	Grant Admin Consent

NOTE:You may need to provide additional permissions 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

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
```
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
```
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
Get-MsolUser
Set-MsolUser

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 or later 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.

For prerequisites to install the EXO V2 module, see Prerequisites for EXO V2 module.
For installing the EXO V2 module, see Install the EXO 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.

NOTE:Before upgrading to 5.1.6 ensure to run this command on the server running the Identity Manager Exchange Service using PowerShell.

The procedure to set the permission is shown below:

Login to the Azure AD Portal.
Select Azure Active Directory.
Navigate to App Registration > find and select your application in the list (for example: <MySample_Azure_Appln>) > Authentication > Advanced Settings.
Set Enable the following mobile and desktop flows under Allow public client flows permission to Yes.

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

3.1.2 Installing the Driver and the Identity Manager Exchange Service

You can install the Azure AD driver on the Identity Manager server or with the Remote Loader. The driver installation program guides you through the driver and the Identity Manager Exchange Service installation.

NOTE:

IDM Exchange service must be run on the same machine as the driver and configured to listen only on local host.
IDM Exchange service must be run with least privilege required for the configured PowerShell cmdlets to execute.
Only system administrator must be provided access to the IDM exchange service machine

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

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.
Navigate to the directory where you copied the ExchServerHost.exe in the first step.

For example, C:\ExchangeService
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.
Ensure the server certificate is available in iManager. To create the server certificate, see Securing Communication with Identity Manager Exchange Service
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 configureExchService batch file as explained below.

NOTE:When upgrading the driver from 5.1.5 to 5.1.6 in the Identity Manager Exchange Server, you need to replace ExchServerHost.exe,IDMExchServer.dll files and configureExchService.bat files located in \ExchangeService folder.

While installing the Identity Manager Exchange Service for the first time using the port and certificate, you need to add an additional argument AuthenticationType. This argument refers to whether you want to use the Basic Authentication or Certificate Based Authentication. The certificate friendly name provided in the command should be the nickname (exchcba) of the certificate to be created for the Identity Manager Exchange Service.

Example for Basic Authentication Command:

configureExchService.bat 9001 exchcba 0

Example for Certificate Based Authentication Command:

configureExchService.bat 9001 exchcba 5

There is another way of choosing the authentication type via Registry Editor as explained below.

Goto Registry Editor and navigate to HKEY_LOCAL_MACHINE -> Software -> Novell -> ExchServer

You can edit the value of the key AuthenticationType as required.

Below is the snapshot of the Registry Editor where only 3 keys are present after upgrading to 5.1.6.

Figure 3-1

NOTE:When you choose Basic Authentication in iManager, go to the Identity Manager Exchange Server and edit the value of AuthenticationType in the registry to 0. Similarly when you choose Certificate Based Authentication in iManager, then go to the Identity Manager > Exchange Server and edit the value of AuthenticationType in the registry to 5.

Apart from this, you need to run the IDMExchangeOnline service as an Administrator. Run Services.msc and go to the IDMExchangeOnline, right click IDMExchangeOnline and select Properties and under Log On, Select “This account” and provide the credentials of Local administrator account as shown below.

Figure 3-2

NOTE:Windows Local Administrator account is the one that gets created when you install a Windows Server and this account is not part of domain.
To start the service, navigate to Control Panel > Administrative Tools > Services.
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.

3.1.3 Securing Driver Communication

The driver communicates over SSL with Azure AD and Identity Manager Exchange Service.

IMPORTANT:The connection accepts certificates only from a Java keystore. Make sure that the keystore for the certificates is a Java keystore.

The following sections provide instructions for creating a secure connection:

Securing Communication with Identity Manager Exchange Service

To set up SSL between the driver and Identity Manager Exchange Service, you need to create and import a server certificate into the root certificate store of the Windows server where the service is deployed. The following procedure assumes eDirectory as the Certificate Authority (CA).

Login to Identity Console as an Administrator -> Certificate Management -> Server Certificate Management -> Click “+” icon
1. Provide the Nickname and for creation method select Custom.
  
  For example: Nickname could be “exchcba”.
2. Select Organizational Certificate Authority.
3. Click Next.
4. Under Certificate Parameters, click + for Subject Alternative Names, select Type (Choose IP Address from the drop-down and Name: Enter the IP Address of the Server running Identity Manager Exchange Service). Click Next.
5. Select Your organization's certificate and click Next.
6. Click OK until the certificate is successfully created.
Export the server certificate created for Identity Manager Exchange Service in step 1a, from the connected eDirectory server and save it to a file in the pfx format.
1. Login to Identity Console, log in to the connected eDirectory server with administrator rights.
2. Click Certificate Management > Server Certificate Management , then select the Server Certificate that has been created (ex: exchcba) for exchange service in step1.
3. Click to export the certificate.
4. Ensure that by default the Identity Manager Exchange Server Certificate (as created in Step1) has been selected and select Export Private Key.
5. Enter the password and click OK.
6. To save the certificate to a file, click Save the Exported File.
Import the certificate to the trusted store of the Windows server on which you will run Identity Manager Exchange Service.
1. Copy the .pfx file to the Windows server.
2. Click Start > Run> mmc.
3. Click File > Add/Remove Snap-in.
4. Select Certificates and click Add to import this snap-in by choosing Computer account.
5. Click Finish.
6. Navigate to Certificates > Trusted Root Certification Authorities.
7. Right-click and then select All Tasks > Import.
8. On the Welcome to the Certificate Import Wizard page, click Next.
9. Click Browse and select the eDirectory certificate you exported in
10. Specify the password and click Next.
11. Click Finish to import the certificate into the trust store.
Start Identity Manager Exchange Service. For more information, see Verifying and Starting the Identity Manager Exchange Service.
Open the following Exchange service URL from your browser:

https://<Exchange_Service>:Port/ExchServer
Obtain the public certificate and import it into the same keystore which was created and placed in IDM Server as mentioned in (for example, the keystore azuread).

For example, perform the following steps to obtain a public certificate on Google Chrome:
1. Click from the address bar and then click Details.
2. In the Security tab, click View Certificate.
3. In the Details tab, click Copy to File.
4. In the Certificate Import Wizard, click Next.
5. Select DER encoded binary and click Next.
6. Click Browse and navigate to the directory where you want to save the certificate.
7. Specify a name for the certificate and click Next.
8. Click Finish to complete the export.
9. Add the exported key to the driver keystore by using the following Java keytool command:
```
keytool -import -file <path to the exchange cert file>\<certname.cer> -keystore <mykeystore> -alias <aliasname>
```
  NOTE:Ensure that certificates inside the keystore have different alias names for all the imported certificates. Use the existing driver keystore if you are upgrading the driver from 5.1.5 to 5.1.6.

Secured Communication with Microsoft Graph API

To set up SSL between the driver and Azure AD graph REST endpoints, perform the following steps:

Open the following URL from your browser:
- https://login.microsoftonline.com/
- https://graph.microsoft.com/
- https://azure.microsoft.com/
Obtain the public certificate and import it into the keystore.

For example (Suppose you are accessing https://graph.microsoft.com/), if you are using Google Chrome, perform the following steps:
1. In the address bar, click and then click next to browser address bar (for example:graph.microsoft.com).
2. Select Certificate (Valid). The certificate is displayed.
3. Click Certification Path. The Certification Path displays the hierarchical structure of the structure of all the certificates.
4. Select the root certificate (the top most parent certificate), and click View Certificate. The root certificate is displayed.
5. To save the certificate to your system, click Details > Copy to File > Next > Next.
6. Enter a filename for the certificate and save it to a location as required.
7. Add the exported key to the driver keystore using the following Java keytool command:
  
  You might have to create a new keystore(.jks file), if one such file doesn’t exist already. This keystore file will contain the public certificate of the Azure graph endpoint and the exchange service certificate.
```
keytool -import -file <path to the graph cert file>\<certname.crt> -keystore <mykeystore> -alias <aliasname>
```
  For example: keytool -import -file msgraph.cer -keystore azuread.jks -alias msgraph
  NOTE:
  Ensure to place the new keystore in IDM Server. In case of Remote Loader place the keystore file in the system where the Azure AD driver is running.
  
  Ensure that you follow the above steps to import all the certificates into the keystore.

Certificate Based Authentication in Azure AD Driver 5.1.6

Generate a password protected private key in PEM format by executing the below commands. You can use an existing password protected private key in PEM format or create a password protected private key using the below command.

openssl genrsa -aes256 -out private_key.pem 2048

Note: this command will ask you to provide a password for this private key.
Generate a certificate signing request using the private key.

openssl req -new -key private_key.pem -out cert.csr

Note: This command will ask you to input the password for the private key.

Also, this command will ask for a variety of extra information, like company name, country, and a password. None of this is used by the sample, so you can set these values as nothing/anything you want.
Generate a x509-certificate using the csr file and the private key

openssl x509 -req -days 365 -in cert.csr -signkey private_key.pem -out cert.crt

Note: This command will ask you to input the password for the private key
Generate the pfx certificate using the crt file and the private key

openssl pkcs12 -export -out certcba.pfx -inkey private_key.pem -in cert.crt -name "mypfxfile"

Note: This command will first ask you to input the password for the private key.Then it asks you to provide the password for the pfx certificate which will be used as the keystore password in configuring Azure CBA. In the above command the “-name” parameter refers to alias which will be used as an input in configuring Azure CBA.
Using Designer, perform the following steps.
1. Right Click Driver Object and click Properties.
2. Goto Driver Configuration -> Driver Parameter
3. Under Driver Options, choose Certificate Based Authentication as authentication type and provide following details.
  1. Tenant ID
  2. Keystore Path (Ex: /yourdirectorypath/certcba.pfx) - is the absolute location to keystore file created in Step 4.
  3. Keystore Password: the password that you provided in step 4 for generating the pfx certificate.
  4. Certificate Path (Ex: /yourdirectorypath/cert.crt) - is the absolute location to the certificate created in Step 3.
  5. Alias: the value of the parameter “-name” that you provided in step 4.
  6. Uploading certificate to Azure AD and configure the driver parameters.
    
    Login to the Azure portal. In the Application menu blade, click on the Certificates & secrets, in the Certificates section, upload certificate generated in Step 3 (the crt file).