Protocol API Reference

Configuring Heimdall

Heimdall is fully configured through environment variables, enabling seamless setup for local development, continuous integration (CI) pipelines, and production deployments. This approach ensures portability, simplifies configuration management, and eliminates the complexity of database-stored configuration state found in comparable solutions. By using environment variables, Heimdall reduces setup overhead, enhances reproducibility, and minimizes the risk of configuration drift across environments.

This guide outlines the required and optional environment variables, their default values, and best practices for configuring Heimdall for your application.

Ensure you have a running MongoDB instance and generated RSA keys before configuring Heimdall. See the Quickstart for initial setup or Running Locally for detailed instructions.

Environment Variables

Heimdall’s configuration is defined in an .env file or through environment variables set in your deployment environment. Below is a comprehensive list of variables, categorized by their purpose.

Required Variables

These variables must be set for Heimdall to function correctly:

  • MONGODB_URI: The connection string for your MongoDB instance.

    • Example: mongodb://localhost:27017
    • Description: Specifies the MongoDB server address and port. Ensure the MongoDB instance is accessible from the Heimdall container.

  • JWT_SECRET: A secure secret used for signing JSON Web Tokens (JWTs).

    • Example: your_jwt_secret_here
    • Description: Must be a strong, unique value to ensure token security. Generate a random string (e.g., using a password manager or cryptographic tool).

  • RSA_PRIVATE_KEY_BASE64: The base64-encoded RSA private key in PEM format.

    • Example: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0t...
    • Description: Used for signing tokens and secure operations. Must be paired with RSA_PUBLIC_KEY_BASE64.

  • RSA_PUBLIC_KEY_BASE64: The base64-encoded RSA public key in PEM format.

    • Example: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0...
    • Description: Used for verifying signatures. Must correspond to RSA_PRIVATE_KEY_BASE64.

Optional Variables

These variables have default values but can be customized as needed:

  • DATABASE_NAME: The name of the MongoDB database.

    • Default: oidc
    • Example: heimdall_db
    • Description: Specifies the database within MongoDB for Heimdall’s data.

  • BASE_URL: The base URL for Heimdall’s endpoints.

    • Default: https://oidc.example.com
    • Example: https://auth.yourdomain.com
    • Description: Defines the root URL for all OIDC endpoints unless overridden.

  • ISSUER: The OIDC issuer identifier.

    • Default: ${BASE_URL}
    • Example: https://auth.yourdomain.com
    • Description: Identifies the Heimdall server in OIDC flows.

  • JWKS_URI: The JSON Web Key Set endpoint.

    • Default: ${BASE_URL}/jwks
    • Example: https://auth.yourdomain.com/jwks
    • Description: Exposes public keys for token verification.

  • AUTHORIZATION_ENDPOINT: The OIDC authorization endpoint.

    • Default: ${BASE_URL}/authorize
    • Example: https://auth.yourdomain.com/authorize
    • Description: Handles authorization requests.

  • TOKEN_ENDPOINT: The OIDC token endpoint.

    • Default: ${BASE_URL}/token
    • Example: https://auth.yourdomain.com/token
    • Description: Issues access and refresh tokens.

  • USERINFO_ENDPOINT: The OIDC userinfo endpoint.

    • Default: ${BASE_URL}/userinfo
    • Example: https://auth.yourdomain.com/userinfo
    • Description: Provides user profile information.

  • END_SESSION_ENDPOINT: The OIDC end-session endpoint.

    • Default: ${BASE_URL}/endsession
    • Example: https://auth.yourdomain.com/endsession
    • Description: Handles logout requests.

  • INTROSPECTION_ENDPOINT: The OIDC token introspection endpoint.

    • Default: ${BASE_URL}/introspect
    • Example: https://auth.yourdomain.com/introspect
    • Description: Validates token status.

  • REVOCATION_ENDPOINT: The OIDC token revocation endpoint.

    • Default: ${BASE_URL}/revoke
    • Example: https://auth.yourdomain.com/revoke
    • Description: Revokes tokens.

  • REGISTRATION_ENDPOINT: The OIDC client registration endpoint.

    • Default: ${BASE_URL}/register
    • Example: https://auth.yourdomain.com/register
    • Description: Registers new clients dynamically.

  • ACCESS_TOKEN_EXPIRY: Duration (in seconds) for access token validity.

    • Default: 3600 (1 hour)
    • Example: 7200 (2 hours)
    • Description: Controls how long access tokens remain valid.

  • REFRESH_TOKEN_EXPIRY: Duration (in seconds) for refresh token validity.

    • Default: 2592000 (30 days)
    • Example: 604800 (7 days)
    • Description: Sets the lifespan of refresh tokens.

  • AUTH_CODE_EXPIRY: Duration (in seconds) for authorization code validity.

    • Default: 600 (10 minutes)
    • Example: 300 (5 minutes)
    • Description: Defines the validity period for authorization codes.

  • PUBLIC_URL: The public-facing URL for Heimdall.

    • Default: None
    • Example: https://auth.yourdomain.com
    • Description: Used for external access if different from BASE_URL.

  • PORT: The port on which Heimdall runs.

    • Default: 8080
    • Example: 3000
    • Description: Specifies the HTTP server port.

  • APP_NAME: The name of the Heimdall instance.

    • Default: Heimdall
    • Example: YourApp Auth
    • Description: Used in user-facing interfaces and emails.

  • LOGO_SVG_BASE64: Base64-encoded SVG logo.

    • Default: None
    • Example: PHN2ZyB4bWxucz0...
    • Description: Custom logo for user interfaces (SVG format).

  • LOGO_PNG_BASE64: Base64-encoded PNG logo.

    • Default: None
    • Example: iVBORw0KGgo...
    • Description: Custom logo for user interfaces (PNG format).

Email Configuration

Email settings are optional and used for sending verification emails and notifications:

  • SMTP_HOST: The SMTP server host.

    • Default: localhost
    • Example: smtp.gmail.com
    • Description: Specifies the SMTP server for sending emails.

  • SMTP_PORT: The SMTP server port.

    • Default: 587
    • Example: 465
    • Description: Port for SMTP communication.

  • SMTP_USERNAME: The SMTP server username.

    • Default: Empty
    • Example: user@yourdomain.com
    • Description: Username for SMTP authentication.

  • SMTP_PASSWORD: The SMTP server password.

    • Default: Empty
    • Example: your_smtp_password
    • Description: Password for SMTP authentication.

  • SMTP_FROM_EMAIL: The sender email address.

    • Default: noreply@proton.is
    • Example: noreply@yourdomain.com
    • Description: Email address used as the sender.

  • SMTP_FROM_NAME: The sender display name.

    • Default: Heimdall
    • Example: YourApp Support
    • Description: Name displayed in email sender field.

  • VERIFICATION_URL_TEMPLATE: Template for email verification URLs.

    • Default: ${BASE_URL}/account/verify/email?token={token}&email={email}
    • Example: https://auth.yourdomain.com/verify?token={token}&email={email}
    • Description: URL template for email verification links.

Client Configuration

Heimdall supports multiple OIDC clients, each configured with a unique index (e.g., OIDC_CLIENT_ID_1, OIDC_CLIENT_ID_2). For each client, set the following variables:

  • OIDC_CLIENT_ID_(N): The client identifier.

    • Example: my_client_1
    • Description: Unique ID for the client.

  • OIDC_CLIENT_(N)_SECRET: The client secret (optional for public clients).

    • Example: client1_secret_value
    • Description: Secret for client authentication (leave empty for public clients).

  • OIDC_CLIENT_(N)_REDIRECT_URIS: Comma-separated list of redirect URIs.

    • Example: https://app1.example.com/callback,https://app1.example.com/cb
    • Description: Allowed URIs for redirect after authentication.

  • OIDC_CLIENT_(N)_SCOPES: Comma-separated list of supported scopes.

    • Default: openid
    • Example: openid,profile,email
    • Description: Scopes the client can request. Supported scopes: openid, profile, email, address, phone.

  • OIDC_CLIENT_(N)_GRANT_TYPES: Comma-separated list of grant types.

    • Default: authorization_code
    • Example: authorization_code,refresh_token
    • Description: Grant types the client can use. Supported: authorization_code, refresh_token, client_credentials.

  • OIDC_CLIENT_(N)_RESPONSE_TYPES: Comma-separated list of response types.

    • Default: code
    • Example: code,form_post
    • Description: Response types the client can request. Supported: code, token, id_token, id_token token, form_post.

  • OIDC_CLIENT_(N)_TOKEN_AUTH_METHOD: Token endpoint authentication method.

    • Default: client_secret_basic
    • Example: none
    • Description: Authentication method for the token endpoint. Supported: client_secret_basic, client_secret_post, none.

Example .env File

Below is an example .env file demonstrating a complete configuration with two clients:

Example .env File

# Required Variables
MONGODB_URI=mongodb://localhost:27017
JWT_SECRET=your_jwt_secret_here
RSA_PRIVATE_KEY_BASE64=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0t...
RSA_PUBLIC_KEY_BASE64=LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0...

# Optional Variables
DATABASE_NAME=heimdall_db
BASE_URL=https://auth.yourdomain.com
PORT=3000
APP_NAME=YourApp Auth

# Email Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=user@yourdomain.com
SMTP_PASSWORD=your_smtp_password
SMTP_FROM_EMAIL=noreply@yourdomain.com
SMTP_FROM_NAME=YourApp Support
VERIFICATION_URL_TEMPLATE=https://auth.yourdomain.com/verify?token={token}&email={email}

# First Client (Confidential Client)
OIDC_CLIENT_ID_1=my_client_1
OIDC_CLIENT_1_SECRET=client1_secret_value
OIDC_CLIENT_1_REDIRECT_URIS=https://app1.example.com/callback,https://app1.example.com/cb
OIDC_CLIENT_1_SCOPES=openid,profile,email
OIDC_CLIENT_1_GRANT_TYPES=authorization_code,refresh_token
OIDC_CLIENT_1_RESPONSE_TYPES=code,form_post
OIDC_CLIENT_1_TOKEN_AUTH_METHOD=client_secret_basic

# Second Client (Public Client, e.g., SPA)
OIDC_CLIENT_ID_2=my_spa_client
OIDC_CLIENT_2_SECRET=
OIDC_CLIENT_2_REDIRECT_URIS=https://spa.example.com/auth-callback
OIDC_CLIENT_2_SCOPES=openid,profile
OIDC_CLIENT_2_GRANT_TYPES=authorization_code
OIDC_CLIENT_2_RESPONSE_TYPES=code
OIDC_CLIENT_2_TOKEN_AUTH_METHOD=none

Generating RSA Keys

Heimdall requires RSA keys for signing and verifying tokens. You can generate a key pair using a tool like openssl:

Generate RSA Keys

# Generate a private key
openssl genrsa -out private.pem 2048

# Extract the public key
openssl rsa -in private.pem -pubout -out public.pem

# Convert to base64 for environment variables
base64 -i private.pem | tr -d '
' > private_key_b64.txt
base64 -i public.pem | tr -d '
' > public_key_b64.txt

Set the contents of private_key_b64.txt and public_key_b64.txt as RSA_PRIVATE_KEY_BASE64 and RSA_PUBLIC_KEY_BASE64, respectively, in your .env file.

Configuration Best Practices

  • Secure Secrets: Store JWT_SECRET, RSA_PRIVATE_KEY_BASE64, RSA_PUBLIC_KEY_BASE64, and SMTP credentials in a secure vault or secret management system (e.g., AWS Secrets Manager, HashiCorp Vault).
  • Consistent Environments: Use the same .env file structure across development, CI, and production to ensure consistency.
  • Validate Redirect URIs: Ensure client redirect URIs are HTTPS and specific to prevent open redirect vulnerabilities.
  • Monitor Token Expiry: Adjust token expiry durations (ACCESS_TOKEN_EXPIRY, REFRESH_TOKEN_EXPIRY, AUTH_CODE_EXPIRY) based on your application’s security requirements.
  • Test Email Configuration: Verify SMTP settings in a staging environment to ensure email delivery works as expected.

Next Steps

Was this page helpful?