How to configure Microsoft Entra certificate-based authentication

Microsoft Entra certificate-based authentication (CBA) enables organizations to configure their Microsoft Entra 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 also see 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 Microsoft Entra 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 certificate authority (CA) and any intermediate CAs in Microsoft Entra ID.
• 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 Microsoft Entra ID.
• 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, Microsoft Entra ID doesn't perform any CRL checking, revocation of user certificates doesn't work, and authentication isn't blocked.

Steps to configure and test Microsoft Entra CBA

Some configuration steps need to be done before you enable Microsoft Entra 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.

A Global Administrator is needed to manage this feature.

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 Microsoft Entra CBA on the tenant.

Step 1: Configure the certificate authorities with PKI-based trust store (Preview)

Entra has a new public key infrastructure (PKI) based certificate authorities (CA) trust store. The PKI-based CA trust store keeps CAs within a container object for each different PKI. Admins can manage CAs in a container based on PKI easier than one flat list of CAs.

The PKI-based trust store has higher limits for the number of CAs and the size of each CA file. A PKI-based trust store supports up to 250 CAs and 8-KB size for each CA object. We highly recommended you use the new PKI-based trust store for storing CAs, which is scalable and supports new functionality like issuer hints.

An admin must configure the trusted CAs that issue user certificates. Only least-privileged administrators are needed to make changes. A PKI-based trust store has RBAC roles Privilege Authentication Administrator and Authentication Administrator.

Upload PKI feature of the PKI-based trust store is available only with Microsoft Entra ID P1 or P2 license. However, with free license as well, admins can upload all the CAs individually instead of the PKI file and configure the PKI-based trust store.

Configure certificate authorities by using the Microsoft Entra admin center

Create a PKI container object

1. Create a PKI container object.

2. Sign in to the Microsoft Entra admin center as an Authentication Policy Administrator.

3. Browse to Protection > Show more > Security Center (or Identity Secure Score) > Public key infrastructure (Preview).

4. Click + Create PKI.

5. Enter Display Name.

6. Click Create.

   

7. Select Columns to add or delete columns.

8. Select Refresh to refresh the list of PKIs.

Delete a PKI container object

1. To delete a PKI, select the PKI and select Delete. If the PKI has CAs in it, enter the name of the PKI to acknowledge the deletion of all CAs within it and select Delete.

   

Upload individual CAs into PKI container object

1. To upload a CA into the PKI container:

   1. Click on + Add certificate authority.

   2. Select the CA file.

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

   4. 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 doesn't fail.

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

   6. The Issuer hints flag is enabled by default. Turn off Issuer hints if the CA shouldn't be included in issuer hints.

   7. Select Save.

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

      

   9. Select Columns to add or delete columns.

   10. Select Refresh to refresh the list of CAs.

Upload all CAs with upload PKI into PKI container object

1. To upload all CAs at once into the PKI container:

   1. Create a PKI container object, or open one.
   2. Select Upload PKI.
   3. Enter the http internet facing URL where the .p7b file is available.
   4. Enter the SHA256 checksum of the file.
   5. Select the upload.
   6. Upload PKI is an asynchronous process. As each CA is uploaded, it's available in the PKI. Completion of PKI upload can take up to 30 minutes.
   7. Select Refresh to refresh the CAs.

   To generate the SHA256 checksum of the PKI .p7b file, run this command:

   Get-FileHash .\CBARootPKI.p7b -Algorithm SHA256
   

Edit a PKI

1. To edit PKI, select ... on the PKI row and select Edit.
2. Enter a new PKI name and select Save.

Edit a CA

1. To edit CA, select ... on the CA row and select Edit.
2. Enter new values for Certificate Authority type (root/intermediate), CRL URL, Delta CRL URL, Issuer Hints enabled flag as necessary and select Save.

Restore a PKI

1. Select the Deleted PKIs tab.
2. Select the PKI and select Restore PKI.

Restore a CA

1. Select the Deleted CAs tab.
2. Select the CA file and select Restore certificate authority.

Understanding isIssuerHintEnabled attribute on CA

Issuer hints send back a Trusted CA Indication as part of the Transport Layer Security (TLS) handshake. The trusted CA list is set to the subject of the CAs uploaded by the tenant in the Entra trust store. For more information about issuer hints, see Understanding Issuer Hints.

By default, the subject names of all CAs in the Microsoft Entra trust store are sent as hints. If you want to send back a hint with only specific CAs, set the issuer hint attribute isIssuerHintEnabled to true.

There's a character limit of 16 KB for the issuer hints (subject name of the CA) that the server can send back to the TLS client. As a good practice, set the attribute isIssuerHintEnabled to true only for the CAs that issue user certificates.

If multiple intermediate CAs from the same root certificate issue the end user certificates, then by default all the certificates show up in the certificate picker. But if you set isIssuerHintEnabled to true for specific CAs, only the proper user certificates appear in the certificate picker. To enable isIssuerHintEnabled, edit the CA, and update the value to true.

Configure certificate authorities using the Microsoft Graph APIs

Microsoft Graph APIs can be used to configure CAs. The following examples show how to use Microsoft Graph to run Create, Read, Update, or Delete (CRUD) operations for a PKI or CA.

Create a PKI container object

PATCH https://graph.microsoft.com/beta/directory/publicKeyInfrastructure/certificateBasedAuthConfigurations/
Content-Type: application/json
{
   "displayName": "ContosoPKI"
}

Get all the PKI objects

GET https://graph.microsoft.com/beta/directory/publicKeyInfrastructure/certificateBasedAuthConfigurations
ConsistencyLevel: eventual

Get PKI object by PKI-id

GET https://graph.microsoft.com/beta/directory/publicKeyInfrastructure/certificateBasedAuthConfigurations/{PKI-id}/
ConsistencyLevel: eventual

Upload CAs with a .p7b file

PATCH https://graph.microsoft.com/beta/directory/publicKeyInfrastructure/certificateBasedAuthConfigurations/{PKI-id}/certificateAuthorities/{CA-id}
Content-Type: application/json
{
    	"uploadUrl":"https://CBA/demo/CBARootPKI.p7b,
    	"sha256FileHash": "AAAAAAD7F909EC2688567DE4B4B0C404443140D128FE14C577C5E0873F68C0FE861E6F"
}

Get all CAs in a PKI

GET https://graph.microsoft.com/beta/directory/publicKeyInfrastructure/certificateBasedAuthConfigurations/{PKI-id}/certificateAuthorities
ConsistencyLevel: eventual

Get a specific CA within a PKI by CA-id

GET https://graph.microsoft.com/beta/directory/publicKeyInfrastructure/certificateBasedAuthConfigurations/{PKI-id}/certificateAuthorities/{CA-id}
ConsistencyLevel: eventual

Update specific CA issuer hints flag

PATCH https://graph.microsoft.com/beta/directory/publicKeyInfrastructure/certificateBasedAuthConfigurations/{PKI-id}/certificateAuthorities/{CA-id}
Content-Type: application/json
{
   "isIssuerHintEnabled": true
}

Configure certificate authorities (CA) using PowerShell For this configuration, you can use [Microsoft Graph PowerShell] (/powershell/microsoftgraph/installation).

1. Start PowerShell with administrator privileges.

2. Install and import the Microsoft Graph PowerShell SDK.

   Install-Module Microsoft.Graph -Scope AllUsers
   Import-Module Microsoft.Graph.Authentication
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

3. Connect to the tenant and accept all.

      Connect-MGGraph -Scopes "Directory.ReadWrite.All", "User.ReadWrite.All" -TenantId <tenantId>
   

Audit log

Any CRUD operations on a PKI or CA within the trust store are logged into the Microsoft Entra audit logs.

FAQs

Question: Why does upload PKI fail?

Answer: Check if the PKI file is valid and can be accessed without any issues. The max size of PKI file should be

Question: What is the service level agreement (SLA) for PKI upload?

Answer: PKI upload is an asynchronous operation and may take up to 30 minutes for completion.

Question: How do you generate SHA256 checksum for PKI file?

Answer: To generate the SHA256 checksum of the PKI.p7b file, run this command:

Get-FileHash .\CBARootPKI.p7b -Algorithm SHA256

Step 2: Enable CBA on the tenant

To enable CBA in the Microsoft Entra admin center, complete the following steps:

1. Sign in to the Microsoft Entra admin center as at least an Authentication Policy Administrator.

2. Browse to Groups > All groups > select New group and create a group for CBA users.

3. Browse to Protection > Authentication methods > Certificate-based Authentication.

4. Under Enable and Target, select Enable.

5. Select Add groups to select specific groups like the one you created. Use specific groups rather than All users.

   

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

Step 3: Configure authentication binding policy

The authentication binding policy helps determine the strength of authentication to either a single factor or multifactor. The default protection level for the certificates on the tenant is single-factor authentication.

An Authentication Policy Administrator can change the default value from single-factor to multifactor and configure custom policy rules. Authentication binding rules map certificate attributes, such as Issuer, or Policy Object ID (OID), or Issuer and Policy OID, to a value and select default protection level for that rule. You can create multiple rules.

To modify tenant default settings in the Microsoft Entra admin center, complete the following steps:

1. Sign in to the Microsoft Entra admin center as at least an Authentication Policy Administrator.

2. Browse to Protection > Authentication methods > Policies.

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

   

4. Select Configure to set up authentication binding and username binding.

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

   Note

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

   

6. 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 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, select Add rule.

   

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

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

   2. Select Multifactor authentication, Low affinity binding, and then click Add. When prompted, click I acknowledge to finish adding the rule.

      

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

   1. Enter a value for Policy OID.

   2. Select Multifactor authentication, Low affinity binding, and then click Add. When prompted, click I acknowledge to finish adding the rule.

      

   To create a rule by Issuer and Policy OID:

   1. Select Certificate Issuer and Policy OID.

   2. Select an issuer and enter the policy OID.

   3. For Authentication strength, select Single-factor authentication or Multifactor authentication.

   4. For Affinity binding, select Low.

      

   5. Select Add.

      

   6. Authenticate with a certificate that has policy OID of 3.4.5.6 and Issued by CN=CBATestRootProd. Authentication should pass and get a multifactor claim.

To create a rule by Issuer and Serial Number:

1. Add an authentication binding policy. The policy requires that any certificate issued by CN=CBATestRootProd with policyOID 1.2.3.4.6 needs only high affinity binding. Issuer and serial number are used.

   

2. Select the certificate field. In this example, let's select Issuer and Serial number.

   

3. The only user attribute supported is CertificateUserIds. Select Add.

   

4. Select Save.

   The sign-in log shows which binding was used for sign-in, and the details from the certificate.

   

5. Select 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 Authentication Policy Administrator can override the default and create a custom mapping. To determine how to configure username binding, see How username binding works.

For other scenarios that use the certificateUserIds attribute, see Certificate user IDs.

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.

   

   If the specified X.509 certificate field is found on the certificate, but Microsoft Entra ID doesn't find a user object using that value, the authentication fails. Microsoft Entra ID tries the next binding in the list.

2. Select Save to save the changes.

The final configuration looks like this image:

Step 5: Test your configuration

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

Test 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).

   

2. Select Next.

   

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

   

3. Select Sign in with a certificate.

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

   

5. Users should be signed into MyApps portal.

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

• The user certificate is provisioned into your test device.
• Microsoft Entra ID is configured correctly with trusted CAs.
• Username binding is configured correctly, and the user is found and authenticated.

Test custom authentication binding rules

Let's walk through a scenario where we validate strong authentication. We 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 OIDs in your certificate. For example, 1.2.3.4.

   

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 select Next.

   

5. Select Sign in with a certificate.

   

   If you enabled other authentication methods like Phone sign-in or security keys, users might see a different sign-in screen.

   

6. Select the client certificate and select Certificate Information.

   

7. The certificate appears, and you can verify the issuer and policy OID values.

8. To see Policy OID values, select Details.

   

9. Select the client certificate and select OK.

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

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

12. The Conditional Access policy for the user requires MFA and the certificate satisfies multifactor, so the user can sign in to the application.

Test username binding policy

The username binding policy helps validate the certificate of the user. There are three bindings that are supported for the username binding policy:

• IssuerAndSerialNumber > CertificateUserIds
• IssuerAndSubject > CertificateUserIds
• Subject > CertificateUserIds

By default, Microsoft Entra ID maps Principal Name in the certificate to UserPrincipalName in the user object to determine the user. An Authentication Policy Administrator can override the default and create a custom mapping, as explained earlier.

An Authentication Policy Administrator needs to enable the new bindings. To prepare, they must make sure the correct values for the corresponding username bindings are updated in the CertificateUserIds attribute of the user object:

• For cloud only users, use the Microsoft Entra admin center or Microsoft Graph APIs to update the value in CertificateUserIds.
• For on-premises synced users, use Microsoft Entra Connect to sync the values from on-premises by following Microsoft Entra Connect Rules or syncing AltSecId value.

Issuer and Serial Number manual mapping

Here's an example for Issuer and Serial Number manual mapping. The Issuer value to be added is:

C=US,O=U.SGovernment,OU=DoD,OU=PKI,OU=CONTRACTOR,CN=CRL.BALA.SelfSignedCertificate

To get the correct value for serial number, run the following command, and store the value shown in CertificateUserIds. The command syntax is:

Certutil –dump –v [~certificate path~] >> [~dumpFile path~] 

For example:

certutil -dump -v firstusercert.cer >> firstCertDump.txt

Here's an example for the certutil command:

certutil -dump -v C:\save\CBA\certs\CBATestRootProd\mfausercer.cer 

X509 Certificate: 
Version: 3 
Serial Number: 48efa06ba8127299499b069f133441b2 

   b2 41 34 13 9f 06 9b 49 99 72 12 a8 6b a0 ef 48 

The SerialNumber value to be added in CertificateUserId is:

b24134139f069b49997212a86ba0ef48

CertificateUserId:

X509:<I>C=US,O=U.SGovernment,OU=DoD,OU=PKI,OU=CONTRACTOR,CN=CRL.BALA.SelfSignedCertificate<SR> b24134139f069b49997212a86ba0ef48 

Issue and Subject manual mapping

Here's an example for Issue and Subject manual mapping. The Issuer value is:

The Subject value is:

CertificateUserId:

X509:<I>C=US,O=U.SGovernment,OU=DoD,OU=PKI,OU=CONTRACTOR,CN=CRL.BALA.SelfSignedCertificate<S> DC=com,DC=contoso,DC=corp,OU=UserAccounts,CN=FirstUserATCSession

Subject manual mapping

Here's an example for Subject manual mapping. The Subject value is:

CertificateUserId:

X509:<S>DC=com,DC=contoso,DC=corp,OU=UserAccounts,CN=FirstUserATCSession

Test affinity binding

1. Sign in to the Microsoft Entra admin center as at least an Authentication Policy Administrator.

2. Browse to Protection > Authentication methods > Policies.

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

4. Select Configure.

5. Set Required Affinity Binding at the tenant level.

   Important

   Be careful with the tenant-wide affinity setting. You can lock out the entire tenant if you change the Required Affinity Binding for the tenant and you don't have proper values in the user object. Similarly, if you create a custom rule that applies to all users and requires high affinity binding, users in the tenant can get locked out.

   

6. To test, select Required Affinity Binding to be Low.

7. Add a high affinity binding like SKI. Select Add rule under Username binding.

8. Select SKI and select Add.

   

   When finished, the rule looks like this screenshot:

   

9. Update all user objects CertificateUserIds attribute to have the correct value of SKI from the user certificate. For more information, see Supported patterns for CertificateUserIDs.

10. Create a custom rule for Authentication binding.

11. Select Add.

    

    When finished, the rule looks like this screenshot:

    

12. Update the user CertificateUserIds with correct SKI value from the certificate with policy OID 9.8.7.5.

13. Test with a certificate with policy OID 9.8.7.5 and the user should be authenticated with SKI binding and get MFA with only the certificate.

Enable CBA using Microsoft Graph API

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

1. Go to Microsoft Graph Explorer.

2. Select 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 x509 Certificate authentication method:

   GET https://graph.microsoft.com/v1.0/policies/authenticationmethodspolicy/authenticationMethodConfigurations/X509Certificate
   

6. By default, the x509 Certificate 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 get a 204 No content response code. Rerun 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.

Enable CBA using Microsoft PowerShell

1. Open PowerShell.
2. Connect to Microsoft Graph:

   Connect-MgGraph -Scopes "Policy.ReadWrite.AuthenticationMethod"
   

3. Create a variable for defining group for CBA users:

   $group = Get-MgGroup -Filter "displayName eq 'CBATestGroup'"
   

4. Define the request body:

   $body = @{
   "@odata.type" = "#microsoft.graph.x509CertificateAuthenticationMethodConfiguration"
   "id" = "X509Certificate"
   "state" = "enabled"
   "certificateUserBindings" = @(
       @{
           "@odata.type" = "#microsoft.graph.x509CertificateUserBinding"
           "x509CertificateField" = "SubjectKeyIdentifier"
           "userProperty" = "certificateUserIds"
           "priority" = 1
       },
       @{
           "@odata.type" = "#microsoft.graph.x509CertificateUserBinding"
           "x509CertificateField" = "PrincipalName"
           "userProperty" = "UserPrincipalName"
           "priority" = 2
       },
       @{
           "@odata.type" = "#microsoft.graph.x509CertificateUserBinding"
           "x509CertificateField" = "RFC822Name"
           "userProperty" = "userPrincipalName"
           "priority" = 3
       }
   )
   "authenticationModeConfiguration" = @{
       "@odata.type" = "#microsoft.graph.x509CertificateAuthenticationModeConfiguration"
       "x509CertificateAuthenticationDefaultMode" = "x509CertificateMultiFactor"
       "rules" = @(
           @{
               "@odata.type" = "#microsoft.graph.x509CertificateRule"
               "x509CertificateRuleType" = "policyOID"
               "identifier" = "1.3.6.1.4.1.311.21.1"
               "x509CertificateAuthenticationMode" = "x509CertificateMultiFactor"
           }
       )
   }
   "includeTargets" = @(
       @{
           "targetType" = "group"
           "id" = $group.Id
           "isRegistrationRequired" = $false
       }
   ) } | ConvertTo-Json -Depth 5
   

5. Run the PATCH request:

   Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/x509Certificate" -Body $body -ContentType "application/json"
   

Next steps

• Overview of Microsoft Entra CBA
• Technical deep dive for Microsoft Entra CBA
• Limitations with Microsoft Entra CBA
• Windows SmartCard logon using Microsoft Entra CBA
• Microsoft Entra CBA on mobile devices (Android and iOS)
• Certificate user IDs
• How to migrate federated users
• FAQ