Certificate-Based Authentication (CBA) lets users sign in to Microsoft 365 and Azure services using an X.509 certificate instead of a password. It’s phishing-resistant, passwordless, and pairs beautifully with smart cards and USB security keys. This guide walks you through the entire process of enabling CBA in a brand-new Entra ID tenant, from creating your own Certificate Authority to a successful first login.

Prerequisites

  • A Microsoft Entra ID (Azure AD) tenant with at least a P1 license
  • Global Administrator or Authentication Policy Administrator role
  • OpenSSL installed on your machine (comes pre-installed on macOS and most Linux distros; on Windows, install via Git for Windows or OpenSSL for Windows)
  • A user account to test with

Step 1: Create Your Root Certificate Authority

You need a Certificate Authority (CA) to sign user certificates. For production environments you’d use Active Directory Certificate Services or a third-party CA, but a self-signed root CA works perfectly for smaller organizations.

On macOS / Linux

Open Terminal and run:

openssl genrsa -out rootCA.key 4096
openssl req -x509 -new -key rootCA.key -sha256 -days 1825 -out rootCA.crt -subj "/CN=YourOrg Root CA"

On Windows

Open PowerShell or Git Bash and run:

openssl genrsa -out rootCA.key 4096
openssl req -x509 -new -key rootCA.key -sha256 -days 1825 -out rootCA.crt -subj "/CN=YourOrg Root CA"

This creates two files:

  • rootCA.key — Your CA’s private key. Guard this carefully. Anyone with this file can issue trusted certificates for your tenant.
  • rootCA.crt — Your CA’s public certificate. This gets uploaded to Entra ID.

Step 2: Convert the Root CA to .cer Format

Entra ID expects a .cer file for upload. Convert your root certificate:

openssl x509 -in rootCA.crt -out rootCA.cer -outform DER

If you run into issues with DER format during upload, try PEM instead:

openssl x509 -in rootCA.crt -out rootCA.cer -outform PEM

Step 3: Upload the Root CA to Entra ID

  1. Sign in to the Microsoft Entra admin center
  2. Navigate to Security → Certificate authorities
  3. Click Upload
  4. Upload your rootCA.cer file
  5. Toggle “Is root CA” to Yes
  6. Click Save

You should now see your CA listed with its thumbprint and expiration date.

Step 4: Enable Certificate-Based Authentication

  1. In the Entra admin center, go to Security → Authentication methods → Policies
  2. Find Certificate-based authentication and click on it
  3. On the Enable and Target tab:
    • Toggle the method to Enabled
    • Under Target, set it to All users or select a specific group
  4. Click Save

Step 5: Configure Username Binding

This is the step that trips most people up. You need to tell Entra ID how to match a certificate to a user account.

  1. Still in the CBA configuration, click the Configure tab
  2. Scroll down to Username binding
  3. You should see default rules for PrincipalName, RFC822Name, and SKI

The PrincipalName binding maps the certificate’s Subject Alternative Name (SAN) UPN field to the user’s userPrincipalName in Entra. This is the binding we’ll use.

Important: The PrincipalName binding looks for the Microsoft UPN OID (1.3.6.1.4.1.311.20.2.3) in the certificate’s SAN extension — not the Subject CN field. Your certificates must include this SAN, or authentication will fail with “No value in the certificate, as requested by tenant policy, is able to validate the user claim.”

Optional: CRL Validation

On the Configure tab you’ll also see Certificate revocation list (CRL) validation. For initial setup, leave “Require CRL validation” unchecked. You can enable it later once you have a CRL distribution point configured for your CA.

Step 6: Generate a User Certificate

Now create a certificate for your first user. The critical piece is including the UPN in the Subject Alternative Name using the Microsoft UPN OID.

On macOS / Linux

openssl genrsa -out user-cba.key 2048

openssl req -new -key user-cba.key \
  -out user-cba.csr \
  -subj "/CN=user@yourdomain.com" \
  -addext "subjectAltName=otherName:1.3.6.1.4.1.311.20.2.3;UTF8:user@yourdomain.com"

openssl x509 -req -in user-cba.csr \
  -CA rootCA.crt -CAkey rootCA.key -CAcreateserial \
  -out user-cba.crt -days 365 -sha256 \
  -copy_extensions copyall

On Windows

openssl genrsa -out user-cba.key 2048

openssl req -new -key user-cba.key -out user-cba.csr -subj "/CN=user@yourdomain.com" -addext "subjectAltName=otherName:1.3.6.1.4.1.311.20.2.3;UTF8:user@yourdomain.com"

openssl x509 -req -in user-cba.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out user-cba.crt -days 365 -sha256 -copy_extensions copyall

Replace user@yourdomain.com with the user’s actual UPN in Entra ID.

Step 7: Bundle into a .pfx File

Combine the certificate and private key into a PKCS#12 (.pfx) file. This is the portable format you’ll import onto the user’s machine.

On macOS

macOS Keychain requires the legacy PKCS#12 format. If you’re on OpenSSL 3.x (check with openssl version), add the -legacy flag:

openssl pkcs12 -export -out user-cba.pfx \
  -inkey user-cba.key \
  -in user-cba.crt \
  -certfile rootCA.crt \
  -legacy

On Windows

openssl pkcs12 -export -out user-cba.pfx -inkey user-cba.key -in user-cba.crt -certfile rootCA.crt

You’ll be prompted to set an export password. Remember it — you’ll need it during import.

Step 8: Import the Certificate

On macOS

security import user-cba.pfx -k ~/Library/Keychains/login.keychain-db -P "YourPassword"
security import rootCA.cer -k ~/Library/Keychains/login.keychain-db

If the security import command fails with “MAC verification failed during PKCS12 import,” you need to recreate the .pfx with the -legacy flag (see Step 7).

On Windows

Option A — GUI:

  1. Double-click the .pfx file
  2. The Certificate Import Wizard opens
  3. Choose Current User and click Next
  4. Enter the export password
  5. Leave defaults and click through to finish

Option B — Command line (run as Administrator):

certutil -addstore Root rootCA.cer
certutil -importpfx user-cba.pfx

Step 9: Test the Login

  1. Fully quit your browser (Cmd+Q on Mac, or close all windows on Windows)
  2. Reopen the browser and navigate to https://login.microsoftonline.com
  3. Enter the user’s email address
  4. When prompted, choose “Use a certificate or smart card”
  5. Your OS will present a certificate picker — select the correct certificate
  6. On macOS, you’ll be prompted for your Mac login password (Keychain password) — enter it and click Always Allow

If everything is configured correctly, you’ll be signed in.

Troubleshooting

“No certificate detected”

The certificate isn’t installed in your OS certificate store, or your browser needs to be restarted. Make sure both the user .pfx and root CA .cer are imported.

“We couldn’t sign you in with a certificate”

The certificate was found and sent, but Entra rejected it. Check the Sign-in logs in Entra admin center for the specific error code.

Error 1001009: “No value in the certificate… is able to validate the user claim”

Your certificate doesn’t have the UPN in the SAN field. Regenerate the certificate with the -addext "subjectAltName=otherName:1.3.6.1.4.1.311.20.2.3;UTF8:user@domain.com" flag and use -copy_extensions copyall when signing.

“MAC verification failed during PKCS12 import” (macOS)

OpenSSL 3.x uses newer encryption that macOS Keychain doesn’t support. Recreate the .pfx with the -legacy flag.

Security Best Practices

  • Protect your Root CA key. Store rootCA.key offline or in a hardware security module. Anyone with this key can issue certificates trusted by your tenant.
  • Set reasonable certificate lifetimes. 365 days for user certificates is a good balance between security and convenience.
  • Enable CRL validation once you have a revocation infrastructure in place, so you can revoke compromised certificates.
  • Consider Multi-Factor strength. In the CBA configuration, you can set the authentication strength to Multi-factor if CBA should satisfy your MFA requirements on its own.

Automating Certificate Deployment via USB (Windows)

If you’re deploying certificates as part of a Windows unattended install, you can automate the import. Place rootCA.cer and user-cba.pfx in a Certs folder on your USB drive, then add the following to your autounattend.xml:

<RunSynchronousCommand wcm:action="add">
    <Order>1</Order>
    <Path>powershell -ExecutionPolicy Bypass -Command "$d=(Get-Volume -FileSystemLabel 'ESD-USB').DriveLetter; certutil -addstore Root ${d}:\Certs\rootCA.cer; certutil -importpfx -p 'YourPassword' ${d}:\Certs\user-cba.pfx"</Path>
    <Description>Import CBA Certificates</Description>
</RunSynchronousCommand>

This automatically finds the USB by volume label and imports both certificates during Windows setup.

What’s Next?

Now that your tenant is set up for CBA, adding new users is straightforward — you just generate a new certificate for each user using the same Root CA. See the companion article: Issuing CBA Certificates for New Users.