PIV/CAC/Smart cards

Login to Keeper Connection Manager with a PIV/CAC device

KCM allows authentication with the web application using the DoD's Common Access Cards (CAC), as well as with any smart card supported by the browser for SSL client auth such as Personal Identity Verification (PIV).

This feature allows users to authenticate to Keeper Connection Manager using CAC, this does not allow pass-through of CAC to the remote desktop.

This support depends on an SSL termination instance providing SSL/TLS authentication, a capability that was added to KCM version 2.12.0.

A typical configuration for PIV/CAC would be the following:

  1. An SSL termination instance configured with two hostnames: one for normal access (such as kcm.example.net) and another just for handling SSL client auth, which should ideally be a wildcard domain (such as *.login.kcm.example.net). The SSL client auth configuration would include the certificate of the CA providing the PIV/CAC cards.

  2. PIV/CAC support installed and configured to authenticate users against *.login.kcm.example.net and redirect them back to kcm.example.net once ready.

  3. Database backend configured to automatically create user accounts for users coming from SSO.

  4. User creation workflow configured to require approval for users that SSO from PIV/CAC.

Configuration Options for PIV/CAC

Support for PIV/CAC is configured using Keeper's new support for SSL/TLS client authentication. This support is provided by the “guacamole-auth-sso-ssl” extension, which we package as kcm-guacamole-auth-sso-ssl. Setting any SSL_* variable will implicitly include the kcm-guacamole-auth-sso-ssl package.

The following options will need to be set in the keeper/guacamole Docker container definition (or in guacamole.properties for linux distributions):

The following options are also available, though it would be unusual to need to set them:

SSL (NGINX) Configuration Options for PIV/CAC

Authenticating with PIV/CAC (or any smart card) via the browser is using SSL/TLS client authentication. This capability was further enhanced for PIV/CAC by adding convenient configuration options for testing whether certificates have been revoked via OCSP or a CRL. For reference, the following are all options related to SSL/TLS client authentication currently supported by the keeper/guacamole-ssl-nginx Docker image:

Example PIV/CAC Configuration

The example docker-compose.yml below uses the following placeholders:

In practice, these values will vary, as will whether the user chooses to use MySQL or PostgreSQL. The example below was written using PostgreSQL.

version: "3"
services:

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            POSTGRES_HOSTNAME: "db"
            POSTGRES_DATABASE: "guacamole_db"
            POSTGRES_USERNAME: "guacamole_user"
            POSTGRES_PASSWORD: "PasswordForGuacamole"
            SSL_PRIMARY_URI: "https://kcm.example.net"
            SSL_CLIENT_AUTH_URI: "https://*.kcm.example.net"
            SSL_SUBJECT_BASE_DN: "ou=test department,o=u.s. government,c=us"
            POSTGRESQL_AUTO_CREATE_ACCOUNTS: "true"
            REQUIRE_ACCOUNT_APPROVAL: "ssl"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    db:
        image: keeper/guacamole-db-postgres:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_DATABASE: "guacamole_db"
            GUACAMOLE_USERNAME: "guacamole_user"
            GUACAMOLE_PASSWORD: "PasswordForGuacamole"
            GUACAMOLE_ADMIN_PASSWORD: "guacadmin"
            POSTGRES_PASSWORD: "PasswordForPostgresAdmin"

    guacd:
        image: keeper/guacd:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        volumes:
            - "/path/to/pki:/pki:ro"
        environment:

            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: "guacamole"

            SERVERS: |

              # Main hostname, referenced by SSL_PRIMARY_URI
              - SSL_HOSTNAME: "kcm.example.net"
                CERTIFICATE_FILE: "/pki/kcm.example.net.crt"
                PRIVATE_KEY_FILE: "/pki/kcm.example.net.key"

                # The default CSP must be overridden for the main URI to allow
                # it to issue requests to its SSL/TLS-authenticating
                # counterpart. The only change from the default CSP here is to
                # add an the wildcard URI (including https://) to connect-src.
                CONTENT_SECURITY_POLICY: "default-src 'none'; script-src 'self' 'unsafe-eval'; connect-src 'self' wss://kcm.example.net https://*.kcm.example.net; object-src 'self'; frame-src 'self' https:; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline'; font-src 'self' data:; form-action 'self'; base-uri 'self'; frame-ancestors 'self';"

              # Hostname requiring client auth, referenced by SSL_CLIENT_AUTH_URI
              - SSL_HOSTNAME: "*.kcm.example.net"
                CERTIFICATE_FILE: "/pki/_.kcm.example.net.crt"
                PRIVATE_KEY_FILE: "/pki/_.kcm.example.net.key"
                CLIENT_CERTIFICATE_FILE: "/pki/cac-certificate.pem"
                SSL_VERIFY_CLIENT: "optional" # This is necessary to allow the webapp to receive
                                              # verification failures. Without this, Nginx would
                                              # respond directly to any verification failures and
                                              # will not include the CORS headers necessary to
                                              # allow the webapp to actually see that failure. This
                                              # also allows the webapp to see the nature of the
                                              # failure by investigating the headers Nginx sends.
                                              # There are no such headers (and no such request) if
                                              # this is set to "required" and Nginx aborts
                                              # processing due to an invalid certificate.

volumes:
    common-storage:

Configuring the KCM user creation workflow

Prior to configuring the user workflow, make sure to set the REQUIRE_ACCOUNT_APPROVAL key to the appropriate authentication method.

For PIV/CAC, you would set it to ssl:

 guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            SSL_PRIMARY_URI: "https://kcm.example.net"
            SSL_CLIENT_AUTH_URI: "https://*.kcm.example.net"
            SSL_SUBJECT_BASE_DN: "ou=test department,o=u.s. government,c=us"
            POSTGRESQL_AUTO_CREATE_ACCOUNTS: "true"
            REQUIRE_ACCOUNT_APPROVAL: "ssl"

Once you have successfully configured, there will be a new "Use Certificate or Smart Card" link on the login screen of the application as seen below:

For additional details on user creation workflow, visit this page.

Installing CA Authority

For each end-user client device that will need access to Keeper Connection Manager, you may need to install the internal CA as a trusted authority into the user's browser. The installation of CA trusted authority varies by platform.

Last updated