This is an example orchestration for deploying STIG Manager with support for user authentication incorporating the U.S. Department of Defense Common Access Card (CAC). The example supports connections to and from localhost only and is NOT intended for production use.
nginxexecutes a TLS stack with client certificate verification and listens on a front channel HTTPS port.nginxproxies traffic tostigmanandkeycloakwhich are listening on back channel HTTP ports.stigmancommunicates withkeycloakandmysqlusing their back channel ports.browser with CACconnects tonginxon the front channel HTTPS port and requests resources fromstigmanandkeycloak.
This general architecture can be implemented with a wide range of technologies, from bare-metal deployments to complex containerized orchestrations. The example uses a simple docker-compose orchestration.
- Recent Windows, Linux, or macOS
- CAC reader configured for your OS
- docker
- docker-compose
- Chrome, Edge, or Firefox browser
The example uses a server certificate issued to the host localhost and signed by a CA named demoCA. For the example to work, you must (temporarily) import trust in your browser for the demoCA certificate, found at certs/ca/demoCA.crt.
How you do this varies across operating systems and browsers. For Windows, you import the certificate into "Trusted Root Certification Authorities". You should remove the certificate when finished running the orchestrations.
You have two options:
-
If you have
gitinstalled, clone this repository. Then change to the newly created directory. -
Download a ZIP of this repository using the green Code button above. Extract the archive to an appropriate directory and change to the newly extracted directory.
docker-compose up
The orchestration's container images will be downloaded if they are not already available on your system. How long this takes depends on your connection speed and registry performance. Once all container images are available, the orchestration will start.
The orchestration has successfully bootstrapped when you see a started message like this from the STIG Manager API:
{"date":"2022-10-01T18:04:26.734Z","level":3,"component":"index","type":"started","data":{"durationS":21.180474449,"port":54000,"api":"/api","client":"/","documentation":"/docs"}}
Once STIG Manager has started, navigate your browser to:
https://localhost/stigman/
- You are prompted by your browser to select a certificate from your CAC. You may be asked to enter the PIN for your CAC if you have not done so previously.
- The STIG Manager Web App begins to load and redirects your browser to Keycloak for authentication.
- You are prompted by Keycloak to start a Single-Sign On session using your certificate's Common Name (CN) field as the username.
- The STIG Manager Web App finishes loading and uses the OAuth2 token generated by Keycloak to make requests to the STIG Manager API on your behalf.
You can access the Keycloak admin pages by navigating to:
https://localhost/kc/admin
Login with the credentials admin/Pa55w0rd
Type Ctrl-C to end the orchestration, followed by:
docker-compose down
After using Chrome to HTTPS connect to
https://localhost, you may find Chrome will no longer make HTTP connections tohttp://localhost:[ANY_PORT]. Once you're finished with the example, see this note for how to remedy this.
Client certificate authentication is required for access to the Keycloak authorization endpoint. Client certificate authentication is optional for API endpoints since access to the API is controlled by OAuth2 tokens.
Nginx requires a PEM file containing certificates for the DoD Root CA and Intermediate CAs used to sign CAC certificates.
The example provides the file
certs/dod/Certificates_PKCS7_v5.9_DoD.pem.pemfor this purpose, which is mounted to the Nginx container at/etc/nginx/dod-certs.pem
You can review the file nginx/nginx.conf.
The environment variables STIGMAN_OIDC_PROVIDER and STIGMAN_CLIENT_OIDC_PROVIDER are set to the Keycloak back channel and front channel realm URLs, respectively.
The Keycloak Guides provide documentation on configuring Keycloak for many deployment scenarios including this example orchestration.
During startup, Keycloak imports a realm configuration file which includes the X.509 Browser Authentication Flow to support X.509 certificate mapping. This Keycloak documentation describes how to configure authentication flows to include X.509 client certificates.
The example uses a custom provider modified from this project that extends the built-in X.509 authenticator. The custom provider will create a new user account if a certificate cannot be mapped to an existing account. The provider file is kc/create-x509-user.jar which is mounted to the Keycloak container at /opt/keycloak/providers.
Keycloak behind Nginx requires a keystore that contains certificates for the DoD Root CA and Intermediate CAs used to sign CAC certificates.
The example provides the file
certs/dod/Certificates_PKCS7_v5.9_DoD.pem.p12for this purpose, which is mounted to the Keycloak container at/tmp/truststore.p12
chrome://net-internals/#hsts - Delete domain security policies
chrome://settings/clearBrowserData - Cached images and files
The demo-auth-no-CAC branch of this repo demonstrates a configuration that does not require CAC or mutual TLS, and uses a Keycloak container with built-in usernames and passwords available here: https://hub.docker.com/r/nuwcdivnpt/stig-manager-auth
The following repos are not maintained or tested by the STIG Manager team, but offer alternate STIG Manager deployment configurations that have been shared by the community:
- @jeremyatourville/stigman-orchestration - A docker-compose orchestration that uses a reverse proxy and username/password authentication.
If you have a solution you'd like to share, you can open a pull request to add it to this list!