Setting Up DoD/DoW Smart Card (CAC/PIV) Authentication in Okta

A Comprehensive Guide: Setting Up DoD/DoW Smart Card (CAC/PIV) Authentication in Okta

Okta is agnostic to the type of authenticator used on the platform. This allows customers to ensure high levels of assurance before reaching sensitive data classifications. This guide provides a step-by-step walkthrough that combines best practices for preparing Department of War (DoW) Common Access Card (CAC) certificate chains and configuring the necessary components in the Okta Admin Console to support smart card/certificate authentication.

The process involves preparing DoW certificate trust chains, configuring a Smart Card Identity Provider (IdP) to validate user certificates, setting up the Smart Card Authenticator, and enforcing its use through authentication policies.

Step 1: Prepare the DoD/DoW Certificate Chains

DoD/DoW Public Key Infrastructure (PKI) certificate chains. Okta uses these chains (also called "trust anchors") to validate the authenticity of the certificate presented by a user's smart card. For optimal performance and security, it's recommended to create separate certificate bundles for each Root Certificate Authority (CA).

There are two primary methods to gather these certificates.

Note: While certificates are currently issued under the Department of Defense (DoD), future issuers may use a different designation such as DoW.

Method 1: Download and Parse the Full DoD/DoW PKI Bundle (Recommended)

This method is ideal for ensuring you have all the necessary CAs and for automating the process.

1. Download the DoD PKI Bundle: Navigate to the DoD Cyber Exchange website (https://public.cyber.mil/pki-pke/) and find the "PKI CA Certificate Bundles." Download the PKCS#7 bundle for DoD PKI.
2. Extract Certificates from the P7B File: The downloaded file is a binary-encoded P7B bundle. Use OpenSSL to convert all the certificates within it to the human-readable PEM format.
   1. openssl pkcs7 -in Certificates_PKCS7_v5_14_DoD.der.p7b -inform der -print_certs -out all_certs.pem
3. Filter for Necessary Certificates: The all_certs.pem file now contains all DoD certificates, including those for email, software signing, and identity. For CAC authentication, you only need the ID CAs and their corresponding Root CAs. Optionally, you can include the DERILITY CAs to support authentication from mobile devices credentialed via Purebred. Including unnecessary certificates can cause performance issues.
   1. Open all_certs.pem in a text editor.
   2. Manually copy the required certificates into new, separate files. For example, create one file for all CAs that chain up to DoD Root CA 3 and another for those that chain up to DoD Root CA 6.
4. Order the Certificates Correctly: Within each new file, the order is crucial. The certificate chain must be ordered from the intermediate CA to the root CA. The root certificate (e.g., DoD Root CA 6) must be the last certificate in the file.
5. Example Certificate Chain File (DoD_Root_CA_6_Chain.pem):

-----BEGIN CERTIFICATE-----

(DOD ID CA-72 Certificate)

-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----

(DOD ID CA-73 Certificate)

-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----

(DoD Root CA 6 Certificate)

-----END CERTIFICATE-----

Method 2: Manually Download and Combine Certificates from DISA

Situation: Simpler for supporting a subset of Certificate Authorities or not having access to OpenSSL.

1. Obtain from DISA:  Download each CA ID (ID59,62,63,64,65,70,71,72,73, etc..): https://crl.gds.disa.mil/ - note: The Root CAs are not available for download here.
2. Rename each CA Certificate: For each intermediate and root certificate, rename to .crt
3. Combine and Order: Combine the contents of each exported file into a single .pem text file, ensuring the order is correct (intermediates first, root last) as described in Method 1.
   1. Alternate: Use the Certificate builder feature when configuring a SmartCard IdP and select each certificate in the chain.  

Method 3: Manually Download and Combine Certificates from a Smart Card

Situation: If you only need to trust a few specific CAs for a subset of users, without access to download certificates from DISA.

1. Identify the Certificate Chain: Insert a user's CAC and view their authentication certificate in the browser or OS certificate manager. On the "Certification Path" tab, you can see the full chain, from the user's certificate up to the root.
2. Export Each CA Certificate: For each intermediate and root certificate in the path, open it, go to the "Details" tab, and click "Copy to File..."
3. Choose the Correct Format: Select Base-64 encoded X.509 (.CER) as the export format.
4. Combine and Order: Combine the contents of each exported file into a single .pem text file, ensuring the order is correct (intermediates first, root last) as described in Method 1.
   1. Alternate: Use the Certificate builder feature when configuring a SmartCard IdP and select each certificate in the chain. 

Step 2: Configure the Smart Card Identity Provider (IdP)

You will create one IdP for each certificate chain file you prepared. Only one Root CA can be configured in Okta at a time.

1. In the Okta Admin Console, navigate to Security > Identity Providers.
2. Click Add Identity Provider and select Add Smart Card IdP.
3. Configure the IdP Settings:
   1. Name: Give the IdP a descriptive name (e.g., "DoD Root CA 6 CAC").
   2. Certificate Chain: Upload the corresponding PEM file you created in Step 1.
   3. IdP Username: This defines how Okta maps the certificate to a user. This is a critical step.
   4. To find the right value, inspect a user's certificate and look at the Subject Alternative Name (SAN).
   5. For DoD CACs, the User Principal Name (UPN) is often used. The expression idpuser.subjectAltNameUpn will map to the full 16-digit EDIPI (e.g., 1234567890123456@mil).
   6. If you only store the 10-digit EDIPI in Okta user profiles, you can use a substring expression: String.substring(idpuser.subjectAltNameUpn, 0, 10).
   7. Match against: Select the Okta user attribute that will be matched against the IdP Username. This could be the default Login attribute or a custom attribute you've created for the EDIPI.
   8. If no match is found: We recommend selecting Redirect to Okta sign-in page.
   9. Security Characteristics: Select both PIN-protected and Hardware-protected.
4. Click Add Identity Provider. Repeat this process for any other certificate chains (e.g., one for Root CA 3, one for Root CA 6).

Step 3: Add and Configure the Smart Card Authenticator

These steps involve applying the IdP to the user's authenticators to ensure that the Authentication Policies are enforced correctly.

1. Navigate to Security > Authenticators.
2. On the Setup tab, click Add Authenticator and select the Smart Card authenticator.
3. In the configuration window, associate the authenticator with the Smart Card IdP(s) you created in the previous step. You can add multiple IdPs to a single authenticator.
4. Click Add.

Step 4: Update Authentication and Enrollment Policies

Once the authenticator is configured, you must update your policies to enforce its use. It is strongly recommended to test new policies on a small group of test users before applying them to your entire organization.

1. Authenticator Enrollment Policies: Navigate to Security > Authenticators and select the Enrollment tab. Update or create a policy for your DoD users to make the Smart Card authenticator either "Optional" or "Required" for enrollment.
2. Update Authentication Policies and/or Global Session Policies: If you want to force CAC authentication, set these policies to require Smart Card as the only acceptable method. 

Step 5: (Optional) Customize the Sign-In Widget

A default labeled button is pushed to the Sign-In Widget. You can customize the text on the smart card login button to make it more intuitive for users.

1. Navigate to Customizations > Brands and select your brand.
2. Go to the Sign-In Page tab and click Customize.
3. Enable the Code editor.
4. Find the line: var config = OktaUtil.getSignInWidgetConfig();
5. To change the button text, add the following line below it:
   1. config.piv.text = 'Sign in with CAC/PIV';
6. Click Save and Publish.

Step 6: Verify the Configuration

To verify the setup, a user can:

• Go to your Okta sign-in page and click the newly configured "Sign in with CAC/PIV" button.
• The browser will prompt them to select their certificate and enter their CAC PIN.
• Upon successful PIN entry, Okta will validate the certificate against the IdP, match the user to their Okta profile, and grant access.