Setup of certificate based authentication for Exchange Online integration

How does it work?

The Exchange Online PowerShell module uses the Active Directory Authentication Library to fetch an app-only token using the application ID, tenant ID (organization), and certificate thumbprint. The application object provisioned inside Azure AD has a Directory Role assigned to it, which is returned in the access token. The session's role based access control (RBAC) is configured using the directory role information that's available in the token.

Connection:

The connection to Security & Compliance PowerShell is used through a CertificateThumbprint parameter which is supported only in Microsoft Windows.

Connect-IPPSSession -CertificateThumbPrint " Certificate_ThumbPrint >" -AppID Your_ AppID > -Organization " organization >" Prerequisites:

The certificate needs to be installed on all the computer/computers (MID server) where you're running the integration. The certificate should be installed in the user certificate store. Exchange Online Powershell V3 module (Version 3.2.0) must be installed on all the required Windows MID servers. Exchange Online cmdlets in this module are REST-backed and do not require Basic Authentication to be enabled in WinRM Link - ExchangeOnlineManagement 3.2.0 Set up Certificate based authentication (CBA) or app-only authentication An initial onboarding is required for authentication using application objects. Application and service principal are used interchangeably, but an application is like a class object while a service principal is like an instance of the class. For more information, see Application and service principal objects in Azure Active Directory .

For a detailed visual flow about creating applications in Azure AD, see https://aka.ms/azuread-app .

Register the application in Azure AD .

Assign API permissions to the application

For the application object to access resources, it needs to have the Application permission Exchange.ManageAsApp and Mail.ReadWrite Generate a self-signed certificate and grant access to private key

Create and configure a self-signed X.509 certificate, which is used to authenticate your Application against Azure AD, while requesting the app-only access token. Next Generation (CNG) certificates are not supported for app-only authentication with Exchange. CNG certificates are created by default in modern Windows versions. You must use a certificate from a CSP key provider. (-Provider = ' Microsoft Strong Cryptographic Provider ')

Attach the certificate to the Azure AD application

Assign Azure AD roles to the application

The application needs to have the Compliance Administrator Azure AD role assigned.

Create a new service principal Step 1: Register the application in Azure AD Open the Azure AD portal at https://portal.azure.com/ .

In the Search box at the top of the page, start typing App registrations , and then select App registrations from the results in the Services section.

Or, to go directly to the App registrations page, use https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade .

On the App registrations page, select New registration .

On the Register an application page that opens, configure the following settings:

Name : Enter something descriptive. For example, ExO PowerShell CBA.

Supported account types : Verify that Accounts in this organizational directory only ( only - Single tenant) is selected.

To make the application multi-tenant for Exchange Online delegated scenarios, select the value Accounts in any organizational directory (Any Azure AD directory - Multitenant) .

When you're finished on the App registrations page, select Register .

Leave the app page that you return to open. You'll use it in the next step.

Step 2: Assign API permissions to the application The procedures in this section replace any default permissions that were automatically configured for the new app. The app doesn't need the default permissions that were replaced.

On the app page under Management , select Manifest .

On the Manifest page that opens, find the requiredResourceAccess entry (on or about line 47).

Modify the resourceAppId , resourceAccess id , and resourceAccess type values as shown in the following code snippet:

"requiredResourceAccess": [ { "resourceAppId": "00000002-0000-0ff1-ce00-000000000000", "resourceAccess": [ { "id": "dc50a0fb-09a3-484d-be87-e023b12c6440", "type": "Role" } ] }, { "resourceAppId": "00000003-0000-0000-c000-000000000000", "resourceAccess": [ { "id": "e2a3a72e-5f79-4c64-b1b1-878b674786c9", "type": "Role" } ] } ], When you're finished on the Manifest page, select Save .

Still on the Manifest page, select API permissions under Management .

On the API permissions page that opens, do the following steps:

API / Permissions name : Verify the value Exchange.ManageAsApp and Mail.ReadWrite is shown.

Status : The current incorrect value is Not granted for , and this value needs to be changed.

Select Grant admin consent for , read the confirmation dialog that opens, and then select Yes .

The Status value should now be Granted for .

Close the current API permissions page (not the browser tab) to return to the App registrations page. You use the App registrations page in an upcoming step.

Step 3: Generate a self-signed certificate and grant access to private key Create a self-signed x.509 certificate using the following methods:

Use the New-SelfSignedCertificate , Export-Certificate and Export-PfxCertificate cmdlets in an elevated (run as administrator) Windows PowerShell session to request a self-signed certificate and export it to .cer and .pfx (SHA1 by default). For example:

# Create certificate $mycert = New-SelfSignedCertificate -DnsName "snowsecops.onmicrosoft.com" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter ( Get-Date ).AddYears(2) -KeySpec KeyExchange -Provider "Microsoft Strong Cryptographic Provider" # generate password fro private key $mypwd = ConvertTo-SecureString -String ' ' -Force -AsPlainText # Export certificate to .pfx file $mycert | Export-PfxCertificate -FilePath mycert.pfx -Password $mypwd # Export certificate to .cer file $mycert | Export-Certificate -FilePath mycert.cer Grant private key access to MID service user:

Open mmc : (Microsoft Management Console) From your Microsoft Management Console (MMC), navigate to and expand Certificates(Local Computer) > Personal > Certificates (If mmc has no menu item, add them. File -> Add Remove snap-in) Right-click on the certificate which you have generated in the previous step. Expand All Tasks > Manage Private Keys Add the MID service user to the accessor list.

Step 4: Attach the certificate to the Azure AD application After you register the certificate with your application, you can use the thumbprint for authentication.

On the Owned applications tab on the Apps registration page from the end of Step 2 , select your application.

If you need to get back to Apps registration page, use https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps , verify the Owned applications tab is selected, and then select your application.

On the application page that opens, under Manage , select Certificates & secrets .

On the Certificates & secrets page that opens, select Upload certificate .

In the dialog that opens, browse to the self-signed certificate ( .cer file) that you created in Step 3 .

When you're finished, select Add .

The certificate is now shown in the Certificates section.

Note down the CertificateThumbPrint and close the current Certificates & secrets page. You'll use it in Step 6.

Step 5: Assign Azure AD roles to the application In Azure AD portal at https://portal.azure.com/ , start typing roles and administrators in the Search box at the top of the page, and then select Azure AD roles and administrators from the results in the Services section.

Or, to go directly to the Azure AD roles and administrators page, use https://portal.azure.com/#view/Microsoft_AAD_IAM/AllRolesBlade .

On the Roles and administrators page that opens, find and select one of the supported roles by clicking on the name of the role (not the check box) in the results.

Find and select the Compliance Administrator role.

On the Assignments page that opens, select Add assignments .

In the Add assignments flyout that opens, find and select the app that you created in Step 1 .

When you're finished in the Add assignments flyout, select Add .

Back on the Assignments page, verify that the role has been assigned to the app.

Step 6: Create a new service principal Note: You need to connect to Security & Compliance PowerShell before completing steps to create a new service principal. Creating a new service principal without connecting to PowerShell won't work (your Azure App ID and Object ID are needed to create the new service principal).

Run the following command to store the details of the Azure application that you registered in Step 1 ( ) in a variable:

Install-Module -Name AzureAD Import-Module -Name AzureAD Connect-AzureAD $AADApp = Get-AzureADServicePrincipal -SearchString " " For detailed syntax and parameter information, see Get-AzureADServicePrincipal .

In the same PowerShell window, connect to Security & Compliance PowerShell :

Import-Module ExchangeOnlineManagement Connect-IPPSSession -CertificateThumbPrint " Certificate_ThumbPrint >" -AppID $AADApp.AppId -Organization " organization >" and run the following commands to create a service principal object for the Azure application New-ServicePrincipal -AppId $AADApp .AppId -ObjectId $AADApp .ObjectId -DisplayName " " For detailed syntax and parameter information, see New-ServicePrincipal .