Edge configuration

edge reads one HOCON file at startup. This page lists its keys, says which secret each one holds and where that secret comes from, and describes what makes edge refuse to start. For loading rules, environment variables and the blocks shared with auth and central, see Configuration reference.

versola configure and the Helm chart generate this file for the release you deploy, so you rarely write it by hand. On the vps target a hand edit is lost on the next configure.

Loading and environment variables

The file path comes from CONFIG_PATH (image default /app/config/env.conf). ENV_CONFIG can hold the whole file inline instead. Keys are kebab-case, durations are HOCON durations ("60 seconds", 5 minutes), and ${VAR} substitution works.

edge does not read APORT or MPORT.

Keys

“Required” means the key has no default and edge does not start without it.

Top level

security

postgres

Same block as in auth and central: see Configuration reference. edge needs its own database, or its own schema in a shared one (the CLI targets use a shared database with ...?currentSchema=edge). edge listens for revocations on a dedicated connection, so behind a pooler in transaction mode set notifications-url. Generated values for edge: maximum-pool-size = 10, minimum-idle = 10.

cleanup

Deletes expired rows. Generated for edge, with max-threads = 2:

revocation

Optional block. The defaults below are in code.

dpop

Optional block. Without it, edge refuses requests with the DPoP scheme, but a key-bound token over Bearer is still refused. A native block requires it. The accepted algorithms come from the server metadata in central, and whether a nonce is required is the Require DPoP nonce setting on the edge in Edges; neither is configured here.

native

Optional block. Absent: every /native/* call answers 404. See Native apps for the flow.

Secrets and where they come from

On vps and the local target, versola configure generates each secret, stores it in OpenBao under secret/versola/<target>/edge and writes it into the container environment as a ${VAR} that the HOCON file references. On Kubernetes the same keys come from a Secret (Kubernetes). See Secrets.

A 32-byte secret is URL-safe base64 of exactly 32 bytes. A different length stops startup.

Startup validation

edge refuses to start, with a message naming the key, when:

• a required key is missing, a secret has the wrong length, or private-key is not a PKCS#8 RSA key;
• a path in versola-internal-trusted-certificates or native.trusted-certificates holds no certificate, or holds a certificate authority. Every certificate in every file is checked, and only leaf certificates pass;
• native.trusted-certificates is empty;
• a native block exists without a dpop block;
• a trusted-certificates value is a bare string. It must be a list;
• the database schema is out of date and RUN_MIGRATIONS is not true;
• env = "prod" and a non-loopback Postgres URL does not verify TLS;
• it cannot read the revocation list from the database. A replica with no list would accept revoked tokens, so it stays out of service.

Annotated minimal example

This is a vps-style file with the optional blocks left out except dpop. Secrets are placeholders resolved from the environment.

env = prod
id = "edge-default"                     # same ID as the edge in central
key-id = ${EDGE_KEY_ID}
private-key = ${EDGE_PRIVATE_KEY}       # PKCS#8 RSA, base64

configuration-cache-refresh-interval = "5 minutes"

versola-url = "https://id.example.com"  # what browsers and token iss use
edge-url    = "https://id.example.com"  # DPoP htu is built from this

central { url = "http://127.0.0.1:8090" }

security {
  token-encryption { key = ${EDGE_TOKEN_ENC_KEY} }
  edge-sessions {
    secret = ${EDGE_SESSIONS_SECRET}
    ttl = 30 days
  }
}

postgres {
  url = "jdbc:postgresql://db.example.com:5432/versola?currentSchema=edge"
  user = "versola"
  password = ${POSTGRES_PASSWORD}
  maximum-pool-size = 10
  minimum-idle = 10
  connection-timeout = "30 seconds"
  max-lifetime = "30 minutes"
  leak-detection-threshold = "60 seconds"
}

cleanup {
  max-threads = 2
  tables = [
    { table-name = "pending_logins", batch-size = 1000, interval = "5 minutes", key-column = "state" }
    { table-name = "edge_sessions",  batch-size = 500,  interval = "1 hour",    key-column = "ctid" }
    { table-name = "revocations",    batch-size = 1000, interval = "1 hour",    key-column = "revoked_key" }
  ]
}

dpop {
  nonce-salt = ${EDGE_DPOP_NONCE_SALT}
  iat-leeway = "60 seconds"
  nonce-ttl  = "600 seconds"
}

Add a native block only if you serve native apps:

native {
  auth-mutual-tls-url  = "https://id.example.com:8083"
  trusted-certificates = ["/certs/auth-mtls.crt"]
  blob-key             = ${EDGE_NATIVE_BLOB_KEY}
}

Pinned certificates

versola-internal-trusted-certificates and native.trusted-certificates are lists of PEM file paths. Each entry is a pin on a leaf certificate, not a trust anchor. The HTTP client edge uses does no host-name verification, so trusting a CA would accept any certificate that CA ever issued, for any host. That is why a CA is refused at startup.

native {
  trusted-certificates = ["/certs/auth-mtls-old.crt", "/certs/auth-mtls-new.crt"]
}
versola-internal-trusted-certificates = ["/certs/auth-internal.crt"]

A server certificate that matches any entry is accepted. To rotate the certificate of auth’s listener without an outage:

1. Put the old and the new leaf in the list on every edge and restart them.
2. Switch auth to the new certificate and restart it.
3. When every edge has the new list, remove the old entry.

edge reads the files at startup, so a changed file needs a restart. The old form trusted-certificates = "/path" no longer parses; wrap it in [...].

Next steps

• Edge client certificates: how edge gets the certificate it presents to auth.
• Secrets: where the generated values live.
• Kubernetes: the same keys in the Helm chart.