Skip to main content

Authentication

Authentication restricts access to resources in a multi-tenant environment.

Machine to Machine​

Machine to machine authentication uses the AUTH_API_KEY environment variable to enable internal communication between Orchestrate microservices. All running microservices from the same Orchestrate instance must be given the same key when they are started or restarted.

info

Ensure the value of AUTH_API_KEY is not inferable by the client. We recommend generating a strong secret.

Ensure the value of the secret cannot leak and is not used for client to server authentication. Having the AUTH_API_KEY value enables full access to the entire data stack in the Orchestrate instance.

Client to Server​

Client to server authentication is based on OpenID-Connect. Three parties are involved:

  • Client - User or external app sending a request to Orchestrate.

  • Server - Orchestrate microservice receiving a request.

  • Identity provider - Third-party compatible with OpenID-Connect. The identity provider generates and signs the JWT token. For example, Auth0.

Authentication occurs in multiple steps:

  1. The client authenticates with the identity provider.
  2. The client request an access token from the identity provider.
  3. The client passes the access token as a JWT bearer token to Orchestrate in the authorization request header. The JWT token is checked and access to the authenticated tenant is allowed.
  4. The same JWT can be used in multiple requests until the token expires.
info

The Prometheus HTTP endpoints for metrics (by default, on port 8082) are not protected by authentication. To hide the metrics endpoint externally, do not expose the endpoint when configuring the ingress to your Kubernetes cluster. The Orchestrate Helm charts have an example.

Custom Claims Format​

An example JWT for Orchestrate multi-tenancy is displayed below.

Multi-tenancy

The custom part of the claim is the namespace defined by the AUTH_JWT_ORCHESTRATE_CLAIMS environment variable.

The tenant_id and username are specified only in the JWT and are set by the identity provider (for example, Auth0). When you enable multi-tenancy, all requests require an authorization token so that resources (accounts, chains, and transactions) are associated with a tenant ID or username on creation. Authenticated requests only return resources linked to the tenant ID or username. You can use define access using nested tenants to create more advanced levels of authorization.

Configure authentication by setting the relevant environment variables.