PIV/CAC/Smart cards
Login to Keeper Connection Manager with a PIV/CAC device
![](https://docs.keeper.io/~gitbook/image?url=https%3A%2F%2F3357255970-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fb7weUpu7VBcMnESSH8vG%252Fuploads%252FAv3ZfBzp49B1xqpcxP7z%252Fsmart-card%25402x.png%3Falt%3Dmedia%26token%3D0f341a4d-e836-4bc1-98a1-c332debcdf76&width=768&dpr=4&quality=100&sign=316491fb&sv=1)
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):
Property | Environment Variable | Description |
---|---|---|
|
| REQUIRED. A wildcard URI that points to this Guacamole instance and requests SSL/TLS client authentication. |
|
| REQUIRED. A non-wildcard URI that points to this Guacamole instance and DOES NOT request SSL/TLS client authentication. |
|
| 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. |
|
| 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:
Property | Environment Variable | Description | Default Value |
---|---|---|---|
|
| 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 |
|
|
| 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 |
|
|
| 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 |
|
| 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:
Environmental Variable | Description | Default Value |
---|---|---|
| Arbitrary, additional NGINX configuration statements that should be included within the |
|
| The certificate that NGINX should use to verify the certificate presented by the SSL/TLS client. |
|
| 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 This variable will be ignored unless If available, OCSP is often preferable to using a CRL file. |
|
| Controls whether NGINX will use OCSP to check whether a client’s certificate has been revoked, as provided by NGINX This variable will be ignored unless If enabled, | off |
| The DNS server that NGINX should use to resolve domain names. This is only required if OCSP is enabled. |
|
| Controls how and whether NGINX requires and verifies the certificate presented by the client (browser), as provided by NGINX | on |
| Controls how deep NGINX will follow through the client’s certificate chain when attempting to validate their certificate, as provided by NGINX | 1 |
Example PIV/CAC Configuration
The example docker-compose.yml
below uses the following placeholders:
Placeholder | Description |
| Some reasonable password to assign to PostgreSQL’s |
| The name of the Guacamole database within PostgreSQL. This value is used automatically by |
| The limited-privilege PostgreSQL user that Guacamole should use to execute queries against its database. This value is used automatically by |
| Some reasonable password to assign to the PostgreSQL user that Guacamole will use to authenticate with the database as the limited-privilege account |
| The base DN of the subject DNs that should be accepted when presented via SSL/TLS client authentication (smart card authentication via browser). |
| The domain that users will visit with their browsers to use KCM. |
| The path on the Docker host containing the certificates and private keys used for SSL, including for client authentication. |
| The path within the Docker container that |
| 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:
![](https://docs.keeper.io/~gitbook/image?url=https%3A%2F%2F3357255970-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fb7weUpu7VBcMnESSH8vG%252Fuploads%252Fr9qGCyZ25me4jGmzSi0J%252Fimage.png%3Falt%3Dmedia%26token%3D89509d97-41eb-4550-be74-6d0eeac7f4c7&width=768&dpr=4&quality=100&sign=cbfbccbe&sv=1)
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