How to configure Azure AD certificate-based authentication

Azure Active Directory (Azure AD) certificate-based authentication (CBA) enables organizations to configure their Azure AD tenants to allow or require users to authenticate with X.509 certificates created by their Enterprise Public Key Infrastructure (PKI) for app and browser sign-in. This feature enables organizations to adopt phishing-resistant modern passwordless authentication by using an x.509 certificate.

During sign-in, users will see also an option to authenticate with a certificate instead of entering a password. If multiple matching certificates are present on the device, the user can pick which one to use. The certificate is validated against the user account and if successful, they sign in.

Follow these instructions to configure and use Azure AD CBA for tenants in Office 365 Enterprise and US Government plans. You should already have a public key infrastructure (PKI) configured.

Prerequisites

Make sure that the following prerequisites are in place:

  • Configure at least one certification authority (CA) and any intermediate CAs in Azure AD.
  • The user must have access to a user certificate (issued from a trusted Public Key Infrastructure configured on the tenant) intended for client authentication to authenticate against Azure AD.
  • Each CA should have a certificate revocation list (CRL) that can be referenced from internet-facing URLs. If the trusted CA doesn't have a CRL configured, Azure AD won't perform any CRL checking, revocation of user certificates won't work, and authentication won't be blocked.

Important

Make sure the PKI is secure and can't be easily compromised. In the event of a compromise, the attacker can create and sign client certificates and compromise any user in the tenant, both users whom are synchronized from on-premises and cloud-only users. However, a strong key protection strategy, along with other physical and logical controls, such as HSM activation cards or tokens for the secure storage of artifacts, can provide defense-in-depth to prevent external attackers or insider threats from compromising the integrity of the PKI. For more information, see Securing PKI.

Note

When evaluating a PKI, it is important to review certificate issuance policies and enforcement. As mentioned, adding certificate authorities (CAs) to Azure AD configuration allows certificates issued by those CAs to authenticate any user in Azure AD. For this reason, it is important to consider how and when the CAs are allowed to issue certificates, and how they implement reusable identifiers. Where administrators need to ensure only a specific certificate is able to be used to authenticate a user, admins should exclusively use high-affinity bindings to achieve a higher level of assurance that only a specific certificate is able to authenticate the user. For more information, see high-affinity bindings.

Steps to configure and test Azure AD CBA

Some configuration steps to be done before you enable Azure AD CBA. First, an admin must configure the trusted CAs that issue user certificates. As seen in the following diagram, we use role-based access control to make sure only least-privileged administrators are needed to make changes. Only the Privileged Authentication Administrator role can configure the CA.

Optionally, you can also configure authentication bindings to map certificates to single-factor or multifactor authentication, and configure username bindings to map the certificate field to an attribute of the user object. Authentication Policy Administrators can configure user-related settings. Once all the configurations are complete, enable Azure AD CBA on the tenant.

Diagram of the steps required to enable Azure Active Directory certificate-based authentication.

Step 1: Configure the certification authorities

You can configure CAs by using the Azure portal or PowerShell.

Configure certification authorities using the Azure portal

To enable the certificate-based authentication and configure user bindings in the Azure portal, complete the following steps:

  1. Sign in to the Azure portal as a Global Administrator.

  2. Click Azure Active Directory > Security.

    Screenshot of certification authorities.

  3. To upload a CA, click Upload:

    1. Select the CA file.

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

    3. Set the http 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. Set Delta CRL URL - the http internet-facing URL for the CRL that contains all revoked certificates since the last base CRL was published.

    5. Click Add.

      Screenshot of how to upload certification authority file.

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

  5. Click Columns to add or delete columns.

Configure certification authorities using PowerShell

Only one CRL Distribution Point (CDP) for a trusted CA is supported. The CDP can only be HTTP URLs. Online Certificate Status Protocol (OCSP) or Lightweight Directory Access Protocol (LDAP) URLs aren't supported.

To configure your certificate authorities in Azure Active Directory, 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 the Azure Active Directory PowerShell Version 2:

  1. Start Windows PowerShell with administrator privileges.

  2. Install the Azure AD module version 2.0.0.33 or higher.

        Install-Module -Name AzureAD –RequiredVersion 2.0.0.33
    

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 the Connect-AzureAD cmdlet:

    Connect-AzureAD

Retrieve

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

    Get-AzureADTrustedCertificateAuthority

Add

To create a trusted certificate authority, use the New-AzureADTrustedCertificateAuthority cmdlet and set the crlDistributionPoint attribute to a correct value:

    $cert=Get-Content -Encoding byte "[LOCATION OF THE CER FILE]"
    $new_ca=New-Object -TypeName Microsoft.Open.AzureAD.Model.CertificateAuthorityInformation
    $new_ca.AuthorityType=0
    $new_ca.TrustedCertificate=$cert
    $new_ca.crlDistributionPoint="<CRL Distribution URL>"
    New-AzureADTrustedCertificateAuthority -CertificateAuthorityInformation $new_ca

AuthorityType

  • Use 0 to indicate a Root certification authority
  • Use 1 to indicate an Intermediate or Issuing certification authority

crlDistributionPoint

You can download the CRL and compare the CA certificate and the CRL information to validate the crlDistributionPoint value in the preceding PowerShell example is valid for the CA you want to add.

The following table and graphic show how to map information from the CA certificate to the attributes of the downloaded CRL.

CA Certificate Info = Downloaded CRL Info
Subject = Issuer
Subject Key Identifier = Authority Key Identifier (KeyID)

Compare CA Certificate with CRL Information.

Tip

The value for crlDistributionPoint in the preceding example is the http location for the CA’s Certificate Revocation List (CRL). This can be found in a few places.

  • In the CRL Distribution Point (CDP) attribute of a certificate issued from the CA.

If Issuing CA is Windows Server:

  • On the Properties of the CA in the certification authority Microsoft Management Console (MMC).
  • On the CA by running certutil -cainfo cdp. For more information, see certutil.

For more information, see Understanding the certificate revocation process.

Remove

To remove a trusted certificate authority, use the Remove-AzureADTrustedCertificateAuthority cmdlet:

    $c=Get-AzureADTrustedCertificateAuthority
    Remove-AzureADTrustedCertificateAuthority -CertificateAuthorityInformation $c[2]

You can change the command to remove 0th element by changing to Remove-AzureADTrustedCertificateAuthority -CertificateAuthorityInformation $c[0].

Modify

To modify a trusted certificate authority, use the Set-AzureADTrustedCertificateAuthority cmdlet:

    $c=Get-AzureADTrustedCertificateAuthority
    $c[0].AuthorityType=1
    Set-AzureADTrustedCertificateAuthority -CertificateAuthorityInformation $c[0]

Step 2: Enable CBA on the tenant

To enable the certificate-based authentication in the Azure portal, complete the following steps:

  1. Sign in to the Azure portal as an Authentication Policy Administrator.

  2. Select Azure Active Directory, then choose Security from the menu on the left-hand side.

  3. Under Manage, select Authentication methods > Certificate-based Authentication.

  4. Under Enable and Target, click Enable.

  5. Click All users, or click Add groups to select specific groups.

    Screenshot of how to enable CBA.

Once certificate-based authentication is enabled on the tenant, all users in the tenant will see the option to sign in with a certificate. Only users who are enabled for certificate-based authentication will be able to authenticate using the X.509 certificate.

Note

The network administrator should allow access to certauth endpoint for the customer’s cloud environment in addition to login.microsoftonline.com. Disable TLS inspection on the certauth endpoint to make sure the client certificate request succeeds as part of the TLS handshake.

Step 3: Configure authentication binding policy

The authentication binding policy helps determine the strength of authentication to either a single factor or multi factor. An admin can change the default value from single-factor to multifactor and configure custom policy rules by mapping to issuer Subject or policy OID fields in the certificate.

To enable Azure AD CBA and configure user bindings in the Azure portal, complete the following steps:

  1. Sign in to the Azure portal as an Authentication Policy Administrator.

  2. Select Azure Active Directory, then choose Security from the menu on the left-hand side.

  3. Click Authentication methods > Policies.

  4. Under Manage, select Authentication methods > Certificate-based Authentication.

    Screenshot of Authentication policy.

  5. Click Configure to set up authentication binding and username binding.

  6. The protection level attribute has a default value of Single-factor authentication. Select Multi-factor authentication to change the default value to MFA.

    Note

    The default protection level value will be in effect if no custom rules are added. If custom rules are added, the protection level defined at the rule level will be honored instead.

    Screenshot of how to change the default policy to MFA.

  7. You can also set up custom authentication binding rules to help determine the protection level for client certificates. It can be configured using either the issuer Subject or Policy OID fields in the certificate.

    Authentication binding rules will map the certificate attributes (issuer or Policy OID) to a value, and select default protection level for that rule. Multiple rules can be created.

    To add custom rules, click on Add rule.

    Screenshot of how to add a rule.

    To create a rule by certificate issuer, click Certificate issuer.

    1. Select a Certificate issuer identifier from the list box.

    2. Click Multi-factor authentication.

      Screenshot of multifactor authentication policy.

    To create a rule by Policy OID, click Policy OID.

    1. Enter a value for Policy OID.

    2. Click Multi-factor authentication.

      Screenshot of mapping to Policy OID.

  8. Click Ok to save any custom rule.

Step 4: Configure username binding policy

The username binding policy helps validate the certificate of the user. By default, we map Principal Name in the certificate to UserPrincipalName in the user object to determine the user. An admin can override the default and create a custom mapping.

To determine how to configure username binding, see How username binding works.

Important

If a username binding policy uses synchronized attributes, such as onPremisesUserPrincipalName attribute of the user object, be aware that any user with Active Directory Administrators privileges can make changes that impact the onPremisesUserPrincipalName value in Azure AD for any synchronized accounts, including users with delegated administrative privilege over synchronized user accounts or administrative rights over the Azure AD Connect Servers.

  1. Create the username binding by selecting one of the X.509 certificate fields to bind with one of the user attributes. The username binding order represents the priority level of the binding. The first one has the highest priority, and so on.

    Screenshot of a username binding policy.

    If the specified X.509 certificate field is found on the certificate, but Azure AD doesn’t find a user object using that value, the authentication fails. Azure AD will fall back and try the next binding in the list.

  2. Click Save to save the changes.

The final configuration will look like this image:

Screenshot of the final configuration.

Step 5: Test your configuration

This section covers how to test your certificate and custom authentication binding rules.

Testing your certificate

As a first configuration test, you should try to sign in to the MyApps portal using your on-device browser.

  1. Enter your User Principal Name (UPN).

    Screenshot of the User Principal Name.

  2. Click Next.

    Screenshot of sign-in with certificate.

    If you enabled other authentication methods like Phone sign-in or FIDO2, users may see a different sign-in screen.

    Screenshot of the alternative sign-in.

  3. Select Sign in with a certificate.

  4. Pick the correct user certificate in the client certificate picker UI and click OK.

Screenshot of the certificate picker UI.

  1. Users should be signed into MyApps portal.

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

  • The user certificate has been provisioned into your test device.
  • Azure AD is configured correctly with trusted CAs.
  • Username binding is configured correctly, and the user is found and authenticated.

Testing custom authentication binding rules

Let's walk through a scenario where we validate strong authentication. We'll create two authentication policy rules, one by using issuer subject to satisfy single-factor authentication, and another by using policy OID to satisfy multifactor authentication.

  1. Create an issuer Subject rule with protection level as single-factor authentication and value set to your CAs Subject value. For example:

    CN = WoodgroveCA

  2. Create a policy OID rule, with protection level as multifactor authentication and value set to one of the policy OID’s in your certificate. For example, 1.2.3.4.

    Screenshot of the Policy OID rule.

  3. Create a Conditional Access policy for the user to require multifactor authentication by following steps at Conditional Access - Require MFA.

  4. Navigate to MyApps portal. Enter your UPN and click Next.

    Screenshot of the User Principal Name.

  5. Select Sign in with a certificate.

    Screenshot of sign-in with certificate.

    If you enabled other authentication methods like Phone sign-in or FIDO2, users may see a different sign-in screen.

    Screenshot of the alternative sign-in.

  6. Select the client certificate and click Certificate Information.

    Screenshot of the client picker.

  7. The certificate will be shown, and you can verify the issuer and policy OID values. Screenshot of the issuer.

  8. To see Policy OID values, click Details.

    Screenshot of the authentication details.

  9. Select the client certificate and click OK.

  10. The policy OID in the certificate matches the configured value of 1.2.3.4 and it will satisfy multifactor authentication. Similarly, the issuer in the certificate matches the configured value of CN=WoodgroveCA and it will satisfy single-factor authentication.

  11. Because policy OID rule takes precedence over issuer rule, the certificate will satisfy multifactor authentication.

  12. The Conditional Access policy for the user requires MFA and the certificate satisfies multifactor, so the user will be authenticated into the application.

Enable Azure AD CBA using Microsoft Graph API

To enable CBA and configure username bindings using Graph API, complete the following steps.

Note

The following steps use Graph Explorer which is not available in the US Government cloud. US Government cloud tenants can use Postman to test the Microsoft Graph queries.

  1. Go to Microsoft Graph Explorer.

  2. Click Sign into Graph Explorer and sign in to your tenant.

  3. Follow the steps to consent to the Policy.ReadWrite.AuthenticationMethod delegated permission.

  4. GET all authentication methods:

    GET  https://graph.microsoft.com/v1.0/policies/authenticationmethodspolicy
    
  5. GET the configuration for the x509Certificate authentication method:

    GET https://graph.microsoft.com/v1.0/policies/authenticationmethodspolicy/authenticationMethodConfigurations/X509Certificate
    
  6. By default, the x509Certificate authentication method is disabled. To allow users to sign in with a certificate, you must enable the authentication method and configure the authentication and username binding policies through an update operation. To update policy, run a PATCH request.

    Request body:

    PATCH https: //graph.microsoft.com/v1.0/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/x509Certificate
    Content-Type: application/json
    
    {
        "@odata.type": "#microsoft.graph.x509CertificateAuthenticationMethodConfiguration",
        "id": "X509Certificate",
        "state": "enabled",
        "certificateUserBindings": [
            {
                "x509CertificateField": "PrincipalName",
                "userProperty": "onPremisesUserPrincipalName",
                "priority": 1
            },
            {
                "x509CertificateField": "RFC822Name",
                "userProperty": "userPrincipalName",
                "priority": 2
            }, 
            {
                "x509CertificateField": "PrincipalName",
                "userProperty": "certificateUserIds",
                "priority": 3
            }
        ],
        "authenticationModeConfiguration": {
            "x509CertificateAuthenticationDefaultMode": "x509CertificateSingleFactor",
            "rules": [
                {
                    "x509CertificateRuleType": "issuerSubject",
                    "identifier": "CN=WoodgroveCA ",
                    "x509CertificateAuthenticationMode": "x509CertificateMultiFactor"
                },
                {
                    "x509CertificateRuleType": "policyOID",
                    "identifier": "1.2.3.4",
                    "x509CertificateAuthenticationMode": "x509CertificateMultiFactor"
                }
            ]
        },
        "includeTargets": [
            {
                "targetType": "group",
                "id": "all_users",
                "isRegistrationRequired": false
            }
        ]
    }
    
  7. You'll get a 204 No content response code. Re-run the GET request to make sure the policies are updated correctly.

  8. Test the configuration by signing in with a certificate that satisfies the policy.

Next steps