Microsoft Entra certificate-based authentication technical deep dive

This article explains how Microsoft Entra certificate-based authentication (CBA) works, and dives into technical details on Microsoft Entra CBA configurations.

How does Microsoft Entra certificate-based authentication work?

The following image describes what happens when a user tries to sign in to an application in a tenant where Microsoft Entra CBA is enabled.

Now we'll walk through each step:

1. The user tries to access an application, such as MyApps portal.

2. If the user isn't already signed in, the user is redirected to the Microsoft Entra ID User Sign-in page at https://login.microsoftonline.com/.

3. The user enters their username into the Microsoft Entra sign-in page, and then selects Next. Microsoft Entra ID does home realm discovery using the tenant name and the username is used to look up the user in the tenant.

   

4. Microsoft Entra ID checks whether CBA is enabled for the tenant. If CBA is enabled, the user sees a link to Use a certificate or smartcard on the password page. If the user doesn't see the sign-in link, make sure CBA is enabled on the tenant. For more information, see How do I enable Microsoft Entra CBA?.

   Note

   If CBA is enabled on the tenant, all users see the link to Use a certificate or smart card on the password page. However, only the users in scope for CBA can authenticate successfully against an application that uses Microsoft Entra ID as their Identity provider (IdP).

   

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

   

5. Once the user selects certificate-based authentication, the client is redirected to the certauth endpoint, which is https://certauth.login.microsoftonline.com for public Microsoft Entra ID. For Azure Government, the certauth endpoint is https://certauth.login.microsoftonline.us.

   The endpoint performs TLS mutual authentication, and requests the client certificate as part of the TLS handshake. An entry for this request appears in the sign-in log.

   Note

   The network administrator should allow access to the User sign-in page and certauth endpoint *.certauth.login.microsoftonline.com for the customer's cloud environment. Disable TLS inspection on the certauth endpoint to make sure the client certificate request succeeds as part of the TLS handshake.

   Make sure your TLS inspection disablement also works for the new url with issuer hints. Don't hardcode the url with tenantId because it might change for B2B users. Use a regular expression to allow both the old and new URL to work for TLS inspection disablement. For example, depending on the proxy, use *.certauth.login.microsoftonline.com or *certauth.login.microsoftonline.com. In Azure Government, use *.certauth.login.microsoftonline.us or *certauth.login.microsoftonline.us.

   Unless access is allowed, certificate-based authentication fails if you enable issuer hints.

6. Microsoft Entra ID requests a client certificate. The user picks the client certificate, and selects Ok.

   

7. Microsoft Entra ID verifies the certificate revocation list to make sure the certificate isn't revoked and is valid. Microsoft Entra ID identifies the user by using the username binding configured on the tenant to map the certificate field value to the user attribute value.

8. If a unique user is found with a Conditional Access policy that requires multifactor authentication, and the certificate authentication binding rule satisfies MFA, then Microsoft Entra ID signs the user in immediately. If MFA is required but the certificate satisfies only a single factor, either passwordless sign-in or FIDO2 is offered as a second factor if they're already registered.

9. Microsoft Entra ID completes the sign-in process by sending a primary refresh token back to indicate successful sign-in.

10. If the user sign-in is successful, the user can access the application.

Understanding issuer hints (Preview)

Issuer hints send back a Trusted CA Indication as part of the TLS handshake. The trusted CA list is set to subject of the Certificate Authorities (CAs) uploaded by the tenant in the Entra trust store. A browser client or native application client can use the hints sent back by server to filter the certificates shown in the certificate picker. The client shows only the authentication certificates issued by the CAs in the trust store.

Enable issuer hints

To enable click on the check box Issuer Hints. Authentication Policy Administrators should click I acknowledge after making sure that the proxy with TLS inspection enabled is updated correctly, and save.

Note

If your organization has firewalls or proxies with TLS inspection, acknowledge that you have disabled TLS inspection of the certauth endpoint capable of matching any name under [*.]certauth.login.microsoftonline.com, customized according to the specific proxy in use.

Note

The certificate authority URL will be of a format t{tenantId}.certauth.login.microsoftonline.com after issuer hints are enabled.

CA trust store update propagation

After you enable issuer hints and add, update, or delete CAs from the trust state, there's a delay of up to 10 minutes to propagate the issuer hints back to client. Users can't authenticate with certificates issued by the new CAs until the hints are propagated.

Authentication Policy Administrators should sign in with a certificate after they enable issuer hints to initiate the propagation. Users will see the error message below when CA trust store updates are in propagation.

MFA with single-factor certificate-based authentication

Microsoft Entra CBA is supported as both first factor and selcond factor for authentication. Some of the supported combinations are:

1. CBA (first factor) and passkeys (second factor)
2. CBA (first factor) and passwordless phone sign-in (second factor)
3. CBA (first factor) and FIDO2 security keys (second factor)
4. Password (first factor) + CBA (second factor) (Preview)

Note

CBA as a second factor on iOS has known issues and is blocked on iOS. We are working on fixing the issues and should be supported on iOS.

Users need to have a way to get MFA and register passwordless sign-in or FIDO2 in advance to signing in with Microsoft Entra CBA.

Important

A user is considered MFA capable when they are included in the CBA method settings. This means the user can't use proof up as part of their authentication to register other available methods. Make sure users without a valid certificate aren't included in the CBA method settings. For more information about how authentication works, see Microsoft Entra multifactor authentication.

Options to get MFA capability with Single factor certificates

Microsoft Entra CBA is capable of multifactor authentication (MFA). Microsoft Entra CBA can be either single-factor (SF) or multifactor (MF) depending on the tenant configuration. Enabling CBA makes a user potentially capable to complete MFA. A user with single factor certificate will need another factor to complete MFA. If the user does not have any other auth method registered and are added into scope for CBA auth method, the user cannot proof up to register other authentication methods.

If the CBA-enabled user only has a Single Factor (SF) certificate and needs to complete MFA:

1. Use a password and SF certificate.
2. Issue a Temporary Access Pass.
3. Authentication Policy Administrator adds a phone number and allows voice/text message authentication for the user account.

If the CBA-enabled user hasn't yet been issued a certificate and needs to complete MFA:

1. Issue a Temporary Access Pass.
2. Authentication Policy Administrator adds a phone number and allows voice/text message authentication for the user account.

If the CBA-enabled user can't use an MF cert, such as on mobile device without smart card support, and needs to complete MFA:

1. Issue a Temporary Access Pass.
2. User needs to register another MFA method (when user can use MF cert).
3. Use password and MF cert (when user can use MF cert).
4. Authentication Policy Administrator adds a phone number and allows voice/text message authentication for the user account.

Steps to set up passwordless phone sign in (PSI) with CBA

For passwordless sign-in to work, users should disable legacy notification through their mobile app.

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

2. Follow the steps at Enable passwordless phone sign-in authentication.

   Important

   In the preceding configuration, make sure you chose Passwordless option. You need to change the Authentication mode for any groups added for PSI to Passwordless. If you choose Any, CBA and PSI don't work.

3. Select Protection > Multifactor authentication > Additional cloud-based multifactor authentication settings.

   

4. Under Verification options, clear Notification through mobile app, and select Save.

   

MFA authentication flow using single factor certificates and passwordless sign in

Let's look at an example of a user who has single-factor certificate, and is configured for passwordless sign-in.

1. Enter your user principal name (UPN) and select Next.

   

2. Select Sign in with a certificate.

   

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

   

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

   

4. Because the certificate is configured to be single-factor authentication strength, the user needs a second factor to meet MFA requirements. The user sees available second factors, which in this case is passwordless sign-in. Select Approve a request on my Microsoft Authenticator app.

   

5. You'll get a notification on your phone. Select Approve Sign-in?.

6. Enter the number you see on the browser or app screen into Microsoft Authenticator.

   

7. Select Yes and user can authenticate and sign in.

Understanding the authentication binding policy

The authentication binding policy helps determine the strength of authentication as either single-factor or multifactor. Authentication Policy Administrators can change the default value from single-factor to multifactor, or set up custom policy configurations either by using issuer subject or policy OID or Issuer and Policy OID fields in the certificate.

Certificate strengths

Authentication Policy Administrators can determine whether the certificates are single-factor or multifactor strength. For more information, see the documentation that maps NIST Authentication Assurance Levels to Microsoft Entra auth Methods, which builds upon NIST 800-63B SP 800-63B, Digital Identity Guidelines: Authentication and Lifecycle Mgmt.

Multifactor certificate authentication

When a user has a multifactor certificate, they can perform multifactor authentication only with certificates. However, an Authentication Policy Administrator should make sure the certificates are protected with a PIN or biometric to be considered multifactor.

How Microsoft Entra ID resolves multiple authentication policy binding rules

Because multiple custom authentication binding policy rules can be created with different certificate fields like using issuer + policy OID, or just Policy OID or just issuer. Below are the steps used to determine the authentication protection level when custom rules overlap. They are as follows:

1. Issuer + policy OID rules take precedence over Policy OID rules. Policy OID rules take precedence over certificate issuer rules.
2. Issuer + policy OID rules are evaluated first. If you have a custom rule with issuer CA1 and policy OID 1.2.3.4.5 with MFA, only certificate A satisfies both issuer value and policy OID will be given MFA.
3. Next, custom rules using policy OIDs are evaluated. If you have a certificate A with policy OID 1.2.3.4.5 and a derived credential B based on that certificate has a policy OID 1.2.3.4.5.6, and the custom rule is defined as Policy OID with value 1.2.3.4.5 with MFA, only certificate A satisfies MFA, and credential B satisfies only single-factor authentication. If the user used derived credential during sign-in and was configured to have MFA, the user is asked for a second factor for successful authentication.
4. If there's a conflict between multiple policy OIDs (such as when a certificate has two policy OIDs, where one binds to single-factor authentication and the other binds to MFA) then treat the certificate as a single-factor authentication.
5. Next, custom rules using issuer CA are evaluated.
6. If a certificate has both policy OID and Issuer rules matching, the policy OID is always checked first, and if no policy rule is found then the issuer bindings are checked. Policy OID has a higher strong authentication binding priority than the issuer.
7. If one CA binds to MFA, all user certificates that the CA issues qualify as MFA. The same logic applies for single-factor authentication.
8. If one policy OID binds to MFA, all user certificates that include this policy OID as one of the OIDs (A user certificate could have multiple policy OIDs) qualify as MFA.
9. One certificate issuer can only have one valid strong authentication binding (that is, a certificate can't bind to both single-factor and MFA).

Important

There is a known issue where a Microsoft Entra Authentication Policy Administrator configures a CBA authentication policy rule using both Issuer and Policy OID impacts some device registration scenarios including:

• Windows Hello For Business enrollment
• Fido2 Security Key registration
• Windows Passwordless Phone Sign-in

Device registration with Workplace Join, Microsoft Entra ID and Hybrid Microsoft Entra device join scenarios are not impacted. CBA authentication policy rules using either Issuer OR Policy OID are not impacted. To mitigate, Authentication Policy Administrators should :

• Edit the certificate-based authentication policy rules currently using both Issuer and Policy OID options and remove either the Issuer or OID requirement and save. OR
• Remove the authentication policy rule currently using both Issuer and Policy OID and create rules using only issuer or policy OID

We are working to fix the issue.

Understanding the username binding policy

The username binding policy helps validate the certificate of the user. By default, Subject Alternate Name (SAN) Principal Name in the certificate is mapped to UserPrincipalName attribute of the user object to determine the user.

Achieve higher security with certificate bindings

There are seven supported methods for certificate bindings. In general, mapping types are considered high-affinity if they're based on identifiers that you can't reuse, such as Subject Key Identifiers or SHA1 Public Key. These identifiers convey a higher assurance that only a single certificate can be used to authenticate the respective user.

Mapping types based on user names and email addresses are considered low-affinity. Microsoft Entra ID implements three mappings considered low-affinity based on reusable identifiers. The others are considered high-affinity bindings. For more information, see certificateUserIds.

Certificate mapping field	Examples of values in certificateUserIds	User object attributes	Type
PrincipalName	X509:<PN>bob@woodgrove.com	userPrincipalName onPremisesUserPrincipalName certificateUserIds	low-affinity
RFC822Name	X509:<RFC822>user@woodgrove.com	userPrincipalName onPremisesUserPrincipalName certificateUserIds	low-affinity
IssuerAndSubject (preview)	X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<S>DC=com,DC=contoso,OU=UserAccounts,CN=mfatest	certificateUserIds	low-affinity
Subject (preview)	X509:<S>DC=com,DC=contoso,OU=UserAccounts,CN=mfatest	certificateUserIds	low-affinity
SKI	X509:<SKI>aB1cD2eF3gH4iJ5kL6-mN7oP8qR=	certificateUserIds	high-affinity
SHA1PublicKey	X509:<SHA1-PUKEY>aB1cD2eF3gH4iJ5kL6-mN7oP8qR	certificateUserIds	high-affinity
IssuerAndSerialNumber (preview)	X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>cD2eF3gH4iJ5kL6mN7-oP8qR9sT To get the correct value for serial number, run this command and store the value shown in CertificateUserIds: Syntax: Certutil –dump –v [~certificate path~] >> [~dumpFile path~] Example: certutil -dump -v firstusercert.cer >> firstCertDump.txt	certificateUserIds	high-affinity

Define Affinity binding at the tenant level and override with custom rules (Preview)

With this feature an Authentication Policy Administrator can configure whether a user can be authenticated by using low-affinity or high-affinity username binding mapping. You can set Required affinity binding for the tenant, which applies to all users. You can also override the tenant-wide default value by creating custom rules based on Issuer and Policy OID, or Policy OID, or Issuer.

How Microsoft Entra ID resolves multiple username policy binding rules

Use the highest priority (lowest number) binding.

1. Look up the user object by using the username or User Principal Name.
2. Get the list of all username bindings setup by the Authentication Policy Administrator in the CBA authentication method configuration ordered by the 'priority' attribute. Today the concept of priority is not exposed in Portal UX. Graph will return you the priority attribute for each binding and they are used in the evaluation process.
3. If the tenant has high affinity binding enabled or if the certificate value matches a custom rule that required high affinity binding, remove all the low affinity bindings from the list.
4. Evaluate each binding in the list until a successful authentication occurs.
5. If the X.509 certificate field of the configured binding is on the presented certificate, Microsoft Entra ID matches the value in the certificate field to the user object attribute value.
   1. If a match is found, user authentication is successful.
   2. If a match isn't found, move to the next priority binding.
6. If the X.509 certificate field isn't on the presented certificate, move to the next priority binding.
7. Validate all the configured username bindings until one of them results in a match and user authentication is successful.
8. If a match isn't found on any of the configured username bindings, user authentication fails.

Securing Microsoft Entra configuration with multiple username bindings

Each of the Microsoft Entra user object attributes (userPrincipalName, onPremiseUserPrincipalName, certificateUserIds) available to bind certificates to Microsoft Entra user accounts has a unique constraint to ensure a certificate only matches a single Microsoft Entra user account. However, Microsoft Entra CBA supports multiple binding methods in the username binding policy which allows an Authentication Policy Administrator to accommodate one certificate to multiple Microsoft Entra user accounts configurations.

Important

If you configure multiple bindings, Microsoft Entra CBA authentication is only as secure as your lowest affinity binding because CBA validates each binding to authenticate the user. To prevent a scenario where a single certificate matches multiple Microsoft Entra accounts, an Authentication Policy Administrator can:

• Configure a single binding method in the username binding policy.
• If a tenant has multiple binding methods configured and doesn't want to allow one certificate to map to multiple accounts, the Authentication Policy Administrator must ensure all allowable methods configured in the policy map to the same Microsoft Entra account. All user accounts should have values matching all of the bindings.
• If a tenant has multiple binding methods configured, the Authentication Policy Administrator should make sure that they don't have more than one low-affinity binding.

For example, lets suppose you have two username bindings on PrincipalName mapped to UPN and SubjectKeyIdentifier (SKI) to certificateUserIds. If you want a certificate to only be used for a single account, an Authentication Policy Administrator must make sure that account has the UPN that is present in the certificate, and implement the SKI mapping in the certificateUserId attribute of the same account.

Support for multiple certificates with one Microsoft Entra user account (M:1)

There are scenarios where an organization issues multiple certificates for a single identity. Most commonly this could be a derived credential for a mobile device or can also be for a secondary smartcard or x509 credential holder capable device such as a Yubikey.

Cloud only accounts For cloud-only accounts you can map multiple certificates (up to 5) for use by populating the certificateUserIds field (Authorization info in the User Portal) with unique values identifying each certificate. If the organization is using high affinity bindings say Issuer + SerialNumber, values within CertificateUserIds may look like the following:

X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>cD2eF3gH4iJ5kL6mN7-oP8qR9sT
X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>eF3gH4iJ5kL6mN7oP8-qR9sT0uV

In this example the first value represents X509Certificate1 and the second value represents X509Certificate2. The user may present either certificate at sign-in and as long as the CBA Username Binding is set to point to the certificateUserIds field to look for the particular binding type (that is, Issuer+SerialNumber in this example), then the user will successfully sign-in.

Hybrid Synchronized accounts For synchronized accounts you can map multiple certificates for use by populating the altSecurityIdentities field in AD the values identifying each certificate. If the organization is using high affinity (that is, strong authentication) bindings say Issuer + SerialNumber, this could look like the following:

X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>cD2eF3gH4iJ5kL6mN7-oP8qR9sT
X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>eF3gH4iJ5kL6mN7oP8-qR9sT0uV

In this example the first value represents X509Certificate1 and the second value represents X509Certificate2. These values must then be synchronized to the certificateUserIds field in Microsoft Entra ID.

Support for one certificate with multiple Microsoft Entra user accounts (1:M)

There are scenarios where an organization needs the user to use the same certificate to authenticate into multiple identities. Most commonly this is for administrative accounts. It can also be for developer accounts or temporary duty accounts. In traditional AD the altSecurityIdentities field is used to populate the certificate values and a Hint is used during login to direct AD to the desired account to check for the login. With Microsoft Entra CBA this is different and there is no Hint. Instead, Home Realm Discovery identifies the desired account to check the certificate values. The other key difference is that Microsoft Entra CBA enforces uniqueness in the certificateUserIds field. This means that two accounts cannot both populate the same certificate values.

Important

It is not a very secure configuration to use same credential to authenticate into different Microsoft Entra accounts and it is recommended not to allow one certificate for multiple Microsoft Entra user accounts.

Cloud only accounts For cloud-only accounts you need to create multiple username bindings and need to map unique values to each user account that will be utilizing the certificate. Each account will be authenticated into using a different username binding. This applies within the boundary of a single directory/tenant (that is, Authentication Policy Administrators can map the certificate for use in another directory/tenant as well, as long as the values remain unique per account too).

Populate the certificateUserIds field (Authorization info in the User Portal) with a unique value identifying the desired certificate. If the organization is using high affinity bindings (that is, strong authentication) bindings say Issuer + SerialNumber and SKI, this could look like the following:

Username bindings:

• Issuer + Serial Number -> CertificateUserIds
• SKI -> CertificateUserIds

User account CertificateUserIds values:
X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>aB1cD2eF3gH4iJ5kL6-mN7oP8qR
X509:<SKI>cD2eF3gH4iJ5kL6mN7-oP8qR9sT

Now, when either user presents the same certificate at sign-in the user will successfully sign-in because their account matches a unique value on that certificate. One account will be authenticated into using Issuer+SerialNumber and the other using SKI binding.

Note

The number of accounts that can be used in this manner is limited by the number of username bindings configured on the tenant. If the organization is using only High Affinity bindings the number of accounts supported will be limited to 3. If the organization is also utilizing low affinity bindings then this number increases to 7 accounts (1 PrincipalName, 1 RFC822Name, 1 SubjectKeyIdentifier, 1 SHA1PublicKey, 1 Issuer+Subject, 1 Issuer+SerialNumber, 1 Subject).

Hybrid Synchronized accounts For synchronized accounts the approach will be different. While Authentication Policy Administrators can map unique values to each user account that will be utilizing the certificate, the common practice of populating all values to each account in Microsoft Entra ID would make this difficult. Instead, Microsoft Entra Connect should filter the desired values per account to unique values populated into the account in Microsoft Entra ID. The uniqueness rule applies within the boundary of a single directory/tenant (that is, Authentication Policy Administrators can map the certificate for use in another directory/tenant as well, as long as the values remain unique per account too). Further, the organization may have multiple AD forests contributing users into a single Microsoft Entra tenant. In this case Microsoft Entra Connect will apply the filter to each of these AD forests with the same goal to populate only a desired unique value to the cloud account.

Populate the altSecurityIdentities field in AD with the values identifying the desired certificate and to include the desired certificate value for that user account type (such as detailee, admin, developer, and so on). Select a key attribute in AD which will tell the synchronization which user account type the user is evaluating (such as msDS-cloudExtensionAttribute1). Populate this attribute with the user type value you desire such as detailee, admin, or developer. If this is the user’s primary account, the value can be left empty/null.

The accounts could look like the following:

Forest 1 - Account1 (bob@woodgrove.com):
X509:<SKI>aB1cD2eF3gH4iJ5kL6mN7oP8qR
X509:<SHA1-PUKEY>cD2eF3gH4iJ5kL6mN7oP8qR9sT
X509:<PN>bob@woodgrove.com

Forest 1 - Account2 (bob-admin@woodgrove.com):
X509:<SKI>aB1cD2eF3gH4iJ5kL6mN7oP8qR
X509:<SHA1-PUKEY>>cD2eF3gH4iJ5kL6mN7oP8qR9sT
X509:<PN>bob@woodgrove.com

Forest 2 – ADAccount1 (bob-tdy@woodgrove.com):
X509:<SKI>aB1cD2eF3gH4iJ5kL6mN7oP8qR
X509:<SHA1-PUKEY>>cD2eF3gH4iJ5kL6mN7oP8qR9sT
X509:<PN>bob@woodgrove.com

These values must then be synchronized to the certificateUserIds field in Microsoft Entra ID.

Steps to synchronize to certificateUserIds

1. Configure Microsoft Entra Connect to add the alternativeSecurityIds field to the Metaverse
2. For each AD Forest, configure a new custom inbound rule with a high precedence (low number below 100). Add an Expression transform with the altSecurityIdentities field as the source. The target expression will use the Key Attribute that you selected and populated as well as the mapping to the User Types that you defined.
3. For example:

IIF((IsPresent([msDS-cloudExtensionAttribute1]) && IsPresent([altSecurityIdentities])), 
    IIF((InStr(LCase([msDS-cloudExtensionAttribute1]),LCase("detailee"))>0), 
    Where($item,[altSecurityIdentities],(InStr($item, "X509:<SHA1-PUKEY>")>0)), 
        IIF((InStr(LCase([msDS-cloudExtensionAttribute1]),LCase("developer"))>0), 
        Where($item,[altSecurityIdentities],(InStr($item, "X509:<SKI>")>0)), NULL) ), 
    IIF(IsPresent([altSecurityIdentities]), 
    Where($item,[altSecurityIdentities],(BitAnd(InStr($item, "X509:<I>"),InStrRev($item, "<SR>"))>0)), NULL) 
)

In the example above, altSecurityIdentities and the key attribute msDS-cloudExtensionAttribute1is are first checked to see if they are populated. If not, altSecurityIdentities is checked to see if it's populated. If it is empty then we set it to NULL. Otherwise the account falls into the default case and in this example we filter to only the Issuer+SerialNumber mapping. If the key attribute is populated, then the value is checked to see if it is equal to one of our defined user types. In this example if that value is detailee, then we filter to the SHA1PublicKey value from altSecurityIdentities. If the value is developer, then we filter to the SubjectKeyIssuer value from altSecurityIdentities. There may be multiple certificate values of a specific type. For example, multiple PrincipalName values or multiple SKI or SHA1-PUKEY values. The filter will get all the values and sync into Microsoft Entra ID – not just the first one it finds.

1. A second example that shows how to push an empty value if the control attribute is empty is below.

IIF((IsPresent([msDS-cloudExtensionAttribute1]) && IsPresent([altSecurityIdentities])), 
    IIF((InStr(LCase([msDS-cloudExtensionAttribute1]),LCase("detailee"))>0), 
    Where($item,[altSecurityIdentities],(InStr($item, "X509:<SHA1-PUKEY>")>0)), 
        IIF((InStr(LCase([msDS-cloudExtensionAttribute1]),LCase("developer")>0), 
        Where($item,[altSecurityIdentities],(InStr($item, "X509:<SKI>")>0)), NULL) ), 
    IIF(IsPresent([altSecurityIdentities]), 
    AuthoritativeNull, NULL) 
) 

If the value in altSecurityIdentities does not match any of the search values in the control attribute, then an AuthoritativeNull is passed. This ensures that prior or subsequent rules which populate alternativeSecurityId are ignored and the result is empty in Microsoft Entra ID.

1. Configure a new custom outbound rule with a low precedence (high number above 160 – bottom of list).
2. Add a direct transform with the alternativeSecurityIds field as the source and the certificateUserIds field as the target.
3. Run a synchronization cycle to complete the population of the data in Microsoft Entra ID.

Ensure that CBA in each tenant is configured with the Username Bindings pointing to the certificateUserIds field for the field types that you have mapped from the certificate. Now any of these users may present the certificate at sign-in and after the unique value from the certificate is validated against the certificateUserIds field, that user will be successfully signed-in.

Understanding the certificate revocation process

The certificate revocation process allows Authentication Policy Administrators to revoke a previously issued certificate from being used for future authentication. The certificate revocation won't revoke already issued tokens of the user. Follow the steps to manually revoke tokens at Configure revocation.

Microsoft Entra ID downloads and caches the customers certificate revocation list (CRL) from their certificate authority to check if certificates are revoked during the authentication of the user.

Authentication Policy Administrators can configure the CRL distribution point during the setup process of the trusted issuers in the Microsoft Entra tenant. Each trusted issuer should have a CRL that can be referenced by using an internet-facing URL.

Important

The maximum size of a CRL for Microsoft Entra ID to successfully download on an interactive sign-in and cache is 20 MB in public Microsoft Entra ID and 45 MB in Azure US Government clouds, and the time required to download the CRL must not exceed 10 seconds. If Microsoft Entra ID can't download a CRL, certificate-based authentications using certificates issued by the corresponding CA fail. As a best practice to keep CRL files within size limits, keep certificate lifetimes within reasonable limits and to clean up expired certificates. For more information, see Is there a limit for CRL size?.

When a user performs an interactive sign-in with a certificate, and the CRL exceeds the interactive limit for a cloud, their initial sign-in fails with the following error:

"The Certificate Revocation List (CRL) downloaded from {uri} has exceeded the maximum allowed size ({size} bytes) for CRLs in Microsoft Entra ID. Try again in few minutes. If the issue persists, contact your tenant administrators."

After the error, Microsoft Entra ID attempts to download the CRL subject to the service-side limits (45 MB in public Microsoft Entra ID and 150 MB in Azure US Government clouds).

Important

If an Authentication Policy Administrator skips the configuration of the CRL, Microsoft Entra ID doesn't perform any CRL checks during the certificate-based authentication of the user. This can be helpful for initial troubleshooting, but shouldn't be considered for production use.

As of now, we don't support Online Certificate Status Protocol (OCSP) because of performance and reliability reasons. Instead of downloading the CRL at every connection by the client browser for OCSP, Microsoft Entra ID downloads once at the first sign-in and caches it, thereby improving the performance and reliability of CRL verification. We also index the cache so the search is much faster every time. Customers must publish CRLs for certificate revocation.

The following steps are a typical flow of the CRL check:

1. Microsoft Entra ID attempts to download the CRL at the first sign-in event of any user with a certificate of the corresponding trusted issuer or certificate authority.
2. Microsoft Entra ID caches and reuses the CRL for any subsequent usage. It honors the Next update date and, if available, Next CRL Publish date (used by Windows Server CAs) in the CRL document.
3. The user certificate-based authentication fails if:

   • A CRL has been configured for the trusted issuer and Microsoft Entra ID can't download the CRL, due to availability, size, or latency constraints.

   • The user's certificate is listed as revoked on the CRL.

     

   • Microsoft Entra ID attempts to download a new CRL from the distribution point if the cached CRL document is expired.

Note

Microsoft Entra ID checks the CRL of the issuing CA and other CAs in the PKI trust chain up to the root CA. We have a limit of up to 10 CAs from the leaf client certificate for CRL validation in the PKI chain. The limitation is to make sure a bad actor doesn't bring down the service by uploading a PKI chain with a huge number of CAs with a bigger CRL size. If the tenant's PKI chain has more than 5 CAs and in case of a CA compromise, Authentication Policy Administrators should remove the compromised trusted issuer from the Microsoft Entra tenant configuration.

Important

Due to the nature of CRL caching and publishing cycles, it is highly recommended in case of a certificate revocation to also revoke all sessions of the affected user in Microsoft Entra ID.

As of now, there's no way to manually force or retrigger the download of the CRL.

How to 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.

Note

Azure AD and MSOnline PowerShell modules are deprecated as of March 30, 2024. To learn more, read the deprecation update. After this date, support for these modules are limited to migration assistance to Microsoft Graph PowerShell SDK and security fixes. The deprecated modules will continue to function through March, 30 2025.

We recommend migrating to Microsoft Graph PowerShell to interact with Microsoft Entra ID (formerly Azure AD). For common migration questions, refer to the Migration FAQ. Note: Versions 1.0.x of MSOnline may experience disruption after June 30, 2024.

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 test@yourdomain.com`
           $user.StsRefreshTokensValidFrom
   

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

           Set-MsolUser -UserPrincipalName test@yourdomain.com -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).

Understanding CRL validation (Preview)

A CRL is a record of digital certificates that have been revoked before the end of their validity period by a certificate authority (CA). When CAs are uploaded to the Microsoft Entra trust store, a CRL, or more specifically the CrlDistributionPoint attribute, isn't required. A CA can be uploaded without a CRL endpoint, and certificate-based authentication won't fail if an issuing CA doesn't have a CRL specified.

To strengthen security and avoid misconfigurations, an Authentication Policy Administrator can require CBA authentication to fail if no CRL is configured for a CA that issues an end user certificate.

Enable CRL validation

To enable CRL validation, click Require CRL validation (recommended).

Once enabled, any CBA will fail is the end user certificate was issued by a CA with no CRL configured.

An Authentication Policy Administrator can exempt a CA if its CRL has issues that should be fixed. Click Add Exemption and select any CAs that should be exempted.

The CAs in the exempted list aren't required to have CRL configured and the end-user certificates that they issue don't fail authentication.

Note

There's a known issue with the object picker where the selected items aren't displayed correctly. Use the Certificate Authorities tab to select or remove CAs.

How CBA works with a Conditional Access authentication strength policy

Customers can create a Conditional Access authentication strength policy to specify that CBA be used to access a resource.

You can use the built-in Phishing-resistant MFA authentication strength. That policy only allows authentication methods that are phishing-resistant like CBA, FIDO2 security keys, and Windows Hello for Business.

You can also create a custom authentication strength to allow only CBA to access sensitive resources. You can allow CBA as a single-factor, multifactor, or both. For more information, see Conditional Access authentication strength.

CBA authentication strength with advanced options

In the CBA Authentication methods policy, an Authentication Policy Administrator can determine the strength of the certificate by using authentication binding policy on the CBA method. Now you can configure Advanced options when you create a custom authentication strength to require a specific certificate to be used, based on issuer and policy OIDs, when users perform CBA to access certain sensitive resources. This feature provides a more precise configuration to determine the certificates and users that can access resources. For more information, see Advanced options for Conditional Access authentication strength.

Understanding Sign-in logs

Sign-in logs provide information about sign-ins and how your resources are used by your users. For more information about sign-in logs, see Sign-in logs in Microsoft Entra ID.

Let's walk through two scenarios, one where the certificate satisfies single-factor authentication and another where the certificate satisfies MFA.

For the test scenarios, choose a user with a Conditional Access policy that requires MFA. Configure the user binding policy by mapping SAN Principal Name to UserPrincipalName.

The user certificate should be configured like this screenshot:

Troubleshooting sign-in issues with dynamic variables in sign-in logs

Although sign-in logs provide all the information to debug a user's sign-in issues, there are times when specific values are required and since sign-in logs do not support dynamic variables, the sign-in logs would have missing information. For ex: The failure reason in sign-in log would show something like "The Certificate Revocation List (CRL) failed signature validation. Expected Subject Key Identifier {expectedSKI} does not match CRL Authority Key {crlAK}. Please request your tenant administrator to check the CRL configuration." where {expectedSKI} and {crlAKI} are not populated with correct values.

When users sign-in with CBA fails, please copy the log details from 'More Details' link in the error page. For more detailed info, look at understanding CBA error page

Test single-factor authentication

For the first test scenario, configure the authentication policy where the Issuer subject rule satisfies single-factor authentication.

1. Sign in to the Microsoft Entra admin center as the test user by using CBA. The authentication policy is set where Issuer subject rule satisfies single-factor authentication.

2. Search for and select Sign-in logs.

   Let's look closer at some of the entries you can find in the Sign-in logs.

   The first entry requests the X.509 certificate from the user. The status Interrupted means that Microsoft Entra ID validated that CBA is enabled in the tenant and a certificate is requested for authentication.

   

   The Activity Details shows this is just part of the expected login flow where the user selects a certificate.

   

   The Additional Details show the certificate information.

   

   These additional entries show that the authentication is complete, a primary refresh token is sent back to the browser, and user is given access to the resource.

   

Test multifactor authentication

For the next test scenario, configure the authentication policy where the policyOID rule satisfies multifactor authentication.

1. Sign in to the Microsoft Entra admin center using CBA. Since the policy was set to satisfy multifactor authentication, the user sign-in is successful without a second factor.

2. Search for and select Sign-ins.

   You'll see several entries in the Sign-in logs, including an entry with Interrupted status.

   

   The Activity Details shows this is just part of the expected login flow where the user selects a certificate.

   

   The entry with Interrupted status has more diagnostic info on the Additional Details tab.

   

   The following table has a description of each field.

   Field	Description
   User certificate subject name	Refers to the subject name field in the certificate.
   User certificate binding	Certificate: Principal Name; User Attribute: userPrincipalName; Rank: 1 This shows which SAN PrincipalName certificate field was mapped to userPrincipalName user attribute and was priority 1.
   User certificate authentication level	multiFactorAuthentication
   User certificate authentication level type	PolicyId This shows policy OID was used to determine the authentication strength.
   User certificate authentication level identifier	1.2.3.4 This shows the value of the identifier policy OID from the certificate.

Understanding the certificate-based authentication error page

Certificate-based authentication can fail for reasons such as the certificate being invalid, or the user selected the wrong certificate or an expired certificate, or because of a Certificate Revocation List (CRL) issue. When certificate validation fails, the user sees this error:

If CBA fails on a browser, even if the failure is because you cancel the certificate picker, you need to close the browser session and open a new session to try CBA again. A new session is required because browsers cache the certificate. When CBA is retried, the browser sends the cached certificate during the TLS challenge, which causes sign-in failure and the validation error.

Select More details to get logging information that can be sent to an Authentication Policy Administrator, who in turn can get more information from the Sign-in logs.

Select Other ways to sign in to try other methods available to the user to sign in.

Note

If you retry CBA in a browser, it'll keep failing due to the browser caching issue. Users need to open a new browser session and sign in again.

Certificate-based authentication in MostRecentlyUsed (MRU) methods

Once a user authenticates successfully using CBA, the user's MostRecentlyUsed (MRU) authentication method is set to CBA. Next time, when the user enters their UPN and selects Next, the user is taken to the CBA method directly, and need not select Use the certificate or smart card.

To reset the MRU method, the user needs to cancel the certificate picker, select Other ways to sign in, and select another method available to the user and authenticate successfully.

External identity support

An external identity B2B guest user can use CBA on the home tenant and if the cross tenant settings for the resource tenant is set up to trust MFA from the home tenant, user's CBA auth on home tenant will be honored. For more information about how to enable Trust multifactor authentication from Microsoft Entra tenants, see Configure B2B collaboration cross-tenant access. CBA on resource tenant is not supported yet.

Next steps

• Overview of Microsoft Entra CBA
• How to configure Microsoft Entra CBA
• Microsoft Entra CBA on iOS devices
• Microsoft Entra CBA on Android devices
• Windows smart card logon using Microsoft Entra CBA
• Certificate user IDs
• How to migrate federated users
• FAQ
• Troubleshoot Microsoft Entra CBA