Конфигурация edge

edge при старте читает один HOCON-файл. На странице перечислены его ключи, указано, какой секрет стоит за каждым и откуда он берётся, и описано, из-за чего edge отказывается запускаться. О правилах загрузки, переменных окружения и блоках, общих с auth и central, см. Справочник по конфигурации.

versola configure и Helm-чарт генерируют этот файл для разворачиваемого релиза, поэтому вручную его пишут редко. В цели vps ручная правка пропадает при следующем configure.

Загрузка и переменные окружения

Путь к файлу берётся из CONFIG_PATH (в образе по умолчанию /app/config/env.conf). Вместо файла весь HOCON можно передать в ENV_CONFIG. Ключи пишутся в kebab-case, длительности — в формате HOCON ("60 seconds", 5 minutes), подстановка ${VAR} работает.

edge не читает APORT и MPORT.

Ключи

«Обязательный» означает, что у ключа нет значения по умолчанию и без него edge не запустится.

Верхний уровень

security

postgres

Тот же блок, что в auth и central: см. Справочник по конфигурации. Для edge нужна своя база или своя схема в общей базе (цели CLI используют общую базу с ...?currentSchema=edge). edge слушает отзывы на отдельном соединении, поэтому за пулером в transaction-режиме задайте notifications-url. Генерируемые значения для edge: maximum-pool-size = 10, minimum-idle = 10.

cleanup

Удаляет просроченные строки. Для edge генерируется, max-threads = 2:

revocation

Необязательный блок. Значения ниже заданы в коде.

dpop

Необязательный блок. Без него edge отклоняет запросы со схемой DPoP, но токен, привязанный к ключу, через Bearer всё равно отклоняется. Блоку native он обязателен. Допустимые алгоритмы берутся из метаданных сервера в central, а требование nonce задаётся настройкой Require DPoP nonce у этого edge в разделе Edges. Здесь ни то ни другое не настраивается.

native

Необязательный блок. Если его нет, любой вызов /native/* отвечает 404. Описание потока — в разделе Нативные приложения.

Секреты и откуда они берутся

В цели vps и в локальной цели versola configure генерирует каждый секрет, сохраняет его в OpenBao по пути secret/versola/<target>/edge и передаёт в окружение контейнера как ${VAR}, на которую ссылается HOCON-файл. В Kubernetes те же ключи приходят из Secret (Kubernetes). См. Секреты.

Секрет в 32 байта — это URL-safe base64 ровно от 32 байт. Другая длина останавливает запуск.

Проверки при старте

edge отказывается запускаться и называет ключ, если:

• не задан обязательный ключ, у секрета неверная длина или private-key не является ключом RSA в формате PKCS#8;
• путь в versola-internal-trusted-certificates или native.trusted-certificates не содержит сертификата либо содержит удостоверяющий центр. Проверяется каждый сертификат в каждом файле, проходят только конечные сертификаты;
• native.trusted-certificates пуст;
• блок native есть, а блока dpop нет;
• значение trusted-certificates — просто строка. Нужен список;
• схема базы устарела, а RUN_MIGRATIONS не равен true;
• env = "prod", а URL Postgres не на loopback не проверяет TLS;
• он не может прочитать список отзывов из базы. Реплика без списка принимала бы отозванные токены, поэтому она остаётся вне обслуживания.

Минимальный пример с комментариями

Это файл в стиле vps; необязательные блоки опущены, кроме dpop. Секреты — подстановки, которые берутся из окружения.

env = prod
id = "edge-default"                     # тот же ID, что у edge в 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"  # что видят браузеры и что сверяется с iss токена
edge-url    = "https://id.example.com"  # из этого строится htu для DPoP

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"
}

Блок native добавляйте, только если обслуживаете нативные приложения:

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

Закреплённые сертификаты

versola-internal-trusted-certificates и native.trusted-certificates — списки путей к PEM-файлам. Каждый элемент закрепляет конкретный конечный сертификат, это не якорь доверия. HTTP-клиент edge не проверяет имя хоста, поэтому доверие к УЦ принимало бы любой сертификат, который этот УЦ когда-либо выпустил, для любого хоста. Поэтому УЦ отклоняется при старте.

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

Принимается серверный сертификат, совпавший с любым элементом списка. Чтобы сменить сертификат слушателя auth без простоя:

1. Положите старый и новый конечные сертификаты в список на каждом edge и перезапустите их.
2. Переключите auth на новый сертификат и перезапустите его.
3. Когда у каждого edge новый список, удалите старый элемент.

edge читает файлы при старте, поэтому после замены файла нужен перезапуск. Старая форма trusted-certificates = "/path" больше не разбирается: оберните значение в [...].

Что дальше

• Клиентские сертификаты edge: как edge получает сертификат, который предъявляет auth.
• Секреты: где лежат сгенерированные значения.
• Kubernetes: те же ключи в Helm-чарте.