Skip to main content

Run a Binary Authenticator

This walk-through will describe how to set up the Authenticator as a standalone binary.

Prerequisites​

  • If using a self-signed CA, ensure the CA cert is added to the operating system's trusted CA cert pool.

Obtaining the Binary​

For this integration, we will be deploying a binary version of the Corsha Authenticator. To get the Authenticator binary, contact your Corsha TPOC.

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. You may need to generate a new Authenticator Secret if your deployment takes over an hour.

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.

Configure the Authenticator​

For either platform, you will need to create a configuration file for the authenticator. The structure of this file can be found on the configuration page.

Sample Authenticator configuration file:

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

  authServerTrustedMachine:
    url: authserver-trusted.corsha.tld:443
  authServerUntrustedMachine:
    url: authserver-untrusted.corsha.tld:443

  loggingLevel: info
  writeTime: "2h"
  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:
  api:
    host: "localhost:8082"
    upstreamURL: "http://api:8080/"

CA Certs​

In some cases, the device running the Authenticator will need to extend trust to a Certificate Authority (CA) to connect to the Corsha Auth Server and Corsha Gatekeeper. For example, if the Corsha Gatekeeper deployed in your network is using self-signed certs, the Corsha Authenticator would need to extend trust to the self-signed CA.

In rare cases, Corsha will be using self-signed certs as well. If that is the case, we will provide a CA cert you will need to extend trust to.

Extending Trust to a CA is different depending on the OS the binary is being deployed on. Please extend trust to the required CA certs based on the OS's guidelines before proceeding to the next step.

Running the Authenticator Binary on Linux​

Once you have a config.yaml file, you only need to set the AUTHENTICATOR_SECRET environment variable. In this example, we read the authenticator-secret.txt into the AUTHENTICATOR_SECRET variable and run the binary.

AUTHENTICATOR_SECRET=$(<authenticator-secret.txt)
./corsha-authenticator --config=config.yaml

Running the Authenticator Binary on Windows​

Running the Authenticator on Windows is similar to on Linux. You need to set the AUTHENTICATOR_SECRET environment variable and invoke the command.

set AUTHENTICATOR_SECRET=<authenticator-secret.txt
.\corsha-authenticator.exe --config=config.yaml

Next Steps​

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