Troubleshooting Smart Card/PIV authentication

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

  • Subject Alternate Name: Ensure that the Subject Alternate Name or expression result matches the Okta attribute that you specified. It must be either email or Okta username.
  • Certificate Chain: Ensure that the entire certificate chain of issuers is uploaded in the correct format. 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. About user account status.
  • Browser session: Always start with a brand new browser session to avoid caching issues. Close out all browser windows before testing the feature.

CRL endpoints

Test the accessibility of CRL endpoints. Okta requires access to the Certificate Revocation List distribution points on a perpetual basis for PIV card authentication to work. This access is necessary so that Okta can verify that the certificate that the end user is presenting isn't revoked, expired, or otherwise not trustworthy. Revocation checking is a critical process to ensure the security of PIV Authentication. Typically, Certificate Revocation Lists are posted in a publicly reachable HTTP location on the internet, but in some highly secure environments, the revocation endpoints aren't public.

To verify that the CRL is posted in a location where Okta can reach it:

  1. Copy the Certificate Revocation List Endpoint URL from the client's public X.509 certificate (that ends in .crl).
  2. Paste the CRL Endpoint URL into a browser on an off-network device.
  3. If the CRL is accessible, the .crl file downloads automatically.
  4. If the URL returns a 401 error, then it isn't public. The Okta service can't access the endpoints.

For more information, see Allow access to Okta IP addresses. Ensure that the Okta IP can access the CRL distribution point over HTTP.

Revocation checking occurs for every certificate in the chain. It might be necessary to repeat this process for each intermediate certificate in the PKI chain.

Multiple certificates

If you're using more than one certificate, combine them into a single file.

  1. Convert DER encoded root and intermediate certificates (with .cer, .crt extension) into PEM format using the following openssl command: openssl x509 -inform der -in $input-cert-file-name -out $out-cert-file-name-with-pem-extension
  2. Concatenate all the PEM certificates into a single file with the root certificate being the last one using the following command: cat $intermediate-cert-file-1 ... $intermediate-cert-file-N $root-cert-file-with-pem-extension > trust-chain.pem
  3. Upload trust-chain.pem when creating the Smart Card Identity Provider and ensure that no other Smart Cards IDPs exist.

Be sure that the root certificate is the last of the PEM certificates in the single file.

Related topics

Format a PKI Certificate Chain

Add a Smart Card identity provider

Sign in with a Smart Card/PIV as an end user