Auth Container Configuration

All runtime settings for the Auth container live in /app/config/config.yaml. When you deploy with Docker Compose (see deployment/docker-compose.authlance.yml) the file is bind-mounted into the container, so you edit the host copy (for example cmd/config/authlance-config.yaml) and restart the service. This guide walks through each key using a single, consistent example so you know what values to supply and why they matter.

port: 8000

database:
  host: mysql.internal
  port: 3306
  user: auth_user
  password: "S3cur3Pa55!"
  dbname: authlance

kratos:
  url: https://kratos.example.com/
  adminUrl: http://kratos-admin.internal/

hydra:
  url: https://hydra.example.com/
  adminUrl: http://hydra-admin.internal/
  hydraLoginToken: s.CMSULuWcPZFakeToken

authlance:
  autoCreateGroup: true

users:
  - email: admin@example.com
    admin: true
    firstName: Ada
    lastName: Lovelace
    groups:
      - core-team

requireGenderExtra: false
requireBirthDateExtra: true

nats:
  url: nats://nats.internal:4222

jwtKey: "4d9c2b4f0e0f4c3cb2d9af9cd5b3d6ce"
cookieDomain: ".example.com"
debug: false

mailAuth:
  port: 8001
  user: mailbot
  password: "mailbot-secret"

s3Config:
  key: "AKIAFAKEKEY"
  secret: "fake/secret/key"
  region: "us-east-1"
  endpoint: "https://s3.us-east-1.amazonaws.com"
  bucket: "authlance-assets"
  secondaryBucket: "authlance-backups"
  cdnUrl: "https://cdn.example.com"

backup:
  databases:
    - authlance
    - authlance_audit

paymentTier:
  tierName: "standard"
  maxMembers: 10
  price: 39.00
  billingCycle: "monthly"
  lookupKey: "standard_monthly"
  tierDescription: "Default SaaS tier"

personalAccessTokens:
  routeScopes:
    - method: GET
      path: /authlance/identity/api/v1/profile
      scope: public_scope
    - path: /authlance/identity/api/v1/profile/*
      scope: public_scope

events:
  disableUserAuthenticated: false
  disableSubscriptionEvents: false

stripe:
  secretKey: "sk_live_fake_123"
  webhookSecret: "whsec_fake_456"
  webhookBaseUrl: "https://auth.example.com/authlance/payments/api/v1/stripe/webhook"
  successBaseUrl: "https://dashboard.example.com/billing/success"
  rootAppUrl: "https://dashboard.example.com"
  frontEndBasePath: "/billing"
  trialPeriodDays: 14
  portalReturnUrl: "https://dashboard.example.com/billing/portal"

license:
  filePath: "/app/config/authlance.lic"
  refreshInterval: "15m"
  gracePeriodDays: 7

Key-by-key reference

Service basics

  • port: Internal port used by the application, should be set to 8000, on change you will need to provide a custom NGINX or Compose configuration. NGINx do a reverse proxy to it and exposes the port 1080.
  • mailAuth.port: Port where the Mail API listens for authenticated requests, should be set to 8001.
  • debug: Enables verbose logging when true; prefer false in production.
  • cookieDomain: Domain suffix applied to loopToken. Use a leading dot so it shares cookies across subdomains, e.g., .example.com. This is what you use when issuing a license tied to a specific domain.
  • jwtKey: Symmetric signing key for the internal JWT issued by /authlance/identity/me. Generate a long random string and keep it secret.

Database block

  • database.host / port: Address of the MySQL instance the service uses.
  • database.user / password: Credentials with permission to read/write the Auth schema.
  • database.dbname: Default schema the ORM connects to.

If you run read replicas, point only the primary write endpoint here; replicas are not supported directly in this config.

Ory services

  • kratos.url / hydra.url: Public URLs the browser hits for identity flows and OAuth callbacks. It should not be exposed outside your cluster.
  • kratos.adminUrl / hydra.adminUrl: Internal URLs reachable from the Auth container for administrative APIs. It should not be exposed outside your cluster.
  • hydra.hydraLoginToken: Shared secret that lets Hydras login handler trust this service.

Make sure the URLs use HTTPS when fronted by a load balancer.

Bootstrap automation

  • authlance.autoCreateGroup: When true, the first login for a new organization automatically creates a group record.
  • users: Seeded administrator accounts. Each entry defines the email, whether the user should receive admin rights, optional name fields, and the groups they belong to. Keep this list small; you can remove entries after the bootstrap finishes.

Required profile extras

  • requireGenderExtra and requireBirthDateExtra: Toggle whether those fields must be collected to get a valid profile. Set them to true if your compliance workflow mandates these demographics.

Messaging

  • nats.url: Connection string for the JetStream cluster used for login, payment, and license events. Use the nats:// scheme and include credentials if needed (e.g., nats://user:pass@nats.internal:4222).

Mail relay

  • mailAuth.port, user, password: Basic-auth credentials the Mail API expects when other services request transactional emails. Kratos courier calls the internal /authlance/identity/email routes exposed on this port, so keep the credentials synchronized across both systems even though the endpoint is not public.

Object storage and backups

  • s3Config: Access keys, region, and buckets for user uploads and exported files. secondaryBucket must exist because the backup command uploads database dumps there, which stores a daily mysql backup. If you front assets with a CDN, place the HTTPS origin in cdnUrl.
  • backup.databases: List every schema that should be dumped by the backup command. Include the primary auth database plus any audit schemas that live on the same MySQL instance.

Payment tiers

  • paymentTier: Defines or updates the canonical Stripe tier that should exist inside the Auth DB. On startup the backend ensures this tier exists (creating or updating it using the provided values). Leave it empty if you manage tiers manually; otherwise keep it in sync with the product you sell (lookup key, billing cadence, seat cap, etc.).

Personal access tokens

Personal access tokens (PATs) allow automation to call /authlance/identity/** without a loopToken. Each request is matched against the configured route scopes, so only the endpoints you list become callable with a PAT.

  • personalAccessTokens.routeScopes: Static list of REST paths and the scopes required to call them with a PAT. method is optional; omit it to cover all verbs. Paths ending in /* match nested resources. The scope value must be one of the supported PAT scopes (for example public_scope or full_scope).

Event emission

  • events.disableUserAuthenticated: Set to true to opt-out of publishing the user.authenticated event when users exchange sessions for loopToken.
  • events.disableSubscriptionEvents: Set to true to stop emitting subscription.* events after payment or admin flows. Database updates still occur; only NATS notifications are skipped.

Stripe integration

  • stripe.secretKey: Server-side secret for REST and webhook calls.
  • stripe.webhookSecret: Signing secret you obtain when registering the webhook via authlance stripe-webhook.
  • stripe.webhookBaseUrl: Fully-qualified URL where Stripe should post events (usually fronted by NGINX).
  • stripe.successBaseUrl: Redirect shown after checkout completes.
  • stripe.rootAppUrl and frontEndBasePath: Used to compose hosted links for the customer portal and the dashboard.
  • stripe.trialPeriodDays: Default free trial length automatically applied to new subscriptions.
  • stripe.portalReturnUrl: Where Stripe sends the user after they exit the billing portal.

License enforcement

  • license.filePath: Absolute path to the .lic file mounted inside the container.
  • license.refreshInterval: How often the license manager re-reads the file or remote store (duration strings such as 15m, 1h).
  • license.gracePeriodDays: How many days customers stay in grace after expiration before enforcement kicks in.

The service also accepts LICENSE_PATH, LICENSE_REFRESH_INTERVAL, and LICENSE_GRACE_PERIOD_DAYS environment variables which override the YAML at runtime. Use them when injecting secrets through Docker/Kubernetes.

Managing the file

  1. Copy the template to a safe location (for example, deployment/docker-compose/app/auth/config.yaml).
  2. Replace every placeholder with your real infrastructure values. Keep the YAML indentation exactly as shown.
  3. Mount the file into the container (Docker Compose already does this via the app_auth_config volume).
  4. Restart the authlance service so the new configuration is loaded.

Keep sensitive fields such as jwtKey, database passwords, and Stripe secrets in a secret manager or .env file. The Docker Compose template already pulls them from ${VAR} placeholders, but if you edit the YAML manually make sure you store it securely.