Get started with certificate-based authentication in Microsoft Entra ID with federation

Certificate-based authentication (CBA) with federation enables Microsoft Entra ID to authenticate you with a client certificate on a Windows, Android, or iOS device when connecting your Exchange online account to:

• Microsoft mobile applications such as Microsoft Outlook and Microsoft Word
• Exchange ActiveSync (EAS) clients

Configuring this feature eliminates the need to enter a username and password combination into certain mail and Microsoft Office applications on your mobile device.

This topic:

• Provides steps to configure and utilize CBA for users of tenants in Office 365 Enterprise, Business, Education, and US Government plans.
• Assumes that you already have a public key infrastructure (PKI) and AD FS configured.

Requirements

To configure CBA with federation, the following statements must be true:

• CBA with federation is only supported for Federated environments for browser applications, native clients using modern authentication, or MSAL libraries. The one exception is Exchange Active Sync (EAS) for Exchange Online (EXO), which can be used for federated and managed accounts. To configure Microsoft Entra CBA without needing federation, see How to configure Microsoft Entra certificate-based authentication.
• The root certificate authority and any intermediate certificate authorities must be configured in Microsoft Entra ID.
• Each certificate authority must have a certificate revocation list (CRL) that can be referenced via an internet-facing URL.
• You must have at least one certificate authority configured in Microsoft Entra ID. You can find related steps in the Configure the certificate authorities section.
• For Exchange ActiveSync clients, the client certificate must have the user's routable email address in Exchange online in either the Principal Name or the RFC822 Name value of the Subject Alternative Name field. Microsoft Entra ID maps the RFC822 value to the Proxy Address attribute in the directory.
• Your client device must have access to at least one certificate authority that issues client certificates.
• A client certificate for client authentication must have been issued to your client.

Step 1: Select your device platform

As a first step, for the device platform you care about, you need to review the following:

• The Office mobile applications support
• The specific implementation requirements

The related information exists for the following device platforms:

• Android
• iOS

Step 2: Configure the certificate authorities

To configure your certificate authorities in Microsoft Entra ID, for each certificate authority, upload the following:

• The public portion of the certificate, in .cer format
• The internet-facing URLs where the Certificate Revocation Lists (CRLs) reside

The schema for a certificate authority looks as follows:

    class TrustedCAsForPasswordlessAuth
    {
       CertificateAuthorityInformation[] certificateAuthorities;
    }

    class CertificateAuthorityInformation

    {
        CertAuthorityType authorityType;
        X509Certificate trustedCertificate;
        string crlDistributionPoint;
        string deltaCrlDistributionPoint;
        string trustedIssuer;
        string trustedIssuerSKI;
    }

    enum CertAuthorityType
    {
        RootAuthority = 0,
        IntermediateAuthority = 1
    }

For the configuration, you can use Microsoft Graph PowerShell:

1. Start Windows PowerShell with administrator privileges.

2. Install Microsoft Graph PowerShell:

       Install-Module Microsoft.Graph
   

As a first configuration step, you need to establish a connection with your tenant. As soon as a connection to your tenant exists, you can review, add, delete, and modify the trusted certificate authorities that are defined in your directory.

Connect

To establish a connection with your tenant, use Connect-MgGraph:

    Connect-MgGraph

Retrieve

To retrieve the trusted certificate authorities that are defined in your directory, use Get-MgOrganizationCertificateBasedAuthConfiguration.

    Get-MgOrganizationCertificateBasedAuthConfiguration

To add, modify, or remove a CA, use the Microsoft Entra admin center:

1. Sign in to the Microsoft Entra admin center as a Global Administrator.

2. Browse to Protection > Show more > Security Center (or Identity Secure Score) > Certificate authorities.

3. To upload a CA, select Upload:

   1. Select the CA file.

   2. Select Yes if the CA is a root certificate, otherwise select No.

   3. For Certificate Revocation List URL, set the internet-facing URL for the CA base CRL that contains all revoked certificates. If the URL isn't set, authentication with revoked certificates won't fail.

   4. For Delta Certificate Revocation List URL, set the internet-facing URL for the CRL that contains all revoked certificates since the last base CRL was published.

   5. Select Add.

      

4. To delete a CA certificate, select the certificate and select Delete.

5. Select Columns to add or delete columns.

Step 3: Configure revocation

To revoke a client certificate, Microsoft Entra ID fetches the certificate revocation list (CRL) from the URLs uploaded as part of certificate authority information and caches it. The last publish timestamp (Effective Date property) in the CRL is used to ensure the CRL is still valid. The CRL is periodically referenced to revoke access to certificates that are a part of the list.

If a more instant revocation is required (for example, if a user loses a device), the authorization token of the user can be invalidated. To invalidate the authorization token, set the StsRefreshTokenValidFrom field for this particular user using Windows PowerShell. You must update the StsRefreshTokenValidFrom field for each user you want to revoke access for.

To ensure that the revocation persists, you must set the Effective Date of the CRL to a date after the value set by StsRefreshTokenValidFrom and ensure the certificate in question is in the CRL.

The following steps outline the process for updating and invalidating the authorization token by setting the StsRefreshTokenValidFrom field.

1. Connect to PowerShell:

   Connect-MgGraph
   

2. Retrieve the current StsRefreshTokensValidFrom value for a user:

           $user = Get-MsolUser -UserPrincipalName [email protected]`
           $user.StsRefreshTokensValidFrom
   

3. Configure a new StsRefreshTokensValidFrom value for the user equal to the current timestamp:

           Set-MsolUser -UserPrincipalName [email protected] -StsRefreshTokensValidFrom ("03/05/2021")
   

The date you set must be in the future. If the date is not in the future, the StsRefreshTokensValidFrom property is not set. If the date is in the future, StsRefreshTokensValidFrom is set to the current time (not the date indicated by Set-MsolUser command).

Step 4: Test your configuration

Testing your certificate

As a first configuration test, you should try to sign in to Outlook Web Access or SharePoint Online using your on-device browser.

If your sign-in is successful, then you know that:

• The user certificate has been provisioned to your test device
• AD FS is configured correctly

Testing Office mobile applications

1. On your test device, install an Office mobile application (for example, OneDrive).
2. Launch the application.
3. Enter your username, and then select the user certificate you want to use.

You should be successfully signed in.

Testing Exchange ActiveSync client applications

To access Exchange ActiveSync (EAS) via certificate-based authentication, an EAS profile containing the client certificate must be available to the application.

The EAS profile must contain the following information:

• The user certificate to be used for authentication

• The EAS endpoint (for example, outlook.office365.com)

An EAS profile can be configured and placed on the device through the utilization of Mobile device management (MDM) such as Microsoft Intune or by manually placing the certificate in the EAS profile on the device.

Testing EAS client applications on Android

1. Configure an EAS profile in the application that satisfies the requirements in the prior section.
2. Open the application, and verify that mail is synchronizing.

Next steps

Additional information about certificate-based authentication on Android devices.

Additional information about certificate-based authentication on iOS devices.