Configuring Microsoft Azure for Email Archive

The following steps provide guidelines for granting Email Archive access to Microsoft 365 mailboxes.

  1. Registering an application in Microsoft Azure
  2. Configuring role based access control for the application in Exchange Online
  3. Configuring the Email Archive profile

1) Registering an application in Microsoft Azure

  1. Go to https://portal.azure.com/#home.
  2. Navigate to App registrations (you may want to search for it), and then select New registration.
  3. Provide an application name.
  4. Under Supported account types, choose who can use the application. Microsoft recommends that organizations select the Accounts in this organizational directory only option for most applications.
  5. Select Register to complete the app registration. Azure AD will assign a unique application (client) ID to your app, and then take you to your application's Overview page. Record the Application (client) ID and Directory (tenant) IDfor use in the Email Archive profile configuration process.
  6. Select Certificates & secrets > Client secrets > New client secret.
  7. Provide a description and an expiration time period, and click Add.

    8. Important: Keep a record of your client secret value because it will be hidden next time you view it.

  8. On the App registrations page, click the app you just created, and then select Authentication.
  9. Click Add a platform, and select Mobile and desktop applications.
  10. Select https://login.microsoftonline.com/common/oauth2/nativeclient and https://login.live.com/oauth20_desktop.srf (LiveSDK). Then, click Configure.
  11. Navigate to Enterprise applications (you may want to search for it). Record the Application ID and Object ID. It will be used when configuring Role Based Access Control for Applications in Exchange Online.

2) Configuring Role Based Access Control for Applications in Exchange Online

Grant permissions to an application that needs to access data in Exchange Online. Use a resource scope to specify which mailboxes an app can access. Microsoft documents two options for defining a resource scope, using either management scopes or administrative units. You can create management scopes through an Exchange PowerShell cmdlet. You can create administrative units with the Microsoft Entra admin center user interface.

The general process for how to create Application RBAC assignments:

  1. Create a new resource scope. Choose between Administrative Units or Management Scopes.
  2. Create a pointer to a Microsoft Entra service principal
  3. Take note of the appropriate application role for the service principal. Email Archive requires the Mail.Read and Mail.ReadWrite roles.
  4. Create a new role assignment where the Mail.Read and Mail.ReadWrite roles are assigned to the resource scope.
  5. Test the new service principal

Option 1: Creating a role assignment using administrative units

  1. Follow the steps outlined in Create an administrative unit to create a new administrative unit.
  2. Follow the steps outlined in Add users, groups, or devices to an administrative unit to add users/mailboxes to the administrative unit. These are the mailboxes that you want Email Archive to access.
  3. Record the Object ID of the administrative unit. It will be used in Create a New Role assignment section.
  4. Connect to the Exchange Online PowerShell module. The following sample PowerShell commands demonstrate the process.

    Install-Module -Name ExchangeOnlineManagement

    Import-Module ExchangeOnlineManagement

    Connect-ExchangeOnline -Organization <TENANT_ID>

  5. Create a pointer to a Microsoft Entra service principal. The following sample PowerShell command demonstrates the process. Replace <APPLICATION_ID> and <Object_ID> with the Application ID and the Object ID values recorded in step 11 when registering an application in Azure.

    New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID> -DisplayName <name>

  6. Create a new role assignment that grants the Mail.Read and Mail.ReadWrite permissions to the administrative unit. The following sample PowerShell commands demonstrate the process. Replace <APPLICATION_ID> with the Application ID of the registered Azure application and <ADMIN_UNIT_OBJECTID> with the Object ID recorded when creating the administrative unit.

    New-ManagementRoleAssignment -Name <name> -Role "Application Mail.Read" -App <APPLICATION_ID> -RecipientAdministrativeUnitScope <ADMIN_UNIT_OBJECTID>

    New-ManagementRoleAssignment -Name <name> -Role "Application Mail.ReadWrite" -App <APPLICATION_ID> -RecipientAdministrativeUnitScope <ADMIN_UNIT_OBJECTID>

  7. Optional: Testing the new role assignment for the service principal. The following sample PowerShell command demonstrates using the Test-ServicePrincipalAuthorization cmdlet. Replace <APPLICATION_ID> with the Application ID of the registered Azure application and <MAILBOXADDRESS> with the email address you want Email Archive to access.

    Test-ServicePrincipalAuthorization -Identity <APPLICATION_ID> -Resource <MailBoxAddress>

Option 2: Creating a role assignment using management scopes

Use the New-ManagementScope cmdlet to create a management scope.

  1. Connect to the Exchange Online PowerShell module. The following sample PowerShell commands demonstrate the process.

    Install-Module -Name ExchangeOnlineManagement

    Import-Module ExchangeOnlineManagement

    Connect-ExchangeOnline -Organization <TENANT_ID>

  2. Run the following command in Windows PowerShell to create a management scope. Replace <MANAGEMENT_SCOPE_NAME> with a name for the management scope. This name will then be used in a following step when creating a role assignment. Replace <USER_PRINCIPAL_NAME> with the email address you want Email Archive to access. See Microsoft's documentation for additional details on the RecipientFilter paramater.

    New-ManagementScope -Name "<MANAGEMENT_SCOPE_NAME>" -RecipientRestrictionFilter "UserPrincipalName -eq '<USER_PRINCIPAL_NAME>'"

  3. Create a pointer to a Microsoft Entra service principal. The following sample PowerShell command demonstrates the process. Replace <APPLICATION_ID> and <Object_ID> with the Application ID and the Object ID values recorded in step 11 when registering an application in Azure.

    New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID> -DisplayName <name>

  4. Create a new role assignment that grants the Mail.Read and Mail.ReadWrite permissions to the management scope. The following sample PowerShell commands demonstrate the process. Replace <APPLICATION_ID> with the Application ID of the registered Azure application and <Management Scope> with the name of the management scope.

    New-ManagementRoleAssignment -Name <name> -Role "Application Mail.Read" -App <APPLICATION_ID> -CustomResourceScope <Management Scope>

    New-ManagementRoleAssignment -Name <name> -Role "Application Mail.ReadWrite" -App <APPLICATION_ID> -CustomResourceScope <Management Scope>

  5. Optional: Testing the new role assignment for the service principal. The following sample PowerShell command demonstrates using the Test-ServicePrincipalAuthorization cmdlet. Replace <APPLICATION_ID> with the Application ID of the registered Azure application and <MAILBOXADDRESS> with the email address you want Email Archive to access.

    Test-ServicePrincipalAuthorization -Identity <APPLICATION_ID> -Resource <MailBoxAddress>

For more information, see Microsoft's documentation on Role Based Access Control for Applications in Exchange Online.

3) Configuring an Email Archive Profile

When configuring an Email Archive profile, for the Microsoft 365 server type, type in the Application (client) ID, client secret, and Tenant ID recorded during the Azure application registration.

For more information on creating an Email Archive profile, see the profile configuration documentation.