Configuration

How the environment is read#

Access reads its environment once, at start, in src/runtime/env.ts, which is the only module that reads process.env. Every problem is collected and reported in one message that starts with the environment is invalid: and names each variable, so you fix them all before the next start (§4.4).

Development values are in packages/access/.env.example. Never copy them into production: a production start refuses every example value and every secret made of one repeated character (§4.1).

Variables#

"Production" says whether ACCESS_ENVIRONMENT=production refuses to start without the variable.

Listener and public URLs#

Database and shared store#

Credentials#

In production the five single-token variables (ACCESS_ADMIN_TOKEN, ACCESS_PREVIOUS_ADMIN_TOKEN, ACCESS_DECISION_TOKEN, ACCESS_PREVIOUS_DECISION_TOKEN, ACCESS_METRICS_TOKEN) must hold at least 16 bytes, counted as written (§4.1). The tokens inside the two JSON maps must be at least 16 characters in every environment.

In production the credentials of the access context are credentials of the deployment: each of them must hold at least 32 bytes, counted as decoded, and none of them may be a value the repository publishes (§4.1).

Secrets and keys#

ACCESS_STATE_SECRET and ACCESS_SECRET_ENCRYPTION_KEY are checked wherever they are set, not only in production. Their length is counted as decoded: an even-length hex string counts half its characters (64 hex characters are 32 bytes), a base64 string counts its decoded bytes (44 base64 characters are 32 bytes), and anything else counts its UTF-8 bytes. Generate one with openssl rand -base64 32.

Deadlines and logging#

Integer variables must be whole numbers; an empty or non-numeric value stops the service.

Secrets in files#

Set ACCESS_<NAME>_FILE to a path, and Access reads the value of ACCESS_<NAME> from that file (§4.5). These variables accept a file:

ACCESS_ADMIN_TOKENS has no file form in this release: set it in the environment.

ACCESS_SIGNING_KEY_FILE=/run/secrets/access-signing-key.pem
ACCESS_STATE_SECRET_FILE=/run/secrets/access-state-secret

Surrounding whitespace, including the trailing newline, is trimmed. The start fails with ACCESS_<NAME> and ACCESS_<NAME>_FILE are both set when you set both forms, and with ACCESS_<NAME>_FILE names a file that cannot be read when the file is missing or unreadable.

Administration credentials#

ACCESS_ADMIN_TOKENS is a JSON object. Each key is a bearer token; each value is its scope (§4.6, §10.1):

{
  "the-token-of-the-operator-of-the-platform": null,
  "the-token-of-the-operator-of-acme": {"tenant": "acme", "operator": "alice"}
}

Each token is at least 16 characters. A value that is not a JSON object, a scope that is neither null nor an object, an empty tenant or a non-string operator stops the service at start. ACCESS_ADMIN_TOKEN and ACCESS_ADMIN_TOKENS may be set together.

Access context credentials#

ACCESS_CONTEXT_TOKENS is a JSON object. Each key is a bearer token; each value is the list of tenant ids (UUIDs) that token may ask about, or null for a platform credential (§9.2):

{"the-token-of-the-backend-of-acme": ["22222222-2222-4222-8222-222222222222"]}

Each token is at least 16 characters. A value that is not a JSON object, or a scope that is neither null nor a list of strings, stops the service at start.

In production each token is at least 32 bytes, counted as decoded, and none of them may be a value the repository publishes (§4.1): the credential of the contract is a credential of the platform, and a published one lets anybody read the context of the principals.

A scope of null is a credential that may ask about every tenant of the platform. It is a choice of the deployment and never the default: the deployment says it out loud with ACCESS_CONTEXT_ALLOW_PLATFORM_TOKEN=true, and the service refuses to start without it.

Files the service reads#

Access reads no other configuration file: tenants, principals, groups, roles and grants live in the database and change only through the administration (§10).

Variables of the scripts and tests#

These variables are read by operator scripts and test suites, never by the service.