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:
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.PIV/CAC support installed and configured to authenticate users against
*.login.kcm.example.net
and redirect them back tokcm.example.net
once ready.Database backend configured to automatically create user accounts for users coming from SSO.
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):
ssl-client-auth-uri
SSL_CLIENT_AUTH_URI
REQUIRED. A wildcard URI that points to this Guacamole instance and requests SSL/TLS client authentication.
ssl-primary-uri
SSL_PRIMARY_URI
REQUIRED. A non-wildcard URI that points to this Guacamole instance and DOES NOT request SSL/TLS client authentication.
ssl-subject-base-dn
SSL_SUBJECT_BASE_DN
The base DN containing all valid subject DNs. If specified, only certificates asserting subject DNs beneath this base DN will be accepted.
By default, all DNs are accepted.
ssl-subject-username-attribute
SSL_SUBJECT_USERNAME_ATTRIBUTE
The LDAP attribute or attributes that may be used to represent a username within the subject DN of a user's X.509 certificate. If the least-significant attribute of the subject DN is not one of these attributes, the certificate will be rejected.
By default, any attribute is accepted.
The following options are also available, though it would be unusual to need to set them:
ssl-client-certificate-header
SSL_CLIENT_CERTIFICATE_HEADER
The name of the header to use to retrieve the URL-encoded client certificate from an HTTP request received from an SSL termination service providing SSL/TLS client authentication.
This should not normally need to be set, as the defaults of the keeper/guacamole-ssl-nginx
image match the default value of this option.
X-Client-Certificate
ssl-client-verified-header
SSL_CLIENT_VERIFIED_HEADER
The name of the header to use to retrieve the verification status of the certificate an HTTP request received from an SSL termination service providing SSL/TLS client authentication. This value of this header must be "SUCCESS" (all uppercase) if the certificate was successfully verified.
This should not normally need to be set, as the defaults of the keeper/guacamole-ssl-nginx
image match the default value of this option.
X-Client-Verified
ssl-max-domain-validity
SSL_MAX_DOMAIN_VALIDITY
The amount of time that the temporary, unique subdomain generated for SSL/TLS authentication may remain valid, in minutes.
This subdomain is used to ensure each SSL/TLS authentication attempt is fresh and does not potentially reuse a previous authentication attempt that was cached by the browser or OS. This interval must be long enough to allow for network delays in authenticating the user with the SSL termination service that enforces SSL/TLS client authentication, but short enough that an unused domain does not consume unnecessary server resources and cannot potentially be guessed while that subdomain is still valid. These subdomains are 128-bit secure random values.
This should not normally need to be set, though it’s conceivable that an administrator may wish to reduce this value.
5
ssl-max-token-validity
SSL_MAX_TOKEN_VALIDITY
The amount of time that a temporary authentication token for SSL/TLS authentication may remain valid, in minutes.
This token is used to represent the user's asserted identity after it has been verified by the SSL termination service. This interval must be long enough to allow for network delays in receiving the token, but short enough that unused tokens do not consume unnecessary server resources and cannot potentially be guessed while the token is still valid. These tokens are 256-bit secure random values.
This should not normally need to be set, though it’s conceivable that an administrator may wish to reduce this value.
5
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:
ADDITIONAL_PROXY_CONFIG
Arbitrary, additional NGINX configuration statements that should be included within the location
block that configures NGINX to proxy Guacamole.
CLIENT_CERTIFICATE_FILE
The certificate that NGINX should use to verify the certificate presented by the SSL/TLS client.
CLIENT_CRL_FILE
Controls the certificate revocation list (CRL) file that NGINX should use to check whether a client’s certificate has been revoked, as provided by NGINX ssl_crl
directive. This file must be in PEM format and may contain multiple CRLs. If omitted, no CRL file will be used.
This variable will be ignored unless CLIENT_CERTIFICATE_FILE
is specified.
If available, OCSP is often preferable to using a CRL file.
CLIENT_OCSP
Controls whether NGINX will use OCSP to check whether a client’s certificate has been revoked, as provided by NGINX ssl_ocsp
directive. Setting this variable to on
will use OCSP to check client certificates.
This variable will be ignored unless CLIENT_CERTIFICATE_FILE
is specified.
If enabled, RESOLVER
must also be specified.
off
RESOLVER
The DNS server that NGINX should use to resolve domain names. This is only required if OCSP is enabled.
SSL_VERIFY_CLIENT
Controls how and whether NGINX requires and verifies the certificate presented by the client (browser), as provided by NGINX ssl_verify_client
directive.
on
SSL_VERIFY_DEPTH
Controls how deep NGINX will follow through the client’s certificate chain when attempting to validate their certificate, as provided by NGINX ssl_verify_depth
directive.
1
Example PIV/CAC Configuration
The example docker-compose.yml
below uses the following placeholders:
Placeholder
Description
PasswordForPostgresAdmin
Some reasonable password to assign to PostgreSQL’s postgres
user - the typical root user of a PostgreSQL database. This account is used only if an administrator needs to manually connect to the database using a tool like psql
.
guacamole_db
The name of the Guacamole database within PostgreSQL. This value is used automatically by kcm-setup.run
and is documented as a reasonable value both within Keeper’s docs and upstream, so it is uncommon to use any other value here.
guacamole_user
The limited-privilege PostgreSQL user that Guacamole should use to execute queries against its database. This value is used automatically by kcm-setup.run
and is documented as a reasonable value both within Keeper’s docs and upstream, so it is uncommon to use any other value here.
PasswordForGuacamole
Some reasonable password to assign to the PostgreSQL user that Guacamole will use to authenticate with the database as the limited-privilege account guacamole_user
and execute queries.
ou=test department,o=u.s. government,c=us
The base DN of the subject DNs that should be accepted when presented via SSL/TLS client authentication (smart card authentication via browser).
kcm.example.net
The domain that users will visit with their browsers to use KCM.
/path/to/pki
The path on the Docker host containing the certificates and private keys used for SSL, including for client authentication.
/pki
The path within the Docker container that /path/to/pki
should be mounted to, so that its files may be accessed by NGINX.
cac-certificate.pem
The filename of the PEM-format certificate that NGINX should use to validate the certificates it receives from users when they attempt to authenticate with smart cards.
In practice, these values will vary, as will whether the user chooses to use MySQL or PostgreSQL. The example below was written using PostgreSQL.
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
:
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