Skip to main content

Authenticator

The Authenticator establishes and maintains dynamic machine identities for use in proxy mode. In firewall mode, machines are passively discovered by Gatekeepers observing network traffic, and no Authenticators are required.

Machine Identity in Different Modes​

Firewall Mode: Machines are discovered and identified by Gatekeepers observing network traffic. No Authenticators need to be deployed to machines. Connection rules define how machines can communicate, and Gatekeepers block unauthorized connections based on the configured enforcement mode.

Proxy Mode: Machines deploy Authenticators that:

  1. Generate cryptographic "beats" on configurable intervals
  2. Send beats to the DLN to establish and maintain dynamic identity streams
  3. Generate one-time MFA credentials for API requests

The Authenticator provides the machine's dynamic identity for MFA validation by Gatekeepers.

How the Authenticator Works (Proxy Mode)​

The Authenticator is a lightweight component deployed alongside API clients to generate and inject MFA credentials into outgoing requests. It acts as either a service or a proxy to add authentication to API calls.

Dynamic Identity Streams​

Authenticators establish and maintain continuous identity streams through the DLN:

  1. Beat Generation: On configurable intervals (e.g., every 5 seconds), the Authenticator generates cryptographic "beats"
  2. DLN Registration: Beats are sent to the DLN to prove the machine is active and trusted
  3. Identity Validation: The DLN validates each beat and maintains the machine's identity stream
  4. Credential Generation: When an API request is made, the Authenticator generates a one-time MFA credential
  5. Credential Injection: The MFA credential is added to the request (HTTP header or protocol-specific field)

Integration with Proxy Mode Gatekeepers​

Authenticators work in conjunction with Corsha Gatekeepers deployed in proxy mode:

Client-Side (Authenticator):

  • Deployed alongside API clients (as sidecar container, Docker image, or Helm chart)
  • Generates beats continuously to maintain identity stream
  • Creates one-time MFA credentials for each API request
  • Injects credentials into requests automatically (as service or proxy)

Server-Side (Gatekeeper):

  • Deployed in front of protected API services
  • Extracts MFA credentials from incoming requests
  • Validates credentials against the DLN in real-time
  • Forwards only authenticated requests to backend services
  • Rejects requests with invalid, expired, or reused credentials

Authentication Flow:

API Client → Authenticator → Gatekeeper → Protected API Service
           ↓                  ↓
        Generates          Validates
        MFA Cred          against DLN

Deployment Options​

The Authenticator can be provided as a Docker image or a Helm Chart. The Authenticator needs to be deployed local to your client application. For example, in a Helm deployment, your Authenticator would be stored in the same pod as your API client.

Priming an Authenticator​

An Authenticator requires a time-limited, unique Authenticator Secret to register with the Corsha DLN. The Primer is a simple service that can be used to generate these Authenticator Secrets. The Primer requires a Primer Secret that you generate in the Console.

Using the Authenticator​

Once an Authenticator has been deployed, it can distribute Corsha Creds in two different ways: as a service that returns Corsha Creds over a simple API, or a proxy that adds a Corsha Cred to the headers of a Corsha Enabled API request.

Using the Authenticator as a Service​

An Authenticator can fetch a Corsha Cred to use with the protected API service. In your client code you will do the following:

  1. Make a POST to /api/v1/cred and extract the corsha_cred value from the returned JSON
  2. Make a request to the Corsha Protected API Service with the cred set in the X-Corsha-Cred HTTP header

Here is example code to demonstrate using the Authenticator service to get and use a Corsha Cred:

# Fetch the CRED from the service
CRED=$(curl http://localhost:8083/api/v1/cred -X POST | jq -r .corsha_cred)

# This request will succeed because of the X-Corsha-Cred
curl -H "X-Corsha-Cred: $CRED" https://<Corsha-Protected-API>

# This second request with the same MFA Cred will fail because creds are one time use
curl -H "X-Corsha-Cred: $CRED" https://<Corsha-Protected-API>

Using the Authenticator as a Proxy Service​

The Authenticator also serves as an Egress proxy. This proxy will add the X-Corsha-Cred to API Client request headers automatically.

To demonstrate how to use the proxy, here is a simple Bash script:

# This request will fail because the api is MFA protected and expects a valid MFA credential as an HTTP header
curl https://<Corsha-Protected-API>

# This request will be proxied to the api service with the X-Corsha-Cred header
curl https://<Corsha-Authenticator-Sidecar>