Environment Variables

Aura Auth supports environment variables for configuring runtime behavior, OAuth providers, cryptographic secrets, and JWT keys. Environment variables allow sensitive values to remain outside the source code and make configuration easier to manage across development, staging, and production environments.

Environment variables take precedence over the corresponding options provided to createAuth. When both are configured, Aura Auth uses the environment variable's value.

Environment Variable Naming

Aura Auth supports multiple naming conventions for environment variables. This allows configuration values to be resolved automatically without explicitly passing them to createAuth.

When resolving a variable, Aura Auth checks the following names in order and uses the first non-undefined value:

AURA_AUTH_{NAME}
AURA_{NAME}
AUTH_{NAME}
{NAME}

For example, the BASE_URL variable can be configured using AURA_AUTH_BASE_URL, AURA_BASE_URL, AUTH_BASE_URL, or BASE_URL.

Runtime Variables

Runtime variables control the behavior of the Aura Auth instance.

Variable	Type	Description
`BASE_URL`	`string`	The application's base URL, used to resolve relative URLs for redirects and other URL-dependent operations.
`TRUSTED_PROXY_HEADERS`	`boolean`	Enables support for trusted proxy headers when set to `1`, `true`, `yes`, or `on`. Trusted origins must also be configured when this option is enabled.
`TRUSTED_ORIGINS`	`string`	A list of trusted origins separated by commas, semicolons, or newlines.
`DEBUG`	`boolean`	Enables debug logging when set to `1`, `true`, `yes`, `on`, or `debug`.
`LOG_LEVEL`	`string`	Sets the built-in logger's verbosity. Supported values are `debug`, `info`, `warn`, and `error`.

Example:

.env

# Base URL where the application is hosted
AURA_AUTH_BASE_URL="https://app.example.com"

# Enable trusted proxy headers
AURA_AUTH_TRUSTED_PROXY_HEADERS=true

# Configure one or more trusted origins
AURA_AUTH_TRUSTED_ORIGINS="https://app.example.com,https://admin.example.com"

# Enable debug logging
AURA_AUTH_DEBUG="1"

# Set the built-in logger's verbosity
AURA_AUTH_LOG_LEVEL="info"

OAuth Variables

OAuth provider credentials can be configured using environment variables rather than being passed directly to each provider configuration.

For a complete list of supported providers, see OAuth Providers.

Variable pattern	Type	Description
`{PROVIDER}_CLIENT_ID`	`string`	The client ID issued when registering an OAuth application with the provider.
`{PROVIDER}_CLIENT_SECRET`	`string`	The client secret issued when registering an OAuth application with the provider.

For example, GitHub credentials can be configured as follows:

.env

# GitHub OAuth credentials
AURA_AUTH_GITHUB_CLIENT_ID=""
AURA_AUTH_GITHUB_CLIENT_SECRET=""

Keep client secrets private. Never commit populated environment files or expose server-side credentials through public client-side variables.

Cryptographic Secrets

Aura Auth uses cryptographic secrets for JWT signing, encryption, and key derivation.

Variable	Type	Description
`SECRET`	`string` or PEM-encoded key material	The secret used for cryptographic operations, depending on the configured JWT mode.
`SALT`	`string`	A salt used during key derivation for cryptographic operations, including signing, encryption, and CSRF token protection.

Example:

.env

# Secret used for cryptographic operations
AURA_AUTH_SECRET=""

# Salt used for key derivation
AURA_AUTH_SALT=""

Configure strong, unpredictable values and keep them private. Follow the Security Model for additional guidance on cryptographic configuration.

PEM-Encoded Keys

Aura Auth supports PEM-encoded keys for JWT signing and encryption. These keys can be supplied through environment variables and are interpreted according to the configured jwt.mode.

When importing PEM keys, Aura Auth can use the following configuration options:

jwt.signingAlgorithm: The algorithm used to import signing keys, such as RS256 or ES256.
jwt.keyAlgorithm: The algorithm used to import encryption keys, such as RSA-OAEP or RSA-OAEP-256.

These options can be configured through createAuth or their corresponding environment variables:

SIGNING_ALGORITHM or SIGNING_ALG for signing keys.
ENCRYPTION_ALGORITHM or ENCRYPTION_ALG for encryption keys.

If no algorithm is specified, Aura Auth uses the appropriate default for the configured operation: RS256 for signing-key imports and RSA-OAEP-256 for encryption-key imports.

Variable pattern	Description
`PUBLIC_KEY`	PEM-encoded public key used in `signed` or `encrypted` JWT modes.
`PRIVATE_KEY`	PEM-encoded private key used in `signed` or `encrypted` JWT modes.
`SIGNING_PUBLIC_KEY`	PEM-encoded public key used for signing in `sealed` JWT mode.
`SIGNING_PRIVATE_KEY`	PEM-encoded private key used for signing in `sealed` JWT mode.
`ENCRYPTION_PUBLIC_KEY`	PEM-encoded public key used for encryption in `sealed` JWT mode.
`ENCRYPTION_PRIVATE_KEY`	PEM-encoded private key used for encryption in `sealed` JWT mode.

The required PEM variables depend on jwt.mode.

For signed or encrypted modes, Aura Auth uses PUBLIC_KEY and PRIVATE_KEY.
For sealed mode, Aura Auth uses separate signing and encryption key pairs.

Environment variables take precedence over the corresponding JWT configuration options.

Loading PEM Keys from Environment Variables

For signed or encrypted JWT modes, configure the key pair using PUBLIC_KEY and PRIVATE_KEY:

.env

AURA_AUTH_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----
REPLACE_WITH_PUBLIC_KEY_CONTENT
-----END PUBLIC KEY-----'

AURA_AUTH_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----
REPLACE_WITH_PRIVATE_KEY_CONTENT
-----END PRIVATE KEY-----'

For sealed JWT mode, configure separate key pairs for signing and encryption:

.env

# PEM-encoded signing keys
AURA_AUTH_SIGNING_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----
REPLACE_WITH_SIGNING_PUBLIC_KEY_CONTENT
-----END PUBLIC KEY-----'

AURA_AUTH_SIGNING_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----
REPLACE_WITH_SIGNING_PRIVATE_KEY_CONTENT
-----END PRIVATE KEY-----'

# PEM-encoded encryption keys
AURA_AUTH_ENCRYPTION_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----
REPLACE_WITH_ENCRYPTION_PUBLIC_KEY_CONTENT
-----END PUBLIC KEY-----'

AURA_AUTH_ENCRYPTION_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----
REPLACE_WITH_ENCRYPTION_PRIVATE_KEY_CONTENT
-----END PRIVATE KEY-----'

Replace the placeholder content with valid PEM-encoded keys. Never commit private keys to version control.

Environment Variables

Environment Variable NamingCopy Anchor Link

Runtime VariablesCopy Anchor Link

OAuth VariablesCopy Anchor Link

Cryptographic SecretsCopy Anchor Link

PEM-Encoded KeysCopy Anchor Link

Loading PEM Keys from Environment VariablesCopy Anchor Link

On this page

Environment Variable Naming

Runtime Variables

OAuth Variables

Cryptographic Secrets

PEM-Encoded Keys

Loading PEM Keys from Environment Variables