Executing unattended scripts is one of the basic requirements for organisations of all scales for various reasons ranging from monitoring, reporting, auditing, scheduling changes, and running a customised portal. In general, these unattended scripts access Exchange Online PowerShell using a user name and a password (aka Basic Authentication), where credentials are stored in a local file or a secret vault. This is not considered a good security practice and Microsoft has decided to retire basic authentication and replace it with certificate-based modern authentication using Azure AD applications.
The decision to retire basic authentication for Exchange Online Remote PowerShell is extended second half of 2021. It gives organisations, that are using basic authentication for Exchange Online Remote PowerShell to execute unattended scripts, time to switch and replace the basic authentication with certificate-based modern authentication. To use the modern authentication for unattended scripts requires:
- Exchange Online PowerShell V2 module (The EXO V2 module uses the Active Directory Authentication Library to fetch an app-only token using the application Id, tenant Id organization, and certificate thumbprint).
- Azure Application Registration with required Application permissions. Please note, delegate permissions are not supported.
- x.509 certificate
- Azure AD role assignment to the Application object
Step 1: Generate an x.509 certificate
This step is required if you want to use a self-signed certificate instead of a third-party certificate purchased for your domain. To generate a self-signed certificate, perform the steps below:
- Open PowerShell as an Admin
and run the cmdlets below to generate a self-signed certificate with .pfx and .cer format.
# Create certificate
$EXOModernAuthCert = New-SelfSignedCertificate -DnsName "mydomain.com" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
The .pfx certificate format will be used while connecting to Exchange Online.
# Export certificate to .pfx file
$EXOModernAuthCert | Export-PfxCertificate -FilePath EXOModernAuthCert.pfx -Password $(ConvertTo-SecureString -String "MyStrongPassword" -Force -AsPlainText)
The .cer format will be used to upload the certificate to Azure AD Application.
# Export certificate to .cer file
$EXOModernAuthCert | Export-Certificate -FilePath EXOModernAuthCert
Step 2: Register an Azure AD App
To delegate Identity and Access Management functionals to Azure AD, an application must be registered with an Azure AD tenant as it creates an identity configuration for the new application that allows it to integrate with Azure AD.
Step 3: Assign Permissions
For the new application object to access Exchange Online resources, it needs to have the Application permission Exchange.ManageAsApp. To assign the required permissions, select Manifest, in the left-hand navigation under Manage, Locate requiredResourceAccess property in the manifest, and add the following inside the square brackets ([]):
{
"resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
"resourceAccess": [
{
"id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
"type": "Role"
}
]
}
It should look, something like this:
Step 4: Consent Permissions
Once the Manifest is updated, go to API Permissions in the left-hand navigation under Manage to confirm Exchange.ManageAsApp application-level permissions are added. However, it is not yet consented. Because these are application permissions, not delegated permissions, an admin must grant consent to use the app roles assigned to the application. To consent, click on Grant admin consent for your tenant and confirm the consent.
Step 5: Upload Certificate
Once the permissions are configured, the certificate generated as per step 1 can be uploaded. To upload the certificate, select Certificates and Secrets under Manage, click Upload Certificate
Step 6: Assign Azure AD Admin Role
For app-only authentication in Exchange Online, currently following admin roles are supported. Depending on the requirement to execute unattended scripts, one or more roles can be assigned.
- Global administrator, Compliance administrator, Security reader, Security administrator, Helpdesk administrator, Exchange administrator, Global Reader
The custom RBAC roles (not available in Azure AD) are not supported.
In this example, the newly registered app is assigned an Exchange Online Admin role in Azure AD (Roles and Administrators):
Step 7: Sign-in to Exchange Online
After the completion of steps 1-6, the Exchange Online Remote PowerShell can be connected using Modern Auth to execute the unattended scripts.
Option 1: Connect to Exchange Online Remote Powershell using a local certificate:
Connect-ExchangeOnline -CertificateFilePath "C:\temp\EXOModernAuthCert.pfx" -CertificatePassword (ConvertTo-SecureString -String "MyStrongPassword" -AsPlainText -Force) -AppID "2803131c-bc1f-45b2-a5de-11aebb100000" -Organization "mydomain.onmicrosoft.com"
In the above command, the AppID is the GUID of the registered app and can be obtained from the overview option of the registered app.
Option 2:
Connect to Exchange Online using Certificate ThumbPrint. When using the CertificateThumbPrint parameter, the certificate needs to be installed on the computer where you are running the command. The certificate should be installed in the user certificate store.
Connect-ExchangeOnline -CertificateThumbPrint "9B25BB6343F0D63929AC88CB287D148026B50E2C" -AppID "2803131c-bc1f-45b2-a5de-11aebb100000" -Organization "mydomain.onmicrosoft.com"
If the certificate is not installed, the following error will be generated "No certificate found for the given Certificate Thumbprint":
Once the certificate is installed in the user certificate store, a successful session is established using the certificate thumbprint, App ID, and the Microsoft 365 domain.
Option 3: using a certificate object
Connect to Exchange Online Remote PowerShell using the Certificate parameter. In this case, the certificate does not need to be installed on the computer where you are running the command. This parameter is applicable for scenarios where the certificate object is stored remotely and fetched at runtime during script execution. The remote server details can be passed in the command below to fetch the certificate details and use it for connection to Exchange Online Remote PowerShell.
Invoke-Command -ScriptBlock {Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Thumbprint -like "9B25BB6343F0D63929AC88CB287D148026B50E2C"}}
This easy to implement and adopt certificate-based modern authentication is a great feature to motivate organisations to move away from Basic Authentication and adopt a good security practices.
