Troubleshooting Smart Card and PIV card authentication

If authentication with a Smart Card or Personal Identity Verification (PIV) card fails, verify the following items:

  • Subject Alternate Name: Ensure that the Subject Alternate Name or expression result matches the Okta attribute that you specified. It must be either the email address or the Okta username.
  • Certificate Chain: Ensure that the entire certificate chain of issuers is uploaded in the correct format, especially if you're using multiple certificates. See Format a PKI certificate chain.
  • User account state: Ensure that the user has an account in an active state. Password reset is considered active. See User account status.
  • Browser session: Always start with a new browser session to avoid caching issues. Close all other browser windows before you test the feature.

Troubleshoot CRL endpoints

Okta automatically downloads and caches Certificate Revocation Lists (CRLs). Okta therefore needs access to the CRL endpoints so that Smart Card and PIV card authentication can work. This ensures that Okta can verify that the certificate that the end user is presenting isn't revoked, expired, or not trustworthy. Verifying revocation status is critical for the security of Smart Card and PIV card authentication. Typically, CRLs are posted in a publicly reachable location on the internet. However, in some highly secure environments, the CRL endpoints aren't public.

Verify that the CRL location is accessible to Okta

Okta checks each certificate in a PKI chain against the CRL. You may need to repeat this procedure for each intermediate certificate in the PKI chain.

  1. Copy the CRL endpoint URL from the client's public X.509 certificate. This file ends in .crl.
  2. Paste the CRL endpoint URL into a browser on an off-network device. If the CRL is accessible, the .crl file downloads automatically.
  3. If the URL returns a 401 error, then it isn't public. The Okta service can't access the endpoint. See Allow access to Okta IP addresses.

Related topics

Format a PKI certificate chain

Add a Smart Card identity provider

Test the Smart Card or PIV card configuration