Environment Variables
Complete guide to configuring Aura Auth via environment variables
Aura Auth requires environment variables to store sensitive data related to OAuth credentials, secret keys for signing and encrypting JWTs and CSRF tokens, and salts for key derivation. Additionally, there are environment variables that control runtime behavior of the core auth module, such as trusted origins and debug mode.
All environment variables support multiple patterns that allow Aura Auth to load automatically without needing to set
them directly in the createAuth function.
When Aura Auth resolves a variable key, it checks the following names in order and uses the first non-empty value:
AURA_AUTH_{KEY}AURA_{KEY}AUTH_{KEY}{KEY}
For more details, read:
Environment variables override the corresponding configuration options in the createAuth function, including secret, and
trustedOrigins. If you set an environment variable for these options, it will take precedence over the value provided in
createAuth.
Secure Variables
| Name | Description |
|---|---|
SECRET | 32-byte secret for JWTs signing/encryption |
SALT | 32-byte salt for key derivation used for signing and encrypting JWTs and CSRF tokens |
Generating Secrets and Salts
# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
# Using OpenSSL
openssl rand -base64 32# Secret
AURA_AUTH_SECRET=
# Salt
AURA_AUTH_SALT=OAuth Variables
| Pattern | Description |
|---|---|
{PROVIDER}_CLIENT_ID | Client ID obtained from the OAuth app |
{PROVIDER}_CLIENT_SECRET | Client Secret obtained from the OAuth app |
# GitHub OAuth Credentials
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
# GitHub OAuth Credentials
AURA_GITHUB_CLIENT_ID=
AURA_GITHUB_CLIENT_SECRET=
# GitHub OAuth Credentials
AURA_AUTH_GITHUB_CLIENT_ID=
AURA_AUTH_GITHUB_CLIENT_SECRET=Some of the supported OAuth providers provided by Aura Auth include:
To see all the providers supported by Aura Auth, see OAuth Providers.
.env file. Always use a secret manager in production.Runtime Variables
These variables control runtime behavior of the core auth module.
| Key | Type | Description |
|---|---|---|
TRUSTED_ORIGINS | string | Comma/semicolon/newline-separated origins used as trusted origin allowlist. |
DEBUG | boolean | Enables debug logging when set to one of: 1, true, yes, on, debug. |
LOG_LEVEL | string | Logger level used by built-in logger (debug, info, warn, error). |
# Trusted origins (one or many)
AURA_AUTH_TRUSTED_ORIGINS="https://app.example.com,https://admin.example.com"
# Debug mode
AURA_AUTH_DEBUG="1"
# Built-in logger level
AURA_AUTH_LOG_LEVEL="info"PEM Variables
PEM variables are used to provide PEM-encoded keys and certificates for JWT signing and encryption. They can be set directly as environment variables, or loaded from files using the _PUBLIC_KEY and _PRIVATE_KEY suffix patterns.
The PEM variables supported by Aura Auth are related to the jwt.mode configuration option which defines if the JWT is signed, encrypted or both. When using PEM keys you can also control the algorithms used to import those keys via two configuration fields:
jwt.signingAlgorithm— algorithm used to import PEM-formatted signing keys (e.g.RS256,ES256).jwt.keyAlgorithm— algorithm used to import PEM-formatted encryption keys (e.g.RSA-OAEP,RSA-OAEP-256).
These can be set either in the createAuth session config or via environment variables SIGNING_ALGORITHM / SIGNING_ALG and ENCRYPTION_ALGORITHM / ENCRYPTION_ALG respectively. If not provided a sensible default is chosen (RS256 for signing imports, RSA-OAEP-256 for encryption imports).
| Pattern | Description |
|---|---|
PUBLIC_KEY | PEM-encoded public key used when jwt.mode is signed or encrypted (single key pair for one operation). |
PRIVATE_KEY | PEM-encoded private key used when jwt.mode is signed or encrypted (single key pair for one operation). |
{KEY}_PUBLIC_KEY | PEM-encoded public key for sealed JWT mode where {KEY} is SIGNING or ENCRYPTION (e.g. SIGNING_PUBLIC_KEY). |
{KEY}_PRIVATE_KEY | PEM-encoded private key for sealed JWT mode where {KEY} is SIGNING or ENCRYPTION (e.g. SIGNING_PRIVATE_KEY). |
The loading of PEM variables depends on the jwt.mode configuration option. If jwt.mode is set to signed or encrypted,
Aura Auth will look for the PUBLIC_KEY and PRIVATE_KEY environment variables. If jwt.mode is set to sealed, Aura Auth
will look for separate key pairs: SIGNING_PUBLIC_KEY/SIGNING_PRIVATE_KEY and
ENCRYPTION_PUBLIC_KEY/ENCRYPTION_PRIVATE_KEY. When importing PEM keys Aura Auth needs to know which algorithm to use for the
import step. Set SIGNING_ALGORITHM/SIGNING_ALG to control the signing key import (or use jwt.signingAlgorithm in the
session config). Set ENCRYPTION_ALGORITHM/ENCRYPTION_ALG to control the encryption key import (or use jwt.keyAlgorithm in
the session config). Environment variables take precedence over the session config.
Loading PEM variables from files
PEM variables for signed or encrypted JWT modes can be loaded from files using the PUBLIC_KEY and PRIVATE_KEY suffix patterns. For example, if you have a signing key pair stored in signing_public.pem and signing_private.pem, you can set the following environment variables:
AURA_AUTH_PUBLIC_KEY='-----BEGIN PUBLIC KEY----- abcd1234 -----END PUBLIC KEY-----'
AURA_AUTH_PRIVATE_KEY='-----BEGIN PRIVATE KEY----- abcd1234 -----END PRIVATE KEY-----'PEM variables for sealed JWT mode can also be loaded from files using the _PUBLIC_KEY and _PRIVATE_KEY variable names. For example, if you have a key pair stored in public.pem and private.pem, you can set the following environment variables:
# PEM variables for signing JWTs
AURA_AUTH_SIGNING_PUBLIC_KEY='-----BEGIN PUBLIC KEY----- abcd1234 -----END PUBLIC KEY-----'
AURA_AUTH_SIGNING_PRIVATE_KEY='-----BEGIN PRIVATE KEY----- abcd1234 -----END PRIVATE KEY-----'
# PEM variables for encrypting JWTs
AURA_AUTH_ENCRYPTION_PUBLIC_KEY='-----BEGIN PUBLIC KEY----- abcd1234 -----END PUBLIC KEY-----'
AURA_AUTH_ENCRYPTION_PRIVATE_KEY='-----BEGIN PRIVATE KEY----- abcd1234 -----END PRIVATE KEY-----'