App-only authentication for unattended scripts in Exchange Online PowerShell and Security & Compliance PowerShell

Auditing and reporting scenarios in Microsoft 365 often involve unattended scripts in Exchange Online PowerShell and Security & Compliance PowerShell. In the past, unattended sign in required you to store the username and password in a local file or in a secret vault that's accessed at run-time. But, as we all know, storing user credentials locally is not a good security practice.

Certificate based authentication (CBA) or app-only authentication as described in this article supports unattended script and automation scenarios by using Azure AD apps and self-signed certificates.

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 examples

The following examples show how to use the Exchange Online PowerShell module with app-only authentication:

• Connect using a certificate thumbprint:

  Note

  The CertificateThumbprint parameter is supported only in Microsoft Windows.

  The certificate needs to be installed on the computer where you're running the command. The certificate should be installed in the user certificate store.

  • Exchange Online PowerShell:

    Connect-ExchangeOnline -CertificateThumbPrint "012THISISADEMOTHUMBPRINT" -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

  • Security & Compliance PowerShell:

    Connect-IPPSSession -CertificateThumbPrint "012THISISADEMOTHUMBPRINT" -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

• Connect using a certificate object:

  The certificate does not need to be installed on the computer where you're running the command. You can store the certificate object remotely. The certificate is fetched when the script is run.

  • Exchange Online PowerShell:

    Connect-ExchangeOnline -Certificate <%X509Certificate2 Object%> -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

  • Security & Compliance PowerShell:

    Connect-IPPSSession -Certificate <%X509Certificate2 Object%> -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

• Connect using a local certificate:

  Note

  Using a ConvertTo-SecureString command to store the password of the certificate locally defeats the purpose of a secure connection method for automation scenarios. Using a Get-Credential command to prompt you for the password of the certificate securely isn't ideal for automation scenarios. In other words, there's really no automated and secure way to connect using a local certificate.

  • Exchange Online PowerShell:

    Connect-ExchangeOnline -CertificateFilePath "C:\Users\navin\Desktop\automation-cert.pfx" -CertificatePassword (Get-Credential).password -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

  • Security & Compliance PowerShell:

    Connect-IPPSSession -CertificateFilePath "C:\Users\navin\Desktop\automation-cert.pfx" -CertificatePassword (Get-Credential).password -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

Set up 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. You can learn more about this at 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.

1. Register the application in Azure AD.

2. Assign API permissions to the application.

   An application object has the default permission User.Read. For the application object to access resources, it needs to have the Application permission Exchange.ManageAsApp.

3. Generate a self-signed certificate

   • For app-only authentication in Azure AD, you typically use a certificate to request access. Anyone who has the certificate and its private key can use the app, and the permissions granted to the app.

   • Create and configure a self-signed X.509 certificate, which will be used to authenticate your Application against Azure AD, while requesting the app-only access token.

   • This is similar to generating a password for user accounts. The certificate can be self-signed as well. See the Appendix section later in this article for instructions for generating certificates in PowerShell.

     Note

     Cryptography: 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. The Appendix section covers two supported methods to create a CSP certificate.

4. Attach the certificate to the Azure AD application

5. Assign Azure AD roles to the application

   The application needs to have the appropriate RBAC roles assigned. Because the apps are provisioned in Azure AD, you can use any of the supported built-in roles.

Step 1: Register the application in Azure AD

1. Open the Azure AD portal at https://portal.azure.com/.

2. 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.

3. On the App registrations page, click 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 (<YourOrganizationName> only - Single tenant) is selected.

     Note

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

   • Redirect URI (optional): In the first box, verify that Web is selected. In the second box, enter the URI where the access token is sent.

     Note

     You can't create credentials for native applications, because you can't use that type for automated applications.

     

   When you're finished, click Register.

4. 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

1. On the app page under Management, select Manifest.

   

2. 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"
            }
         ]
      }
   ],
   

   Note

   Microsoft 365 GCC High or DoD environments have access to Security & Compliance PowerShell only. Use the following values for resourceAppId, resourceAccess id, and resourceAccess type:

   "requiredResourceAccess": [
      {
        "resourceAppId": "00000007-0000-0ff1-ce00-000000000000",
        "resourceAccess": [
           {
              "id": "455e5cd2-84e8-4751-8344-5672145dfa17",
              "type": "Role"
           }
        ]
      }
   ],
   

   When you're finished, click Save.

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

   

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

   • API / Permissions name: Verify the value Exchange.ManageAsApp is shown.

     Note

     If necessary, search for Office 365 Exchange under APIs my organization uses on the Request API Permissions page.

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

     

     Select Grant admin consent for <Organization>, read the confirmation dialog that opens, and then click Yes.

     The Status value should now be Granted for <Organization>.

     

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

Step 3: Generate a self-signed certificate

Create a self-signed x.509 certificate using one of the following methods:

• (Recommended) 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 "contoso.org" -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
  
  # Export certificate to .pfx file
  $mycert | Export-PfxCertificate -FilePath mycert.pfx -Password (Get-Credential).password
  
  # Export certificate to .cer file
  $mycert | Export-Certificate -FilePath mycert.cer
  

• Use the Create-SelfSignedCertificate script script to generate SHA1 certificates.

  .\Create-SelfSignedCertificate.ps1 -CommonName "MyCompanyName" -StartDate 2021-01-06 -EndDate 2022-01-06
  

Step 4: Attach the certificate to the Azure AD application

After you register the certificate with your application, you can use the private key (.pfx file) or the thumbprint for authentication.

1. 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.

   

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

   

3. On the Certificates & secrets page that opens, click 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, click Add.

   The certificate is now shown in the Certificates section.

   

4. Close the current Certificates & secrets page, and then the App registrations page to return to the main https://portal.azure.com/ page. You'll use it in the next step.

Step 4b: Exchange Online delegated scenarios only: Grant admin consent for the multi-tenant app

If you made the application multi-tenant for Exchange Online delegated scenarios in Step 1, you need to grant admin consent to the Exchange.ManageAsApp permission so the application can run cmdlets in Exchange Online in each tenant organization. To do this, generate an admin consent URL for each customer tenant. Before anyone uses the multi-tenant application to connect to Exchange Online in the tenant organization, an admin in the customer tenant should open the following URL:

https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<client-id>&scope=https://outlook.office365.com/.default

• <tenant-id> is the customer's tenant ID.
• <client-id> is the ID of the multi-tenant application.
• The default scope is used to grant application permissions.

For more information about the URL syntax, see Request the permissions from a directory admin.

Step 5: Assign Azure AD roles to the application

You have two options:

• Assign Azure AD roles to the application: This method is supported in Exchange Online PowerShell and Security & Compliance PowerShell.
• Assign custom Exchange Online role groups to the application using service principals: This method is supported only when you connect in REST API mode.

Assign Azure AD roles to the application

The supported Azure AD roles are described in the following table:

^* The Global Administrator and Exchange Administrator roles provide the required permissions for any task in Exchange Online PowerShell. For example:

• Recipient management.
• Security and protection features. For example, anti-spam, anti-malware, anti-phishing, and the associated reports.

The Security Administrator role does not have the necessary permissions for those same tasks.

For general instructions about assigning roles in Azure AD, see View and assign administrator roles in Azure Active Directory.

1. 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.

2. 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.

   • Exchange Online PowerShell: For example, find and select the Exchange administrator role.

     

   • Security & Compliance PowerShell: For example, find and select the Compliance Administrator role.

     

3. On the Assignments page that opens, click Add assignments.

   • Exchange Online PowerShell:

     

   • Security & Compliance PowerShell:

     

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

   

   When you're finished, click Add.

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

   • Exchange Online PowerShell:

     

   • Security & Compliance PowerShell:

     

Assign custom Exchange Online role groups to the application using service principals

For information about creating custom role groups, see Create role groups. The custom role group that you assign to the application can contain any combination of built-in and custom roles.

To assign custom role groups to the application using service principals, do the following steps:

1. In Azure Active Directory PowerShell for Graph, run the following command to store the details of the Azure application that you registered in Step 1 in a variable:

   $<VariableName1> = Get-AzureADServicePrincipal -SearchString "<AppName>"
   

   For example:

   $AADApp = Get-AzureADServicePrincipal -SearchString "ExO PowerShell CBA"
   

   For detailed syntax and parameter information, see Get-AzureADServicePrincipal.

2. In the same PowerShell window, connect to Exchange Online PowerShell or Security & Compliance PowerShell and run the following commands to:

   • Create a service principal object for the Azure application.
   • Store the details of the service principal in a variable.

   New-ServicePrincipal -AppId $<VariableName1>.AppId -ServiceId $<VariableName1>.ObjectId -DisplayName "<Descriptive Name>"
   
   $<VariableName2> = Get-ServicePrincipal -Identity "<Descriptive Name>"
   

   For example:

   New-ServicePrincipal -AppId $AADApp.AppId -ServiceId $AADApp.ObjectId -DisplayName "SP for Azure App ExO PowerShell CBA"
   
   $SP = Get-ServicePrincipal -Identity "SP for Azure App ExO PowerShell CBA"
   

   For detailed syntax and parameter information, see New-ServicePrincipal.

3. In Exchange Online PowerShell or Security & Compliance PowerShell, run the following command to add the service principal as a member of the custom role group:

   Add-RoleGroupMember -Identity "<CustomRoleGroupName>" -Member <$<VariableName2>.Identity | $<VariableName2>.ServiceId | $<VariableName2>.Id>
   

   For example:

   Add-RoleGroupMember -Identity "Contoso View-Only Recipients" -Member $SP.Identity
   

   For detailed syntax and parameter information, see Add-RoleGroupMember.