Skip to main content

Run an Authenticator via Docker

This walk-through will describe how to set up and run the Corsha Authenticator in Docker using Docker Compose.

Prerequisites​

There are a few prerequisites to check before deploying the Corsha Authenticator.

  • It is strongly recommended that you configure your Corsha-Protected API before deploying Authenticators. Deployment documentation is available for the Corsha Gatekeeper or as a Kong Gateway Plug-in.

  • Access to the Console is required to deploy a Primer.

Running in Docker​

In this integration guide, we use a docker-compose.yaml file to stand up a Corsha Authenticator to authenticate a service's downstream client.

You will need to log into the Corsha Docker repository to pull Corsha images.

docker login corsha-docker.jfrog.io --username <username>
tip

Contact Corsha if you do not have credentials to access our Corsha Docker repository running in Artifactory.

Setup the Local Filesystem​

Let's create a local directory on your client machine to store the Corsha Authenticator's configuration and its persistent authentication stream. The directory layout below is used in the subsequent sections.

corsha-authenticator/
├── docker-compose.yaml # Defines the Corsha Authenticator's Docker environment.
├── config              # Configuration files for the Corsha Authenticator
    └── config.yaml     # The Corsha Authenticator's application configuration

Create and Populate the Authenticator's Configuration Files​

The following steps guide you through configuring your Corsha Authenticator to run via Docker.

Fetch an Authenticator Secret to seed your Authenticator​

Each Authenticator instance has a unique Authenticator Secret that is used to seed the singular client it represents and start building a dynamic identity.

To generate an Authenticator Secret, login to the Console and create a new Machine (see Creating Machines with Authenticators). At the end of the workflow you will be given a one-time-use, short-lived Authenticator Secret. An Authenticator should be deployed shortly after generating the Authenticator Secret, before the Authenticator Secret expires.

note

If you need to create Authenticator Secrets programmatically or in bulk, you can use the Corsha Primer binary. Follow the Primer binary guide to generate Authenticator Secrets using the Primer binary instead of using the Console.

Authenticator's Docker Compose File​

Let's create a docker-compose.yaml to configure our Authenticator's Docker environment. To get the Corsha Authenticator Docker image, please contact your Corsha TPOC.

version: "3.9"
services:
    authenticator:
        image: corsha-docker.jfrog.io/corsha-authenticator:<version> # Fill in with the version provided by your TPOC
        restart: always # the Authenticator will start on system startup
        ports:
            - "127.0.0.1:8082:8082"
            - "127.0.0.1:8083:8083"
        volumes:
            - ./config:/config
            - ./authenticator-data:/opt/corsha/authenticator
            # Trusted CAs can be configured for TLS validation as follows but are not required for this demo
            # - ./ca.crt:/etc/pki/ca-trust/source/anchors/ca-bundle.trust.pem
        command: --config=/config/config.yaml
        environment:
            - AUTHENTICATOR_SECRET=<fill in> # generated by running the Corsha Primer
Authenticator's Application Configuration​

Next, we will create config/config.yaml file (details about this file can be found here)

authenticator:
  # listen address for the authenticator service
  listen: 0.0.0.0:8083

  authServerTrustedMachine:
    url: auth-server-trusted.corsha.tld:443 # provided in your Corsha deployment guide
  authServerUntrustedMachine:
    url: auth-server-untrusted.corsha.tld:443 # provided in your Corsha deployment guide

  loggingLevel: info
  writeTime: "2h" # how frequently the Authenticator performs a Corsha `crypto beat`
  streamsDir: "/opt/corsha/authenticator"

# listen address for the proxy service, omit to disable the proxy service
listen: 0.0.0.0:8082

# the services to proxy to, omit if you have disabled the proxy service
proxies:
  exampleProxy:
    host: "localhost:8082" # host address to proxy downstream client requests
    upstreamURL: "http://api:8080/" # host address of the upstream Gatekeeper service

Start the Corsha Authenticator​

Now that we've created and populated the Corsha Authenticator's configuration, we are ready to start the application. Open a terminal in the Authenticator directory containing the docker-compose.yaml file and run the following commands (as admin if needed):

mkdir authenticator-data
docker compose up
note

The Authenticator runs in a rootless environment. As a result, the Authenticator's authenticator-data directory, which contains its authentication stream, is stored on the local filesystem and must be writeable by the docker container, i.e., a Linux user would use chown 10001:10001 authenticator-data if the authenticator-data folder is in a protected directory.

Next Steps​

Once you have successfully deployed the Authenticator, you can use it to get Corsha Creds. Check out Using the Authenticator