Configuring CAC Authentication

Background Information

Keycloak supports logging in with an X.509 client certificate if you have configured the server to use mutual SSL authentication. As a result, Keycloak must be configured to use passthrough ingress.

Additionally, Keycloak must be provided with Certificate Authorities (CAs) to trust when verifying client certificates.

Within SmoothGlue, Keycloak can easily be configured to support CAC authentication. Some additional settings must be applied to the realm to enable users to login with their CAC.

Users will only be prompted for their CAC if they have it inserted before visiting the login page. If it is not present when visiting the login page, the user will be prompted for username and password or an error if username and password authentication has been disabled.

Configuring Keycloak for Passthrough Ingress

Enabling the necessary IaC components and resulting bigbang configuration is as simple as toggling this variable in the IaC inputs:

locals {
  cluster_inputs = {
    sso_passthrough_enable = true
  }
}

Enabling CAC Login

These steps are largely the same as Keycloak's documentation with some minor changes, given the format of CAC certificates.

1. While you are in the smoothglue realm, click on Authentication under Configure in the left pane.
2. Select the browser flow.
3. In the top right, select Action -> Duplicate.
   1. Name: Browser CAC Auth
   2. Description: Browser based authentication with CAC authentication
4. Click Duplicate.
5. Click Add step.
6. Search and select X509/Validate Username Form.
7. Click Add.
8. Drag X509/Validate Username Form block to be the second block just under Cookie.
9. In X509/Validate Username Form's Requirement drop-down, select Alternative.
10. Click on X509/Validate Username Form's settings (gear icon) and update the following:
    1. Alias: CAC Auth
    2. A regular expression to extract user identity: CN=(?:.*?)(\d*)(?:,|$)
    3. A name of user attribute: DOD_ID
    4. Check certificate validity: toggle on.
11. Click Save.
12. Click Action -> Bind flow:
    1. Choose binding type: Browser flow
13. Click Save.

Associating Users with CACs

Now that Keycloak can prompt users for their CAC, Keycloak needs to know what user is associated to which CAC.

For each user you want to associate:

1. While you are in the smoothglue realm, click on Users under Manage in the left pane.
2. Select the desired user.
3. Click the Attributes tab.
4. Add an attribute:
   1. Key: DOD_ID
   2. Value: The DOD ID number found on the back of their CAC.
5. Click Save.

Troubleshooting

Users Are Not Being Prompted for Their CAC

There are a few likely causes for this:

1. The Browser flow authentication flow, created in the steps above, is not bound for the smoothglue realm.
   1. Please ensure the authentication flow is bound so that users will be prompted for their CAC.
2. User has visited the login page before inserting their CAC.
   1. Have the user restart their browser or try visiting the login page from an incognito window.
3. Custom Keycloak configuration has overwritten settings necessary for CAC authentication.
   1. Please review the default configuration provided by SmoothGlue and Keycloak documentation to determine what was lost.
4. If you are providing a custom Truststore for validating smart cards in addition to CACs:
   1. Please ensure the custom Truststore also includes the DoD CAs required for CAC authentication.

X509 certificate authentication's failed. Invalid user

This error usually means the user attempted to login with their CAC, and Keycloak was unable to associate it to an account.

Please review their DoD ID and ensure it is set correctly within their user account attributes.