Общие сведения

О продукте

Stronghold обеспечивает безопасное хранение и управление жизненным циклом конфиденциальных данных. Хранилище защищаемой информации реализовано в формате key-value и совместимо с Hashicorp Vault API.

Stronghold предоставляет доступ к данным и управляется через:

• Веб-интерфейс
• API

Основные сферы применения

• Хранение секретов: Доступ к секретам в зашифрованном хранилище через API. Безопасная доставка секретов в качестве переменных окружения или файлов в приложения с помощью специального модуля
• Аутентификация и авторизация: Интеграция с существующими системами аутентификации, такими как LDAP, Active Directory, Blitz, Keycloak и Kubernetes. Настройка политик доступа, чтобы контролировать, кто и к каким секретам может получить доступ
• Секреты для DevOps и CI/CD: Управление секретами и учётными данными для Jenkins, GitLab CI, CircleCI и других CI/CD-инструментов. Автоматическое обновление секретов и учётных данных в процессе развёртывания приложений
• Безопасное хранение сертификатов и ключей: Приложения получают доступ к секретам через API, нет необходимости хранить их в коде или конфигурационных файлах. Для взаимодействия с внешними сервисами, такими как AWS, Azure и GCP, используется автоматическая ротация ключей API
• Управление динамическими секретами: Создание временных учётных данных для доступа разработчиков и приложений к базам данных PostgreSQL, MySQL и MongoDB
• Автоматизация процессов управления секретами: Автоматическая выдача и управление SSL/TLS-сертификатами для внутреннего и внешнего использования. Хранение и управление ключами SSH для безопасного доступа к серверам

Установка и настройка

Установка

Stronghold поддерживает мультисерверный режим для обеспечения высокой доступности (HA). Этот режим автоматически включается при использовании хранилища данных, которое его поддерживает, и защищает систему от сбоев за счёт работы нескольких серверов Stronghold.

Как определить, поддерживает ли ваше хранилище данных режим высокой доступности? Запустите сервер и проверьте, выводится ли сообщение HA available рядом с информацией о хранилище. Если да, то Stronghold будет автоматически использовать режим HA.

Для обеспечения высокой доступности один из узлов Stronghold получает блокировку в системе хранения данных. Затем этот узел становится активным, в то время как остальные узлы переходят в режим ожидания. Если резервные узлы получают запросы, они либо перенаправляют их, либо переадресовывают клиентов в соответствии с настройками и текущим состоянием кластера.

Для развёртывания Stronghold в режиме HA с интегрированным хранилищем Raft вам понадобятся как минимум три сервера Stronghold. В противном случае не получится достичь кворума и распечатать хранилище.

Предварительные требования:

• На сервер установлена поддерживаемая ОС (Ubuntu, RedOS, Astra Linux).
• На сервер скопирован дистрибутив Stronghold.
• Создан systemd-unit.
• Есть сертификаты для каждого узла в кластере Raft, а также сертификат корневого центра сертификации.

Предварительная подготовка инфраструктуры

Сценарий ниже описывает процесс построения кластера Stronghold, который состоит из трёх узлов Stronghold — одного активного и двух резервных.

Запуск через systemd-unit

{% alert level="warning" %}Все примеры предполагают, что существует пользователь stronghold, и сервис запущен под ним. Если вы хотите запустить сервис под другим пользователем, замените имя пользователя на необходимое.

Создайте файл /etc/systemd/system/stronghold.service:

[Unit]
Description=Stronghold service
Documentation=https://deckhouse.ru/products/stronghold/
After=network.target

[Service]
Type=simple
ExecStart=/opt/stronghold/stronghold server -config=/opt/stronghold/config.hcl
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
Restart=on-failure
RestartSec=5
User=stronghold
Group=stronghold
LimitNOFILE=65536
CapabilityBoundingSet=CAP_IPC_LOCK
AmbientCapabilities=CAP_IPC_LOCK
SecureBits=noroot

[Install]
WantedBy=multi-user.target

Выполните команду systemctl daemon-reload.

Включите автозапуск сервиса systemctl enable stronghold.service.

Создайте каталог /opt/stronghold/data и установите права доступа на него:

mkdir -p /opt/stronghold/data
chown stronghold:stronghold /opt/stronghold/data
chmod 0700 /opt/stronghold/data

Подготовка необходимых сертификатов

Для настройки TLS требуется описанный ниже набор сертификатов и ключей, размещённых в каталоге /opt/stronghold/tls.

Сертификат корневого центра сертификации, который подписал сертификат Stronghold TLS. В данном сценарии его имя — stronghold-ca.pem.

Сертификаты узлов Raft. В текущем сценарии в кластер будет добавлено три узла, для которых будут созданы такие сертификаты:

• node-1-cert.pem
• node-2-cert.pem
• node-3-cert.pem

Закрытые ключи сертификатов узлов:

• node-1-key.pem
• node-2-key.pem
• node-3-key.pem

В этом примере создадим корневой сертификат, а также набор самоподписанных сертификатов для каждого узла.

Хотя самоподписанные сертификаты и подходят для экспериментов с развёртыванием и запуском Stronghold, мы настоятельно рекомендуем использовать сертификаты, созданные и подписанные соответствующим центром сертификации.

Порядок действий

На первом узле перейдите в каталог /opt/stronghold/tls/. Если каталог ещё не существует — создайте его:

mkdir -p /opt/stronghold/tls
cd /opt/stronghold/tls/

Сгенерируйте ключ для корневого сертификата:

openssl genrsa 2048 > stronghold-ca-key.pem

Выпустите корневой сертификат:

openssl req -new -x509 -nodes -days 3650 -key stronghold-ca-key.pem -out stronghold-ca.pem

Country Name (2 letter code) [XX]:RU
State or Province Name (full name) []:
Locality Name (eg, city) [Default City]:Moscow
Organization Name (eg, company) [Default Company Ltd]:MyOrg
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server hostname) []:demo.tld

Атрибуты сертификата приведены для примера. Для выпуска сертификатов узлов создайте конфигурационные файлы, содержащие subjectAltName (SAN). Например, файл для узла raft-node-1 будет выглядеть так:

cat << EOF > node-1.cnf
[v3_ca]
subjectAltName = @alt_names
[alt_names]
DNS.1 = raft-node-1.demo.tld
IP.1 = 10.20.30.10
IP.2 = 127.0.0.1
EOF

Каждый узел должен иметь корректные FQDN и IP-адрес. Поле subjectAltName в сертификате должно содержать соответствующие значения для конкретного узла.

Также нужно создать конфигурационный файл для каждого узла, который вы планируете добавить в кластер.

Для каждого узла сформируйте файл запроса:

openssl req -newkey rsa:2048 -nodes -keyout node-1-key.pem -out node-1-csr.pem -subj "/CN=raft-node-1.demo.tld"
openssl req -newkey rsa:2048 -nodes -keyout node-2-key.pem -out node-2-csr.pem -subj "/CN=raft-node-2.demo.tld"
openssl req -newkey rsa:2048 -nodes -keyout node-3-key.pem -out node-3-csr.pem -subj "/CN=raft-node-3.demo.tld"

Выпустите сертификаты на основании запросов:

openssl x509 -req -set_serial 01 -days 3650 -in node-1-csr.pem -out node-1-cert.pem -CA stronghold-ca.pem -CAkey stronghold-ca-key.pem -extensions v3_ca -extfile ./node-1.cnf
openssl x509 -req -set_serial 01 -days 3650 -in node-2-csr.pem -out node-2-cert.pem -CA stronghold-ca.pem -CAkey stronghold-ca-key.pem -extensions v3_ca -extfile ./node-2.cnf
openssl x509 -req -set_serial 01 -days 3650 -in node-3-csr.pem -out node-3-cert.pem -CA stronghold-ca.pem -CAkey stronghold-ca-key.pem -extensions v3_ca -extfile ./node-3.cnf

Для автоматического подключения узлов скопируйте на каждый из них:

• Файл сертификата этого узла.
• Файл ключа этого узла.
• Файл корневого сертификата.

Например:

scp ./node-2-key.pem ./node-2-cert.pem ./stronghold-ca.pem  raft-node-2.demo.tld:/opt/stronghold/tls
scp ./node-3-key.pem ./node-3-cert.pem ./stronghold-ca.pem  raft-node-3.demo.tld:/opt/stronghold/tls

Если каталога /opt/stronghold/tls нет на целевых узлах — создайте его.

Развёртывание кластера с Raft

Подключитесь к первому серверу, на котором будет выполняться инициализация кластера Stronghold.

Добавьте разрешающие правила на сетевом экране для TCP-портов 8200 и 8201. Вот пример для firewalld:

firewall-cmd --add-port=8200/tcp --permanent
firewall-cmd --add-port=8201/tcp --permanent
firewall-cmd --reload

Вы можете использовать и любые другие порты, указав их в конфигурационном файле /opt/stronghold/config.hcl.

Создайте файл /opt/stronghold/config.hcl для конфигурации Raft. Если каталог /etc/stronghold/ не существует, создайте его. Добавьте в файл следующее содержимое, заменив значения соответствующих параметров своими:

ui = true
cluster_addr  = "https://10.20.30.10:8201"
api_addr      = "https://10.20.30.10:8200"
disable_mlock = true

listener "tcp" {
  address       = "0.0.0.0:8200"
  tls_cert_file      = "/opt/stronghold/tls/node-1-cert.pem"
  tls_key_file       = "/opt/stronghold/tls/node-1-key.pem"
}

storage "raft" {
  path = "/opt/stronghold/data"
  node_id = "raft-node-1"

  retry_join {
    leader_tls_servername   = "raft-node-1.demo.tld"
    leader_api_addr         = "https://10.20.30.10:8200"
    leader_ca_cert_file     = "/opt/stronghold/tls/stronghold-ca.pem"
    leader_client_cert_file = "/opt/stronghold/tls/node-1-cert.pem"
    leader_client_key_file  = "/opt/stronghold/tls/node-1-key.pem"
  }
  retry_join {
    leader_tls_servername   = "raft-node-2.demo.tld"
    leader_api_addr         = "https://10.20.30.11:8200"
    leader_ca_cert_file     = "/opt/stronghold/tls/stronghold-ca.pem"
    leader_client_cert_file = "/opt/stronghold/tls/node-1-cert.pem"
    leader_client_key_file  = "/opt/stronghold/tls/node-1-key.pem"
  }
  retry_join {
    leader_tls_servername   = "raft-node-3.demo.tld"
    leader_api_addr         = "https://10.20.30.12:8200"
    leader_ca_cert_file     = "/opt/stronghold/tls/stronghold-ca.pem"
    leader_client_cert_file = "/opt/stronghold/tls/node-1-cert.pem"
    leader_client_key_file  = "/opt/stronghold/tls/node-1-key.pem"
  }
}

Выполните запуск:

systemctl start stronghold

Выполните инициализацию:

stronghold operator init -ca-cert /opt/stronghold/tls/stronghold-ca.pem

Вы можете передать параметры -key-shares и -key-threshold, чтобы определить, на сколько частей будет разбит ключ и сколько из них будет достаточно для распечатывания хранилища. По умолчанию key-shares=5, а key-threshold=3.

{% alert level="warning" %}После завершения инициализации в терминал будут выведены все части ключа и корневой токен. Обязательно сохраните эти данные в надёжном месте. Части ключа и начальный корневой токен крайне важны. Если вы потеряете часть ключа, то не сможете получить доступ к данным Stronghold.{% endalert %}

Дальше нужно распечатать кластер. Для этого выполните необходимое количество раз команду:

stronghold operator unseal -ca-cert /opt/stronghold/tls/stronghold-ca.pem

и введите ключи распечатки, полученные на предыдущем шаге. Если вы не меняли параметр -key-threshold, то ввести нужно 3 части ключа.

Повторите настройку на остальных нодах кластера. Для этого укажите в файле /opt/stronghold/config.hcl в параметрах cluster_addr и api_addr соответствующие IP-адреса нод. Пропустите шаг с инициализацией и сразу переходите к шагу распечатки кластера.

Остаётся только проверить работу кластера:

stronghold status -ca-cert /opt/stronghold/tls/stronghold-ca.pem
Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            5
Threshold               3
Version                 1.15.2
Build Date              2025-03-07T16:10:46Z
Storage Type            raft
Cluster Name            stronghold-cluster-a3fcc270
Cluster ID              f682968d-5e6c-9ad4-8303-5aecb259ca0b
HA Enabled              true
HA Cluster              https://10.20.30.10:8201
HA Mode                 active
Active Node Address     https://10.20.30.10:8200
Raft Committed Index    40
Raft Applied Index      40

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

Обзор конфигурации

Серверы Stronghold настраиваются с использованием конфигурационного файла в формате HCL или JSON.

Чтобы усилить контроль за доступом к файлам, можно включить проверку прав доступа к файлам с помощью переменной окружения VAULT_ENABLE_FILE_PERMISSIONS_CHECK. Если проверка активирована, Stronghold проверяет, принадлежат ли директория конфигурации и файлы пользователю, который запускает Stronghold. Дополнительно проверяется, что у группы или других пользователей нет прав на запись или выполнение этих файлов.

При необходимости оператор может указать пользователя и права доступа к директории плагинов и исполняемым файлам. Для этого используются параметры plugin_file_uid и plugin_file_permissions в конфигурации. По умолчанию проверка прав в Stronghold отключена.

Вот пример конфигурации:

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_id"
}

listener "tcp" {
  address       = "127.0.0.1:8200"
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}

Для применения новых параметров после изменения файла конфигурации нужно перезапустить сервис Stronghold: systemctl restart stronghold.

Обзор параметров

• storage — обязательный блок параметров. Настройка бэкенда хранилища, где будут сохраняться данные Stronghold. Для работы Stronghold в режиме высокой доступности (HA) нужно использовать бэкенд, который поддерживает семантику координации. Если выбранный бэкенд хранения это позволяет, параметры HA можно указать прямо внутри блока storage. В ином случае следует настроить отдельный параметр ha_storage с бэкендом, который поддерживает HA, вместе с соответствующими параметрами HA. Подробности о параметрах бэкенда хранилища — в разделе Секция storage.

• ha_storage — необязательный блок параметров. Настройка бэкенда хранилища, где будет происходить координация Stronghold в режиме высокой доступности (HA). Указанный бэкенд должен поддерживать HA. Если параметр не установлен, будет выполнена попытка запустить HA на бэкенде, который указан в параметре storage. Если бэкенд хранилища уже поддерживает координацию HA и если специфические параметры HA уже указаны в блоке storage, дополнительная настройка ha_storage не требуется.

• listener — обязательный блок параметров. Настройка параметров прослушивания запросов API Stronghold. Подробности — в разделе Секция listener.

• user_lockout — необязательный блок параметров. Настройка поведения блокировки пользователя при неудачном входе в систему. Подробности — в разделе Секция user_lockout.

• cluster_name — необязательный строковый параметр. Указывает идентификатор для кластера Stronghold. Если значение не указано, Stronghold его сгенерирует.

• cache_size — необязательный строковый параметр. Определяет размер кэша чтения, который использует физическая подсистема хранения. Значение указывается в количестве хранимых записей, поэтому общий размер кэша зависит от их размера. По умолчанию 131072.

• disable_cache — необязательный логический параметр. Отключает все кэши в Stronghold, в том числе кэш чтения, который использует физическая подсистема хранения. Сильно влияет на производительность. По умолчанию false.

• disable_mlock — необязательный логический параметр. Отключает возможность сервера выполнять системный вызов mlock, который предотвращает выгрузку памяти на диск.

Не рекомендуется отключать mlock, если не используется интегрированное хранилище. При отключении mlock стоит соблюдать описанные ниже дополнительные меры безопасности.

Не рекомендуется отключать mlock, если системы, на которых работает Stronghold, не используют swap или используют только зашифрованный swap. Поддержка блокировки памяти реализована только в UNIX-подобных системах, таких как Linux или FreeBSD, которые поддерживают системный вызов mlock() . В таких системах как, например, Windows, NaCL, Android нет механизмов для предотвращения записи всего адресного пространства памяти процесса на диск, поэтому данная функция автоматически отключается для неподдерживаемых платформ.

Напротив, настоятельно рекомендуется отключить mlock при использовании интегрированного хранилища. Этот системный вызов плохо совместим с отображаемыми в памяти файлами, такими как те, что создаются BoltDB, который Raft использует для отслеживания состояния.

Использование mlock с интегрированным хранилищем может вызвать нехватку памяти, если объём данных Stronghold превысит доступный объём ОЗУ. Дело в том, что отображаемые в память файлы загружаются в резидентную память, а это приводит к загрузке всех данных Stronghold в оперативную память. В этом случае, несмотря на то, что данные в BoltDB остаются зашифрованными в состоянии покоя, swap нужно отключить. Это позволит предотвратить выгрузку на диск других конфиденциальных данных Stronghold, которые находятся в памяти.

В Linux можно дать исполняемому файлу Stronghold возможность использовать системный вызов mlock без запуска процесса от имени root, выполнив следующую команду:

shell sudo setcap cap_ipc_lock=+ep $(readlink -f $(which stronghold))

Каждый плагин запускается как отдельный процесс, поэтому нужно применить аналогичные настройки для каждого плагина в директории plugins. Если вы используете дистрибутив Linux с актуальной версией systemd, то можете добавить следующую директиву в секцию [Service] конфигурационного файла:

console LimitMEMLOCK=infinity

• plugin_directory — необязательный строковый параметр. Определяет каталог, из которого разрешено загружать плагины. Для успешной загрузки плагинов Stronghold должен иметь разрешение на чтение файлов в этой директории, а значение не может быть символической ссылкой. По умолчанию параметр не задан и имеет значение "".

• plugin_tmpdir — необязательный строковый параметр. Указывает каталог, где Stronghold может создавать временные файлы для поддержки взаимодействия Unix-сокета с контейнеризированными плагинами. Если значение не задано, Stronghold будет использовать каталог по умолчанию для временных файлов. В большинстве случаев настройка этого параметра не требуется, за исключением ситуаций, когда используются контейнеризированные плагины и Stronghold разделяет временную папку с другими процессами, например при использовании параметра PrivateTmp в systemd.

• plugin_file_uid — необязательный целочисленный параметр. Идентификатор пользователя (UID) директорий плагинов и исполняемых файлов плагинов в случае, если они принадлежат пользователю, отличному от того, кто запускает Stronghold.

• plugin_file_permissions — необязательный строковый параметр. Строка восьмеричных прав доступа для директорий плагинов и исполняемых файлов плагинов в случае, если установлены права на запись или выполнение для группы или других пользователей.

• telemetry — необязательный блок параметров. Указывает систему телеметрии для сбора и отправки статистики.

• default_lease_ttl — необязательный строковый параметр. Определяет срок действия аренды для токенов и секретов по умолчанию. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час), и не может быть больше, чем max_lease_ttl. По умолчанию 768h.

• max_lease_ttl — необязательный строковый параметр. Определяет максимальный срок действия аренды для токенов и секретов. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час). Отдельные точки монтирования могут переопределить это значение, настроив точку монтирования с помощью флага max-lease-ttl в командах auth или secret. По умолчанию 768h.

• default_max_request_duration — необязательный строковый параметр. Указывает максимальное стандартное время выполнения запроса, после которого Stronghold его отменит. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час) и может быть переопределено для каждого слушателя (listener) через параметр max_request_duration. По умолчанию 90s.

• detect_deadlocks — необязательный строковый параметр. Строка значений, разделённых запятыми. Указывает внутренние взаимоисключающие блокировки, за которыми следует следить на предмет потенциальных взаимоблокировок. Сейчас поддерживаются значения statelock, quotas и expiration, что приведёт к записи "POTENTIAL DEADLOCK:"в лог , если попытка блокировки состояния ядра кажется заблокированной. Включение detect_deadlocks может негативно повлиять на производительность из-за отслеживания каждой попытки блокировки. По умолчанию параметр не задан и имеет значение "".

• raw_storage_endpoint — необязательный логический параметр. Активирует эндпоинт sys/raw с высоким уровнем привилегий. Этот эндпоинт позволяет выполнять дешифрование и шифрование необработанных данных на входе и выходе из защитного барьера. По умолчанию false.

• introspection_endpoint — необязательный логический параметр. Активирует эндпоинт sys/internal/inspect, который позволяет проводить инспекцию определённых подсистем внутри Stronghold пользователям с root-токеном или привилегиями sudo. По умолчанию false.

• ui — необязательный логический параметр. Активирует встроенный веб-интерфейс пользователя, доступный на всех слушателях (адрес + порт) по пути /ui. При обращении браузеров к стандартному адресу API Stronghold они будут автоматически перенаправлены на интерфейс. По умолчанию false. Подробности — в разделе Секция ui.

• pid_file — необязательный строковый параметр. Указывает путь к файлу, где должен храниться идентификатор процесса (PID) сервера Stronghold.

• enable_response_header_hostname — необязательный логический параметр. Активирует добавление HTTP-заголовка X-Vault-Hostname во все HTTP-ответы Stronghold. Этот заголовок будет содержать имя узла Stronghold, который обработал HTTP-запрос. Наличие этой информации не гарантируется — она будет предоставлена по возможности. Если опция включена, но заголовок X-Vault-Hostname отсутствует в ответе, это может указывать на ошибку при извлечении имени хоста из операционной системы. По умолчанию false.

• enable_response_header_raft_node_id — необязательный логический параметр. Активирует добавление HTTP-заголовка X-Vault-Raft-Node-ID во все HTTP-ответы Stronghold. Если Stronghold использует интегрированное хранилище (то есть участвует в кластере Raft), заголовок X-Vault-Raft-Node-ID будет содержать идентификатор узла Raft, который обработал HTTP-запрос. Если же узел Stronghold не участвует в кластере Raft, этот заголовок будет опущен независимо от того, включена ли опция. По умолчанию false.

• log_level — необязательный строковый параметр. Определяет уровень подробности журнала. Поддерживаются следующие пять значений в порядке убывания детализации: trace, debug, info, warn и error. Это значение также можно задать с помощью переменной окружения VAULT_LOG_LEVEL. По умолчанию info.

Если указано корректное значение параметра log_level, при SIGHUP (sudo kill -s HUP pid Stronghold), Stronghold обновит существующий уровень журнала. При этом будут отменены как флаг CLI, так и переменная окружения. Динамически изменять таким образом уровень журнала могут не все части журнала Stronghold. Например, сейчас не обновляются динамически плагины secrets/auth.

• log_format — необязательный строковый параметр. Формат журнала. Поддерживаются два значения: standard и json. По умолчанию standard.

• log_file — необязательный строковый параметр. Абсолютный путь, по которому Stronghold должен сохранять сообщения журнала в дополнение к другим существующим выводам, таким как journald/stdout. Пути, которые заканчиваются разделителем пути, используют имя файла по умолчанию — vault.log. Пути, которые не заканчиваются расширением файла, используют расширение по умолчанию — .log. Если файл журнала перезаписывается, в момент перезаписи Stronghold добавляет к имени файла текущую временную метку.

• log_rotate_duration — необязательный строковый параметр. Указывает максимальную продолжительность записи в файл журнала перед до его перезаписи. Значение указывается с использованием суффикса времени, например, 40s. По умолчанию 24h.

• log_rotate_bytes — необязательный целочисленный параметр. Указывает количество байт, которое можно записать в файл журнала до его перезаписи. Если значение не указано, то количество байт, которое можно записать в файл журнала, не ограничено.

• log_rotate_max_files — необязательный целочисленный параметр. Указывает максимальное количество старых файлов журнала, которые нужно сохранять. По умолчанию установлено значение 0, то есть файлы никогда не удаляются. Чтобы удалять старые файлы журналы при создании нового установите значение -1.

• imprecise_lease_role_tracking — необязательный логический параметр. Позволяет пропустить подсчёт аренды по ролям, если квоты на основе ролей не включены. Когда этот параметр установлен в значение true и включена новая квота на основе ролей, последующий подсчёт аренд начнётся 0. Параметр влияет на квоты подсчёта аренды на основе ролей, но уменьшает задержки, если квоты на основе роли не используются.

• experiments — необязательный массив значений. Список экспериментальных функций, которые следует активировать для узла. Не используйте экспериментальные функции в production-среде! Связанные с ними API могут между релизами претерпевать несовместимые с предыдущими версиями изменения. Дополнительные экспериментальные функции также можно указать через переменную окружения VAULT_EXPERIMENTS в виде списка значений, разделённых запятыми.

Параметры высокой доступности

Для бэкендов, которые поддерживают режим высокой доступности (HA), используются следующие параметры:

• api_addr — необязательный строковый параметр. Указывает адрес, который будет анонсироваться другим серверам Stronghold в кластере для перенаправления клиентов. Также это значение используется для бэкендов плагинов. Параметр api_addr также можно задать через переменную окружения VAULT_API_ADDR. В общем случае это должен быть полный URL, который указывает на значение адреса слушателя (listener). Адрес может быть динамически определён с помощью шаблона go-sockaddr, который разрешается во время выполнения.

• cluster_addr — необязательный строковый параметр. Указывает адрес для анонсирования другим серверам Stronghold в кластере для перенаправления запросов. Этот параметр также можно задать через переменную окружения VAULT_CLUSTER_ADDR. Подобно api_addr это полный URL, но Stronghold будет игнорировать схему (все участники кластера всегда используют TLS с приватным ключом/сертификатом). Адрес может быть динамически определён с помощью шаблона go-sockaddr, который разрешается во время выполнения.

• disable_clustering — необязательный логический параметр. Указывает, включены ли функции кластеризации, например, переадресация запросов. Если установить значение true для одного узла хранилища, функции кластеризации будут отключены только в случае, если этот узел является активным. Параметр нельзя установить в true, если типом хранилища является raft. По умолчанию false.

Секция listener

Секция listener настраивает адреса и порты, на которых Stronghold будет отвечать на запросы. Сейчас существует два типа слушателей:

1. TCP
2. Unix Domain Socket

TCP

TCP-слушатель настраивает Stronghold на прослушивание TCP-адреса/порта.

listener "tcp" {
  address = "127.0.0.1:8200"
}

Можно указать секцию listener больше одного раза, чтобы Stronghold прослушивал несколько интерфейсов. При настройке нескольких слушателей обязательно указывайте параметры api_addr и cluster_addr, чтобы Stronghold анонсировал другим узлам корректный адрес.

Сокрытие конфиденциальных данных для неаутентифицированных эндпоинтов

Неаутентифицированные API-эндпоинты могут возвращать такую конфиденциальную информацию:

1. Номер версии Stronghold.
2. Дату сборки бинарного файла Stronghold.
3. Имя кластера Stronghold.
4. IP-адрес узлов в кластере.

При этом Stronghold позволяет настроить каждую секцию tcp listener так, чтобы при необходимости удалить эти данные из ответов API. Удаление чувствительной информации на основе конфигурации секции listener поддерживают три эндпоинта API:

1. /sys/health
2. /sys/leader
3. /sys/seal-status

Удалённую информацию Stronghold заменяет пустой строкой — "". Также некоторые API Stronghold опускают ключи в ответе, если соответствующее значение пустое ("").

{% alert level="warning" %}Удаление значений влияет на ответы для всех клиентов API. Клиентская командная строка Stronghold и пользовательский интерфейс используют ответы API Stronghold. В результате настройки удаления будут применяться к выводу в CLI и пользовательском интерфейсе, а также к прямым вызовам API.

Пользовательские заголовки ответов

Stronghold позволяет задавать пользовательские HTTP-заголовки ответов для корневого пути (/) и для эндпоинтов API (/v1/). Эти заголовки определяются на основе возвращаемого кода состояния. Например, пользователь может определить один список пользовательских заголовков ответов для кода состояния 200 и другой список для кода состояния 307.

Эндпоинт API /sys/config/ui позволяет пользователям устанавливать специфические для UI пользовательские заголовки. Однако если заголовок настроен в конфигурационном файле, перенастроить его через данный эндпоинт нельзя. Чтобы удалить пользовательский заголовок или изменить его значение, нужно изменить файл конфигурации Stronghold и отправить сигнал SIGHUP в процесс Stronghold.

Если в конфигурационном файле задан пользовательский заголовок и такой же заголовок используют внутренние процессы Stronghold, настроенный заголовок не будет принят. Например, не будет принят пользовательский заголовок с префиксом X-Vault-. При запуске в журналах Stronghold будет зарегистрировано соответствующее сообщение.

Порядок приоритетов

Если один и тот же заголовок указан как в конфигурационном файле, так и через эндпоинт API /sys/config/ui, приоритет отдаётся заголовку из конфигурационного файла. Например, заголовок Content-Security-Policy по умолчанию определён в эндпоинте API /sys/config/ui. Однако если этот же заголовок прописан в конфигурационном файле, Stronghold использует именно его, подставляя в ответ вместо значения по умолчанию в /sys/config/ui.

Параметры слушателя TCP

• address — строковый параметр в формате ip-адрес:порт. Указывает назначенные для прослушивания адрес и порт. Параметр может быть динамически определён с помощью шаблона go-sockaddr, который разрешается во время выполнения.

• cluster_address — строковый параметр в формате ip-адрес:порт. Указывает адрес и порт, назначенные для прослушивания запросов типа сервер-сервер в кластере. По умолчанию значение параметра на один порт выше значения address. В большинстве случаев задавать cluster_address не нужно, однако параметр может быть полезен, если изолированным серверам Stronghold нужно перескакивать через TCP-балансировщик нагрузки или использовать какую-то другую схему для связи. Параметр может быть динамически определён с помощью шаблона go-sockaddr, который разрешается во время выполнения.

• http_idle_timeout — строковый параметр. Указывает максимальное время ожидания следующего запроса при включении режима keep-alives. Значение задаётся с помощью суффикса времени, например "40s" (40 секунд) или "1h" (1 час). Если значение параметра равно нулю, будет использоваться значение http_read_timeout. Если же оба этих значения равны нулю, будет использоваться значение http_read_header_timeout.

• http_read_header_timeout — строковый параметр. Указывает время, отведённое на чтение заголовков запроса. Значение задаётся с помощью суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

• http_read_timeout — строковый параметр. Указывает максимальную продолжительность чтения всего запроса, включая заголовки и тело. Значение задаётся с помощью суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

• http_write_timeout — строковый параметр. Указывает максимальную продолжительность записи ответа. Сбрасывается каждый раз, когда считывается заголовок нового запроса. Значение по умолчанию 0 означает отсутствие ограничения по времени. Задаётся с помощью суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

• max_request_size — целочисленный параметр. Указывает максимально допустимый размер запроса в байтах. По умолчанию равен 32 МБ, если не задан или установлен в 0. Значение меньше 0 отключает ограничение.

• max_request_duration — строковый параметр. Указывает максимальное время обработки запроса, после которого Stronghold его отменит. Этот параметр отменяет значение default_max_request_duration для данного слушателя. Задаётся с помощью суффикса времени, например "90s" (90 секунд).

• proxy_protocol_behavior — строковый параметр. Включает поведение протокола PROXY версии 1 для слушателя. Принимаются следующие значения:

• use_always — всегда будет использоваться IP-адрес клиента.
• allow_authorized — будет использоваться IP-адрес клиента, если исходный IP-адрес находится в списке.
• proxy_protocol_authorized_addrs — будет использоваться исходный IP-адрес, если исходного IP в списке нет.

• deny_unauthorized — если исходный IP-адрес не в списке proxy_protocol_authorized_addrs, трафик будет отклонён.

• proxy_protocol_authorized_addrs — строковый параметр или массив строк. Определяет список разрешённых IP-адресов источников для использования с протоколом PROXY. Не требуется, если для параметра proxy_protocol_behavior установлено значение use_always. При указании в формате строки значения нужно разделить запятыми. Значение proxy_protocol_authorized_addrs не может быть пустым: нужно указать как минимум один IP-адрес источника.

• redact_addresses — логический параметр. Скрывает значения leader_address и cluster_leader_address в соответствующих ответах API, если установлен в значение true.

• redact_cluster_name — логический параметр. Скрывает значения cluster_name в соответствующих ответах API, если установлен в значение true.

• redact_version — логический параметр. Скрывает значения version и build_date в соответствующих ответах API, если установлен в значение true.

• tls_disable — логический параметр. Указывает, будет ли отключен TLS. Stronghold использует TLS по умолчанию, и поэтому необходимо явно отключить TLS, чтобы отказаться от небезопасной связи. Отключение может привести к отключению некоторых функций пользовательского интерфейса.

• tls_cert_file — строковый параметр. Указывает путь к файлу сертификата для TLS. Файл должен быть в кодировке PEM. Для настройки слушателя на использование сертификата ЦС нужно объединить основной сертификат и сертификат ЦС. При этом в начале объединённого файла должен находиться основной сертификат. Указанный в параметре tls_cert_file путь используется при запуске Stronghold. Изменение значения во время работы Stronghold ни на что не повлияет.

• tls_key_file — строковый параметр. Указывает путь к закрытому ключу для сертификата. Файл должен быть в кодировке PEM. Если файл ключа зашифрован, при запуске сервера потребуется ввести парольную фразу. При перезагрузке конфигурации с помощью SIGHUP парольная фраза между файлами ключей должна оставаться неизменной. Указанный в параметре tls_key_file путь используется при запуске Stronghold. Изменение значения во время работы Stronghold ни на что не повлияет.

• tls_min_version — строковый параметр. Указывает минимальную версию TLS, поддерживаемую слушателем. Допустимые значения: "tls10", "tls11", "tls12" или "tls13". TLS 1.1 и ниже, то есть значения tls10 и tls11, указанные в параметре tls_min_version, считаются небезопасными и не рекомендуются.

• tls_max_version — строковый параметр. Указывает максимальную версию TLS, поддерживаемую слушателем. Допустимые значения: "tls10", "tls11", "tls12" или "tls13". TLS 1.1 и ниже, то есть значения tls10 и tls11, указанные в параметре tls_max_version, считаются небезопасными и не рекомендуются.

• tls_cipher_suites — строковый параметр. Указывает список поддерживаемых наборов шифров в виде списка значений, перечисленных через запятую. Список всех доступных наборов шифров можно найти в документации по TLS для Go.

Go использует список, заданный в параметре tls_cipher_suites, только для TLSv1.2 и более ранних версий. Порядок шифров при этом не важен. Для эффективности tls_cipher_suites, параметр tls_max_version нужно установить в "tls12", чтобы предотвратить согласование TLSv1.3. Подробнее об этом и других связанных с TLS изменениях можно узнать из официального поста о TLS от Go.

• tls_require_and_verify_client_cert — логический параметр. Включает аутентификацию клиента для данного слушателя. При этом слушателю понадобится представленный клиентский сертификат, успешно проверенный на системных ЦС.

• tls_client_ca_file — строковый параметр. Файл сертификата ЦС в кодировке PEM, который используется для проверки подлинности клиента.

• tls_disable_client_certs — логический параметр. Отключает аутентификацию клиента для данного слушателя. По умолчанию — при установленном значении false — Stronghold запрашивает сертификаты аутентификации клиента, когда они доступны.

Внимание. Поля tls_disable_client_certs и tls_require_and_verify_client_cert в секции listener — взаимоисключающие. Обязательно убедитесь, что они оба не установлены в значение true. С настройками по умолчанию проверка клиента TLS не обязательна. |

• x_forwarded_for_authorized_addrs — строковый параметр. Может быть указан в формате строки со списком разделённых запятыми значений или в формате JSON-массива. Указывает список CIDR исходных IP-адресов, для которых заголовок X-Forwarded-For будет доверенным. Включает поддержку X-Forwarded-For.

Например, Stronghold получает соединение от IP-адреса балансировщика нагрузки 1.2.3.4. Добавление 1.2.3.4 в параметр x_forwarded_for_authorized_addrs приведёт к тому, что в поле remote_address журнала аудита будет отображён IP-адрес клиента, инициировавшего подключение, например 3.4.5.6. Важно, чтобы балансировщик нагрузки отправлял IP-адрес подключающегося клиента в заголовке X-Forwarded-For.

• x_forwarded_for_hop_skips — строковый параметр. Указывает количество адресов, которые нужно пропустить с конца набора переходов. Например, если в заголовке X-Forwarded-For указаны адреса 1.2.3.4, 2.3.4.5, 3.4.5.6, 4.5.6.7, и параметр x_forwarded_for_hop_skips установлен в значение "1", то в качестве IP-адреса исходящего клиента будет использован 3.4.5.6.

• x_forwarded_for_reject_not_authorized — логический параметр. При установке значения false позволяет игнорировать заголовок X-Forwarded-For, если он поступает в соединении с неавторизованного адреса. Клиентское соединение в этом случае будет использоваться как есть, а не будет отклонено.

• x_forwarded_for_reject_not_present — логический параметр. При установке значения false позволяет использовать адрес клиента как есть, если заголовок X-Forwarded-For отсутствует или пуст, вместо того чтобы отклонить соединение с клиентом.

• disable_replication_status_endpoints — логический параметр. При установке значения true отключит эндпоинты статуса репликации для данного слушателя.

Параметры telemetry:

• unauthenticated_metrics_access — логический параметр. При установке значения true разрешает неаутентифицированный доступ к эндпоинту /v1/sys/metrics.

Параметры profiling:

• unauthenticated_pprof_access — логический параметр. При установке значения true разрешает неаутентифицированный доступ к эндпоинту /v1/sys/pprof.

Параметры inflight_requests_logging:

• unauthenticated_in_flight_requests_access — логический параметр. При установке значения true разрешает неаутентифицированный доступ к эндпоинту /v1/sys/in-flight-req.

Параметры custom_response_headers default:

Список сопоставлений типа:

{
  "ключ1" = ["значение1", "значение 2", ...],
  "ключ2" = ["значение1", "значение 2", ...],
}

позволяет сопоставить имена заголовков по умолчанию с массивом значений. Заголовки по умолчанию устанавливаются на всех эндпоинтах независимо от значения кода состояния.

Список сопоставлений типа:

{
  "ключ1" = ["значение1", "значение 2", ...],
  "ключ2" = ["значение1", "значение 2", ...],
}

позволяет сопоставить имена заголовков с массивом значений. Заголовки, указанные в этой секции устанавливаются для указанных кодов состояния.

Список сопоставлений типа:

{
  "ключ1" = ["значение1", "значение 2", ...],
  "ключ2" = ["значение1", "значение 2", ...],
}

позволяет сопоставить имена заголовков с массивом значений. Заголовки, указанные в этой секции устанавливаются для кодов состояния, попадающих в указанные группы кодов состояния.

Примеры конфигурации секции listener tcp

Пример 1. Указание необходимых параметров для TLS.

Здесь демонстрируется указание сертификата и ключа для TLS.

listener "tcp" {
  tls_cert_file = "/etc/certs/tls.crt"
  tls_key_file  = "/etc/certs/tls.key"
}

Пример 2. Прослушивание на нескольких интерфейсах.

Здесь показано прослушивание Stronghold на частном интерфейсе, а также localhost.

listener "tcp" {
  address = "127.0.0.1:8200"
}

listener "tcp" {
  address = "10.0.0.5:8200"
}

# Advertise the non-loopback interface
api_addr = "https://10.0.0.5:8200"
cluster_addr = "https://10.0.0.5:8201"

Пример 3. Разрешение неаутентифицированного доступа к метрикам.

listener "tcp" {
  telemetry {
    unauthenticated_metrics_access = true
  }
}

Пример 4. Разрешение неаутентифицированного доступа к профилированию.

listener "tcp" {
  profiling {
    unauthenticated_pprof_access = true
    unauthenticated_in_flight_request_access = true
  }
}

Пример 5. Настройка пользовательских HTTP-заголовков ответов.

Операторы могут настроить подсекцию custom_response_headers в секции listener для добавления пользовательских HTTP-заголовков, соответствующих их приложениям.

listener "tcp" {
  custom_response_headers {
    "default" = {
      "Strict-Transport-Security" = ["max-age=31536000","includeSubDomains"],
      "Content-Security-Policy" = ["connect-src https://clusterA.vault.external/"],
      "X-Custom-Header" = ["Custom Header Default Value"],
    },
    "2xx" = {
      "Content-Security-Policy" = ["connect-src https://clusterB.vault.external/"],
      "X-Custom-Header" = ["Custom Header Value 1", "Custom Header Value 2"],
    },
    "301" = {
      "Strict-Transport-Security" = ["max-age=31536000"],
      "Content-Security-Policy" = ["connect-src https://clusterC.vault.external/"],
    },
  }
}

Примеры пользовательских HTTP-заголовков — Strict-Transport-Security и Content-Security-Policy. Их можно настроить для усиления безопасности приложения, которое взаимодействует с эндпоинтами Stronghold. Сканеры уязвимостей часто исследуют такие связанные с безопасностью HTTP-заголовки. Также можно настроить и специфические для приложения пользовательские заголовки, как настроен X-Custom-Header в примере выше.

Если заголовок определён в нескольких подразделах кодов состояния, будет возвращён заголовок, соответствующий наиболее конкретному коду ответа. Из примера конфигурации ниже, ответ 306 вернёт значение заголовка Custom для 3xx, а 307 вернёт значение заголовка Custom для 307.

listener "tcp" {
  custom_response_headers {
    "default" = {
       "X-Custom-Header" = ["default Custom header value"]
    },
    "3xx" = {
       "X-Custom-Header" = ["3xx Custom header value"]
    },
    "307" = {
       "X-Custom-Header" = ["307 Custom header value"]
    }
  }
}

Пример 6. Прослушивание на всех IPv4- и IPv6-интерфейсах.

В этом примере Stronghold прослушивает все интерфейсы IPv4 и IPv6, включая localhost.

listener "tcp" {
  address         = "[::]:8200"
  cluster_address = "[::]:8201"
}

Пример 7. Прослушивание на определённых IPv6-адресах.

В примере настроено использование только IPv6 с привязкой к интерфейсу с IP-адресом 2001:1c04:90d:1c00:a00:27ff:fefa:58ec.

listener "tcp" {
  address         = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
  cluster_address = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"
}

Объявление не loopback-интерфейса:

api_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
cluster_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"

Примеры скрытия информации

Пример 1. Конфигурация с использованием параметров redact_addresses, redact_cluster_name и redact_version для скрытия информации в ответах.

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_1"
}

listener "tcp" {
  address             = "127.0.0.1:8200",
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
  redact_addresses    = "true"
  redact_cluster_name = "true"
  redact_version      = "true"
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}

Пример 2. Результаты применения параметров скрытия API: /sys/health.

Пример вызова /sys/health/, где скрыты cluster_name и version. Поле cluster_name полностью исключено из ответа, а version представлено пустой строкой ("").

$ curl -s https://127.0.0.1:8200/v1/sys/health | jq

{
  "initialized": true,
  "sealed": false,
  "standby": false,
  "performance_standby": false,
  "replication_performance_mode": "disabled",
  "replication_dr_mode": "disabled",
  "server_time_utc": 1715935559,
  "version": "",
  "cluster_id": "be574716-e7e9-a950-ee34-d62d56cd6d4a"
}

Пример 3. Результаты применения параметров скрытия API: sys/leader.

Пример вызова /sys/leader/, где скрыты leader_address и leader_cluster_address. Они установлены в пустую строку ("").

$ curl -s https://127.0.0.1:8200/v1/sys/leader | jq

{
  "ha_enabled": true,
  "is_self": true,
  "active_time": "2024-05-13T07:54:20.471072843Z",
  "leader_address": "",
  "leader_cluster_address": "",
  "performance_standby": false,
  "performance_standby_last_remote_wal": 0,
  "raft_committed_index": 78,
  "raft_applied_index": 78
}

Пример 4. Результаты применения параметров скрытия API: sys/seal-status.

Пример вызова /sys/seal-status/, где скрыты поля cluster_name, build_date и version. Поле cluster_name полностью исключено из ответа, а build_date и version представлены пустыми строками ("").

$ curl -s https://127.0.0.1:8200/v1/sys/seal-status | jq

{
  "type": "shamir",
  "initialized": true,
  "sealed": false,
  "t": 3,
  "n": 6,
  "progress": 0,
  "nonce": "",
  "version": "",
  "build_date": "",
  "migration": false,
  "cluster_id": "be574716-e7e9-a950-ee34-d62d56cd6d4a",
  "recovery_seal": false,
  "storage_type": "raft"
}

Пример 5. CLI: stronghold status

Команда CLI stronghold status использует эндпоинты, которые поддерживают скрытие данных, поэтому в выводе скрываются Version, Build Date, HA Cluster и Active Node Address.

Version, Build Date и HA Cluster показывают n/a, потому что соответствующий эндпоинт вернул пустую строку. В свою очередь Active Node Address показывается как <none>, потому что адрес был опущен в ответе API.

stronghold status

Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            6
Threshold               3
Version                 n/a
Build Date              n/a
Storage Type            raft
HA Enabled              true
HA Cluster              n/a
HA Mode                 active
Active Since            2024-05-13T07:54:20.471072843Z
Active Node Address     <none>
Raft Committed Index    78
Raft Applied Index      78

Unix

Конфигурация слушателя Unix настраивает Stronghold на прослушивание на указанном Unix доменном сокете:

listener "unix" {
  address = "/run/vault.sock"
}

Можно указать секцию listener больше одного раза, чтобы Stronghold прослушивал несколько сокетов.

Параметры слушателя Unix

• address — обязательный строковый параметр. Указывает адрес для привязки Unix-сокета.

• socket_mode — необязательный строковый параметр. Изменяет права доступа и специальные флаги Unix-сокета.

• socket_user — необязательный строковый параметр. Изменяет пользователя-владельца Unix-сокета.

• socket_group — необязательный строковый параметр. Изменяет группу-владельца Unix-сокета.

Примеры конфигурации секции listener unix

Пример 1. Прослушивание на нескольких сокетах.

В примере Stronghold настроен на прослушивание на указанном сокете и сокете по умолчанию.

listener "unix" {}

listener "unix" {
  address = "/var/run/vault.sock"
}

Пример 2. Прослушивание на нескольких интерфейсах.

В этом примере Stronghold настроен на прослушивание на указанном Unix-сокете, а также на loopback-интерфейсе.

listener "unix" {
  address = "/var/run/vault.sock"
}

listener "tcp" {
  address = "127.0.0.1:8200"
}

Пример 3. Настройка прав.

В примере показана конфигурация прав и владельца — пользователя и группы.

listener "unix" {
  address = "/var/run/vault.sock"
  socket_mode = "644"
  socket_user = "1000"
  socket_group = "1000"
}

Секция storage

Секция storage настраивает бэкенд хранения, который используется для долговременного хранения данных Stronghold.

У каждого бэкенда — свои плюсы и минусы, преимущества и компромиссы. Так, одни бэкенды предоставляют более надёжный процесс резервного копирования и восстановления, а другие поддерживают высокую доступность.

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

Бэкенд хранилища настраивается в конфигурационном файле Stronghold через секцию storage.

storage [NAME] {
  [PARAMETERS...]
}

Например:

storage "file" {
  path = "/mnt/vault/data"
}

Для параметров конфигурации, которые также считывают переменную окружения, приоритет будет отдан переменной окружения, а не значениям в файле конфигурации.

Бэкенд хранения filesystem

Бэкенд хранения типа filesystem сохраняет данные Stronghold в файловой системе, используя стандартную структуру каталогов. Его можно использовать в ситуациях с одним долговечным сервером или для локальной разработки, где долговечность не является критической.

Бэкенд хранения типа filesystem не поддерживает высокую доступность.

Пример конфигурации секции storage с таким бэкендом хранения:

storage "file" {
  path = "/mnt/vault/data"
}

Хотя данные Stronghold и зашифрованы в состоянии покоя, нужно принять соответствующие меры для обеспечения безопасности доступа к файловой системе.

Параметры

• path — обязательный строковый параметр. Абсолютный путь к каталогу, где будут храниться данные. Если каталога не существует, Stronghold его создаст.

Бэкенд хранения Raft

Бэкенд интегрированного хранилища (Raft) используется для хранения данных Stronghold. В отличие от других бэкендов хранения, он не работает с одним источником данных: вместо этого все узлы кластера Stronghold будут иметь реплицированную копию данных. Данные реплицируются между всеми узлами с помощью алгоритма консенсуса Raft.

Бэкенд хранения Raft поддерживает высокую доступность.

Пример конфигурации секции storage с бэкендом хранения типа Raft:

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_1"
}
cluster_addr = "http://127.0.0.1:8201"

При использовании бэкенда интегрированного хранилища нужно указать параметр cluster_addr, то есть адрес и порт, которые будут использоваться для связи между узлами в кластере Raft.

Также при использовании бэкенда интегрированного хранилища нельзя объявлять отдельный бэкенд ha_storage. Плюс настоятельно рекомендуется установить disable_mlock в значение true и отключить своппинг в системе.

Параметры

• path — cтроковый параметр. Указывает путь к каталогу в файловой системе, где хранятся данные Stronghold. Значение может быть переопределено установкой переменной окружения VAULT_RAFT_PATH.

• node_id — cтроковый параметр. Идентификатор узла в кластере Raft. Значение может быть переопределено установкой переменной окружения VAULT_RAFT_NODE_ID.

• performance_multiplier — целочисленный параметр. Множитель, который используют серверы для масштабирования ключевых параметров времени Raft.

Настройка параметра performance_multiplier влияет на время, необходимое Stronghold для обнаружения сбоев лидера и выбора лидера. Это достигается за счёт требования большего количества сетевых и вычислительных ресурсов для улучшения производительности. Если значение не задано или установлено в 0, будет использоваться стандартное время, описанное ниже. Более низкие значения используются для ужесточения времени и повышения чувствительности, а более высокие ослабляют время и снижают чувствительность.

По умолчанию Stronghold использует временные параметры с более низкой производительностью, которые подходят для серверов Stronghold, соответствующих минимальным требованиям. Сейчас это эквивалентно установке значения в 5, но стандарт может измениться в будущих версиях Stronghold, если поменяется целевой минимальный профиль сервера. Установка значения performance_multiplier в 1 настроит Raft на режим с наивысшей производительностью и рекомендуется для серверов Stronghold в production-среде. Максимально допустимое значение — 10.

• trailing_logs — целочисленный параметр. Контролирует количество записей журнала, которые остаются в хранилище журналов на диске после создания снимка. Этот параметр стоит регулировать только если последователи не могут догнать лидера из-за очень большого размера снимка и высокой пропускной способности записи, вызывающей усечение журнала до того, как снимок может быть полностью установлен.

Если вам нужно использовать это для восстановления кластера, рассмотрите возможность снижения пропускной способности записи или объёма данных, которые хранятся в Stronghold. Значение по умолчанию — 10000, и оно подходит для всех нормальных рабочих нагрузок. Метрика trailing_logs не тождественна параметру max_trailing_logs.

• snapshot_threshold — целочисленный параметр. Контролирует минимальное количество записей фиксации Raft между снимками, которые сохраняются на диск. Обычно этот низкоуровневый параметр не требует изменений. В сильно загруженных кластерах, которые испытывают чрезмерный дисковый ввод-вывод, можно увеличить значение, чтобы снизить нагрузку на диск и минимизировать вероятность одновременного создания снимков на всех серверах.

Увеличение параметра snapshot_threshold — это компромисс между дисковым вводом-выводом и дисковым пространством, так как журнал Raft будет значительно расти, и пространство в файле в raft.db нельзя будет очистить до следующего снимка. Кроме того, при восстановлении после сбоев или переключении на резервный узел серверам понадобится больше времени, ведь потребуется воспроизвести больше журналов. Значение по умолчанию — 8192.

• snapshot_interval — целочисленный параметр. Интервал между снимками в секундах, который контролирует, как часто Raft проверяет необходимость сделать снимок. Чтобы предотвратить ситуацию, когда весь кластер создаёт снимок одновременно, Raft случайным образом выбирает время между указанным интервалом и его удвоенным значением. По умолчанию 120 секунд.

• retry_join — список параметров. Позволяет настроить набор параметров подключения для других узлов кластера. Этот набор используется для помощи узлам в поиске лидера для присоединения к кластеру. Можно задать несколько секций retry_join.

Если параметры подключения для всех узлов в кластере известны заранее, можно включить эти секции. В таком случае как только один из узлов будет инициализирован как лидер, оставшиеся будут использовать свою конфигурацию retry_join для поиска лидера и присоединения к кластеру. Обратите внимание, что при использовании схемы разделения секрета Шамира присоединенные узлы нужно будет разблокировать вручную.

Подробнее о параметрах секции retry_join — в разделе Параметры секции retry_join.

• retry_join_as_non_voter — логический параметр. Если установить значение true, то любая конфигурация retry_join присоединяется к кластеру Raft как не участвующая в голосовании. Узел не будет участвовать в кворуме Raft, но будет получать поток репликации данных. Это позволяет добавить кластеру масштабируемость чтения.

Опция имеет тот же эффект, что и флаг -non-voter для команды stronghold operator raft join, но влияет только на статус голосования при присоединении через конфигурацию retry_join. Параметр можно переопределить на true, установив переменную окружения VAULT_RAFT_RETRY_JOIN_AS_NON_VOTER в непустое значение. Действует только при наличии хотя бы одной секции retry_join.

• max_entry_size — целочисленный параметр. Настройка максимального количество байт для записи Raft. Применяется как к операциям put, так и к транзакциям. Любая операция put или транзакция, превышающая это значение конфигурации, приведёт к сбою соответствующей операции. У Raft есть рекомендуемый максимальный размер данных в записи журнала. Он основан на текущей архитектуре, стандартном времени и т. д.

Интегрированное хранилище также использует размер блока — порог, применяемый для разделения большого значения на блоки. По умолчанию размер блока равен максимальному размеру записи журнала Raft. Значение по умолчанию 1048576.

• autopilot_reconcile_interval — строковый параметр. Задаёт временной интервал, после которого автопилот обнаружит любые изменения состояния.

Изменение состояния может означать множество вещей, например: 1. узел, изначально добавленный как не голосующий в кластер Raft, успешно завершил период стабилизации, что квалифицирует его для продвижения в голосующие; 2. узел должен получить статус unhealthy в API состояния; 3. узел был помечен как dead и должен быть исключён из конфигурации Raft.

Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

• autopilot_update_interval — строковый параметр. Временной интервал, после которого автопилот будет опрашивать Stronghold на предмет обновления интересующей информации. Включает такие данные, как конфигурация автопилота и его текущее состояние, конфигурация Raft, известные серверы, последний индекс Raft и статистика для всех известных серверов. Полученная информация будет использоваться для расчёта следующего состояния автопилота. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

Параметры секции retry_join

• leader_api_addr — строковый параметр. IP-адрес возможного узла-лидера.

• leader_tls_servername — строковый параметр. Имя сервера TLS, которое используется при подключении по HTTPS. Должно соответствовать одному из имён в DNS SANs (Subject Alternative Names) TLS-сертификата лидера. Узел использует leader_tls_servername для верификации сертификата лидера, когда пытается соединиться с лидером кластера. Это помогает обеспечить безопасность соединения и убедиться, что соединение происходит с правильным сервером.

• leader_ca_cert_file — строковый параметр. Путь к файлу с сертификатом ЦС возможного узла-лидера.

• leader_client_cert_file — строковый параметр. Путь к файлу сертификата клиента, который используется для аутентификации при соединении с лидером кластера по протоколу TLS. Узел Raft предъявляет этот сертификат при установлении защищённого соединения с лидером, чтобы подтвердить свою подлинность.

• leader_client_key_file — строковый параметр. Путь к файлу приватного ключа, который используется вместе с клиентским сертификатом для аутентификации при соединении с лидером кластера по протоколу TLS.

• leader_ca_cert — строковый параметр. Значение сертификата ЦС возможного узла-лидера.

• leader_client_cert — строковый параметр. Значение сертификата клиента, который используется для аутентификации при соединении с лидером кластера по протоколу TLS. Узел Raft предъявляет этот сертификат при установлении защищённого соединения с лидером, чтобы подтвердить свою подлинность.

• leader_client_key — строковый параметр. Значение приватного ключа, который используется вместе с клиентским сертификатом для аутентификации при соединении с лидером кластера по протоколу TLS.

Каждый блок retry_join может предоставлять TLS-сертификаты через пути к файлам или как значение сертификата, но не комбинацию обоих. Если передаётся значение сертификата, оно должно быть указано в одной строке с использованием \n для указания необходимых переносов на новую строку.

Секция ui

У Stronghold есть пользовательский интерфейс (веб-интерфейс) для операторов. С его помощью можно легко создавать, читать, обновлять и удалять секреты, проходить аутентификацию, распечатывать хранилище и многое другое.

Активация ui

По умолчанию пользовательский интерфейс Stronghold не активирован. Для его активации установите параметр ui в конфигурации сервера Stronghold в значение true.

ui = true

listener "tcp" {
  # ...
}

Доступ к Stronghold UI

Пользовательский интерфейс работает на том же порту, что и слушатель Stronghold. Для доступа к UI необходимо настроить хотя бы одну секцию listener.

listener "tcp" {
  address = "10.0.1.35:8200"
  ...
}

Пользовательский интерфейс в приведённом примере доступен по URL-адресу https://10.0.1.35:8200/ui/ с любой машины в подсети — при условии отсутствия межсетевых экранов или соответствующей их настройке. Также UI доступен по любой записи DNS, которая разрешается на этот IP-адрес.

Секция user_lockout

Секция user_lockout определяет настройки блокировки пользователей при неудачных попытках входа в Stronghold. Настройки можно применить как глобально — для всех методов аутентификации (userpass, ldap и approle) с использованием общего имени секции user_lockout "all", так и индивидуально — для конкретного метода, указав его имя в секции. Поддерживаются следующие значения: all, userpass, ldap и approle.

Конфигурации, заданные для конкретного метода аутентификации, имеют более высокий приоритет по сравнению с настройками для всех методов аутентификации с использованием общего имени секции user_lockout "all". Если присутствуют обе конфигурации, будут применены параметры, которые относятся к конкретному методу.

Параметры секции user_lockout

• lockout_threshold — строковый параметр. Указывает количество неудачных попыток входа в систему, после которых пользователь будет заблокирован.

• lockout_duration — строковый параметр. Указывает длительность блокировки пользователя. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

• lockout_counter_reset — строковый параметр. Определяет временной интервал, после которого счётчик блокировки сбрасывается, если нет неудачных попыток входа в систему. Значение указывается с использованием суффикса времени, например "40s" (40 секунд) или "1h" (1 час).

• disable_lockout — логический параметр. Отключает функцию блокировки пользователя, если установить значение true.

Резервные копии

Deckhouse Stronghold поддерживает создание расписания для выполнения автоматических резервных копий хранилища секретов. Так как Stronghold хранит данные на диске в зашифрованном виде, то резервная копия тоже будет содержать только зашифрованные данные. Для получения доступа к данным нужно будет развернуть резервную копию в кластер Stronghold и провести процедуру распечатывания хранилища.

Поддерживается сохранение резервных копий на локальный диск в выбранную папку, или в S3-совместимое хранилище.

Управление настройками резервных копий и просмотр их статуса доступны через API, CLI и UI.

Создание/обновление конфигурации автоматического бэкапа

Метод	Путь
POST	/sys/storage/raft/snapshot-auto/config/:name

Для взаимодействия потребуются sudo права в политиках доступа

Параметры

• interval (integer or string: ) - Время между снэпшотами. Это может быть либо целое число секунд, либо строка формата Go duration (например, 24h).

• retain (integer: 3) - Сколько снимков должно храниться; при записи снимка, если уже хранится больше снимков, чем это число, самые старые будут удалены.

• path_prefix (immutable string: ) - Для storage_type = local - каталог, в который будут записываться снимки. Для типов облачных хранилищ - префикс bucket, который следует использовать, также игнорируется ведущее `/`. Последующие `/` необязательны. Неизменяемое значение.

• file_prefix (immutable string: "stronghold-snapshot") - В пределах каталога или префикса бакета, заданного `path_prefix`, имя файла или объекта снэпшота будет начинаться с этой строки. Неизменяемое значение.

• storage_type (immutable string: ) - Одно из значений local или aws-s3. Остальные параметры, описанные ниже, специфичны для выбранного storage_type и имеют соответствующий префикс. Неизменяемое значение.

storage_type = "local"

• local_max_space (integer: 0) - Для storage_type=local максимальное пространство в байтах, которое будет использоваться для всех снимков с заданным file_prefix в каталоге path_prefix. Попытки создания снэпшотов будут неудачными, если будет недостаточно места. Значение 0 (по умолчанию) отключает проверку занимаемого места.

storage_type = "aws-s3"

• aws_s3_bucket (string: ) - Название S3 бакета для записи снэпшотов.
• aws_s3_region (string) - Регион S3 бакета.
• aws_access_key_id (string) - Идентификатор ключа для доступа в S3 бакет.
• aws_secret_access_key (string) - Секретный ключ для доступа в S3 бакет.
• aws_s3_endpoint (string) - Адрес сервиса S3 бакета.
• aws_s3_disable_tls (boolean) - Отключение TLS для конечной точки S3. Этот параметр следует использовать только для тестирования, обычно в сочетании с aws_s3_endpoint.
• aws_s3_ca_certificate (string) - Сертификат центра сертификации для конечной точки в формате PEM.

Примеры

Создание

Указываются все обязательные поля

d8 stronghold write sys/storage/raft/snapshot-auto/config/s3every5min - <<EOF
{
    "interval":          "5m",
    "path_prefix":       "backups",
    "file_prefix":       "main_stronghold",
    "retain":            "4",
    "storage_type":      "aws-s3",
    "aws_s3_bucket":         "my_bucket",
    "aws_s3_endpoint":       "minio.domain.ru",
    "aws_access_key_id":     "oWdPcQ50zTuMjJI",
    "aws_secret_access_key": "4NzZjboafWyfNTe7aUVgLUdrMurHjty43iUXHFBw"
}
EOF

Ответ:

Key    Value
---    -----
msg    successfully created config

Обновление

Можно указывать не все поля, уже существующие поля не будут изменены

d8 stronghold write sys/storage/raft/snapshot-auto/config/s3every5min - <<EOF
{
    "interval":          "3m",
    "retain":            "10",
    "aws_access_key_id":     "vnR9Rfp0toPPgK3",
    "aws_secret_access_key": "FuloGN1RZCtwINCLJtwHXTQ50zCL7s"
}
EOF

Ответ:

Key    Value
---    -----
msg    successfully updated config

Вывод списка существующих конфигураций автоматического бэкапа

Метод	Путь
LIST	/sys/storage/raft/snapshot-auto/config

Используется для получения списка названий всех существующих автоматических снэпшотов

Пример

d8 stronghold list sys/storage/raft/snapshot-auto/config

Ответ:

Keys
----
s3every5min
localEvery3min

Получение параметров конфигурации автоматического бэкапа

Метод	Путь
GET	/sys/storage/raft/snapshot-auto/config/:name

Пример

d8 stronghold read sys/storage/raft/snapshot-auto/config/s3every5min

Ответ:

Key                     Value
---                     -----
interval                300
path_prefix             backups
file_prefix             main_stronghold
retain                  4
storage_type            aws-s3
aws_s3_bucket           my_bucket
aws_s3_disable_tls      false
aws_s3_endpoint         minio.domain.ru
aws_s3_region           n/a
aws_s3_ca_certificate   n/a

Удаление конфигурации автоматического бэкапа

Метод	Путь
DELETE	/sys/storage/raft/snapshot-auto/config/:name

Пример

d8 stronghold delete sys/storage/raft/snapshot-auto/config/s3every5min

Ответ:

Key                    Value
---                    -----
consecutive_errors     0
last_snapshot_end      2025-01-31T15:24:14Z
last_snapshot_error    n/a
last_snapshot_start    2025-01-31T15:24:12Z
last_snapshot_url      https://minio.domain.ru/my_bucket/backups/main_stronghold_2025-01-31T15:24:12Z
next_snapshot_start    2025-01-31T15:29:12Z
snapshot_start         2025-01-31T15:24:12Z
snapshot_url           https://minio.domain.ru/my_bucket/backups/main_stronghold_2025-01-31T15:24:12Z

Получение статуса работы автоматического бэкапа

Метод	Путь
GET	/sys/storage/raft/snapshot-auto/status/:name

Пример

d8 stronghold read sys/storage/raft/snapshot-auto/status/s3every5min

Ответ:

Key    Value
---    -----
msg    successfully deleted config

Поддержка HSM

Stronghold поддерживает шифрование Root-ключа с помощью аппаратных модулей шифрования, таких как TPM2, Rutoken ЭЦП 3.0, JaCarta и т.д., имеющих поддержку PKCS11. Также поддерживаются SoftHSM

Для использования автоматического распечатывания через PKCS11 потребуется создать ключи в HSM и сконфигурировать Stronhold на использование этих ключей.

SoftHSM2

Установка libsofthsm2 и pkcs11-tool

apt install libsofthsm2 opensc

Создадим конфигурацию для softhsm2

mkdir /home/stronghold/softhsm
cd softhsm
echo "directories.tokendir = /home/stronghold/softhsm/" > /home/stronghold/softhsm2.conf

Создадим ключи в HSM

$ export SOFTHSM2_CONF=/home/stronghold/softhsm2.conf
$ HSMLIB="/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so"
$ pkcs11-tool --module $HSMLIB --init-token --so-pin 1234 --init-pin --pin 4321 --label my_token --login

Using slot 0 with a present token (0x0)
Token successfully initialized
User PIN successfully initialized

$ pkcs11-tool --module $HSMLIB -L

Available slots:
Slot 0 (0xe6829d3): SoftHSM slot ID 0xe6829d3
  token label        : my_token
  token manufacturer : SoftHSM project
  token model        : SoftHSM v2
  token flags        : login required, rng, token initialized, PIN initialized, other flags=0x20
  hardware version   : 2.6
  firmware version   : 2.6
  serial num         : 6a5468368e6829d3
  pin min/max        : 4/255
Slot 1 (0x1): SoftHSM slot ID 0x1
  token state:   uninitialized


$ pkcs11-tool --module $HSMLIB --login --pin 4321 --keypairgen --key-type rsa:4096 --label "vault-rsa-key"

Using slot 0 with a present token (0xe6829d3)
Key pair generated:
Private Key Object; RSA
  label:      vault-rsa-key
  Usage:      decrypt, sign, signRecover, unwrap
  Access:     sensitive, always sensitive, never extractable, local
Public Key Object; RSA 4096 bits
  label:      vault-rsa-key
  Usage:      encrypt, verify, verifyRecover, wrap
  Access:     local

Пример конфигурации Stronhold (config.hcl)

api_addr="https://0.0.0.0:8200"
log_level = "warn"
ui = true
listener "tcp" {
  address = "0.0.0.0:8200"
  tls_cert_file = "/home/stronghold/cert.pem"
  tls_key_file  = "/home/stronghold/key.pem"
  #tls_require_and_verify_client_cert = true
  #tls_client_ca_file = "ca.crt"
  tls_disable = "false"
}
storage "raft" {
  path = "/home/stronghold/data"
}

seal "pkcs11" {
  lib = "/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so"
  token_label = "my_token"
  pin = "4321"
  key_label = "vault-rsa-key"
  rsa_oaep_hash = "sha1"
}

Запуск Stronghold

export SOFTHSM2_CONF=/home/stronghold/softhsm2.conf
stronghold server -config config.hcl

Использование Rutoken ЭЦП 3.0

Потребуется скачать и установить библиотеку librtpkcs11ecp.so с сайта https://www.rutoken.ru/

Следующим шагом необходимо сгенерировать в токене публичный и приватный ключи, с помошью которых будет проводиться шифрование Root-ключа. Эту операцию можно провести с помощью утилиты pkcs11-tool из состава пакета opensc

$ HSMLIB="/usr/lib/librtpkcs11ecp.so"
$ pkcs11-tool --module $HSMLIB --init-token --so-pin 87654321 \
              --init-pin --pin 12345678 --label my_token --login
$ pkcs11-tool --module $HSMLIB --login --pin 12345678 --keypairgen \
              --key-type rsa:2048 --label "vault-rsa-key"

Using slot 0 with a present token (0x0)
Key pair generated:
Private Key Object; RSA
  label:      vault-rsa-key
  Usage:      decrypt, sign
  Access:     sensitive, always sensitive, never extractable, local
Public Key Object; RSA 2048 bits
  label:      vault-rsa-key
  Usage:      encrypt, verify
  Access:     local

Добавьте в конфигурацию Stronghold метод распечатки pkcs11

...
seal "pkcs11" {
  lib = "/usr/lib/librtpkcs11ecp.so"
  token_label = "my_token"
  pin = "12345678"
  key_label = "vault-rsa-key"
}

Запустите Stronghold и выполните init

systemctl start stronghold

stronghold operator init

Посмотрим статус

stronghold status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    5
Threshold                3
Version                  1.15.2+hsm
Build Date               2025-04-03T13:06:02Z
Storage Type             raft
Cluster Name             stronghold-cluster-6586e287
Cluster ID               d7552773-2e8a-33b6-9c32-6749a4c9af13
HA Enabled               false

Миграция с Shamir ключей на HSM

Измените конфигурацию, добавив блок seal

...
seal "pkcs11" {
  lib = "/usr/lib/librtpkcs11ecp.so"
  token_label = "my_token"
  pin = "12345678"
  key_label = "vault-rsa-key"
}

Перезапустите Stronghold. В логах вы увидите

2025-04-03T17:08:13.431+0300 [WARN]  core: entering seal migration mode; Stronghold will not automatically unseal even if using an autoseal: from_barrier_type=shamir to_barrier_type=pkcs11

Выполните миграцию, введя ключи распечатки

stronghold operator unseal -migrate

После этого при перезапуске Stronhold будет происходить распечатка через pkcs11

Миграция с HSM на Shamir ключи

Измените конфигурацию, добавив параметр disabled = "true" в раздел seal

...
seal "pkcs11" {
  lib = "/usr/lib/librtpkcs11ecp.so"
  token_label = "my_token"
  pin = "12345678"
  key_label = "vault-rsa-key"
  disabled = "true"
}

Перезапустите Stronghold.

Выполните миграцию, введя recovery-ключи.

stronghold operator unseal -migrate

После этого при перезапуске Stronhold будет необходимо ввести ключи распечатки

Основные концепции

Аутентификация

Authentication in Stronghold is the process by which user or machine supplied information is verified against an internal or external system. Stronghold supports multiple auth methods including GitHub, LDAP, AppRole, and more. Each auth method has a specific use case.

Before a client can interact with Stronghold, it must authenticate against an auth method. Upon authentication, a token is generated. This token is conceptually similar to a session ID on a website. The token may have attached policy, which is mapped at authentication time. This process is described in detail in the policies concepts documentation.

Auth methods

Stronghold supports a number of auth methods. Some backends are targeted toward users while others are targeted toward machines. Most authentication backends must be enabled before use. To enable an auth method:

d8 stronghold write sys/auth/my-auth type=userpass

This enables the "userpass" auth method at the path "my-auth". This authentication will be accessible at the path "my-auth". Often you will see authentications at the same path as their name, but this is not a requirement.

To learn more about this authentication, use the built-in path-help command:

$ d8 stronghold path-help auth/my-auth
# ...

Stronghold supports multiple auth methods simultaneously, and you can even mount the same type of auth method at different paths. Only one authentication is required to gain access to Stronghold, and it is not currently possible to force a user through multiple auth methods to gain access, although some backends do support MFA.

Tokens

There is an entire page dedicated to tokens, but it is important to understand that authentication works by verifying your identity and then generating a token to associate with that identity.

For example, even though you may authenticate using something like GitHub, Stronghold generates a unique access token for you to use for future requests. The CLI automatically attaches this token to requests, but if you're using the API you'll have to do this manually.

This token given for authentication with any backend can also be used with the full set of token commands, such as creating new sub-tokens, revoking tokens, and renewing tokens. This is all covered on the token concepts page.

Authenticating

Via the CLI

To authenticate with the CLI, d8 stronghold login is used. This supports many of the built-in auth methods. For example, with GitHub:

$ d8 stronghold login -method=github token=<token>
...

After authenticating, you will be logged in. The CLI command will also output your raw token. This token is used for revocation and renewal. As the user logging in, the primary use case of the token is renewal, covered below in the "Auth Leases" section.

To determine what variables are needed for an auth method, supply the -method flag without any additional arguments and help will be shown.

If you're using a method that isn't supported via the CLI, then the API must be used.

Via the API

API authentication is generally used for machine authentication. Each auth method implements its own login endpoint. Use the d8 stronghold path-help mechanism to find the proper endpoint.

For example, the GitHub login endpoint is located at auth/github/login. And to determine the arguments needed, d8 stronghold path-help auth/github/login can be used.

Auth leases

Just like secrets, identities have leases associated with them. This means that you must reauthenticate after the given lease period to continue accessing Stronghold.

To set the lease associated with an identity, reference the help for the specific auth method in use. It is specific to each backend how leasing is implemented.

And just like secrets, identities can be renewed without having to completely reauthenticate. Just use d8 stronghold token renew <token> with the leased token associated with your identity to renew it.

Идентичность

Identity

This document contains conceptual information about Identity along with an overview of the various terminologies and their concepts. The idea of Identity is to maintain the clients who are recognized by Stronghold. As such, Stronghold provides an identity management solution through the Identity secrets engine. For more information about the Identity secrets engine and how it is used, refer to the Identity Secrets Engine documentation.

Entities and aliases

Each user may have multiple accounts with various identity providers, and Stronghold supports many of those providers to authenticate with Stronghold. Stronghold Identity can tie authentications from various auth methods to a single representation. This representation of a consolidated identity is called an Entity and their corresponding accounts with authentication providers can be mapped as Aliases. In essence, each entity is made up of zero or more aliases. An entity cannot have more than one alias for a particular authentication backend.

For example, a user with accounts in both GitHub and LDAP can be mapped to a single entity in Stronghold with two aliases, one of type GitHub and one of type LDAP.

However, if both aliases are created on the same auth mount, such as a Github mount, both aliases cannot be mapped to the same entity. The aliases can have the same auth type, as long as the auth mounts are different, and still be associated to the same entity. The diagrams below illustrate both valid and invalid scenarios.

When a client authenticates via any credential backend (except the Token backend), Stronghold creates a new entity. It attaches a new alias to it if a corresponding entity does not already exist. The entity identifier will be tied to the authenticated token. When such tokens are used, their entity identifiers are audit logged, marking a trail of actions performed by specific users.

Entity management

Entities in Stronghold do not automatically pull identity information from anywhere. It needs to be explicitly managed by operators. This way, it is flexible in terms of administratively controlling the number of entities to be synced against Stronghold. In some sense, Stronghold will serve as a cache of identities and not as a source of identities.

Entity policies

Stronghold policies can be assigned to entities which will grant additional permissions to the token on top of the existing policies on the token. If the token presented on the API request contains an identifier for the entity and if that entity has a set of policies on it, then the token will be capable of performing actions allowed by the policies on the entity as well.

This is a paradigm shift in terms of when the policies of the token get evaluated. Before identity, the policy names on the token were immutable (not the contents of those policies though). But with entity policies, along with the immutable set of policy names on the token, the evaluation of policies applicable to the token through its identity will happen at request time. This also adds enormous flexibility to control the behavior of already issued tokens.

It is important to note that the policies on the entity are only a means to grant additional capabilities and not a replacement for the policies on the token. To know the full set of capabilities of the token with an associated entity identifier, the policies on the token should be taken into account.

{% alert level="warning" %}

NOTE: Be careful in granting permissions to non-readonly identity endpoints. If a user can modify an entity, they can grant it additional privileges through policies. If a user can modify an alias they can login with, they can bind it to an entity with higher privileges. If a user can modify group membership, they can add their entity to a group with higher privileges.

{% endalert %}

Mount bound aliases

Stronghold supports multiple authentication backends and also allows enabling the same type of authentication backend on different mount paths. The alias name of the user will be unique within the backend's mount. But identity store needs to uniquely distinguish between conflicting alias names across different mounts of these identity providers. Hence, the alias name in combination with the authentication backend mount's accessor, serve as the unique identifier of an alias.

The table below shows what information each of the supported auth methods uses to form the alias name. This is the identifying information that is used to match or create an entity. If no entities are explicitly created or merged, then one entity will be implicitly created for each object on the right-hand side of the table, when it is used to authenticate on a particular auth mount point.

Auth method	Name reported by auth method
AppRole	Role ID
JWT/OIDC	Configurable via user_claim to one of the presented claims (no default value)
Kerberos	Username
Kubernetes	Configurable via alias_name_source to one of: Service account UID (default), Service account name
LDAP	Username
RADIUS	Username
TLS Certificate	Subject CommonName
Token	entity_alias, if provided
Username (userpass)	Username

Implicit entities

Operators can create entities for all the users of an auth mount beforehand and assign policies to them, so that when users login, the desired capabilities to the tokens via entities are already assigned. But if that's not done, upon a successful user login from any of the authentication backends, Stronghold will create a new entity and assign an alias against the login that was successful.

Note that the tokens created using the token authentication backend will not normally have any associated identity information. An existing or new implicit entity can be assigned by using the entity_alias parameter, when creating a token using a token role with a configured list of allowed_entity_aliases.

Identity auditing

If the token used to make API calls has an associated entity identifier, it will be audit logged as well. This leaves a trail of actions performed by specific users.

Identity groups

Stronghold identity has support for groups. A group can contain multiple entities as its members. A group can also have subgroups. Policies set on the group are granted to all members of the group. During request time, when the token's entity ID is being evaluated for the policies that it has access to, policies that are inherited due to group memberships are granted along with the policies on the entity itself.

Group hierarchical permissions

Entities can be direct members of groups, in which case they inherit the policies of the groups they belong to. Entities can also be indirect members of groups. For example, if a GroupA has GroupB as subgroup, then members of GroupB are indirect members of GroupA. Hence, the members of GroupB will have access to policies on both GroupA and GroupB.

External vs internal groups

By default, the groups created in identity store are called the internal groups. The membership management of these groups should be carried out manually. A group can also be created as an external group. In this case, the entity membership in the group is managed semi-automatically. An external group serves as a mapping to a group that is outside of the identity store. External groups can have one (and only one) alias. This alias should map to a notion of a group that is outside of the identity store. For example, groups in LDAP and teams in GitHub. A username in LDAP belonging to a group in LDAP can get its entity ID added as a member of a group in Stronghold automatically during logins and token renewals. This works only if the group in Stronghold is an external group and has an alias that maps to the group in LDAP. If the user is removed from the group in LDAP, that change gets reflected in Stronghold only upon the subsequent login or renewal operation.

For information about Identity Secrets Engine, refer to Identity Secrets Engine.

Аренда

Lease, renew, and revoke

With every dynamic secret and service type authentication token, Stronghold creates a lease: metadata containing information such as a time duration, renewability, and more. Stronghold promises that the data will be valid for the given duration, or Time To Live (TTL). Once the lease is expired, Stronghold can automatically revoke the data, and the consumer of the secret can no longer be certain that it is valid.

The benefit should be clear: consumers of secrets need to check in with Stronghold routinely to either renew the lease (if allowed) or request a replacement secret. This makes the Stronghold audit logs more valuable and also makes key rolling a lot easier.

All dynamic secrets in Stronghold are required to have a lease. Even if the data is meant to be valid for eternity, a lease is required to force the consumer to check in routinely.

In addition to renewals, a lease can be revoked. When a lease is revoked, it invalidates that secret immediately and prevents any further renewals. For example, with the Kubernetes secrets engine, the service accounts will be deleted from Kubernetes the moment a lease is revoked. This renders the access keys invalid from that point forward.

Revocation can happen manually via the API, via the d8 stronghold lease revoke cli command, the user interface (UI) under the Access tab, or automatically by Stronghold. When a lease is expired, Stronghold will automatically revoke that lease. When a token is revoked, Stronghold will revoke all leases that were created using that token.

Note: The Key/Value Backend which stores arbitrary secrets does not issue leases although it will sometimes return a lease duration; see the documentation for more information.

Lease IDs

When reading a dynamic secret, such as via d8 stronghold read, Stronghold always returns a lease_id. This is the ID used with commands such as d8 stronghold lease renew and d8 stronghold lease revoke to manage the lease of the secret.

Lease durations and renewal

Along with the lease ID, a lease duration can be read. The lease duration is a Time To Live value: the time in seconds for which the lease is valid. A consumer of this secret must renew the lease within that time.

When renewing the lease, the user can request a specific amount of time they want remaining on the lease, termed the increment. This is not an increment at the end of the current TTL; it is an increment from the current time. For example, d8 stronghold lease renew -increment=3600 my-lease-id would request that the TTL of the lease be adjusted to 1 hour (3600 seconds). Having the increment be rooted at the current time instead of the end of the lease makes it easy for users to reduce the length of leases if they don't actually need credentials for the full possible lease period, allowing those credentials to expire sooner and resources to be cleaned up earlier.

The requested increment is completely advisory. The backend in charge of the secret can choose to completely ignore it. For most secrets, the backend does its best to respect the increment, but often limits it to ensure renewals every so often.

As a result, the return value of renewals should be carefully inspected to determine what the new lease is.

{% alert level="info" %}

To implement token renewal logic in your application code, refer to the code example in the Authentication doc.

{% endalert %}

Prefix-based revocation

In addition to revoking a single secret, operators with proper access control can revoke multiple secrets based on their lease ID prefix.

Lease IDs are structured in a way that their prefix is always the path where the secret was requested from. This lets you revoke trees of secrets. For example, to revoke all Userpass logins, you can do d8 stronghold lease revoke -prefix auth/userpass/. For more information about revoke command please check cli's lease revoke command docs.

This is very useful if there is an intrusion within a specific system: all secrets of a specific backend or a certain configured backend can be revoked quickly and easily.

Политики

Everything in Stronghold is path-based, and policies are no exception. Policies provide a declarative way to grant or forbid access to certain paths and operations in Stronghold. This section discusses policy workflows and syntaxes.

Policies are deny by default, so an empty policy grants no permission in the system.

Policy-authorization workflow

Before a human or machine can gain access, an administrator must configure Stronghold with an auth method. Authentication is the process by which human or machine-supplied information is verified against an internal or external system.

Consider the following diagram, which illustrates the steps a security team would take to configure Stronghold to authenticate using a corporate LDAP or ActiveDirectory installation. Even though this example uses LDAP, the concept applies to all auth methods.

Stronghold Auth Workflow

The security team configures Stronghold to connect to an auth method. This configuration varies by auth method. In the case of LDAP, Stronghold needs to know the address of the LDAP server and whether to connect using TLS. It is important to note that Stronghold does not store a copy of the LDAP database - Stronghold will delegate the authentication to the auth method.

The security team authors a policy (or uses an existing policy) which grants access to paths in Stronghold. Policies are written in HCL in your editor of preference and saved to disk.

The policy's contents are uploaded and stored in Stronghold and referenced by name. You can think of the policy's name as a pointer or symlink to its set of rules.

Most importantly, the security team maps data in the auth method to a policy. For example, the security team might create mappings like:

Members of the OU group "dev" map to the Stronghold policy named "readonly-dev".

or

Members of the OU group "ops" map to the Stronghold policies "admin" and "auditor".

Now Stronghold has an internal mapping between a backend authentication system and internal policy. When a user authenticates to Vault, the actual authentication is delegated to the auth method. As a user, the flow looks like:

Stronghold Auth Workflow

A user attempts to authenticate to Stronghold using their LDAP credentials, providing Stronghold with their LDAP username and password.

Stronghold establishes a connection to LDAP and asks the LDAP server to verify the given credentials. Assuming this is successful, the LDAP server returns the information about the user, including the OU groups.

Stronghold maps the result from the LDAP server to policies inside Stronghold using the mapping configured by the security team in the previous section. Stronghold then generates a token and attaches the matching policies.

Stronghold returns the token to the user. This token has the correct policies assigned, as dictated by the mapping configuration that was setup by the security team in advance.

The user then uses this Stronghold token for future operations. If the user performs the authentication steps again, they will get a new token. The token will have the same permissions, but the actual token will be different. Authenticating a second time does not invalidate the original token.

Policy syntax

Policies are written in HCL or JSON and describe which paths in Stronghold a user or machine is allowed to access.

Here is a very simple policy which grants read capabilities to the KVv1 path "secret/foo":

path "secret/foo" {
  capabilities = ["read"]
}

When this policy is assigned to a token, the token can read from "secret/foo". However, the token cannot update or delete "secret/foo", since the capabilities do not allow it. Because policies are deny by default, the token would have no other access in Stronghold.

Here is a more detailed policy, and it is documented inline:

# This section grants all access on "secret/*". further restrictions can be
# applied to this broad policy, as shown below.
path "secret/*" {
  capabilities = ["create", "read", "update", "patch", "delete", "list"]
}

# Even though we allowed secret/*, this line explicitly denies
# secret/super-secret. this takes precedence.
path "secret/super-secret" {
  capabilities = ["deny"]
}

# Policies can also specify allowed, disallowed, and required parameters. here
# the key "secret/restricted" can only contain "foo" (any value) and "bar" (one
# of "zip" or "zap").
path "secret/restricted" {
  capabilities = ["create"]
  allowed_parameters = {
    "foo" = []
    "bar" = ["zip", "zap"]
  }
}

Policies use path-based matching to test the set of capabilities against a request. A policy path may specify an exact path to match, or it could specify a glob pattern which instructs Stronghold to use a prefix match:

# Permit reading only "secret/foo". an attached token cannot read "secret/food"
# or "secret/foo/bar".
path "secret/foo" {
  capabilities = ["read"]
}

# Permit reading everything under "secret/bar". an attached token could read
# "secret/bar/zip", "secret/bar/zip/zap", but not "secret/bars/zip".
path "secret/bar/*" {
  capabilities = ["read"]
}

# Permit reading everything prefixed with "zip-". an attached token could read
# "secret/zip-zap" or "secret/zip-zap/zong", but not "secret/zip/zap
path "secret/zip-*" {
  capabilities = ["read"]
}

In addition, a + can be used to denote any number of characters bounded within a single path segment (this appeared in Stronghold 1.1):

# Permit reading the "teamb" path under any top-level path under secret/
path "secret/+/teamb" {
  capabilities = ["read"]
}

# Permit reading secret/foo/bar/teamb, secret/bar/foo/teamb, etc.
path "secret/+/+/teamb" {
  capabilities = ["read"]
}

Vault's architecture is similar to a filesystem. Every action in Stronghold has a corresponding path and capability - even Vault's internal core configuration endpoints live under the "sys/" path. Policies define access to these paths and capabilities, which controls a token's access to credentials in Stronghold.

Note: The policy rules that Stronghold applies are determined by the most-specific match available, using the priority rules described below. This may be an exact match or the longest-prefix match of a glob. If the same pattern appears in multiple policies, we take the union of the capabilities. If different patterns appear in the applicable policies, we take only the highest-priority match from those policies.

This means if you define a policy for "secret/foo*", the policy would also match "secret/foobar". Specifically, when there are potentially multiple matching policy paths, P1 and P2, the following matching criteria is applied:

If the first wildcard (+) or glob () occurs earlier in P1, P1 is lower priority If P1 ends in and P2 doesn't, P1 is lower priority If P1 has more + (wildcard) segments, P1 is lower priority If P1 is shorter, it is lower priority If P1 is smaller lexicographically, it is lower priority For example, given the two paths, "secret/" and "secret/+/+/foo/", the first wildcard appears in the same place, both end in and the latter has two wildcard segments while the former has zero. So we end at rule (3), and give "secret/+/+/foo/" lower priority.

Informational:The glob character referred to in this documentation is the asterisk (*). It is not a regular expression and is only supported as the last character of the path!

When providing list capability, it is important to note that since listing always operates on a prefix, policies must operate on a prefix because Stronghold will sanitize request paths to be prefixes.

Capabilities

Each path must define one or more capabilities which provide fine-grained control over permitted (or denied) operations. As shown in the examples above, capabilities are always specified as a list of strings, even if there is only one capability.

To determine the capabilities needed to perform a specific operation, the -output-policy flag can be added to the CLI subcommand. For an example, refer to the Print Policy Requirements document section.

The list of capabilities include the following:

create (POST/PUT) - Allows creating data at the given path. Very few parts of Stronghold distinguish between create and update, so most operations require both create and update capabilities. Parts of Stronghold that provide such a distinction are noted in documentation.

read (GET) - Allows reading the data at the given path.

update (POST/PUT) - Allows changing the data at the given path. In most parts of Vault, this implicitly includes the ability to create the initial value at the path.

patch (PATCH) - Allows partial updates to the data at a given path.

delete (DELETE) - Allows deleting the data at the given path.

list (LIST) - Allows listing values at the given path. Note that the keys returned by a list operation are not filtered by policies. Do not encode sensitive information in key names. Not all backends support listing.

In the list above, the associated HTTP verbs are shown in parenthesis next to the capability. When authoring policy, it is usually helpful to look at the HTTP API documentation for the paths and HTTP verbs and map them back onto capabilities. While the mapping is not strictly 1:1, they are often very similarly matched.

In addition to the standard set, there are some capabilities that do not map to HTTP verbs.

sudo - Allows access to paths that are root-protected. Tokens are not permitted to interact with these paths unless they have the sudo capability (in addition to the other necessary capabilities for performing an operation against that path, such as read or delete).

For example, modifying the audit log backends requires a token with sudo privileges.

deny - Disallows access. This always takes precedence regardless of any other defined capabilities, including sudo.

Note: Capabilities usually map to the HTTP verb, and not the underlying action taken. This can be a common source of confusion. Generating database credentials creates database credentials, but the HTTP request is a GET which corresponds to a read capability. Thus, to grant access to generate database credentials, the policy would grant read access on the appropriate path.

Templated policies

The policy syntax allows for doing variable replacement in some policy strings with values available to the token. Currently identity information can be injected, and currently the path keys in policies allow injection.

Parameters Name Description identity.entity.id The entity's ID identity.entity.name The entity's name identity.entity.metadata. Metadata associated with the entity for the given key identity.entity.aliases..id Entity alias ID for the given mount identity.entity.aliases..name Entity alias name for the given mount identity.entity.aliases..metadata. Metadata associated with the alias for the given mount and metadata key identity.entity.aliases..custom_metadata. Custom metadata associated with the alias for the given mount and custom metadata key identity.groups.ids..name The group name for the given group ID identity.groups.names..id The group ID for the given group name identity.groups.ids..metadata. Metadata associated with the group for the given key identity.groups.names..metadata. Metadata associated with the group for the given key

Examples

The following policy creates a section of the KVv2 Secret Engine to a specific user

path "secret/data/{{identity.entity.id}}/*" {
  capabilities = ["create", "update", "patch", "read", "delete"]
}

path "secret/metadata/{{identity.entity.id}}/*" {
  capabilities = ["list"]
}

If you wanted to create a shared section of KV that is associated with entities that are in a group.

# In the example below, the group ID maps a group and the path
path "secret/data/groups/{{identity.groups.ids.fb036ebc-2f62-4124-9503-42aa7A869741.name}}/*" {
  capabilities = ["create", "update", "patch", "read", "delete"]
}

path "secret/metadata/groups/{{identity.groups.ids.fb036ebc-2f62-4124-9503-42aa7A869741.name}}/*" {
  capabilities = ["list"]
}

Note: When developing templated policies, use IDs wherever possible. Each ID is unique to the user, whereas names can change over time and can be reused. This ensures that if a given user or group name is changed, the policy will be mapped to the intended entity or group.

If you want to use the metadata associated with an authentication plugin in your templates, you will need to get its mount accessor and access it via the aliases key.

You can get the mount accessor value using the following command:

d8 stronghold auth list

An example of the output:

Path           Type          Accessor                    Description
----           ----          --------                    -----------
kubernetes/    kubernetes    auth_kubernetes_xxxx        n/a
token/         token         auth_token_yyyy             token based credentials

The following templated policy allow to read the path associated with the Kubernetes service account namespace of the identity:

path "secret/data/{{identity.entity.aliases.auth_kubernetes_xxxx.metadata.service_account_namespace}}/*" {
  capabilities = ["read"]
}

Fine-grained control

In addition to the standard set of capabilities, Stronghold offers finer-grained control over permissions at a given path. The capabilities associated with a path take precedence over permissions on parameters.

Parameter constraints

Note: The use of globs (*) may result in surprising or unexpected behavior.

Note: The allowed_parameters, denied_parameters, and required_parameters fields are not supported for policies used with the version 2 kv secrets engine.

See the API Specification for more information.

Policies can take into account HTTP request parameters to further constrain requests, using the following options:

required_parameters - A list of parameters that must be specified.

# This requires the user to create "secret/profile" with a parameter/key named
# "name" and "id" where kv v1 is enabled at "secret/".
path "secret/profile" {
  capabilities = ["create"]
  required_parameters = ["name", "id"]
}

allowed_parameters - A list of keys and values that are permitted on the given path.

Setting a parameter with a value of the empty list allows the parameter to contain any value.

# This allows the user to update the password parameter value set on any
# users configured for userpass auth method. The password value can be
# anything. However, the user cannot update other parameter values such as
# token_ttl.
path "auth/userpass/users/*" {
  capabilities = ["update"]
  allowed_parameters = {
    "password" = []
  }
}

Usage example: The ACL Policy Path Templating tutorial demonstrates the use of allowed_parameters to permit a user to update the user's password when using the userpass auth method to log in with Stronghold.

Setting a parameter with a value of a populated list allows the parameter to contain only those values.

# This allows the user to create or update an encryption key for transit
# secrets engine enabled at "transit/". When you do, you can set the
# "auto_rotate_period" parameter value so that the key gets rotated.
# However, the rotation period must be "8h", "24h", or "5d". Any other value
# will result in an error.
path "transit/keys/*" {
  capabilities = ["create", "update"]
  allowed_parameters = {
    "auto_rotate_period" = ["8h", "24h", "5d"]
  }
}

If any keys are specified, all non-specified parameters will be denied unless the parameter "*" is set to an empty array, which will allow all other parameters to be modified. Parameters with specific values will still be restricted to those values.

# When kv v1 secrets engine is enabled at "secret/", this allows the user to
# create "secret/foo" with a parameter named "bar". The parameter "bar" can
# only contain the values "zip" or "zap", but any other parameters may be
# created with any value.
path "secret/foo" {
  capabilities = ["create"]
  allowed_parameters = {
    "bar" = ["zip", "zap"]
    "*"   = []
  }
}

denied_parameters - A list of keys and values that are not permitted on the given path. Any values specified here take precedence over allowed_parameters.

Setting a parameter with a value of the empty list denies any changes to that parameter.

# This allows the user to update the userpass auth method's user
# configurations (e.g., "password") but cannot update the "token_policies"
# and "policies" parameter values.
path "auth/userpass/users/*" {
  capabilities = ["update"]
  denied_parameters = {
    "token_policies" = []
    "policies" = []
  }
}

Setting a parameter with a value of a populated list denies any parameter containing those values.

# This allows the user to create or update token roles. However, the
# "allowed_policies" parameter value cannot be "admin", but the user can
# assign any other policies to the parameter.
path "auth/token/roles/*" {
  capabilities = ["create", "update"]
  denied_parameters = {
    "allowed_policies" = ["admin"]
  }
}

Setting to "*" will deny any parameter.

# This allows the user to create or update an encryption key for transit
# secrets engine enabled at "transit/". However, the user cannot set any of
# the configuration parameters. As a result, the created key will have all
# parameters set to default values.
path "transit/keys/*" {
  capabilities = ["create", "update"]
  denied_parameters = {
    "*" = []
  }
}

If any parameters are specified, all non-specified parameters are allowed, unless allowed_parameters is also set, in which case normal rules apply.

Parameter values also support prefix/suffix globbing. Globbing is enabled by prepending or appending or prepending a splat (*) to the value:

# Only allow a parameter named "bar" with a value starting with "foo-*".
path "secret/foo" {
  capabilities = ["create"]
  allowed_parameters = {
    "bar" = ["foo-*"]
  }
}

Note: the only value that can be used with the * parameter is [].

Parameter constraints limitations

Default values

Evaluation of policies with allowed_parameters, denied_parameters, and required_parameters happens without consideration of parameters' default values.

Given the following policy:

# The "no_store" parameter cannot be false
path "secret/foo" {
  capabilities = ["create"]
  denied_parameters = {
    "no_store" = [false, "false"]
  }
}

The following operation will error, because "no_store" is set to false:

d8 stronghold write secret/foo no_store=false value=bar

Whereas the following operation will succeed, even if the "no_store" parameter must be a boolean, and it defaults to false:

# Succeeds because "no_store=false" isn't present in the parameters
d8 stronghold write secret/foo value=bar

This is because the policy evaluator does not know what the default value is for the "no_store" parameter. All it sees is that the denied parameter isn't present in the command.

This can be resolved by requiring the "no_store" parameter in your policy:

path "secret/foo" {
  capabilities = ["create"]
  required_parameters = ["no_store"]
  denied_parameters = {
    "no_store" = [false, "false"]
  }
}

The following command, which previously succeeded, will now fail under the new policy because there is no "no_store" parameter:

d8 stronghold write secret/foo value=bar

Globbing

It's also important to note that the use of globbing may result in surprising or unexpected behavior:

# This allows the user to create, update, or patch "secret/foo" with a parameter
# named "bar". the values passed to parameter "bar" must start with "baz/"
# so values like "baz/quux" are fine. however, values like
# "baz/quux,wibble,wobble,wubble" would also be accepted. the API that
# underlies "secret/foo" might allow comma delimited values for the "bar"
# parameter, and if it did, specifying a value like
# "baz/quux,wibble,wobble,wubble" would result in 4 different values getting
# passed along. seeing values like "wibble" or "wobble" getting passed to
# "secret/foo" might surprise someone that expected the allowed_parameters
# constraint to only allow values starting with "baz/".
path "secret/foo" {
  capabilities = ["create", "update", "patch"]
  allowed_parameters = {
    "bar" = ["baz/*"]
  }
}

Required response wrapping TTLs

These parameters can be used to set minimums/maximums on TTLs set by clients when requesting that a response be wrapped, with a granularity of a second. These use duration format strings.

In practice, setting a minimum TTL of one second effectively makes response wrapping mandatory for a particular path.

min_wrapping_ttl - The minimum allowed TTL that clients can specify for a wrapped response. In practice, setting a minimum TTL of one second effectively makes response wrapping mandatory for a particular path. It can also be used to ensure that the TTL is not too low, leading to end targets being unable to unwrap before the token expires.

max_wrapping_ttl - The maximum allowed TTL that clients can specify for a wrapped response.

# This effectively makes response wrapping mandatory for this path by setting min_wrapping_ttl to 1 second.
# This also sets this path's wrapped response maximum allowed TTL to 90 seconds.
path "auth/approle/role/my-role/secret-id" {
    capabilities = ["create", "update"]
    min_wrapping_ttl = "1s"
    max_wrapping_ttl = "90s"
}

If both are specified, the minimum value must be less than the maximum. In addition, if paths are merged from different stanzas, the lowest value specified for each is the value that will result, in line with the idea of keeping token lifetimes as short as possible.

Built-in policies

Stronghold has two built-in policies: default and root. This section describes the two built-in policies.

Default policy

The default policy is a built-in Stronghold policy that cannot be removed. By default, it is attached to all tokens, but may be explicitly excluded at token creation time by supporting authentication methods.

The policy contains basic functionality such as the ability for the token to look up data about itself and to use its cubbyhole data. However, Stronghold is not prescriptive about its contents. It can be modified to suit your needs; Stronghold will never overwrite your modifications. If you want to stay up-to-date with the latest upstream version of the default policy, simply read the contents of the policy from an up-to-date dev server, and write those contents into your Vault's default policy.

To view all permissions granted by the default policy on your Stronghold installation, run:

d8 stronghold read sys/policy/default

To disable attachment of the default policy:

d8 stronghold token create -no-default-policy

or via the API:

curl \
  --request POST \
  --header "X-Vault-Token: ..." \
  --data '{"no_default_policy": "true"}' \
  https://stronghold.example.com/v1/auth/token/create

Root policy

The root policy is a built-in Stronghold policy that cannot be modified or removed. Any user associated with this policy becomes a root user. A root user can do anything within Stronghold. As such, it is highly recommended that you revoke any root tokens before running Stronghold in production.

When a Stronghold server is first initialized, there always exists one root user. This user is used to do the initial configuration and setup of Stronghold. After configured, the initial root token should be revoked and more strictly controlled users and authentication should be used.

To revoke a root token, run:

d8 stronghold token revoke "<token>"

or via the API:

curl \
  --request POST \
  --header "X-Vault-Token: ..." \
  --data '{"token": "<token>"}' \
  https://stronghold.example.com/v1/auth/token/revoke

Managing policies

Policies are authored (written) in your editor of choice. They can be authored in HCL or JSON, and the syntax is described in detail above. Once saved, policies must be uploaded to Stronghold before they can be used.

Listing policies

To list all registered policies in Vault:

d8 stronghold read sys/policy

or via the API:

curl \
  --header "X-Vault-Token: ..." \
  https://stronghold.example.com/v1/sys/policy

Creating policies

Policies may be created (uploaded) via the CLI or via the API. To create a new policy in Vault:

d8 stronghold policy write policy-name policy-file.hcl

or via the API:

curl \
  --request POST \
  --header "X-Vault-Token: ..." \
  --data '{"policy":"path \"...\" {...} "}' \
  https://stronghold.example.com/v1/sys/policy/policy-name

In both examples, the name of the policy is "policy-name". You can think of this name as a pointer or symlink to the policy ACLs. Tokens are attached policies by name, which are then mapped to the set of rules corresponding to that name.

Updating policies

Existing policies may be updated to change permissions via the CLI or via the API. To update an existing policy in Vault, follow the same steps as creating a policy, but use an existing policy name:

d8 stronghold write sys/policy/my-existing-policy policy=@updated-policy.json

or via the API:

curl \
  --request POST \
  --header "X-Vault-Token: ..." \
  --data '{"policy":"path \"...\" {...} "}' \
  https://stronghold.example.com/v1/sys/policy/my-existing-policy

Deleting policies Existing policies may be deleted via the CLI or API. To delete a policy:

d8 stronghold delete sys/policy/policy-name

or via the API:

curl \
  --request DELETE \
  --header "X-Vault-Token: ..." \
  https://stronghold.example.com/v1/sys/policy/policy-name

This is an idempotent operation. Stronghold will not return an error when deleting a policy that does not exist.

Associating policies

Stronghold can automatically associate a set of policies to a token based on an authorization. This configuration varies significantly between authentication backends. For simplicity, this example will use Vault's built-in userpass auth method.

A Stronghold administrator or someone from the security team would create the user in Stronghold with a list of associated policies:

d8 stronghold write auth/userpass/users/sethvargo \
    password="s3cr3t!" \
    policies="dev-readonly,logs"

This creates an authentication mapping to the policy such that, when the user authenticates successfully to Vault, they will be given a token which has the list of policies attached.

The user wishing to authenticate would run

d8 stronghold login -method="userpass" username="sethvargo"
Password (will be hidden): ...

If the provided information is correct, Stronghold will generate a token, assign the list of configured policies to the token, and return that token to the authenticated user.

Root protected API endpoints

Note: Stronghold treats the HTTP POST and PUT verbs as equivalent, so for each mention of POST in the table above, PUT may also be used. Stronghold uses the non-standard LIST HTTP verb, but also allows list requests to be made using the GET verb along with ?list=true as a query parameter, so for each mention of LIST in the table above, GET with ?list=true may also be used.

The following paths requires a root token or sudo capability in the policy:

Path	HTTP verb	Description
auth/token/accessors	LIST	List token accessors for all current Stronghold service tokens
auth/token/create	POST	Create a periodic or an orphan token (period or no_parent) option
pki/root	DELETE	Delete the current CA key (pki secrets engine)
pki/root/sign-self-issued	POST	Use the configured CA certificate to sign a self-issued certificate (pki secrets engine)
sys/audit	GET	List enabled audit devices
sys/audit/:path	POST, DELETE	Enable or remove an audit device
sys/auth/:path	GET, POST, DELETE	Manage the auth methods (enable, read, and delete)
sys/auth/:path/tune	GET, POST	Manage the auth methods (enable, read, delete, and tune)
sys/config/auditing/request-headers	GET	List the request headers that are configured to be audited
sys/config/auditing/request-headers/:name	GET, POST, DELETE	Manage the auditing headers (create, update, read and delete)
sys/config/cors	GET, POST, DELETE	Configure CORS setting
sys/config/ui/headers	GET, LIST	Configure the UI settings
sys/config/ui/headers/:name	POST, DELETE	Configure custom HTTP headers to be served with the UI
sys/internal/inspect/router/:tag	GET	Inspect the internal components of Vault's router. tag must be one of root, uuid, accessor, or storage
sys/leases/lookup/:prefix	LIST	List lease IDs
sys/leases/revoke-force/:prefix	POST	Revoke all secrets or tokens ignoring backend errors
sys/leases/revoke-prefix/:prefix	POST	Revoke all secrets generated under a given prefix
sys/plugins/catalog/:type/:name	GET, POST, DELETE	Register a new plugin, or read/remove an existing plugin
sys/raw:path	GET, POST, DELETE	Used to access the raw underlying store in Stronghold
sys/raw:prefix	GET, LIST	Returns a list keys for a given path prefix
sys/remount	POST	Moves an already-mounted backend to a new mount point
sys/replication/reindex	POST	Reindex the local data storage
sys/replication/performance/primary/secondary-token	POST	Generate a performance secondary activation token
sys/replication/dr/primary/secondary-token	POST	Generate a DR secondary activation token
sys/rotate	POST	Trigger a rotation of the backend encryption key
sys/seal	POST	Seals the Stronghold
sys/step-down	POST	Forces a node to give up active status
sys/storage/raft/snapshot-auto/config	LIST	Lists named configurations
sys/storage/raft/snapshot-auto/config/:name	GET, POST, DELETE	Creates or updates a named configuration

Tokens Tokens have two sets of policies: identity policies, which are computed based on the entity and its groups, and token policies, which are either defined based on the login method or, in the case of explicit token creates via the API, are an input to the token creation. What follows concerns token policies exclusively: a token's identity policies cannot be controlled except by modifying the underlying entities, groups, and group memberships.

Tokens are associated with their policies at creation time. For example:

d8 stronghold token create -policy=dev-readonly -policy=logs

Normally the only policies that may be specified are those which are present in the current token's (i.e. the new token's parent's) token policies. However, root users can assign any policies.

There is no way to modify the policies associated with a token once the token has been issued. The token must be revoked and a new one acquired to receive a new set of policies.

However, the contents of policies are parsed in real-time whenever the token is used. As a result, if a policy is modified, the modified rules will be in force the next time a token, with that policy attached, is used to make a call to Stronghold.

Токены

{% alert level="warning" %}[Internal token structure is volatile]

Tokens are opaque values so their structure is undocumented and subject to change. Scripts and automations that rely on the internal structure of a token in scripts will break.

{% endalert %} Tokens are the core method for authentication within Stronghold. Tokens can be used directly or auth methods can be used to dynamically generate tokens based on external identities.

As stated in the authentication concepts, all external authentication mechanisms, such as GitHub, map down to dynamically created tokens. These tokens have all the same properties as a normal manually created token.

Within Stronghold, tokens map to information. The most important information mapped to a token is a set of one or more attached policies. These policies control what the token holder is allowed to do within Stronghold. Other mapped information includes metadata that can be viewed and is added to the audit log, such as creation time, last renewal time, and more.

Token formats

Tokens are composed of a prefix and a body.

• The prefix indicates the token's type:

Token Type	Prefix
Service tokens	s.
Batch tokens	b.
Recovery tokens	r.

• The body is a randomly-generated 24 or more characters Base62 string.

Token are expected to match the following regexp: [sbr]\.[a-zA-Z0-9]{24,}

Examples:

b.n6keuKu5Q6pXhaIcfnC9cFNd
r.JaKnR2AIHNk3fC4SGyyyDVoQ9O
s.raPGTZdARXdY0KvHcWSpp5wWZIHNT

Token types

There are two types of tokens: service tokens and batch tokens. A section near the bottom of this page contains detailed information about their differences, but it is useful to understand other token concepts first. The features in the following sections all apply to service tokens, and their applicability to batch tokens is discussed later.

The token store

Often in documentation or in help channels, the "token store" is referenced. This is the same as the token authentication backend. This is a special backend in that it is responsible for creating and storing tokens, and cannot be disabled. It is also the only auth method that has no login capability -- all actions require existing authenticated tokens.

Root tokens

Root tokens are tokens that have the root policy attached to them. Root tokens can do anything in Stronghold. Anything. In addition, they are the only type of token within Stronghold that can be set to never expire without any renewal needed. As a result, it is purposefully hard to create root tokens; in fact there are only three ways to create root tokens:

1. The initial root token generated at d8 stronghold operator init time -- this token has no expiration
2. By using another root token; a root token with an expiration cannot create a root token that never expires
3. By using d8 stronghold operator generate-root with the permission of a quorum of unseal key holders

Root tokens are useful in development but should be extremely carefully guarded in production. In fact, the Stronghold team recommends that root tokens are only used for just enough initial setup (usually, setting up auth methods and policies necessary to allow administrators to acquire more limited tokens) or in emergencies, and are revoked immediately after they are no longer needed. If a new root token is needed, the operator generate-root command and associated API endpoint can be used to generate one on-the-fly.

It is also good security practice for there to be multiple eyes on a terminal whenever a root token is live. This way multiple people can verify as to the tasks performed with the root token, and that the token was revoked immediately after these tasks were completed.

Token hierarchies and orphan tokens

Normally, when a token holder creates new tokens, these tokens will be created as children of the original token; tokens they create will be children of them; and so on. When a parent token is revoked, all of its child tokens -- and all of their leases -- are revoked as well. This ensures that a user cannot escape revocation by simply generating a never-ending tree of child tokens.

Often this behavior is not desired, so users with appropriate access can create orphan tokens. These tokens have no parent -- they are the root of their own token tree. These orphan tokens can be created:

1. Via write access to the auth/token/create-orphan endpoint
2. By having sudo or root access to the auth/token/create and setting the no_parent parameter to true
3. Via token store roles
4. By logging in with any other (non-token) auth method

Users with appropriate permissions can also use the auth/token/revoke-orphan endpoint, which revokes the given token but rather than revoke the rest of the tree, it instead sets the tokens' immediate children to be orphans. Use with caution!

Token accessors

When tokens are created, a token accessor is also created and returned. This accessor is a value that acts as a reference to a token and can only be used to perform limited actions:

1. Look up a token's properties (not including the actual token ID)
2. Look up a token's capabilities on a path
3. Renew the token
4. Revoke the token

The token making the call, not the token associated with the accessor, must have appropriate permissions for these functions.

There are many useful workflows around token accessors. As an example, a service that creates tokens on behalf of another service (such as the Nomad scheduler) can store the accessor correlated with a particular job ID. When the job is complete, the accessor can be used to instantly revoke the token given to the job and all of its leased credentials, limiting the chance that a bad actor will discover and use them.

Audit devices can optionally be set to not obfuscate token accessors in audit logs. This provides a way to quickly revoke tokens in case of an emergency. However, it also means that the audit logs can be used to perform a larger-scale denial of service attack.

Finally, the only way to "list tokens" is via the auth/token/accessors command, which actually gives a list of token accessors. While this is still a dangerous endpoint (since listing all of the accessors means that they can then be used to revoke all tokens), it also provides a way to audit and revoke the currently-active set of tokens.

Token Time-To-Live, periodic tokens, and explicit max TTLs

Every non-root token has a time-to-live (TTL) associated with it, which is a current period of validity since either the token's creation time or last renewal time, whichever is more recent. (Root tokens may have a TTL associated, but the TTL may also be 0, indicating a token that never expires). After the current TTL is up, the token will no longer function -- it, and its associated leases, are revoked.

If the token is renewable, Stronghold can be asked to extend the token validity period using d8 stronghold token renew or the appropriate renewal endpoint. At this time, various factors come into play. What happens depends upon whether the token is a periodic token (available for creation by root/sudo users, token store roles, or some auth methods), has an explicit maximum TTL attached, or neither.

The general case

In the general case, where there is neither a period nor explicit maximum TTL value set on the token, the token's lifetime since it was created will be compared to the maximum TTL. This maximum TTL value is dynamically generated and can change from renewal to renewal, so the value cannot be displayed when a token's information is looked up. It is based on a combination of factors:

1. The system max TTL, which is 32 days but can be changed in Stronghold's configuration file.
2. The max TTL set on a mount using mount tuning. This value is allowed to override the system max TTL -- it can be longer or shorter, and if set this value will be respected.
3. A value suggested by the auth method that issued the token. This might be configured on a per-role, per-group, or per-user basis. This value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer.

Note that the values in (2) and (3) may change at any given time, which is why a final determination about the current allowed max TTL is made at renewal time using the current values. It is also why it is important to always ensure that the TTL returned from a renewal operation is within an allowed range; if this value is not extending, likely the TTL of the token cannot be extended past its current value and the client may want to reauthenticate and acquire a new token. However, outside of direct operator interaction, Stronghold will never revoke a token before the returned TTL has expired.

Explicit max TTLs

Tokens can have an explicit max TTL set on them. This value becomes a hard limit on the token's lifetime -- no matter what the values in (1), (2), and (3) from the general case are, the token cannot live past this explicitly-set value. This has an effect even when using periodic tokens to escape the normal TTL mechanism.

Periodic tokens

In some cases, having a token be revoked would be problematic -- for instance, if a long-running service needs to maintain its SQL connection pool over a long period of time. In this scenario, a periodic token can be used. Periodic tokens can be created in a few ways:

1. By having sudo capability or a root token with the auth/token/create endpoint
2. By using token store roles
3. By using an auth method that supports issuing these, such as AppRole

At issue time, the TTL of a periodic token will be equal to the configured period. At every renewal time, the TTL will be reset back to this configured period, and as long as the token is successfully renewed within each of these periods of time, it will never expire. Outside of root tokens, it is currently the only way for a token in Stronghold to have an unlimited lifetime.

The idea behind periodic tokens is that it is easy for systems and services to perform an action relatively frequently -- for instance, every two hours, or even every five minutes. Therefore, as long as a system is actively renewing this token -- in other words, as long as the system is alive -- the system is allowed to keep using the token and any associated leases. However, if the system stops renewing within this period (for instance, if it was shut down), the token will expire relatively quickly. It is good practice to keep this period as short as possible, and generally speaking it is not useful for humans to be given periodic tokens.

There are a few important things to know when using periodic tokens:

• When a periodic token is created via a token store role, the current value of the role's period setting will be used at renewal time
• A token with both a period and an explicit max TTL will act like a periodic token but will be revoked when the explicit max TTL is reached

CIDR-Bound tokens

Some tokens are able to be bound to CIDR(s) that restrict the range of client IPs allowed to use them. These affect all tokens except for non-expiring root tokens (those with a TTL of zero). If a root token has an expiration, it also is affected by CIDR-binding.

Token types in detail

There are currently two types of tokens.

Service tokens

Service tokens are what users will generally think of as "normal" Stronghold tokens. They support all features, such as renewal, revocation, creating child tokens, and more. They are correspondingly heavyweight to create and track.

Batch tokens

Batch tokens are encrypted blobs that carry enough information for them to be used for Stronghold actions, but they require no storage on disk to track them. As a result they are extremely lightweight and scalable, but lack most of the flexibility and features of service tokens.

Token type comparison

This reference chart describes the difference in behavior between service and batch tokens.

	Service Tokens	Batch Tokens
Can Be Root Tokens	Yes	No
Can Create Child Tokens	Yes	No
Can be Renewable	Yes	No
Manually Revocable	Yes	No
Can be Periodic	Yes	No
Can have Explicit Max TTL	Yes	No (always uses a fixed TTL)
Has Accessors	Yes	No
Has Cubbyhole	Yes	No
Revoked with Parent (if not orphan)	Yes	Stops Working
Dynamic Secrets Lease Assignment	Self	Parent (if not orphan)
Cost	Heavyweight; multiple storage writes per token creation	Lightweight; no storage cost for token creation

Service vs. batch token lease handling

1. Service tokens.

Leases created by service tokens (including child tokens' leases) are tracked along with the service token and revoked when the token expires.

1. Batch tokens.

Leases created by batch tokens are constrained to the remaining TTL of the batch tokens and, if the batch token is not an orphan, are tracked by the parent. They are revoked when the batch token's TTL expires, or when the batch token's parent is revoked (at which point the batch token is also denied access to Stronghold).

Пространства имен

Описание механизма "пространства имен" в Stronghold

Под механизмом "пространства имен" (namespaces) подразумевается изолированная логическая область внутри Stronghold, которая предоставляет свои собственные: - политики (policies), - пути монтирования (mount paths), - секреты, - механизмы аутентификации (auth methods), - токены и сессии.

Каждое пространство имен работает как отдельный виртуальный Stronghold, при этом все пространства имен управляются одним экземпляром Stronghold-сервера.

Свойства пространств имен в Stronghold - Иерархия: пространства имен образуют "дерево", корнем которого является root (/) пространство имен. - Каждое пространство имен может иметь вложенные пространства имен, при этом это пространство будет являться родительским. - Каждое пространство имен содержит изолированные экземпляры sys/, auth/, token/, cubbyhole/ и другие пути монтирования, если они созданы. - Изоляция: пути монтирования, секреты, политики, токены и т.д. изолированы между пространствами имен. - Администратор родительского пространства может управлять вложенными пространствами имен. Для пользователя область видимости ограничена своим и дочерними пространствами.

Операции с пространствами имён в Stronghold

Для создания нового пространства имён необходим иметь права на чтение и запись по пути /namespaces в текущем пространстве имён. Новое пространство имён не может иметь путь, который уже зарегистрирован за каким-либо из существующих. Имя пространства имен это его полный путь относительно корневого пространства имен root (/). Для обращения к созданному пространству имён через cli необходимо указывать параметр -namespace=<your_namespace_name> Для обращения к созданному пространству имён через REST API необходимо указывать в запросе заголовок X-Vault-Namespace=<your_namespace_name>

Создание пространства имён через cli Stronghold

d8 stronghold namespace create -namespace=<parent_namespace_name> -custom-metadata=key="value" <new_namespace_name>

Пример ответа:

Key                Value
---                -----
custom_metadata    map[key:value]
id                 c88b1992-d9d3-4160-8283-77163a4e7fae
path               <new_namespace_name>/

Описание параметров:

-namespace - абсолютный путь в иерархии пространств имен, в котором будет создано новое вложенное пространство с именем <new_namespace_name> (может быть не указано, в этом случае новое вложенное пространство создается в root). Необязательный параметр. -custom-metadata - информация, описывающая пространство имен, хранящаяся в формате key/value. Необязательный параметр.

Создание пространства имён через REST API Stronghold

$ curl --header "X-Stronghold-Token: $STRONGHOLD_TOKEN" \
      --header "X-Vault-Namespace: <parent_namespace_name>" \
      --request POST \
      --data @payload.json \
      $STRONGHOLD_ADDR/v1/sys/namespaces/<new_namespace_name> | jq -r ".data"

Описание параметров:

-X-Vault-Namespace - абсолютный путь в иерархии пространств имен, в котором будет создано новое вложенное пространство с именем <new_namespace_name> (может быть не указано, в этом случае новое вложенное пространство создается в root). Необязательный параметр. -data - информация, описывающая пространство имен, хранящаяся в формате key/value. Необязательный параметр.

Чтение пространства имён через cli Stronghold

d8 stronghold namespace lookup -namespace=<parent_namespace_name> <namespace_name>

Пример ответа:

Key                Value
---                -----
custom_metadata    map[key:value]
id                 c88b1992-d9d3-4160-8283-77163a4e7fae
path               <namespace_name>/

Описание параметров:

-namespace - абсолютный путь в иерархии пространств имен, в котором будет произведено чтение вложенного пространства с именем <namespace_name> (может быть не указано, в этом случае чтение вложенного пространства производится в root). Необязательный параметр.

Чтение пространства имён через REST API Stronghold

$ curl --header "X-Stronghold-Token: $STRONGHOLD_TOKEN" \
      --header "X-Vault-Namespace: <parent_namespace_name>" \
      --request GET \
      $STRONGHOLD_ADDR/v1/sys/namespaces/<namespace_name>

Описание параметров:

-X-Vault-Namespace - абсолютный путь в иерархии пространств имен, в котором будет произведено чтение вложенного пространства с именем <namespace_name> (может быть не указано, в этом случае чтение вложенного пространства производится в root). Необязательный параметр.

Вывод списка пространств имён через cli Stronghold

d8 stronghold namespace list -namespace=<parent_namespace_name>

Пример ответа:

Keys
----
ns1/
ns2/

Описание параметров:

-namespace - абсолютный путь в иерархии пространств имен, в котором происходит поиск и вывод вложенных пространств ( может быть не указано, в этом случае поиск и вывод вложенных пространств происходит в root). Необязательный параметр.

Вывод списка пространств имён через REST API Stronghold

$ curl --header "X-Stronghold-Token: $STRONGHOLD_TOKEN" \
      --header "X-Vault-Namespace: <parent_namespace_name>" \
      --request LIST \
      $STRONGHOLD_ADDR/v1/sys/namespaces

Описание параметров:

-X-Vault-Namespace - абсолютный путь в иерархии пространств имен, в котором происходит поиск и вывод вложенных пространств (может быть не указано, в этом случае поиск и вывод вложенных пространств происходит в root). Необязательный параметр.

Удаление пространства имён через cli Stronghold

d8 stronghold namespace delete -namespace=<parent_namespace_name> -custom-metadata=key="value" <namespace_name>

Описание параметров:

-namespace - абсолютный путь в иерархии пространств имен, в котором планируется удаление вложенного пространства с именем <namespace_name> (может быть не указано, в этом случае пространство удаляется из root). Необязательный параметр.

Удаление пространства имён через REST API Stronghold

$ curl --header "X-Stronghold-Token: $STRONGHOLD_TOKEN" \
      --header "X-Vault-Namespace: <parent_namespace_name>" \
      --request DELETE \
      $STRONGHOLD_ADDR/v1/sys/namespaces/<namespace_name>

Описание параметров:

-X-Vault-Namespace - абсолютный путь в иерархии пространств имен, в котором планируется удаление вложенного пространства с именем <namespace_name> (может быть не указано, в этом случае пространство удаляется из root). Необязательный параметр.

Audit log entry schema

Stronghold logs audit entries as individual JSON objects separated by line breaks. Audit log entries include attributes that are common across all API endpoints and endpoint-specific request and response attributes.

Audit log entries represent API requests received by Stronghold and API response sent by Stronghold. You can match response entries to the corresponding request entry with the ID field of the request object (.request.id) included in both entries.

Attribute	Type	Description
auth	object	authentication object describing the authenticated principal making the API call.
error	string	Error string generated by the request or returned in the response. Omitted for successful transactions.
forwarded_from	string	Host and port of the performance standby node forwarding the request. Omitted for requests not forwarded.
request	object	request object describing the request details.
response	object	response object describing response details. Omitted for request entries.
time	string	Date and time of the API request/response in ISO 8601 format.
type	string	Type of the audit log entry. One of request or response.

{
  "auth": <authentication object>,
  "error": "error converting input {\"name\":\"John\"} for field \"data\": '' expected a map, got 'string'",
  "forwarded_from": "vault-1.prod.corp.com:443",
  "request": <request object>,
  "time": "2025-06-05T16:10:22.292517Z",
  "type": "request"
}

{
  "auth": <original authentication object>,
  "error": "1 error occurred:\n\t* invalid request\n\n",
  "forwarded_from": "vault-1.prod.corp.com:443",
  "request": <original request object>,
  "response": <response object>,
  "time": "2025-06-05T16:10:22.292639Z",
  "type": "response"
}

Authentication object

Stronghold omits irrelevant authentication object attributes from the audit entry. For example, accessor and client_token are irrelevant for unauthenticated requests and metadata is irrelevant if the authentication token lacks metadata.

Attribute	Type	Description
accessor	string	Accessor of the Stronghold token that performed the request. This value is hashed by default; the example shows a non-hashed token accessor. Refer to token accessors for more information.
client_token	string	Stronghold token that performed the request, in hashed form.
display_name	string	Name associated with the Stronghold token that performed the request. This is a non-sensitive value that can help identify tokens. If a display name is not set, "token" will be shown.
token_type	string	Whether the Stronghold token is a service, batch, or periodic token. Refer to token types.
token_issue_time	string	Date and time when the Stronghold token was issued, in ISO 8601 format.
token_ttl	integer	Validity period of the Stronghold token, in seconds and as of when the token was first issued, relative to token_issue_time. Note that this value is not updated when the token's lifetime is changed subsequent to initial issuance.
metadata	object	Metadata associated with the Stronghold token.
num_uses	integer	When the API request results in a token being issued, which token has a limited number of uses, the number of uses on that token.
remaining_uses	integer	If the Stronghold token has a limit on the number of uses, the number of uses remaining prior to the current request.
entity_created	boolean	Whether the request resulted in an entity being created, i.e. an authorized principal logs into Stronghold for the first time. Omitted when false.
entity_id	string	If the Stronghold token is associated with an entity, the ID of that entity.
policies	list(string)	List of the names of the ACL policies associated with either the Stronghold token or the corresponding entity.
identity_policies	list(string)	If the Stronghold token is associated with an entity, a list of the names of the ACL policies associated (directly or via group membership) with that entity.
token_policies	list(string)	A list of the names of the ACL policies associated directly with the Stronghold token.
no_default_policy	boolean	Whether the Stronghold token does not have Stronghold's "default" ACL policy associated with it. Omitted when false.
external_namespace_ policies	object	If the Stronghold token is associated with an entity, and that entity inherits ACL policies from a namespace other than the namespace in which the entity exists, a JSON object containing a boolean attribute allowed and granting_policies, a list of those inherited ACL policies. Refer to the JSON structure below for more information about granting_policies.
policy_results	object	JSON object containing a boolean attribute allowed and granting_policies, a list of ACL policies associated with either the Stronghold token or the corresponding entity that resulted in the request being allowed. Refer to the JSON structure below for more information about granting_policies.

{
  "accessor": "",
  "client_token": "",
  "display_name": "",
  "entity_created": "",
  "entity_id": "",
  "external_namespace_policies": {
    "allowed": true,
    "granting_policies": [
      {
        "name": "",
        "namespace_id": "",
        "namespace_path": "",
        "type": ""
      }
    ]
  },
  "identity_policies": [""],
  "metadata": {},
  "no_default_policy": false,
  "num_uses": 10,
  "policies": [""],
  "policy_results": {
    "allowed": true,
    "granting_policies": [
      {
        "name": "",
        "namespace_id": "",
        "namespace_path": "",
        "type": ""
      }
    ]
  },
  "remaining_uses": 5,
  "token_policies": [""],
  "token_issue_time": "",
  "token_ttl": 3600,
  "token_type": ""
}

Request object ((#request))

The following request object definition includes example data with simple types (string, bool, int) and used in other JSON examples that include a <request> object.

Attribute	Type	Description
id	string	Random ID generated by Stronghold to uniquely identify the API request.
operation	string	Whether the request is a create, read, update, delete, or list operation.
namespace	object	JSON object with the namespace's unique id and its path.
path	string	API path that received the request.
request_uri	string	The original request path from the HTTP request, if it differs from path (e.g., when the Stronghold namespace is specified as an HTTP header).
mount_accessor	string	Unique identifier of the Stronghold mount (secret engine or authentication backend) that received the API request.
mount_type	string	Type of Stronghold mount that received the API request.
mount_running_version	string	Version string for the Stronghold mount that received the API request.
mount_running_sha256	string	If the mount that received the API request is an external plugin, the SHA-256 hash of the plugin's running version.
mount_is_external_ plugin	boolean	Whether the mount that received the API request is an external plugin.
remote_address	string	IP address of the client making the request, as seen by Stronghold. Note that load balancers, proxies, and reverse proxies may all mask the true client's IP address.
remote_port	integer	Port number used by the client making the request, as seen by Stronghold.
headers	object	JSON object containing request headers configured to be logged.
policy_override	boolean	Whether the client requested an override of a Sentinel policy.
client_id	string	ID of the Stronghold client making the request.
client_token	string	Stronghold token that performed the request, in hashed form.
client_token_accessor	string	Accessor of the Stronghold token that performed the request. This value is hashed by default; the example shows a non-hashed token accessor. Refer to token accessors for more information.
client_certificate_ serial_number	string	If the client's connection to Stronghold is mutually authenticated, the serial number of the client's TLS certificate.
wrap_ttl	integer	If the client requested the response to be wrapped, the number of seconds for which the wrapped response will be available.
data	object	JSON object containing the request's payload. This is dependent on the API endpoint called.
replication_cluster	string	If the request was forwarded from a Performance Replication secondary cluster, the name of the secondary cluster.

{
  "client_certificate_serial_number": "",
  "client_id": "",
  "client_token": "",
  "client_token_accessor": "",
  "data": {},
  "id": "",
  "headers": {},
  "mount_accessor": "",
  "mount_class": "",
  "mount_point": "",
  "mount_type": "",
  "mount_running_version": "",
  "mount_running_sha256": "",
  "mount_is_external_plugin": "",
  "namespace": {
    "id": "",
    "path": ""
  },
  "operation": "",
  "path": "",
  "policy_override": true,
  "remote_address": "",
  "remote_port": 1234,
  "replication_cluster": "",
  "request_uri": "",
  "wrap_ttl": 60
}

Response object ((#response))

The following response object definition includes example data with simple types (string, bool, int) and used in other JSON examples that include a <response> object.

Attribute	Type	Description
auth	object	If the request results in a token being created, an authentication object with the token information. See authentication above.
headers	object	Set of HTTP response headers sent by the plugin that handled the API request.
redirect	string	For requests sent to authentication backends, the URL to which the authentication backend redirected the user for further authentication.
warnings	list(string)	If the API returned one or more warnings, a list of the warning messages.
data	object	JSON object containing the response payload. This is dependent on the API endpoint called.
secret	object	If the API returned a leased secret, a JSON object with one attribute, lease_id, that identifies that leased secret.
wrap_info	object	If the API returned a response-wrapped secret, a JSON object containing the properties of the wrapping token. See below for the attributes in the JSON object.
mount_class	string	Type of API mount, auth or secret.
mount_accessor	string	Unique identifier of the Stronghold mount (secret engine or authentication backend) that responded to the API request.
mount_type	string	Type of Stronghold mount that responded to the API request.
mount_running_plugin_version	string	Version string for the Stronghold mount that responded to the API request.
mount_running_sha256	string	If the mount that received the API request is an external plugin, the SHA-256 hash of the plugin's running version.
mount_is_external_plugin	boolean	Whether the mount that received the API request is an external plugin.

{
  "auth": <auth>,
  "data": {},
  "headers": {},
  "mount_accessor": "",
  "mount_class": "",
  "mount_is_external_plugin": false,
  "mount_point": "",
  "mount_running_sha256": "",
  "mount_running_plugin_version": "",
  "mount_type": "",
  "redirect": "",
  "secret": {
    "lease_id": ""
  },
  "wrap_info": {
    "accessor": "",
    "creation_path": "",
    "creation_time": "",
    "token": "",
    "ttl": 60,
    "wrapped_accessor": ""
  },
  "warnings": [
    ""
  ]
}

Full entry examples

{
  "auth": {
    "accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3",
    "client_token": "hmac-sha256:c39c69748f0894cb4cd0333c779e72343ba45af287649d0fbcc37e9b079abe5d",
    "display_name": "userpass-alice",
    "entity_id": "62ff123b-7609-1ed9-5707-ea621da72de7",
    "metadata": { "username": "alice" },
    "policies": ["default"],
    "policy_results": {
      "allowed": true,
      "granting_policies": [
        { "type": "" },
        { "name": "default", "namespace_id": "root", "type": "acl" }
      ]
    },
    "token_policies": ["default"],
    "token_issue_time": "2025-06-04T16:01:31-04:00",
    "token_ttl": 2764800,
    "token_type": "service"
  },
  "request": {
    "client_id": "62ff123b-7609-1ed9-5707-ea621da72de7",
    "client_token": "hmac-sha256:3431e8c2ce0e5f5e179a857fcf9d948afd83363de9f64a5e956851262e1285e0",
    "client_token_accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3",
    "headers": { "user-agent": ["Go-http-client/1.1"] },
    "id": "79cc9b26-488f-eabf-2a97-303ed3bef0d6",
    "mount_class": "auth",
    "mount_point": "auth/token/",
    "mount_running_version": "v1.19.1+builtin.vault",
    "mount_type": "token",
    "namespace": { "id": "root" },
    "operation": "read",
    "path": "auth/token/lookup-self",
    "remote_address": "127.0.0.1",
    "remote_port": 64199
  },
  "time": "2025-06-04T20:02:46.117181Z",
  "type": "request"
}

{
  "auth": {
    "accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3",
    "client_token": "hmac-sha256:c39c69748f0894cb4cd0333c779e72343ba45af287649d0fbcc37e9b079abe5d",
    "display_name": "userpass-alice",
    "entity_id": "62ff123b-7609-1ed9-5707-ea621da72de7",
    "metadata": { "username": "alice" },
    "policies": ["default"],
    "policy_results": {
      "allowed": true,
      "granting_policies": [
        { "type": "" },
        { "name": "default", "namespace_id": "root", "type": "acl" }
      ]
    },
    "token_policies": ["default"],
    "token_issue_time": "2025-06-04T16:01:31-04:00",
    "token_ttl": 2764800,
    "token_type": "service"
  },
  "request": {
    "client_id": "62ff123b-7609-1ed9-5707-ea621da72de7",
    "client_token": "hmac-sha256:3431e8c2ce0e5f5e179a857fcf9d948afd83363de9f64a5e956851262e1285e0",
    "client_token_accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3",
    "headers": { "user-agent": ["Go-http-client/1.1"] },
    "id": "79cc9b26-488f-eabf-2a97-303ed3bef0d6",
    "mount_accessor": "auth_token_d43d387d",
    "mount_class": "auth",
    "mount_point": "auth/token/",
    "mount_running_version": "v1.19.1+builtin.vault",
    "mount_type": "token",
    "namespace": { "id": "root" },
    "operation": "read",
    "path": "auth/token/lookup-self",
    "remote_address": "127.0.0.1",
    "remote_port": 64199
  },
  "response": {
    "data": {
      "accessor": "hmac-sha256:3348fe9b24b078f97d747363dda2d55bb0445e90b512e9f68f48d289fed798b3",
      "creation_time": 1749067291,
      "creation_ttl": 2764800,
      "display_name": "hmac-sha256:e9fb3affb6ae22b7f747e1a60bdda5b57809c9e64ae6f39ebac24e371e6b9d89",
      "entity_id": "hmac-sha256:d2458e3011b3567a0070f22bcdd5e513aeb3473457922e1866f01463ccce2b11",
      "expire_time": "2025-07-06T16:01:31.771304-04:00",
      "explicit_max_ttl": 0,
      "id": "hmac-sha256:c39c69748f0894cb4cd0333c779e72343ba45af287649d0fbcc37e9b079abe5d",
      "issue_time": "2025-06-04T16:01:31.771306-04:00",
      "meta": {
        "username": "hmac-sha256:b93081f3689ff25929e88d5c323631ccf7d6145cd9f33c0c5129a7a340248b9a"
      },
      "num_uses": 0,
      "orphan": true,
      "path": "hmac-sha256:82f79af6be9e1d33d6821a8cfcfcba3196e5ec68512c1f5ed4c919acd8443dd6",
      "policies": [
        "hmac-sha256:1b1a37ccd3a6a78da781140396f04eb50e3460504492d2da75b446d775d3325b"
      ],
      "renewable": true,
      "ttl": 2764725,
      "type": "hmac-sha256:b835fe7ff7616f2023c77f6dbddc7afd83ef5c6644aba61c574c378dda710809"
    },
    "mount_accessor": "auth_token_d43d387d",
    "mount_class": "auth",
    "mount_point": "auth/token/",
    "mount_running_plugin_version": "v1.19.1+builtin.vault",
    "mount_type": "token"
  },
  "time": "2025-06-04T20:02:46.117567Z",
  "type": "response"
}

Методы аутентификации

Auth methods

Auth methods are the components in Stronghold that perform authentication and are responsible for assigning identity and a set of policies to a user. In all cases, Stronghold will enforce authentication as part of the request processing. In most cases, Stronghold will delegate the authentication administration and decision to the relevant configured external auth method (e.g., Kubernetes).

Having multiple auth methods enables you to use an auth method that makes the most sense for your use case of Stronghold and your organization.

For example, on developer machines, the Userpass is easiest to use. But for servers the AppRole method is the recommended choice.

To learn more about authentication, see the authentication concepts page.

Enabling/Disabling auth methods

Auth methods can be enabled/disabled using the CLI or the API.

d8 stronghold auth enable userpass

When enabled, auth methods are similar to secrets engines: they are mounted within the Stronghold mount table and can be accessed and configured using the standard read/write API. All auth methods are mounted underneath the auth/ prefix.

By default, auth methods are mounted to auth/<type>. For example, if you enable "ldap", then you can interact with it at auth/ldap. However, this path is customizable, allowing users with advanced use cases to mount a single auth method multiple times.

d8 stronghold auth enable -path=my-login userpass

When an auth method is disabled, all users authenticated via that method are automatically logged out.

External auth method considerations

When using an external auth method (e.g., Kubernetes), Stronghold will call the external service at the time of authentication and for subsequent token renewals. If the status of an entity changes in the external system (e.g., an account expires or is disabled), Stronghold denies requests to renew tokens associated with the entity. However, any existing token remain valid for the original grant period unless they are explicitly revoked within Stronghold. Operators should set appropriate token TTLs when using external authN methods.

Approle

The approle auth method allows machines or apps to authenticate with Stronghold-defined roles. The open design of AppRole enables a varied set of workflows and configurations to handle large numbers of apps. This auth method is oriented to automated workflows (machines and services), and is less useful for human operators.

An "AppRole" represents a set of Stronghold policies and login constraints that must be met to receive a token with those policies. The scope can be as narrow or broad as desired. An AppRole can be created for a particular machine, or even a particular user on that machine, or a service spread across machines. The credentials required for successful login depend upon the constraints set on the AppRole associated with the credentials.

Authentication

Via the CLI:

The default path is /approle. If this auth method was enabled at a different path, specify auth/my-path/login instead.

$ d8 stronghold write auth/approle/login \
    role_id=db02de05-fa39-4855-059b-67221c5c2f63 \
    secret_id=6a174c20-f6de-a53c-74d2-6018fcceff64

Key                Value
---                -----
token              65b74ffd-842c-fd43-1386-f7d7006e520a
token_accessor     3c29bc22-5c72-11a6-f778-2bc8f48cea0e
token_duration     20m0s
token_renewable    true
token_policies     [default]

Via the API:

The default endpoint is auth/approle/login. If this auth method was enabled at a different path, use that value instead of approle.

$ curl \
    --request POST \
    --data '{"role_id":"988a9df-...","secret_id":"37b74931..."}' \
    http://127.0.0.1:8200/v1/auth/approle/login

The response will contain the token at auth.client_token:

{
  "auth": {
    "renewable": true,
    "lease_duration": 2764800,
    "metadata": {},
    "policies": ["default", "dev-policy", "test-policy"],
    "accessor": "5d7fb475-07cb-4060-c2de-1ca3fcbf0c56",
    "client_token": "98a4c7ab-b1fe-361b-ba0b-e307aacfd587"
  }
}

{% alert level="info" %}

Application Integration: See the Code Example section for a code snippet demonstrating the authentication with Stronghold using the AppRole auth method.

{% endalert %}

Configuration

Auth methods must be configured in advance before users or machines can authenticate. These steps are usually completed by an operator or configuration management tool.

Via the CLI:

1. Enable the AppRole auth method:

shell-session d8 stronghold auth enable approle

1. Create a named role:

shell-session $ d8 stronghold write auth/approle/role/my-role \ secret_id_ttl=10m \ token_num_uses=10 \ token_ttl=20m \ token_max_ttl=30m \ secret_id_num_uses=40

{% alert level="warning" %}

Note: If the token issued by your approle needs the ability to create child tokens, you will need to set token_num_uses to 0.

{% endalert %} For the complete list of configuration options, please see the API documentation.

1. Fetch the RoleID of the AppRole:

shell-session $ d8 stronghold read auth/approle/role/my-role/role-id role_id db02de05-fa39-4855-059b-67221c5c2f63

1. Get a SecretID issued against the AppRole:

shell-session $ d8 stronghold write -f auth/approle/role/my-role/secret-id secret_id 6a174c20-f6de-a53c-74d2-6018fcceff64 secret_id_accessor c454f7e5-996e-7230-6074-6ef26b7bcf86 secret_id_ttl 10m secret_id_num_uses 40

Via the API:

1. Enable the AppRole auth method:

shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data '{"type": "approle"}' \ http://127.0.0.1:8200/v1/sys/auth/approle

1. Create an AppRole with desired set of policies:

shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data '{"policies": "dev-policy,test-policy"}' \ http://127.0.0.1:8200/v1/auth/approle/role/my-role

1. Fetch the identifier of the role:

shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/auth/approle/role/my-role/role-id

The response will look like:

json { "data": { "role_id": "988a9dfd-ea69-4a53-6cb6-9d6b86474bba" } }

1. Create a new secret identifier under the role:

shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ http://127.0.0.1:8200/v1/auth/approle/role/my-role/secret-id

The response will look like:

json { "data": { "secret_id_accessor": "45946873-1d96-a9d4-678c-9229f74386a5", "secret_id": "37b74931-c4cd-d49a-9246-ccc62d682a25", "secret_id_ttl": 600, "secret_id_num_uses": 40 } }

Credentials/Constraints

RoleID

RoleID is an identifier that selects the AppRole against which the other credentials are evaluated. When authenticating against this auth method's login endpoint, the RoleID is a required argument (via role_id) at all times. By default, RoleIDs are unique UUIDs, which allow them to serve as secondary secrets to the other credential information. However, they can be set to particular values to match introspected information by the client (for instance, the client's domain name).

SecretID

SecretID is a credential that is required by default for any login (via secret_id) and is intended to always be secret. (For advanced usage, requiring a SecretID can be disabled via an AppRole's bind_secret_id parameter, allowing machines with only knowledge of the RoleID, or matching other set constraints, to fetch a token). SecretIDs can be created against an AppRole either via generation of a 128-bit purely random UUID by the role itself (Pull mode) or via specific, custom values (Push mode). Similarly to tokens, SecretIDs have properties like usage-limit, TTLs and expirations.

Pull and push SecretID modes

If the SecretID used for login is fetched from an AppRole, this is operating in Pull mode. If a "custom" SecretID is set against an AppRole by the client, it is referred to as a Push mode. Push mode mimics the behavior of the deprecated App-ID auth method; however, in most cases Pull mode is the better approach. The reason is that Push mode requires some other system to have knowledge of the full set of client credentials (RoleID and SecretID) in order to create the entry, even if these are then distributed via different paths. However, in Pull mode, even though the RoleID must be known in order to distribute it to the client, the SecretID can be kept confidential from all parties except for the final authenticating client by using Response Wrapping.

Push mode is available for App-ID workflow compatibility, which in some specific cases is preferable, but in most cases Pull mode is more secure and should be preferred.

Further constraints

role_id is a required credential at the login endpoint. AppRole pointed to by the role_id will have constraints set on it. This dictates other required credentials for login. The bind_secret_id constraint requires secret_id to be presented at the login endpoint. Going forward, this auth method can support more constraint parameters to support varied set of Apps. Some constraints will not require a credential, but still enforce constraints for login. For example, secret_id_bound_cidrs will only allow logins coming from IP addresses belonging to configured CIDR blocks on the AppRole.

User lockout

If a user provides bad credentials several times in quick succession, Stronghold will stop trying to validate their credentials for a while, instead returning immediately with a permission denied error. We call this behavior "user lockout". The time for which a user will be locked out is called “lockout duration”. The user will be able to login after the lockout duration has passed. The number of failed login attempts after which the user is locked out is called “lockout threshold”. The lockout threshold counter is reset to zero after a few minutes without login attempts, or upon a successful login attempt. The duration after which the counter will be reset to zero after no login attempts is called "lockout counter reset". This can defeat both automated and targeted requests i.e, user-based password guessing attacks as well as automated attacks.

The user lockout feature is enabled by default. The default values for "lockout threshold" is 5 attempts, "lockout duration" is 15 minutes, "lockout counter reset" is 15 minutes.

The user lockout feature can be disabled as follows:

• It can be disabled globally using environment variable VAULT_DISABLE_USER_LOCKOUT.
• It can be disabled for all supported auth methods (ldap, userpass and approle) or a specific supported auth method using the disable_lockout parameter within user_lockout stanza in configuration file. Please see user lockout configuration for more details.
• It can be disabled for a specific auth mount using "auth tune". Please see auth tune command or auth tune api for more details.

{% alert level="warning" %}

NOTE: This feature is only supported by the userpass, ldap, and approle auth methods.

{% endalert %}

API

The AppRole auth method has a full HTTP API. Please see the AppRole API for more details.

Kubernetes

Kubernetes auth method

The kubernetes auth method can be used to authenticate with Stronghold using a Kubernetes Service Account Token. This method of authentication makes it easy to introduce an Stronghold token into a Kubernetes Pod.

You can also use a Kubernetes Service Account Token to log in via JWT auth. See the section on How to work with short-lived Kubernetes tokens for a summary of why you might want to use JWT auth instead and how it compares to Kubernetes auth.

{% alert level="info" %}

Note: If you are upgrading to Kubernetes v1.21+, ensure the config option disable_iss_validation is set to true. Assuming the default mount path, you can check with d8 stronghold read -field disable_iss_validation auth/kubernetes/config. See Kubernetes 1.21 below for more details.

{% endalert %}

Authentication

Via the CLI

The default path is /kubernetes. If this auth method was enabled at a different path, specify -path=/my-path in the CLI.

d8 stronghold write auth/kubernetes/login role=demo jwt=...

Via the API

The default endpoint is auth/kubernetes/login. If this auth method was enabled at a different path, use that value instead of kubernetes.

$ curl \
    --request POST \
    --data '{"jwt": "<your service account jwt>", "role": "demo"}' \
    http://127.0.0.1:8200/v1/auth/kubernetes/login

The response will contain a token at auth.client_token:

{
  "auth": {
    "client_token": "38fe9691-e623-7238-f618-c94d4e7bc674",
    "accessor": "78e87a38-84ed-2692-538f-ca8b9f400ab3",
    "policies": ["default"],
    "metadata": {
      "role": "demo",
      "service_account_name": "myapp",
      "service_account_namespace": "default",
      "service_account_secret_name": "myapp-token-pd21c",
      "service_account_uid": "aa9aa8ff-98d0-11e7-9bb7-0800276d99bf"
    },
    "lease_duration": 2764800,
    "renewable": true
  }
}

Configuration

Auth methods must be configured in advance before users or machines can authenticate. These steps are usually completed by an operator or configuration management tool.

1. Enable the Kubernetes auth method:

bash d8 stronghold auth enable kubernetes

1. Use the /config endpoint to configure Stronghold to talk to Kubernetes. Use kubectl cluster-info to validate the Kubernetes host address and TCP port. For the list of available configuration options, please see the API documentation.

bash d8 stronghold write auth/kubernetes/config \ token_reviewer_jwt="<your reviewer service account JWT>" \ kubernetes_host=https://192.168.99.100:<your TCP port or blank for 443> \ kubernetes_ca_cert=@ca.crt

{% alert level="critical" %}

Note: The pattern Stronghold uses to authenticate Pods depends on sharing the JWT token over the network. Given the security model of Stronghold, this is allowable because Stronghold is part of the trusted compute base. In general, Kubernetes applications should not share this JWT with other applications, as it allows API calls to be made on behalf of the Pod and can result in unintended access being granted to 3rd parties.

{% endalert %}

1. Create a named role:

text d8 stronghold write auth/kubernetes/role/demo \ bound_service_account_names=myapp \ bound_service_account_namespaces=default \ policies=default \ ttl=1h

This role authorizes the "myapp" service account in the default namespace and it gives it the default policy.

For the complete list of configuration options, please see the API documentation.

Kubernetes 1.21

Starting in version 1.21, the Kubernetes BoundServiceAccountTokenVolume feature defaults to enabled. This changes the JWT token mounted into containers by default in two ways that are important for Kubernetes auth:

• It has an expiry time and is bound to the lifetime of the pod and service account.
• The value of the JWT's "iss" claim depends on the cluster's configuration.

The changes to token lifetime are important when configuring the token_reviewer_jwt option. If a short-lived token is used, Kubernetes will revoke it as soon as the pod or service account are deleted, or if the expiry time passes, and Stronghold will no longer be able to use the TokenReview API. See How to work with short-lived Kubernetes tokens below for details on handling this change.

In response to the issuer changes, Kubernetes auth has been updated to not validate the issuer by default. The Kubernetes API does the same validation when reviewing tokens, so enabling issuer validation on the Stronghold side is duplicated work. Without disabling Stronghold's issuer validation, it is not possible for a single Kubernetes auth configuration to work for default mounted pod tokens with both Kubernetes 1.20 and 1.21.. See Discovering the service account issuer below for guidance if you wish to enable issuer validation in Stronghold.

How to work with short-lived kubernetes tokens

There are a few different ways to configure auth for Kubernetes pods when default mounted pod tokens are short-lived, each with their own tradeoffs. This table summarizes the options, each of which is explained in more detail below.

Option	All tokens are short-lived	Can revoke tokens early	Other considerations
Use local token as reviewer JWT	Yes	Yes	Requires Stronghold to be deployed on the Kubernetes cluster
Use client JWT as reviewer JWT	Yes	Yes	Operational overhead
Use long-lived token as reviewer JWT	No	Yes
Use JWT auth instead	Yes	No

{% alert level="info" %}

Note: By default, Kubernetes currently extends the lifetime of admission injected service account tokens to a year to help smooth the transition to short-lived tokens. If you would like to disable this, set --service-account-extend-token-expiration=false for kube-apiserver or specify your own serviceAccountToken volume mount. See here for an example.

{% endalert %}

Use local service account token as the reviewer JWT

When running Stronghold in a Kubernetes pod the recommended option is to use the pod's local service account token. Stronghold will periodically re-read the file to support short-lived tokens. To use the local token and CA certificate, omit token_reviewer_jwt and kubernetes_ca_cert when configuring the auth method. Stronghold will attempt to load them from token and ca.crt respectively inside the default mount folder /var/run/secrets/kubernetes.io/serviceaccount/.

d8 stronghold write auth/kubernetes/config \
    kubernetes_host=https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT

Use the Stronghold client's JWT as the reviewer JWT

When configuring Kubernetes auth, you can omit the token_reviewer_jwt, and Stronghold will use the Stronghold client's JWT as its own auth token when communicating with the Kubernetes TokenReview API. If Stronghold is running in Kubernetes, you also need to set disable_local_ca_jwt=true.

This means Stronghold does not store any JWTs and allows you to use short-lived tokens everywhere but adds some operational overhead to maintain the cluster role bindings on the set of service accounts you want to be able to authenticate with Stronghold. Each client of Stronghold would need the system:auth-delegator ClusterRole:

kubectl create clusterrolebinding myapp-client-auth-delegator \
  --clusterrole=system:auth-delegator \
  --group=group1 \
  --serviceaccount=default:svcaccount1 \
  ...

Continue using long-lived tokens

You can create a long-lived secret using the instructions here and use that as the token_reviewer_jwt. In this example, the myapp service account would need the system:auth-delegator ClusterRole:

kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: myapp-k8s-auth-secret
  annotations:
    kubernetes.io/service-account.name: myapp
type: kubernetes.io/service-account-token
EOF

Using this maintains previous workflows but does not benefit from the improved security posture of short-lived tokens.

Use JWT auth

Kubernetes auth is specialized to use Kubernetes' TokenReview API. However, the JWT tokens Kubernetes generates can also be verified using Kubernetes as an OIDC provider. The JWT auth method documentation has instructions for setting up JWT auth with Kubernetes as the OIDC provider.

This solution allows you to use short-lived tokens for all clients and removes the need for a reviewer JWT. However, the client tokens cannot be revoked before their TTL expires, so it is recommended to keep the TTL short with that limitation in mind.

Discovering the service account issuer

{% alert level="info" %}

Note: disable_iss_validation and issuer are deprecated and the default for disable_iss_validation has changed to true for new Kubernetes auth mounts. The following section only applies if you have set disable_iss_validation=false , but disable_iss_validation=true is the new recommended value for all versions of Stronghold.

{% endalert %} Kubernetes 1.21+ clusters may require setting the service account issuer to the same value as kube-apiserver's --service-account-issuer flag. This is because the service account JWTs for these clusters may have an issuer specific to the cluster itself, instead of the old default of kubernetes/serviceaccount. If you are unable to check this value directly, you can run the following and look for the "iss" field to find the required value:

echo '{"apiVersion": "authentication.k8s.io/v1", "kind": "TokenRequest"}' \
  | kubectl create -f- --raw /api/v1/namespaces/default/serviceaccounts/default/token \
  | jq -r '.status.token' \
  | cut -d . -f2 \
  | base64 -d

Most clusters will also have that information available at the .well-known/openid-configuration endpoint:

kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

This value is then used when configuring Kubernetes auth, e.g.:

d8 stronghold write auth/kubernetes/config \
  kubernetes_host="https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT" \
  issuer="\"test-aks-cluster-dns-d6cbb78e.hcp.uksouth.azmk8s.io\""

Configuring kubernetes

This auth method accesses the Kubernetes TokenReview API to validate the provided JWT is still valid. Kubernetes should be running with --service-account-lookup. This is defaulted to true from Kubernetes 1.7. Otherwise deleted tokens in Kubernetes will not be properly revoked and will be able to authenticate to this auth method.

Service Accounts used in this auth method will need to have access to the TokenReview API. If Kubernetes is configured to use RBAC roles, the Service Account should be granted permissions to access this API. The following example ClusterRoleBinding could be used to grant these permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: role-tokenreview-binding
  namespace: default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:auth-delegator
subjects:
  - kind: ServiceAccount
    name: myapp-auth
    namespace: default

API

The Kubernetes Auth Plugin has a full HTTP API. Please see the API docs for more details.

LDAP

{% raw %}

LDAP auth method

The ldap auth method allows authentication using an existing LDAP server and user/password credentials. This allows Stronghold to be integrated into environments using LDAP without duplicating the user/pass configuration in multiple places.

The mapping of groups and users in LDAP to Stronghold policies is managed by using the users/ and groups/ paths.

A note on escaping

It is up to the administrator to provide properly escaped DNs. This includes the user DN, bind DN for search, and so on.

The only DN escaping performed by this method is on usernames given at login time when they are inserted into the final bind DN, and uses escaping rules defined in RFC 4514.

Additionally, Active Directory has escaping rules that differ slightly from the RFC; in particular it requires escaping of '#' regardless of position in the DN (the RFC only requires it to be escaped when it is the first character), and '=', which the RFC indicates can be escaped with a backslash, but does not contain in its set of required escapes. If you are using Active Directory and these appear in your usernames, please ensure that they are escaped, in addition to being properly escaped in your configured DNs.

For reference, see RFC 4514 and this TechNet post on characters to escape in Active Directory.

Authentication

Via the CLI

$ d8 stronghold login -method=ldap username=mitchellh
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:

admins

Via the API

$ curl \
    --request POST \
    --data '{"password": "foo"}' \
    http://127.0.0.1:8200/v1/auth/ldap/login/mitchellh

The response will be in JSON. For example:

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "auth": {
    "client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
    "policies": [
      "admins"
    ],
    "metadata": {
      "username": "mitchellh"
    },
    "lease_duration": 0,
    "renewable": false
  }
}

Configuration

Auth methods must be configured in advance before users or machines can authenticate. These steps are usually completed by an operator or configuration management tool.

1. Enable the ldap auth method:

text d8 stronghold auth enable ldap

1. Configure connection details for your LDAP server, information on how to authenticate users, and instructions on how to query for group membership. The configuration options are categorized and detailed below.

Connection parameters

• url (string, required) - The LDAP server to connect to. Examples: ldap://ldap.myorg.com, ldaps://ldap.myorg.com:636. This can also be a comma-delineated list of URLs, e.g. ldap://ldap.myorg.com,ldaps://ldap.myorg.com:636, in which case the servers will be tried in-order if there are errors during the connection process.
• starttls (bool, optional) - If true, issues a StartTLS command after establishing an unencrypted connection.
• insecure_tls - (bool, optional) - If true, skips LDAP server SSL certificate verification - insecure, use with caution!
• certificate - (string, optional) - CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded.
• client_tls_cert - (string, optional) - Client certificate to provide to the LDAP server, must be x509 PEM encoded.
• client_tls_key - (string, optional) - Client certificate key to provide to the LDAP server, must be x509 PEM encoded.

Binding parameters

There are two alternate methods of resolving the user object used to authenticate the end user: Search or User Principal Name. When using Search, the bind can be either anonymous or authenticated. User Principal Name is a method of specifying users supported by Active Directory. More information on UPN can be found here.

Binding - authenticated search

• binddn (string, optional) - Distinguished name of object to bind when performing user and group search. Example: cn=stronghold,ou=Users,dc=example,dc=com
• bindpass (string, optional) - Password to use along with binddn when performing user search.
• userdn (string, optional) - Base DN under which to perform user search. Example: ou=Users,dc=example,dc=com
• userattr (string, optional) - Attribute on user attribute object matching the username passed when authenticating. Examples: sAMAccountName, cn, uid
• userfilter (string, optional) - Go template used to construct a ldap user search filter. The template can access the following context variables: [UserAttr, Username]. The default userfilter is ({{.UserAttr}}={{.Username}}) or (userPrincipalName={{.Username}}@UPNDomain) if the upndomain parameter is set. The user search filter can be used to restrict what user can attempt to log in. For example, to limit login to users that are not contractors, you could write (&(objectClass=user)({{.UserAttr}}={{.Username}})(!(employeeType=Contractor))).

{% endraw %} {% alert level="warning" %} {% raw %} When specifying a userfilter, either the templated value {{.UserAttr}} or the literal value that matches userattr should be present in the filter to ensure that the search returns a unique result that takes userattr into consideration for entity alias mapping purposes and avoid possible collisions on login. {% endraw %} {% endalert %}

Binding - anonymous search

• discoverdn (bool, optional) - If true, use anonymous bind to discover the bind DN of a user
• userdn (string, optional) - Base DN under which to perform user search. Example: ou=Users,dc=example,dc=com
• userattr (string, optional) - Attribute on user attribute object matching the username passed when authenticating. Examples: sAMAccountName, cn, uid
• userfilter (string, optional) - Go template used to construct a ldap user search filter. The template can access the following context variables: [UserAttr, Username]. The default userfilter is ({{.UserAttr}}={{.Username}}) or (userPrincipalName={{.Username}}@UPNDomain) if the upndomain parameter is set. The user search filter can be used to restrict what user can attempt to log in. For example, to limit login to users that are not contractors, you could write (&(objectClass=user)({{.UserAttr}}={{.Username}})(!(employeeType=Contractor))).
• deny_null_bind (bool, optional) - This option prevents users from bypassing authentication when providing an empty password. The default is true.
• anonymous_group_search (bool, optional) - Use anonymous binds when performing LDAP group searches. Defaults to false.

{% endraw %} {% alert level="warning" %} {% raw %} When specifying a userfilter, either the templated value {{.UserAttr}} or the literal value that matches userattr should be present in the filter to ensure that the search returns a unique result that takes userattr into consideration for entity alias mapping purposes and avoid possible collisions on login. {% endraw %} {% endalert %}

Alias dereferencing

• dereference_aliases (string, optional) - Control how aliases are dereferenced when performing the search. Possible values are: never, finding, searching, and always. finding will only dereference aliases during name resolution of the base. searching will dereference aliases after name resolution.

Binding - user principal name (AD)

• upndomain (string, optional) - userPrincipalDomain used to construct the UPN string for the authenticating user. The constructed UPN will appear as [username]@UPNDomain. Example: example.com, which will cause Stronghold to bind as username@example.com.

Group membership resolution

Once a user has been authenticated, the LDAP auth method must know how to resolve which groups the user is a member of. The configuration for this can vary depending on your LDAP server and your directory schema. There are two main strategies when resolving group membership - the first is searching for the authenticated user object and following an attribute to groups it is a member of. The second is to search for group objects of which the authenticated user is a member of. Both methods are supported.

• groupfilter (string, optional) - Go template used when constructing the group membership query. The template can access the following context variables: [UserDN, Username]. The default is (|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}})), which is compatible with several common directory schemas. To support nested group resolution for Active Directory, instead use the following query: (&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}})).
• groupdn (string, required) - LDAP search base to use for group membership search. This can be the root containing either groups or users. Example: ou=Groups,dc=example,dc=com
• groupattr (string, optional) - LDAP attribute to follow on objects returned by groupfilter in order to enumerate user group membership. Examples: for groupfilter queries returning group objects, use: cn. For queries returning user objects, use: memberOf. The default is cn.

Note: When using Authenticated Search for binding parameters (see above) the distinguished name defined for binddn is used for the group search. Otherwise, the authenticating user is used to perform the group search.

Other

• username_as_alias (bool, optional) - If set to true, forces the auth method to use the username passed by the user as the alias name.
• max_page_size (int, optional) - If set to a value greater than 0, the LDAP backend will use the LDAP server's paged search control to request pages of up to the given size. This can be used to avoid hitting the LDAP server's maximum result size limit. Otherwise, the LDAP backend will not use the paged search control.

Examples

Scenario 1

• LDAP server running on ldap.example.com, port 389.
• Server supports STARTTLS command to initiate encryption on the standard port.
• CA Certificate stored in file named ldap_ca_cert.pem
• Server is Active Directory supporting the userPrincipalName attribute. Users are identified as username@example.com.
• Groups are nested, we will use LDAP_MATCHING_RULE_IN_CHAIN to walk the ancestry graph.
• Group search will start under ou=Groups,dc=example,dc=com. For all group objects under that path, the member attribute will be checked for a match against the authenticated user.
• Group names are identified using their cn attribute.

$ d8 stronghold write auth/ldap/config \
    url="ldap://ldap.example.com" \
    userdn="ou=Users,dc=example,dc=com" \
    groupdn="ou=Groups,dc=example,dc=com" \
    groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" \
    groupattr="cn" \
    upndomain="example.com" \
    certificate=@ldap_ca_cert.pem \
    insecure_tls=false \
    starttls=true
...

Scenario 2

• LDAP server running on ldap.example.com, port 389.
• Server supports STARTTLS command to initiate encryption on the standard port.
• CA Certificate stored in file named ldap_ca_cert.pem
• Server does not allow anonymous binds for performing user search.
• Bind account used for searching is cn=stronghold,ou=users,dc=example,dc=com with password My$ecrt3tP4ss.
• User objects are under the ou=Users,dc=example,dc=com organizational unit.
• Username passed to stronghold when authenticating maps to the sAMAccountName attribute.
• Group membership will be resolved via the memberOf attribute of user objects. That search will begin under ou=Users,dc=example,dc=com.

$ d8 stronghold write auth/ldap/config \
    url="ldap://ldap.example.com" \
    userattr=sAMAccountName \
    userdn="ou=Users,dc=example,dc=com" \
    groupdn="ou=Users,dc=example,dc=com" \
    groupfilter="(&(objectClass=person)(uid={{.Username}}))" \
    groupattr="memberOf" \
    binddn="cn=stronghold,ou=users,dc=example,dc=com" \
    bindpass='My$ecrt3tP4ss' \
    certificate=@ldap_ca_cert.pem \
    insecure_tls=false \
    starttls=true
...

Scenario 3

• LDAP server running on ldap.example.com, port 636 (LDAPS)
• CA Certificate stored in file named ldap_ca_cert.pem
• User objects are under the ou=Users,dc=example,dc=com organizational unit.
• Username passed to Stronghold when authenticating maps to the uid attribute.
• User bind DN will be auto-discovered using anonymous binding.
• Group membership will be resolved via any one of memberUid, member, or uniqueMember attributes. That search will begin under ou=Groups,dc=example,dc=com.
• Group names are identified using the cn attribute.

$ d8 stronghold write auth/ldap/config \
    url="ldaps://ldap.example.com" \
    userattr="uid" \
    userdn="ou=Users,dc=example,dc=com" \
    discoverdn=true \
    groupdn="ou=Groups,dc=example,dc=com" \
    certificate=@ldap_ca_cert.pem \
    insecure_tls=false \
    starttls=true
...

LDAP group -> policy mapping

Next we want to create a mapping from an LDAP group to an Stronghold policy:

d8 stronghold write auth/ldap/groups/scientists policies=foo,bar

This maps the LDAP group "scient

User Lockout

If a user repeatedly provides incorrect credentials, Stronghold will temporarily stop attempting to verify the credentials and will immediately return an access denied error instead. We refer to this behavior as "user lockout" (user_lockout). The duration for which the user remains locked out is called the "lockout duration" (lockout_duration). The user will be able to log in again after this period expires. The number of failed login attempts that trigger a lockout is called the "lockout threshold" (lockout_threshold). The lockout threshold counter is reset after a few minutes without login attempts or after a successful login. The period after which the counter is reset in the absence of login attempts is called the "lockout counter reset" (lockout_counter_reset). This mechanism helps prevent password guessing attacks.

The user lockout feature is enabled by default. Default values:

• lockout_threshold - 5 attempts
• lockout_duration - 15 minutes
• lockout_counter_reset - 15 minutes

You can disable the user lockout feature using the auth tune command by setting disable_lockout to true.

{% endraw %} {% alert level="warning" %} This feature is supported only by the userpass, ldap, and approle auth methods. {% endalert %}

ists" to the "foo" and "bar" Stronghold policies. We can also add specific LDAP users to additional (potentially non-LDAP) groups. Note that policies can also be specified on LDAP users as well.

d8 stronghold write auth/ldap/groups/engineers policies=foobar
d8 stronghold write auth/ldap/users/tesla groups=engineers policies=zoobar

This adds the LDAP user "tesla" to the "engineers" group, which maps to the "foobar" Stronghold policy. User "tesla" itself is associated with "zoobar" policy.

Finally, we can test this by authenticating:

$ d8 stronghold login -method=ldap username=tesla
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:

default, foobar, zoobar

Note on policy mapping

It should be noted that user -> policy mapping happens at token creation time. And changes in group membership on the LDAP server will not affect tokens that have already been provisioned. To see these changes, old tokens should be revoked and the user should be asked to reauthenticate.

User lockout

If a user provides bad credentials several times in quick succession, Stronghold will stop trying to validate their credentials for a while, instead returning immediately with a permission denied error. We call this behavior "user lockout". The time for which a user will be locked out is called “lockout duration”. The user will be able to login after the lockout duration has passed. The number of failed login attempts after which the user is locked out is called “lockout threshold”. The lockout threshold counter is reset to zero after a few minutes without login attempts, or upon a successful login attempt. The duration after which the counter will be reset to zero after no login attempts is called "lockout counter reset". This can defeat both automated and targeted requests i.e, user-based password guessing attacks as well as automated attacks.

The user lockout feature is enabled by default. The default values for "lockout threshold" is 5 attempts, "lockout duration" is 15 minutes, "lockout counter reset" is 15 minutes.

The user lockout feature can be disabled as follows:

• It can be disabled globally using environment variable VAULT_DISABLE_USER_LOCKOUT.
• It can be disabled for all supported auth methods (ldap, userpass and approle) or a specific supported auth method using the disable_lockout parameter within user_lockout stanza in configuration file. Please see user lockout configuration for more details.
• It can be disabled for a specific auth mount using "auth tune". Please see auth tune command or auth tune api for more details.

{% endraw %} {% alert level="warning" %} This feature is only supported by the userpass, ldap, and approle auth methods.

API

The LDAP auth method has a full HTTP API. Please see the LDAP auth method API for more details.

OIDC

JWT/OIDC auth method

{% alert level="warning" %}

Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround. See the deprecation FAQ for more information.

{% endalert %} The jwt auth method can be used to authenticate with Stronghold using OIDC or by providing a JWT.

The OIDC method allows authentication via a configured OIDC provider using the user's web browser. This method may be initiated from the Stronghold UI or the command line. Alternatively, a JWT can be provided directly. The JWT is cryptographically verified using locally-provided keys, or, if configured, an OIDC Discovery service can be used to fetch the appropriate keys. The choice of method is configured per role.

Both methods allow additional processing of the claims data in the JWT. Some of the concepts common to both methods will be covered first, followed by specific examples of OIDC and JWT usage.

OIDC authentication

This section covers the setup and use of OIDC roles. If a JWT is to be provided directly, refer to the JWT Authentication section below. Basic familiarity with OIDC concepts is assumed. The Authorization Code flow makes use of the Proof Key for Code Exchange (PKCE) extension.

Stronghold includes two built-in OIDC login flows: the Stronghold UI, and the CLI using a d8 stronghold login.

Redirect URIs

Unless you are using callbackmode=device, an important part of OIDC role configuration is properly setting redirect URIs. This must be done both in Stronghold and with the OIDC provider, and these configurations must align. The redirect URIs are specified for a role with the allowed_redirect_uris parameter. There are different redirect URIs to configure the Stronghold UI and CLI flows, so one or both will need to be set up depending on the installation.

CLI

If you plan to support authentication via d8 stronghold login -method=oidc and are not using callbackmode=device, a redirect URI with a path ending in oidc/callback must be set. With the default callbackmode=client this can usually be http://localhost:8250/oidc/callback. With callbackmode=direct this should be a URI of the form:

https://{host:port}/v1/auth/{path}/oidc/callback

where "host:port" is the Stronghold server name and port, and "path" is the path the JWT backend is mounted at (e.g. "oidc" or "jwt").

Logins via the CLI may specify a different host and/or listening port if needed, and a URI with this host/port must match one of the configured redirected URIs. These same URIs must be added to the provider as well.

Stronghold UI

Logging in via the Stronghold UI requires a redirect URI of the form:

https://{host:port}/ui/vault/auth/{path}/oidc/callback

The "host:port" must be correct for the Stronghold server, and "path" must match the path the JWT backend is mounted at (e.g. "oidc" or "jwt").

If the oidc_response_mode is set to form_post, then logging in via the Stronghold UI requires a redirect URI of the same form as the direct callback mode:

https://{host:port}/v1/auth/{path}/oidc/callback

OIDC login (Stronghold UI)

1. Select the "OIDC" login method.
2. Enter a role name if necessary.
3. Press "Sign In" and complete the authentication with the configured provider.

OIDC login (CLI)

The CLI login defaults to path of /oidc. If this auth method was enabled at a different path, specify -path=/my-path in the CLI.

$ d8 stronghold login -method=oidc port=8400 role=test

Complete the login via your OIDC provider. Launching browser to:

    https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Foidc%2Fcallback&client_id=r3qXc2bix9eF...

The browser will open to the generated URL to complete the provider's login. The URL may be entered manually if the browser cannot be automatically opened.

• skip_browser (default: "false"). Toggle the automatic launching of the default browser to the login URL.

The callback listener may be customized with the following optional parameters. These are typically not required to be set:

• mount (default: "oidc")
• callbackmode (default: "client"). Mode of callback: "client" for connection to a port on the cli client, direct for direct connection to the Stronghold server, or "device" for device flow which has no callback.
• listenaddress (default: "localhost"). Only for client callback mode.
• port (default: 8250). Only for client callback mode.
• callbackhost (default: the Stronghold's server and port in direct callback mode, else "localhost")
• callbackmethod (default: the method used for the Stronghold server in direct callback mode, else "http"). The method to use in an OIDC redirect_uri.
• callbackport (default: value set for port in client callback mode, otherwise the port of the Stronghold server and an added /v1/auth/<path> where <path> is from the login -path option) This value is used in the redirect_uri, whereas port is the localhost port that the listener is using. These two may be different in advanced setups.

OIDC provider configuration

The OIDC authentication flow has been successfully tested with a number of providers. A full guide to configuring OAuth/OIDC applications is beyond the scope of Stronghold documentation, but a collection of provider configuration steps has been collected to help get started: OIDC Provider Setup

OIDC configuration troubleshooting

This amount of configuration required for OIDC is relatively small, but it can be tricky to debug why things aren't working. Some tips for setting up OIDC:

• If a role parameter (e.g. bound_claims) requires a map value, it can't be set individually using the Stronghold CLI. In these cases the best approach is to write the entire configuration as a single JSON object:

d8 stronghold write auth/oidc/role/demo -<<EOF
{
  "user_claim": "sub",
  "bound_audiences": "abc123",
  "role_type": "oidc",
  "policies": "demo",
  "ttl": "1h",
  "bound_claims": { "groups": ["mygroup/mysubgroup"] }
}
EOF

• Monitor Stronghold's log output. Important information about OIDC validation failures will be emitted.

• Ensure Redirect URIs are correct in Stronghold and on the provider. They need to match exactly. Check: http/https, 127.0.0.1/localhost, port numbers, whether trailing slashes are present.

• Start simple. The only claim configuration a role requires is user_claim. After authentication is known to work, you can add additional claims bindings and metadata copying.

• bound_audiences is optional for OIDC roles and typically not required. OIDC providers will use the client_id as the audience and OIDC validation expects this.

• Check your provider for what scopes are required in order to receive all of the information you need. The scopes "profile" and "groups" often need to be requested, and can be added by setting oidc_scopes="profile,groups" on the role.

• If you're seeing claim-related errors in logs, review the provider's docs very carefully to see how they're naming and structuring their claims. Depending on the provider, you may be able to construct a simple curl implicit grant request to obtain a JWT that you can inspect. An example of how to decode the JWT (in this case located in the "access_token" field of a JSON response):

cat jwt.json | jq -r .access_token | cut -d. -f2 | base64 -D

• The verbose_oidc_logging role option is available which will log the received OIDC token to the server logs if debug-level logging is enabled. This can be helpful when debugging provider setup and verifying that the received claims are what you expect. Since claims data is logged verbatim and may contain sensitive information, this option should not be used in production.

• Azure requires some additional configuration when a user is a member of more than 200 groups, described in Azure-specific handling configuration

JWT

JWT authentication

The authentication flow for roles of type "jwt" is simpler than OIDC since Stronghold only needs to validate the provided JWT.

JWT verification

JWT signatures will be verified against public keys from the issuer. This process can be done in three different ways, though only one method may be configured for a single backend:

• Static Keys. A set of public keys is stored directly in the backend configuration.

• JWKS. A JSON Web Key Set (JWKS) URL (and optional certificate chain) is configured. Keys will be fetched from this endpoint during authentication.

• OIDC Discovery. An OIDC Discovery URL (and optional certificate chain) is configured. Keys will be fetched from this URL during authentication. When OIDC Discovery is used, OIDC validation criteria (e.g. iss, aud, etc.) will be applied.

If multiple methods are needed, another instance of the backend can be mounted and configured at a different path.

Via the CLI

The default path is /jwt. If this auth method was enabled at a different path, specify -path=/my-path in the CLI.

d8 stronghold write auth/jwt/login role=demo jwt=...

Via the API

The default endpoint is auth/jwt/login. If this auth method was enabled at a different path, use that value instead of jwt.

$ curl \
    --request POST \
    --data '{"jwt": "your_jwt", "role": "demo"}' \
    http://127.0.0.1:8200/v1/auth/jwt/login

The response will contain a token at auth.client_token:

{
  "auth": {
    "client_token": "38fe9691-e623-7238-f618-c94d4e7bc674",
    "accessor": "78e87a38-84ed-2692-538f-ca8b9f400ab3",
    "policies": ["default"],
    "metadata": {
      "role": "demo"
    },
    "lease_duration": 2764800,
    "renewable": true
  }
}

Configuration

Auth methods must be configured in advance before users or machines can authenticate. These steps are usually completed by an operator or configuration management tool.

1. Enable the JWT auth method. Either the "jwt" or "oidc" name may be used. The backend will be mounted at the chosen name.

text $ d8 stronghold auth enable jwt or $ d8 stronghold auth enable oidc

1. Use the /config endpoint to configure Stronghold. To support JWT roles, either local keys, a JWKS URL, or an OIDC Discovery URL must be present. For OIDC roles, OIDC Discovery URL, OIDC Client ID and OIDC Client Secret are required. For the list of available configuration options, please see the API documentation.

text $ d8 stronghold write auth/jwt/config \ oidc_discovery_url="https://myco.auth0.com/" \ oidc_client_id="m5i8bj3iofytj" \ oidc_client_secret="f4ubv72nfiu23hnsj" \ default_role="demo"

If you need to perform JWT verification with JWT token validation, then leave the oidc_client_id and oidc_client_secret blank.

text $ d8 stronghold write auth/jwt/config \ oidc_discovery_url="https://MYDOMAIN.eu.auth0.com/" \ oidc_client_id="" \ oidc_client_secret="" \

1. Create a named role:

text d8 stronghold write auth/jwt/role/demo \ allowed_redirect_uris="http://localhost:8250/oidc/callback" \ bound_subject="r3qX9DljwFIWhsiqwFiu38209F10atW6@clients" \ bound_audiences="https://vault.plugin.auth.jwt.test" \ user_claim="https://vault/user" \ groups_claim="https://vault/groups" \ policies=webapps \ ttl=1h

This role authorizes JWTs with the given subject and audience claims, gives it the webapps policy, and uses the given user/groups claims to set up Identity aliases.

For the complete list of configuration options, please see the API documentation.

Bound claims

Once a JWT has been validated as being properly signed and not expired, the authorization flow will validate that any configured "bound" parameters match. In some cases there are dedicated parameters, for example bound_subject, which must match the JWT's sub parameter. A role may also be configured to check arbitrary claims through the bound_claims map. The map contains a set of claims and their required values. For example, assume bound_claims is set to:

{
  "division": "Europe",
  "department": "Engineering"
}

Only JWTs containing both the "division" and "department" claims, and respective matching values of "Europe" and "Engineering", would be authorized. If the expected value is a list, the claim must match one of the items in the list. To limit authorization to a set of email addresses:

{
  "email": ["fred@example.com", "julie@example.com"]
}

Bound claims can optionally be configured with globs. See the API documentation for more details.

Claims as metadata

Data from claims can be copied into the resulting auth token and alias metadata by configuring claim_mappings. This role parameter is a map of items to copy. The map elements are of the form: "<JWT claim>":"<metadata key>". Assume claim_mappings is set to:

{
  "division": "organization",
  "department": "department"
}

This specifies that the value in the JWT claim "division" should be copied to the metadata key "organization". The JWT "department" claim value will also be copied into metadata but will retain the key name. If a claim is configured in claim_mappings, it must existing in the JWT or else the authentication will fail.

Note: the metadata key name "role" is reserved and may not be used for claim mappings.

Claim specifications and JSON pointer

Some parameters (e.g. bound_claims, groups_claim, claim_mappings, user_claim) are used to point to data within the JWT. If the desired key is at the top of level of the JWT, the name can be provided directly. If it is nested at a lower level, a JSON Pointer may be used.

Assume the following JSON data to be referenced:

{
  "division": "North America",
  "groups": {
    "primary": "Engineering",
    "secondary": "Software"
  }
}

A parameter of "division" will reference "North America", as this is a top level key. A parameter "/groups/primary" uses JSON Pointer syntax to reference "Engineering" at a lower level. Any valid JSON Pointer can be used as a selector. Refer to the JSON Pointer RFC for a full description of the syntax.

API

The JWT Auth Plugin has a full HTTP API. Please see the API docs for more details.

Userpass

Userpass auth method

The userpass auth method allows users to authenticate with Stronghold using a username and password combination.

The username/password combinations are configured directly to the auth method using the users/ path. This method cannot read usernames and passwords from an external source.

The method lowercases all submitted usernames, e.g. Mary and mary are the same entry.

Authentication

Via the CLI

$ d8 stronghold login -method=userpass \
    username=mitchellh \
    password=foo

Via the API

$ curl \
    --request POST \
    --data '{"password": "foo"}' \
    http://127.0.0.1:8200/v1/auth/userpass/login/mitchellh

The response will contain the token at auth.client_token:

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "auth": {
    "client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
    "policies": ["admins"],
    "metadata": {
      "username": "mitchellh"
    },
    "lease_duration": 0,
    "renewable": false
  }
}

Configuration

Auth methods must be configured in advance before users or machines can authenticate. These steps are usually completed by an operator or configuration management tool.

1. Enable the userpass auth method:

shell-session d8 stronghold auth enable userpass

This enables the userpass auth method at auth/userpass. To enable it at a different path, use the -path flag:

shell-session d8 stronghold auth enable -path=<path> userpass

1. Configure it with users that are allowed to authenticate:

shell-session $ d8 stronghold write auth/<userpass:path>/users/mitchellh \ password=foo \ policies=admins

This creates a new user "mitchellh" with the password "foo" that will be associated with the "admins" policy. This is the only configuration necessary.

User lockout

If a user provides bad credentials several times in quick succession, Stronghold will stop trying to validate their credentials for a while, instead returning immediately with a permission denied error. We call this behavior "user lockout". The time for which a user will be locked out is called “lockout duration”. The user will be able to login after the lockout duration has passed. The number of failed login attempts after which the user is locked out is called “lockout threshold”. The lockout threshold counter is reset to zero after a few minutes without login attempts, or upon a successful login attempt. The duration after which the counter will be reset to zero after no login attempts is called "lockout counter reset". This can defeat both automated and targeted requests i.e, user-based password guessing attacks as well as automated attacks.

The user lockout feature is enabled by default. The default values for "lockout threshold" is 5 attempts, "lockout duration" is 15 minutes, "lockout counter reset" is 15 minutes.

The user lockout feature can be disabled as follows:

• It can be disabled globally using environment variable VAULT_DISABLE_USER_LOCKOUT.
• It can be disabled for all supported auth methods (ldap, userpass and approle) or a specific supported auth method using the disable_lockout parameter within user_lockout stanza in configuration file. Please see user lockout configuration for more details.
• It can be disabled for a specific auth mount using "auth tune". Please see auth tune command or auth tune api for more details.

{% alert level="warning" %}

NOTE: This feature is only supported by the userpass, ldap, and approle auth methods.

{% endalert %}

API

The Userpass auth method has a full HTTP API. Please see the Userpass auth method API for more details.

Token

Token auth method

The token auth method is built-in and automatically available at /auth/token. It allows users to authenticate using a token, as well to create new tokens, revoke secrets by token, and more.

When any other auth method returns an identity, Stronghold core invokes the token method to create a new unique token for that identity.

The token store can also be used to bypass any other auth method: you can create tokens directly, as well as perform a variety of other operations on tokens such as renewal and revocation.

Please see the token concepts page dedicated to tokens.

Authentication

Via the CLI

d8 stronghold login token=<token>

Via the API

The token is set directly as a header for the HTTP API. The header should be either X-Vault-Token: <token> or Authorization: Bearer <token>.

API

The Token auth method has a full HTTP API. Please see the Token auth method API for more details.

Провайдеры OIDC

This page collects high-level setup steps on how to configure an OIDC application for various providers. For more general usage and operation information, see the Stronghold JWT/OIDC method documentation.

OIDC providers are often highly configurable, and you should become familiar with their recommended settings and best practices. The guides listed below are largely community-driven and intended to help you get started.

• Gitlab
• Keycloak
• Kubernetes

Gitlab

Gitlab

1. Visit Settings > Applications.
2. Fill out Name and Redirect URIs.
3. Making sure to select the "openid" scope.
4. Copy client ID and secret.

Keycloak

Keycloak

1. Select/create a Realm and Client. Select a Client and visit Settings.
2. Client Protocol: openid-connect
3. Access Type: confidential
4. Standard Flow Enabled: On
5. Configure Valid Redirect URIs.
6. Save.
7. Visit Credentials. Select Client ID and Secret and note the generated secret.

Kubernetes

Kubernetes

Kubernetes can function as an OIDC provider such that Stronghold can validate its service account tokens using JWT/OIDC auth.

{% alert level="info" %}

Note: The JWT auth engine does not use Kubernetes' TokenReview API during authentication, and instead uses public key cryptography to verify the contents of JWTs. This means tokens that have been revoked by Kubernetes will still be considered valid by Stronghold until their expiry time. To mitigate this risk, use short TTLs for service account tokens or use Kubernetes auth which does use the TokenReview API.

{% endalert %}

Using service account issuer discovery

When using service account issuer discovery, you only need to provide the JWT auth mount with an OIDC discovery URL, and sometimes a TLS certificate authority to trust. This makes it the most straightforward method to configure if your Kubernetes cluster meets the requirements.

Kubernetes cluster requirements:

• ServiceAccountIssuerDiscovery feature enabled.
• Present from 1.18, defaults to enabled from 1.20.
• kube-apiserver's --service-account-issuer flag is set to a URL that is reachable from Stronghold. Public by default for most managed Kubernetes solutions.
• Must use short-lived service account tokens when logging in.
• Tokens mounted into pods default to short-lived from 1.21.

Configuration steps:

1. Ensure OIDC discovery URLs do not require authentication, as detailed here:

bash kubectl create clusterrolebinding oidc-reviewer \ --clusterrole=system:service-account-issuer-discovery \ --group=system:unauthenticated

1. Find the issuer URL of the cluster.

bash ISSUER="$(kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer')"

1. Enable and configure JWT auth in Stronghold.

2. If Stronghold is running in Kubernetes:

   bash d8 stronghold auth enable jwt d8 stronghold write auth/jwt/config \ oidc_discovery_url=https://kubernetes.default.svc.cluster.local \ oidc_discovery_ca_pem=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt

3. Alternatively, if Stronghold is not running in Kubernetes:

Note: When Stronghold is outside the cluster, the $ISSUER endpoint below may or may not be reachable. If not, you can configure JWT auth using jwt_validation_pubkeys instead.

bash d8 stronghold auth enable jwt d8 stronghold write auth/jwt/config oidc_discovery_url="${ISSUER}"

1. Configure a role and log in as detailed below.

Using JWT validation public keys

This method can be useful if Kubernetes' API is not reachable from Stronghold or if you would like a single JWT auth mount to service multiple Kubernetes clusters by chaining their public signing keys.

Kubernetes cluster requirements:

• ServiceAccountIssuerDiscovery feature enabled.
• Present from 1.18, defaults to enabled from 1.20.
• This requirement can be avoided if you can access the Kubernetes master nodes to read the public signing key directly from disk at /etc/kubernetes/pki/sa.pub. In this case, you can skip the steps to retrieve and then convert the key as it will already be in PEM format.
• Must use short-lived service account tokens when logging in.
• Tokens mounted into pods default to short-lived from 1.21.

Configuration steps:

1. Fetch the service account signing public key from your cluster's JWKS URI.

bash # Query the jwks_uri specified in /.well-known/openid-configuration kubectl get --raw "$(kubectl get --raw /.well-known/openid-configuration | jq -r '.jwks_uri' | sed -r 's/.*\.[^/]+(.*)/\1/')"

1. Convert the keys from JWK format to PEM. You can use a CLI tool or an online converter such as this one.

2. Configure the JWT auth mount with those public keys.

bash d8 stronghold write auth/jwt/config \ jwt_validation_pubkeys="-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9... -----END PUBLIC KEY-----","-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9... -----END PUBLIC KEY-----"

1. Configure a role and log in as detailed below.

Creating a role and logging in

Once your JWT auth mount is configured, you're ready to configure a role and log in. The following assumes you use the projected service account token available in all pods by default. See Specifying TTL and audience below if you'd like to control the audience or TTL.

1. Choose any value from the array of default audiences. In these examples, there is only one audience in the aud array, https://kubernetes.default.svc.cluster.local.

To find the default audiences, either create a fresh token (requires kubectl v1.24.0+):

shell-session $ kubectl create token default | cut -f2 -d. | base64 --decode {"aud":["https://kubernetes.default.svc.cluster.local"], ... "sub":"system:serviceaccount:default:default"}

Or read a token from a running pod's filesystem:

shell-session $ kubectl exec my-pod -- cat /var/run/secrets/kubernetes.io/serviceaccount/token | cut -f2 -d. | base64 --decode {"aud":["https://kubernetes.default.svc.cluster.local"], ... "sub":"system:serviceaccount:default:default"}

1. Create a role for JWT auth that the default service account from the default namespace can use.

bash d8 stronghold write auth/jwt/role/my-role \ role_type="jwt" \ bound_audiences="<AUDIENCE-FROM-PREVIOUS-STEP>" \ user_claim="sub" \ bound_subject="system:serviceaccount:default:default" \ policies="default" \ ttl="1h"

1. Pods or other clients with access to a service account JWT can then log in.

bash d8 stronghold write auth/jwt/login \ role=my-role \ jwt=@/var/run/secrets/kubernetes.io/serviceaccount/token # OR equivalent to: curl \ --fail \ --request POST \ --header "X-Vault-Request: true" \ --data '{"jwt":"<JWT-TOKEN-HERE>","role":"my-role"}' \ "${VAULT_ADDR}/v1/auth/jwt/login"

Specifying TTL and audience

If you would like to specify a custom TTL or audience for service account tokens, the following pod spec illustrates a volume mount that overrides the default admission injected token. This is especially relevant if you are unable to disable the --service-account-extend-token-expiration flag for kube-apiserver and want to use short TTLs.

When using the resulting token, you will need to set bound_audiences=stronghold when creating roles in Stronghold's JWT auth mount.

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  # automountServiceAccountToken is redundant in this example because the
  # mountPath used overlaps with the default path. The overlap stops the default
  # admission injected token from being created. You can use this option to
  # ensure only a single token is mounted if you choose a different mount path.
  automountServiceAccountToken: false
  containers:
    - name: nginx
      image: nginx
      volumeMounts:
      - name: custom-token
        mountPath: /var/run/secrets/kubernetes.io/serviceaccount
  volumes:
  - name: custom-token
    projected:
      defaultMode: 420
      sources:
      - serviceAccountToken:
          path: token
          expirationSeconds: 600 # 10 minutes is the minimum TTL
          audience: stronghold   # Must match your JWT role's `bound_audiences`
      # The remaining sources are included to mimic the rest of the default
      # admission injected volume.
      - configMap:
          name: kube-root-ca.crt
          items:
          - key: ca.crt
            path: ca.crt
      - downwardAPI:
          items:
          - fieldRef:
              apiVersion: v1
              fieldPath: metadata.namespace
            path: namespace

MFA

Multifactor

Configuring LDAP Adapter

Coming soon...

TOTP

Configure TOTP

Coming soon...

Механизмы секретов

KV1/KV2

Обзор

The kv secrets engine is a generic Key-Value store used to store arbitrary secrets within the configured physical storage for Stronghold. This backend can be run in one of two modes; either it can be configured to store a single value for a key or, versioning can be enabled and a configurable number of versions for each key will be stored.

KV version 1

When running the kv secrets backend non-versioned, only the most recently written value for a key will be preserved. The benefits of non-versioned kv is a reduced storage size for each key since no additional metadata or history is stored. Additionally, requests going to a backend configured this way will be more performant because for any given request there will be fewer storage calls and no locking.

More information about running in this mode can be found in the K/V Version 1 Docs

KV version 2

When running v2 of the kv backend a key can retain a configurable number of versions. This defaults to 10 versions. The older versions' metadata and data can be retrieved. Additionally, Check-and-Set operations can be used to avoid overwriting data unintentionally.

When a version is deleted the underlying data is not removed, rather it is marked as deleted. Deleted versions can be undeleted. To permanently remove a version's data the destroy command or API endpoint can be used. Additionally all versions and metadata for a key can be deleted by deleting on the metadata command or API endpoint. Each of these operations can be ACL'ed differently, restricting who has permissions to soft delete, undelete, or fully remove data.

More information about running in this mode can be found in the K/V Version 2 Docs

KV версия 1

The kv secrets engine is used to store arbitrary secrets within the configured physical storage for Stronghold.

Writing to a key in the kv backend will replace the old value; sub-fields are not merged together.

Key names must always be strings. If you write non-string values directly via the CLI, they will be converted into strings. However, you can preserve non-string values by writing the key/value pairs to Stronghold from a JSON file or using the HTTP API.

This secrets engine honors the distinction between the create and update capabilities inside ACL policies.

{% alert level="warning" %}

Note: Path and key names are not obfuscated or encrypted; only the values set on keys are. You should not store sensitive information as part of a secret's path.

{% endalert %}

Setup

To enable a version 1 kv store:

d8 stronghold secrets enable -version=1 kv

Usage

After the secrets engine is configured and a user/machine has an Stronghold token with the proper permission, it can generate credentials. The kv secrets engine allows for writing keys with arbitrary values.

1. Write arbitrary data:

shell-session $ d8 stronghold kv put kv/my-secret my-value=s3cr3t Success! Data written to: kv/my-secret

1. Read arbitrary data:

shell-session $ d8 stronghold kv get kv/my-secret Key Value --- ----- my-value s3cr3t

1. List the keys:

```shell-session $ d8 stronghold kv list kv/ Keys

---

my-secret ```

1. Delete a key:

shell-session $ d8 stronghold kv delete kv/my-secret Success! Data deleted (if it existed) at: kv/my-secret

You can also use Stronghold's password policy feature to generate arbitrary values.

1. Write a password policy:

```shell-session $ d8 stronghold write sys/policies/password/example policy=-<<EOF

 length=20

 rule "charset" {
   charset = "abcdefghij0123456789"
   min-chars = 1
 }

 rule "charset" {
   charset = "!@#$%^&*STUVWXYZ"
   min-chars = 1
 }

EOF ```

1. Write data using the example policy:

shell-session $ d8 stronghold kv put kv/my-generated-secret \ password=$(d8 stronghold read -field password sys/policies/password/example/generate)

1. Read the generated data:

shell-session $ d8 stronghold kv get kv/my-generated-secret ====== Data ====== Key Value --- ----- password ^dajd609Xf8Zhac$dW24

TTLs

Unlike other secrets engines, the KV secrets engine does not enforce TTLs for expiration. Instead, the lease_duration is a hint for how often consumers should check back for a new value.

If provided a key of ttl, the KV secrets engine will utilize this value as the lease duration:

$ d8 stronghold kv put kv/my-secret ttl=30m my-value=s3cr3t
Success! Data written to: kv/my-secret

Even with a ttl set, the secrets engine never removes data on its own. The ttl key is merely advisory.

When reading a value with a ttl, both the ttl key and the refresh interval will reflect the value:

$ d8 stronghold kv get kv/my-secret
Key                 Value
---                 -----
my-value            s3cr3t
ttl                 30m

API

The KV secrets engine has a full HTTP API. Please see the KV secrets engine API for more details.

KV версия 2

The kv secrets engine is used to store arbitrary secrets within the configured physical storage for Stronghold.

Key names must always be strings. If you write non-string values directly via the CLI, they will be converted into strings. However, you can preserve non-string values by writing the key/value pairs to Stronghold from a JSON file or using the HTTP API.

This secrets engine honors the distinction between the create and update capabilities inside ACL policies. The patch capability is also supported which is used to represent partial updates whereas the update capability represents full overwrites.

Setup

Most secrets engines must be configured in advance before they can perform their functions. These steps are usually completed by an operator or configuration management tool.

A v2 kv secrets engine can be enabled by:

d8 stronghold secrets enable -version=2 kv

Or, you can pass kv-v2 as the secrets engine type:

d8 stronghold secrets enable kv-v2

Additionally, when running a dev-mode server, the v2 kv secrets engine is enabled by default at the path secret/ (for non-dev servers, it is currently v1). It can be disabled, moved, or enabled multiple times at different paths. Each instance of the KV secrets engine is isolated and unique.

Upgrading from version 1

An existing version 1 kv store can be upgraded to a version 2 kv store via the CLI or API, as shown below. This will start an upgrade process to upgrade the existing key/value data to a versioned format. The mount will be inaccessible during this process. This process could take a long time, so plan accordingly.

Once upgraded to version 2, the former paths at which the data was accessible will no longer suffice. You will need to adjust user policies to add access to the version 2 paths as detailed in the ACL Rules section below. Similarly, users/applications will need to update the paths at which they interact with the kv data once it has been upgraded to version 2.

An existing version 1 kv can be upgraded to a version 2 KV store with the CLI command:

$ d8 stronghold kv enable-versioning secret/
Success! Tuned the secrets engine at: secret/

or via the API:

$ cat payload.json
{
  "options": {
      "version": "2"
  }
}

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/mounts/secret/tune

ACL rules

The version 2 kv store uses a prefixed API, which is different from the version 1 API. Before upgrading from a version 1 kv the ACL rules should be changed. Also different paths in the version 2 API can be ACL'ed differently.

Writing and reading versions are prefixed with the data/ path. This policy that worked for the version 1 kv:

path "secret/dev/team-1/*" {
  capabilities = ["create", "update", "read"]
}

Should be changed to:

path "secret/data/dev/team-1/*" {
  capabilities = ["create", "update", "read"]
}

There are different levels of data deletion for this backend. To grant a policy the permissions to delete the latest version of a key:

path "secret/data/dev/team-1/*" {
  capabilities = ["delete"]
}

To allow the policy to delete any version of a key:

path "secret/delete/dev/team-1/*" {
  capabilities = ["update"]
}

To allow a policy to undelete data:

path "secret/undelete/dev/team-1/*" {
  capabilities = ["update"]
}

To allow a policy to destroy versions:

path "secret/destroy/dev/team-1/*" {
  capabilities = ["update"]
}

To allow a policy to list keys:

path "secret/metadata/dev/team-1/*" {
  capabilities = ["list"]
}

To allow a policy to view metadata for each version:

path "secret/metadata/dev/team-1/*" {
  capabilities = ["read"]
}

To allow a policy to permanently remove all versions and metadata for a key:

path "secret/metadata/dev/team-1/*" {
  capabilities = ["delete"]
}

The allowed_parameters, denied_parameters, and required_parameters fields are not supported for policies used with the version 2 kv store. See the Policies Concepts for a description of these parameters.

See the API Specification for more information.

Usage

After the secrets engine is configured and a user/machine has an Stronghold token with the proper permission, it can generate credentials. The kv secrets engine allows for writing keys with arbitrary values.

The path-like KV-v1 syntax for referencing a secret (secret/foo) can still be used in KV-v2, but we recommend using the -mount=secret flag syntax to avoid mistaking it for the actual path to the secret (secret/data/foo is the real path).

Writing/Reading arbitrary data

1. Write arbitrary data:

shell-session $ d8 stronghold kv put -mount=secret my-secret foo=a bar=b Key Value --- ----- created_time 2024-06-19T17:20:22.985303Z custom_metadata <nil> deletion_time n/a destroyed false version 1

1. Read arbitrary data:

```shell-session $ d8 stronghold kv get -mount=secret my-secret ====== Metadata ====== Key Value --- ----- created_time 2024-06-19T17:20:22.985303Z custom_metadata deletion_time n/a destroyed false version 1

====== Data ====== Key Value --- ----- foo a bar b ```

1. Write another version, the previous version will still be accessible. The -cas flag can optionally be passed to perform a check-and-set operation. If not set the write will be allowed. In order for a write to be successful, cas must be set to the current version of the secret. If set to 0 a write will only be allowed if the key doesn’t exist as unset keys do not have any version information. Also remember that soft deletes do not remove any underlying version data from storage. In order to write to a soft deleted key, the cas parameter must match the key's current version.

shell-session $ d8 stronghold kv put -mount=secret -cas=1 my-secret foo=aa bar=bb Key Value --- ----- created_time 2024-06-19T17:22:23.369372Z custom_metadata <nil> deletion_time n/a destroyed false version 2

1. Reading now will return the newest version of the data:

```shell-session $ d8 stronghold kv get -mount=secret my-secret ====== Metadata ====== Key Value --- ----- created_time 2024-06-19T17:22:23.369372Z custom_metadata deletion_time n/a destroyed false version 2

====== Data ====== Key Value --- ----- foo aa bar bb ```

1. Partial updates can be accomplished using the d8 stronghold kv patch command. A command will initially attempt an HTTP PATCH request which requires the patch ACL capability. The PATCH request will fail if the token used is associated with a policy that does not contain the patch capability. In this case the command will perform a read, local update, and subsequent write which require both the read and update ACL capabilities.

The -cas flag can optionally be passed to perform a check-and-set operation. It will only be used in the case of the initial PATCH request. The read-then-write flow will use the version value from the secret returned by the read to perform a check-and-set operation in the subsequent write.

shell-session $ d8 stronghold kv patch -mount=secret -cas=2 my-secret bar=bbb Key Value --- ----- created_time 2024-06-19T17:23:49.199802Z custom_metadata <nil> deletion_time n/a destroyed false version 3

1. The d8 stronghold kv patch command also supports a -method flag which can be used to specify HTTP PATCH or read-then-write. The supported values are patch and rw for HTTP PATCH and read-then-write, respectively.

Perform a patch using the patch method:

shell-session $ d8 stronghold kv patch -mount=secret -method=patch -cas=2 my-secret bar=bbb Key Value --- ----- created_time 2024-06-19T17:23:49.199802Z custom_metadata <nil> deletion_time n/a destroyed false version 3

Perform a patch using the read-then-write method:

shell-session $ d8 stronghold kv patch -mount=secret -method=rw my-secret bar=bbb Key Value --- ----- created_time 2024-06-19T17:23:49.199802Z custom_metadata <nil> deletion_time n/a destroyed false version 3

1. Reading after a patch will return the newest version of the data in which only the specified fields were updated:

```shell-session $ d8 stronghold kv get -mount=secret my-secret ====== Metadata ====== Key Value --- ----- created_time 2024-06-19T17:23:49.199802Z custom_metadata deletion_time n/a destroyed false version 3

====== Data ====== Key Value --- ----- foo aa bar bbb ```

1. Previous versions can be accessed with the -version flag:

```shell-session $ d8 stronghold kv get -mount=secret -version=1 my-secret ====== Metadata ====== Key Value --- ----- created_time 2024-06-19T17:20:22.985303Z custom_metadata deletion_time n/a destroyed false version 1

====== Data ====== Key Value --- ----- foo a bar b ```

You can also use Stronghold's password policy feature to generate arbitrary values.

1. Write a password policy:

```shell-session $ d8 stronghold write sys/policies/password/example policy=-<<EOF

 length=20

 rule "charset" {
   charset = "abcdefghij0123456789"
   min-chars = 1
 }

 rule "charset" {
   charset = "!@#$%^&*STUVWXYZ"
   min-chars = 1
 }

EOF ```

1. Write data using the example policy:

shell-session $ d8 stronghold kv put -mount=secret my-generated-secret \ password=$(d8 stronghold read -field password sys/policies/password/example/generate)

Example output:

```plaintext ========= Secret Path ========= secret/data/my-generated-secret

======= Metadata ======= Key Value --- ----- created_time 2023-05-10T14:32:32.37354939Z custom_metadata deletion_time n/a destroyed false version 1 ```

1. Read the generated data:

```shell-session $ d8 stronghold kv get -mount=secret my-generated-secret ========= Secret Path ========= secret/data/my-generated-secret

======= Metadata ======= Key Value --- ----- created_time 2023-05-10T14:32:32.37354939Z custom_metadata deletion_time n/a destroyed false version 1

====== Data ====== Key Value --- ----- password !hh&be1e4j16dVc0ggae ```

Deleting and destroying data

When deleting data the standard d8 stronghold kv delete command will perform a soft delete. It will mark the version as deleted and populate a deletion_time timestamp. Soft deletes do not remove the underlying version data from storage, which allows the version to be undeleted. The d8 stronghold kv undelete command handles undeleting versions.

A version's data is permanently deleted only when the key has more versions than are allowed by the max-versions setting, or when using d8 stronghold kv destroy. When the destroy command is used the underlying version data will be removed and the key metadata will be marked as destroyed. If a version is cleaned up by going over max-versions the version metadata will also be removed from the key.

See the commands below for more information:

1. The latest version of a key can be deleted with the delete command, this also takes a -versions flag to delete prior versions:

shell-session $ d8 stronghold kv delete -mount=secret my-secret Success! Data deleted (if it existed) at: secret/data/my-secret

1. Versions can be undeleted:

```shell-session $ d8 stronghold kv undelete -mount=secret -versions=2 my-secret Success! Data written to: secret/undelete/my-secret

$ d8 stronghold kv get -mount=secret my-secret ====== Metadata ====== Key Value --- ----- created_time 2024-06-19T17:23:21.834403Z custom_metadata deletion_time n/a destroyed false version 2

====== Data ====== Key Value --- ----- my-value short-lived-s3cr3t ```

1. Destroying a version permanently deletes the underlying data:

shell-session $ d8 stronghold kv destroy -mount=secret -versions=2 my-secret Success! Data written to: secret/destroy/my-secret

Key metadata

All versions and key metadata can be tracked with the metadata command & API. Deleting the metadata key will cause all metadata and versions for that key to be permanently removed.

See the commands below for more information:

1. All metadata and versions for a key can be viewed:

```shell-session $ d8 stronghold kv metadata get -mount=secret my-secret ========== Metadata ========== Key Value --- ----- cas_required false created_time 2024-06-19T17:20:22.985303Z current_version 2 custom_metadata delete_version_after 0s max_versions 0 oldest_version 0 updated_time 2024-06-19T17:22:23.369372Z

====== Version 1 ====== Key Value --- ----- created_time 2024-06-19T17:20:22.985303Z deletion_time n/a destroyed false

====== Version 2 ====== Key Value --- ----- created_time 2024-06-19T17:22:23.369372Z deletion_time n/a destroyed true ```

1. The metadata settings for a key can be configured:

shell-session $ d8 stronghold kv metadata put -mount=secret -max-versions 2 -delete-version-after="3h25m19s" my-secret Success! Data written to: secret/metadata/my-secret

Delete-version-after settings will apply only to new versions. Max versions changes will be applied on next write:

shell-session $ d8 stronghold kv put -mount=secret my-secret my-value=newer-s3cr3t Key Value --- ----- created_time 2024-06-19T17:31:16.662563Z custom_metadata <nil> deletion_time 2024-06-19T20:56:35.662563Z destroyed false version 4

Once a key has more versions than max versions the oldest versions are cleaned up:

```shell-session $ d8 stronghold kv metadata get -mount=secret my-secret ========== Metadata ========== Key Value --- ----- cas_required false created_time 2024-06-19T17:20:22.985303Z current_version 4 custom_metadata delete_version_after 3h25m19s max_versions 2 oldest_version 3 updated_time 2024-06-19T17:31:16.662563Z

====== Version 3 ====== Key Value --- ----- created_time 2024-06-19T17:23:21.834403Z deletion_time n/a destroyed true

====== Version 4 ====== Key Value --- ----- created_time 2024-06-19T17:31:16.662563Z deletion_time 2024-06-19T20:56:35.662563Z destroyed false ```

A secret's key metadata can contain custom metadata used to describe the secret. The data will be stored as string-to-string key-value pairs. The -custom-metadata flag can be repeated to add multiple key-value pairs.

The d8 stronghold kv metadata put command can be used to fully overwrite the value of custom_metadata:

```shell-session $ d8 stronghold kv metadata put -mount=secret -custom-metadata=foo=abc -custom-metadata=bar=123 my-secret Success! Data written to: secret/metadata/my-secret

$ d8 stronghold kv get -mount=secret my-secret ====== Metadata ====== Key Value --- ----- created_time 2024-06-19T17:22:23.369372Z custom_metadata map[bar:123 foo:abc] deletion_time n/a destroyed false version 2

====== Data ====== Key Value --- ----- foo aa bar bb ```

The d8 stronghold kv metadata patch command can be used to partially overwrite the value of custom_metadata. The following invocation will update custom_metadata sub-field foo but leave bar untouched:

shell-session $ d8 stronghold kv metadata patch -mount=secret -custom-metadata=foo=def my-secret Success! Data written to: secret/metadata/my-secret

```shell-session $ d8 stronghold kv get -mount=secret my-secret ====== Metadata ====== Key Value --- ----- created_time 2024-06-19T17:22:23.369372Z custom_metadata map[bar:123 foo:def] deletion_time n/a destroyed false version 2

====== Data ====== Key Value --- ----- foo aa bar bb ```

1. Permanently delete all metadata and versions for a key:

shell-session $ d8 stronghold kv metadata delete -mount=secret my-secret Success! Data deleted (if it existed) at: secret/metadata/my-secret

API

The KV secrets engine has a full HTTP API. Please see the KV secrets engine API for more details.

PKI

This document provides a brief overview of setting up an Stronghold PKI Secrets Engine with a Root CA certificate.

Mount the backend

The first step to using the PKI backend is to mount it. Unlike the kv backend, the pki backend is not mounted by default.

$ d8 stronghold secrets enable pki
Successfully mounted 'pki' at 'pki'!

Configure a CA certificate

Next, Stronghold must be configured with a CA certificate and associated private key. We'll take advantage of the backend's self-signed root generation support, but Stronghold also supports generating an intermediate CA (with a CSR for signing) or setting a PEM-encoded certificate and private key bundle directly into the backend.

Generally you'll want a root certificate to only be used to sign CA intermediate certificates, but for this example we'll proceed as if you will issue certificates directly from the root. As it's a root, we'll want to set a long maximum life time for the certificate; since it honors the maximum mount TTL, first we adjust that:

$ d8 stronghold secrets tune -max-lease-ttl=87600h pki
Successfully tuned mount 'pki'!

That sets the maximum TTL for secrets issued from the mount to 10 years. (Note that roles can further restrict the maximum TTL.)

Now, we generate our root certificate:

$ d8 stronghold write pki/root/generate/internal common_name=myopenbao.com ttl=87600h
Key             Value
---             -----
certificate     -----BEGIN CERTIFICATE-----
MIIDNTCCAh2gAwIBAgIUJqrw/9EDZbp4DExaLjh0vSAHyBgwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMjA4MTkyMzIwWhcNMjcx
MjA2MTkyMzQ5WjAWMRQwEgYDVQQDEwtteXZhdWx0LmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAKY/vJ6sRFym+yFYUneoVtDmOCaDKAQiGzQw0IXL
wgMBBb82iKpYj5aQjXZGIl+VkVnCi+M2AQ/iYXWZf1kTAdle4A6OC4+VefSIa2b4
eB7R8aiGTce62jB95+s5/YgrfIqk6igfpCSXYLE8ubNDA2/+cqvjhku1UzlvKBX2
hIlgWkKlrsnybHN+B/3Usw9Km/87rzoDR3OMxLV55YPHiq6+olIfSSwKAPjH8LZm
uM1ITLG3WQUl8ARF17Dj+wOKqbUG38PduVwKL5+qPksrvNwlmCP7Kmjncc6xnYp6
5lfr7V4DC/UezrJYCIb0g/SvtxoN1OuqmmvSTKiEE7hVOAcCAwEAAaN7MHkwDgYD
VR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFECKdYM4gDbM
kxRZA2wR4f/yNhQUMB8GA1UdIwQYMBaAFECKdYM4gDbMkxRZA2wR4f/yNhQUMBYG
A1UdEQQPMA2CC215dmF1bHQuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCCJKZPcjjn
7mvD2+sr6lx4DW/vJwVSW8eTuLtOLNu6/aFhcgTY/OOB8q4n6iHuLrEt8/RV7RJI
obRx74SfK9BcOLt4+DHGnFXqu2FNVnhDMOKarj41yGyXlJaQRUPYf6WJJLF+ZphN
nNsZqHJHBfZtpJpE5Vywx3pah08B5yZHk1ItRPEz7EY3uwBI/CJoBb+P5Ahk6krc
LZ62kFwstkVuFp43o3K7cRNexCIsZGx2tsyZ0nyqDUFsBr66xwUfn3C+/1CDc9YL
zjq+8nI2ooIrj4ZKZCOm2fKd1KeGN/CZD7Ob6uNhXrd0Tjwv00a7nffvYQkl/1V5
BT55jevSPVVu
-----END CERTIFICATE-----
expiration      1828121029
issuing_ca      -----BEGIN CERTIFICATE-----
MIIDNTCCAh2gAwIBAgIUJqrw/9EDZbp4DExaLjh0vSAHyBgwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMjA4MTkyMzIwWhcNMjcx
MjA2MTkyMzQ5WjAWMRQwEgYDVQQDEwtteXZhdWx0LmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAKY/vJ6sRFym+yFYUneoVtDmOCaDKAQiGzQw0IXL
wgMBBb82iKpYj5aQjXZGIl+VkVnCi+M2AQ/iYXWZf1kTAdle4A6OC4+VefSIa2b4
eB7R8aiGTce62jB95+s5/YgrfIqk6igfpCSXYLE8ubNDA2/+cqvjhku1UzlvKBX2
hIlgWkKlrsnybHN+B/3Usw9Km/87rzoDR3OMxLV55YPHiq6+olIfSSwKAPjH8LZm
uM1ITLG3WQUl8ARF17Dj+wOKqbUG38PduVwKL5+qPksrvNwlmCP7Kmjncc6xnYp6
5lfr7V4DC/UezrJYCIb0g/SvtxoN1OuqmmvSTKiEE7hVOAcCAwEAAaN7MHkwDgYD
VR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFECKdYM4gDbM
kxRZA2wR4f/yNhQUMB8GA1UdIwQYMBaAFECKdYM4gDbMkxRZA2wR4f/yNhQUMBYG
A1UdEQQPMA2CC215dmF1bHQuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCCJKZPcjjn
7mvD2+sr6lx4DW/vJwVSW8eTuLtOLNu6/aFhcgTY/OOB8q4n6iHuLrEt8/RV7RJI
obRx74SfK9BcOLt4+DHGnFXqu2FNVnhDMOKarj41yGyXlJaQRUPYf6WJJLF+ZphN
nNsZqHJHBfZtpJpE5Vywx3pah08B5yZHk1ItRPEz7EY3uwBI/CJoBb+P5Ahk6krc
LZ62kFwstkVuFp43o3K7cRNexCIsZGx2tsyZ0nyqDUFsBr66xwUfn3C+/1CDc9YL
zjq+8nI2ooIrj4ZKZCOm2fKd1KeGN/CZD7Ob6uNhXrd0Tjwv00a7nffvYQkl/1V5
BT55jevSPVVu
-----END CERTIFICATE-----
serial_number   26:aa:f0:ff:d1:03:65:ba:78:0c:4c:5a:2e:38:74:bd:20:07:c8:18

The returned certificate is purely informational; it and its private key are safely stored in the backend mount.

Set URL configuration

Generated certificates can have the CRL location and the location of the issuing certificate encoded. These values must be set manually and typically to FQDN associated to the Stronghold server, but can be changed at any time.

$ d8 stronghold write pki/config/urls issuing_certificates="http://openbao.example.com:8200/v1/pki/ca" crl_distribution_points="http://openbao.example.com:8200/v1/pki/crl"
Success! Data written to: pki/ca/urls

Configure a role

The next step is to configure a role. A role is a logical name that maps to a policy used to generate those credentials. For example, let's create an "example-dot-com" role:

$ d8 stronghold write pki/roles/example-dot-com \
    allowed_domains=example.com \
    allow_subdomains=true max_ttl=72h
Success! Data written to: pki/roles/example-dot-com

Issue certificates

By writing to the roles/example-dot-com path we are defining the example-dot-com role. To generate a new certificate, we simply write to the issue endpoint with that role name: Stronghold is now configured to create and manage certificates!

$ d8 stronghold write pki/issue/example-dot-com \
    common_name=blah.example.com
Key                 Value
---                 -----
certificate         -----BEGIN CERTIFICATE-----
MIIDvzCCAqegAwIBAgIUWQuvpMpA2ym36EoiYyf3Os5UeIowDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMjA4MTkyNDA1WhcNMTcx
MjExMTkyNDM1WjAbMRkwFwYDVQQDExBibGFoLmV4YW1wbGUuY29tMIIBIjANBgkq
hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1CU93lVgcLXGPxRGTRT3GM5wqytCo7Z6
gjfoHyKoPCAqjRdjsYgp1FMvumNQKjUat5KTtr2fypbOnAURDCh4bN/omcj7eAqt
ldJ8mf8CtKUaaJ1kp3R6RRFY/u96BnmKUG8G7oDeEDsKlXuEuRcNbGlGF8DaM/O1
HFa57cM/8yFB26Nj5wBoG5Om6ee5+W+14Qee8AB6OJbsf883Z+zvhJTaB0QM4ZUq
uAMoMVEutWhdI5EFm5OjtMeMu2U+iJl2XqqgQ/JmLRjRdMn1qd9TzTaVSnjoZ97s
jHK444Px1m45einLqKUJ+Ia2ljXYkkItJj9Ut6ZSAP9fHlAtX84W3QIDAQABo4H/
MIH8MA4GA1UdDwEB/wQEAwIDqDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUH
AwIwHQYDVR0OBBYEFH/YdObW6T94U0zuU5hBfTfU5pt1MB8GA1UdIwQYMBaAFECK
dYM4gDbMkxRZA2wR4f/yNhQUMDsGCCsGAQUFBwEBBC8wLTArBggrBgEFBQcwAoYf
aHR0cDovLzEyNy4wLjAuMTo4MjAwL3YxL3BraS9jYTAbBgNVHREEFDASghBibGFo
LmV4YW1wbGUuY29tMDEGA1UdHwQqMCgwJqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6
ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3DQEBCwUAA4IBAQCDXbHV68VayweB2tkb
KDdCaveaTULjCeJUnm9UT/6C0YqC/RxTAjdKFrilK49elOA3rAtEL6dmsDP2yH25
ptqi2iU+y99HhZgu0zkS/p8elYN3+l+0O7pOxayYXBkFf5t0TlEWSTb7cW+Etz/c
MvSqx6vVvspSjB0PsA3eBq0caZnUJv2u/TEiUe7PPY0UmrZxp/R/P/kE54yI3nWN
4Cwto6yUwScOPbVR1d3hE2KU2toiVkEoOk17UyXWTokbG8rG0KLj99zu7my+Fyre
sjV5nWGDSMZODEsGxHOC+JgNAC1z3n14/InFNOsHICnA5AnJzQdSQQjvcZHN2NyW
+t4f
-----END CERTIFICATE-----
issuing_ca          -----BEGIN CERTIFICATE-----
MIIDNTCCAh2gAwIBAgIUJqrw/9EDZbp4DExaLjh0vSAHyBgwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMjA4MTkyMzIwWhcNMjcx
MjA2MTkyMzQ5WjAWMRQwEgYDVQQDEwtteXZhdWx0LmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAKY/vJ6sRFym+yFYUneoVtDmOCaDKAQiGzQw0IXL
wgMBBb82iKpYj5aQjXZGIl+VkVnCi+M2AQ/iYXWZf1kTAdle4A6OC4+VefSIa2b4
eB7R8aiGTce62jB95+s5/YgrfIqk6igfpCSXYLE8ubNDA2/+cqvjhku1UzlvKBX2
hIlgWkKlrsnybHN+B/3Usw9Km/87rzoDR3OMxLV55YPHiq6+olIfSSwKAPjH8LZm
uM1ITLG3WQUl8ARF17Dj+wOKqbUG38PduVwKL5+qPksrvNwlmCP7Kmjncc6xnYp6
5lfr7V4DC/UezrJYCIb0g/SvtxoN1OuqmmvSTKiEE7hVOAcCAwEAAaN7MHkwDgYD
VR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFECKdYM4gDbM
kxRZA2wR4f/yNhQUMB8GA1UdIwQYMBaAFECKdYM4gDbMkxRZA2wR4f/yNhQUMBYG
A1UdEQQPMA2CC215dmF1bHQuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCCJKZPcjjn
7mvD2+sr6lx4DW/vJwVSW8eTuLtOLNu6/aFhcgTY/OOB8q4n6iHuLrEt8/RV7RJI
obRx74SfK9BcOLt4+DHGnFXqu2FNVnhDMOKarj41yGyXlJaQRUPYf6WJJLF+ZphN
nNsZqHJHBfZtpJpE5Vywx3pah08B5yZHk1ItRPEz7EY3uwBI/CJoBb+P5Ahk6krc
LZ62kFwstkVuFp43o3K7cRNexCIsZGx2tsyZ0nyqDUFsBr66xwUfn3C+/1CDc9YL
zjq+8nI2ooIrj4ZKZCOm2fKd1KeGN/CZD7Ob6uNhXrd0Tjwv00a7nffvYQkl/1V5
BT55jevSPVVu
-----END CERTIFICATE-----
private_key         -----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA1CU93lVgcLXGPxRGTRT3GM5wqytCo7Z6gjfoHyKoPCAqjRdj
sYgp1FMvumNQKjUat5KTtr2fypbOnAURDCh4bN/omcj7eAqtldJ8mf8CtKUaaJ1k
p3R6RRFY/u96BnmKUG8G7oDeEDsKlXuEuRcNbGlGF8DaM/O1HFa57cM/8yFB26Nj
5wBoG5Om6ee5+W+14Qee8AB6OJbsf883Z+zvhJTaB0QM4ZUquAMoMVEutWhdI5EF
m5OjtMeMu2U+iJl2XqqgQ/JmLRjRdMn1qd9TzTaVSnjoZ97sjHK444Px1m45einL
qKUJ+Ia2ljXYkkItJj9Ut6ZSAP9fHlAtX84W3QIDAQABAoIBAQCf5YIANfF+gkNt
/+YM6yRi+hZJrU2I/1zPETxPW1vaFZR8y4hEoxCEDD8JCRm+9k+w1TWoorvxgkEv
r1HuDALYbNtwLd/71nCHYCKyH1b2uQpyl07qOAyASlb9r5oVjz4E6eobkd3N9fJA
QN0EdK+VarN968mLJsD3Hxb8chGdObBCQ+LO+zdqQLaz+JwhfnK98rm6huQtYK3w
ccd0OwoVmtZz2eJl11TJkB9fi4WqJyxl4wST7QC80LstB1deR78oDmN5WUKU12+G
4Mrgc1hRwUSm18HTTgAhaA4A3rjPyirBohb5Sf+jJxusnnay7tvWeMnIiRI9mqCE
dr3tLrcxAoGBAPL+jHVUF6sxBqm6RTe8Ewg/8RrGmd69oB71QlVUrLYyC96E2s56
19dcyt5U2z+F0u9wlwR1rMb2BJIXbxlNk+i87IHmpOjCMS38SPZYWLHKj02eGfvA
MjKKqEjNY/md9eVAVZIWSEy63c4UcBK1qUH3/5PNlyjk53gCOI/4OXX/AoGBAN+A
Alyd6A/pyHWq8WMyAlV18LnzX8XktJ07xrNmjbPGD5sEHp+Q9V33NitOZpu3bQL+
gCNmcrodrbr9LBV83bkAOVJrf82SPaBesV+ATY7ZiWpqvHTmcoS7nglM2XTr+uWR
Y9JGdpCE9U5QwTc6qfcn7Eqj7yNvvHMrT+1SHwsjAoGBALQyQEbhzYuOF7rV/26N
ci+z+0A39vNO++b5Se+tk0apZlPlgb2NK3LxxR+LHevFed9GRzdvbGk/F7Se3CyP
cxgswdazC6fwGjhX1mOYsG1oIU0V6X7f0FnaqWETrwf1M9yGEO78xzDfgozIazP0
s0fQeR9KXsZcuaotO3TIRxRRAoGAMFIDsLRvDKm1rkL0B0czm/hwwDMu/KDyr5/R
2M2OS1TB4PjmCgeUFOmyq3A63OWuStxtJboribOK8Qd1dXvWj/3NZtVY/z/j1P1E
Ceq6We0MOZa0Ae4kyi+p/kbAKPgv+VwSoc6cKailRHZPH7quLoJSIt0IgbfRnXC6
ygtcLNMCgYBwiPw2mTYvXDrAcO17NhK/r7IL7BEdFdx/w8vNJQp+Ub4OO3Iw6ARI
vXxu6A+Qp50jra3UUtnI+hIirMS+XEeWqJghK1js3ZR6wA/ZkYZw5X1RYuPexb/4
6befxmnEuGSbsgvGqYYTf5Z0vgsw4tAHfNS7TqSulYH06CjeG1F8DQ==
-----END RSA PRIVATE KEY-----
private_key_type    rsa
serial_number       59:0b:af:a4:ca:40:db:29:b7:e8:4a:22:63:27:f7:3a:ce:54:78:8a

Stronghold has now generated a new set of credentials using the example-dot-com role configuration. Here we see the dynamically generated private key and certificate.

Using ACLs, it is possible to restrict using the pki backend such that trusted operators can manage the role definitions, and both users and applications are restricted in the credentials they are allowed to read.

If you get stuck at any time, simply run d8 stronghold path-help pki or with a subpath for interactive help output.

API

The PKI secrets engine has a full HTTP API. Please see the PKI secrets engine API for more details.

SSH

The signed SSH certificates is the simplest and most powerful in terms of setup complexity and in terms of being platform agnostic. By leveraging Stronghold's powerful CA capabilities and functionality built into OpenSSH, clients can SSH into target hosts using their own local SSH keys.

In this section, the term "client" refers to the person or machine performing the SSH operation. The "host" refers to the target machine. If this is confusing, substitute "client" with "user".

This page will show a quick start for this secrets engine. For detailed documentation on every path, use bao path-help after mounting the secrets engine.

Client key signing

Before a client can request their SSH key be signed, the Stronghold SSH secrets engine must be configured. Usually an Stronghold administrator or security team performs these steps. It is also possible to automate these actions using a configuration management tool like Chef, Puppet, Ansible, or Salt.

Signing key & role configuration

The following steps are performed in advance by an Stronghold administrator, security team, or configuration management tooling.

1. Mount the secrets engine. Like all secrets engines in Stronghold, the SSH secrets engine must be mounted before use.

   text $ d8 stronghold secrets enable -path=ssh-client-signer ssh Successfully mounted 'ssh' at 'ssh-client-signer'!

   This enables the SSH secrets engine at the path "ssh-client-signer". It is possible to mount the same secrets engine multiple times using different -path arguments. The name "ssh-client-signer" is not special - it can be any name, but this documentation will assume "ssh-client-signer".

2. Configure Stronghold with a CA for signing client keys using the /config/ca endpoint. If you do not have an internal CA, Stronghold can generate a keypair for you.

   text $ d8 stronghold write ssh-client-signer/config/ca generate_signing_key=true Key Value --- ----- public_key ssh-rsa AAAAB3NzaC1yc2EA...

   If you already have a keypair, specify the public and private key parts as part of the payload:

   text $ d8 stronghold write ssh-client-signer/config/ca \ private_key="..." \ public_key="..."

   The SSH secrets engine allows multiple Certificate Authority (CA) certificates ("issuers") to be configured in a single mount. This feature is designed to facilitate CA rotation. When configuring a CA, one issuer is designated as the default - its operations will be used whenever no specific issuer is referenced during role creation. The default issuer can be changed at any time by either generating a new CA or updating it through the configuration endpoint, enabling seamless CA rotation.

   Regardless of whether it is generated or uploaded, the client signer public key is accessible via the API at the /public_key endpoint or the CLI (see next step).

3. Add the public key to all target host's SSH configuration. This process can be manual or automated using a configuration management tool. The public key is accessible via the API and does not require authentication.

   text curl -o /etc/ssh/trusted-user-ca-keys.pem http://127.0.0.1:8200/v1/ssh-client-signer/public_key

   text d8 stronghold read -field=public_key ssh-client-signer/config/ca > /etc/ssh/trusted-user-ca-keys.pem

   Add the path where the public key contents are stored to the SSH configuration file as the TrustedUserCAKeys option.

   ```text

   /etc/ssh/sshd_config

   ...

   TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem ```

   Restart the SSH service to pick up the changes.

4. Create a named Stronghold role for signing client keys.

   Because of the way some SSH certificate features are implemented, options are passed as a map. The following example adds the permit-pty extension to the certificate, and allows the user to specify their own values for permit-pty and permit-port-forwarding when requesting the certificate.

   text $ d8 stronghold write ssh-client-signer/roles/my-role -<<"EOH" { "algorithm_signer": "rsa-sha2-256", "allow_user_certificates": true, "allowed_users": "*", "allowed_extensions": "permit-pty,permit-port-forwarding", "default_extensions": { "permit-pty": "" }, "key_type": "ca", "default_user": "ubuntu", "ttl": "30m0s" } EOH

Client SSH authentication

The following steps are performed by the client (user) that wants to authenticate to machines managed by Stronghold. These commands are usually run from the client's local workstation.

1. Locate or generate the SSH public key. Usually this is ~/.ssh/id_rsa.pub. If you do not have an SSH keypair, generate one:

   text ssh-keygen -t rsa -C "user@example.com"

2. Ask Stronghold to sign your public key. This file usually ends in .pub and the contents begin with ssh-rsa ....

   ```text $ d8 stronghold write ssh-client-signer/sign/my-role \ public_key=@$HOME/.ssh/id_rsa.pub

   Key Value --- ----- serial_number c73f26d2340276aa signed_key ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1... ```

   The result will include the serial and the signed key. This signed key is another public key.

   To customize the signing options, use a JSON payload:

   text $ d8 stronghold write ssh-client-signer/sign/my-role -<<"EOH" { "public_key": "ssh-rsa AAA...", "valid_principals": "my-user", "key_id": "custom-prefix", "extensions": { "permit-pty": "", "permit-port-forwarding": "" } } EOH

3. Save the resulting signed, public key to disk. Limit permissions as needed.

   text $ d8 stronghold write -field=signed_key ssh-client-signer/sign/my-role \ public_key=@$HOME/.ssh/id_rsa.pub > signed-cert.pub

   If you are saving the certificate directly beside your SSH keypair, suffix the name with -cert.pub (~/.ssh/id_rsa-cert.pub). With this naming scheme, OpenSSH will automatically use it during authentication.

4. (Optional) View enabled extensions, principals, and metadata of the signed key.

   text ssh-keygen -Lf ~/.ssh/signed-cert.pub

5. SSH into the host machine using the signed key. You must supply both the signed public key from Stronghold and the corresponding private key as authentication to the SSH call.

   text ssh -i signed-cert.pub -i ~/.ssh/id_rsa username@10.0.23.5

Host key signing

For an added layer of security, we recommend enabling host key signing. This is used in conjunction with client key signing to provide an additional integrity layer. When enabled, the SSH agent will verify the target host is valid and trusted before attempting to SSH. This will reduce the probability of a user accidentally SSHing into an unmanaged or malicious machine.

Signing key configuration

1. Mount the secrets engine. For the most security, mount at a different path from the client signer.

   text $ d8 stronghold secrets enable -path=ssh-host-signer ssh Successfully mounted 'ssh' at 'ssh-host-signer'!

2. Configure Stronghold with a CA for signing host keys using the /config/ca endpoint. If you do not have an internal CA, Stronghold can generate a keypair for you.

   text $ d8 stronghold write ssh-host-signer/config/ca generate_signing_key=true Key Value --- ----- public_key ssh-rsa AAAAB3NzaC1yc2EA...

   If you already have a keypair, specify the public and private key parts as part of the payload:

   text $ d8 stronghold write ssh-host-signer/config/ca \ private_key="..." \ public_key="..."

   Regardless of whether it is generated or uploaded, the host signer public key is accessible via the API at the /public_key endpoint.

3. Extend host key certificate TTLs.

   text d8 stronghold secrets tune -max-lease-ttl=87600h ssh-host-signer

4. Create a role for signing host keys. Be sure to fill in the list of allowed domains, set allow_bare_domains, or both.

   text $ d8 stronghold write ssh-host-signer/roles/hostrole \ key_type=ca \ algorithm_signer=rsa-sha2-256 \ ttl=87600h \ allow_host_certificates=true \ allowed_domains="localdomain,example.com" \ allow_subdomains=true

5. Sign the host's SSH public key.

   text $ d8 stronghold write ssh-host-signer/sign/hostrole \ cert_type=host \ public_key=@/etc/ssh/ssh_host_rsa_key.pub Key Value --- ----- serial_number 3746eb17371540d9 signed_key ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...

6. Set the resulting signed certificate as HostCertificate in the SSH configuration on the host machine.

   text $ d8 stronghold write -field=signed_key ssh-host-signer/sign/hostrole \ cert_type=host \ public_key=@/etc/ssh/ssh_host_rsa_key.pub > /etc/ssh/ssh_host_rsa_key-cert.pub

   Set permissions on the certificate to be 0640:

   text chmod 0640 /etc/ssh/ssh_host_rsa_key-cert.pub

   Add host key and host certificate to the SSH configuration file.

   ```text

   /etc/ssh/sshd_config

   ...

   For client keys

   TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem

   For host keys

   HostKey /etc/ssh/ssh_host_rsa_key HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub ```

   Restart the SSH service to pick up the changes.

Client-Side host verification

1. Retrieve the host signing CA public key to validate the host signature of target machines.

   text curl http://127.0.0.1:8200/v1/ssh-host-signer/public_key

   text d8 stronghold read -field=public_key ssh-host-signer/config/ca

2. Add the resulting public key to the known_hosts file with authority.

   ```text

   ~/.ssh/known_hosts

   @cert-authority *.example.com ssh-rsa AAAAB3NzaC1yc2EAAA... ```

3. SSH into target machines as usual.

Troubleshooting

When initially configuring this type of key signing, enable VERBOSE SSH logging to help annotate any errors in the log.

# /etc/ssh/sshd_config
# ...
LogLevel VERBOSE

Restart SSH after making these changes.

By default, SSH logs to /var/log/auth.log, but so do many other things. To extract just the SSH logs, use the following:

tail -f /var/log/auth.log | grep --line-buffered "sshd"

If you are unable to make a connection to the host, the SSH server logs may provide guidance and insights.

Name is not a listed principal

If the auth.log displays the following messages:

# /var/log/auth.log
key_cert_check_authority: invalid certificate
Certificate invalid: name is not a listed principal

The certificate does not permit the username as a listed principal for authenticating to the system. This is most likely due to an OpenSSH bug (see known issues for more information). This bug does not respect the allowed_users option value of "*". Here are ways to work around this issue:

1. Set default_user in the role. If you are always authenticating as the same user, set the default_user in the role to the username you are SSHing into the target machine:

   text $ d8 stronghold write ssh/roles/my-role -<<"EOH" { "default_user": "YOUR_USER", // ... } EOH

2. Set valid_principals during signing. In situations where multiple users may be authenticating to SSH vian Stronghold, set the list of valid principles during key signing to include the current username:

   text $ d8 stronghold write ssh-client-signer/sign/my-role -<<"EOH" { "valid_principals": "my-user" // ... } EOH

No prompt after login

If you do not see a prompt after authenticating to the host machine, the signed certificate may not have the permit-pty extension. There are two ways to add this extension to the signed certificate.

• As part of the role creation

text $ d8 stronghold write ssh-client-signer/roles/my-role -<<"EOH" { "default_extensions": { "permit-pty": "" } // ... } EOH

• As part of the signing operation itself:

text $ d8 stronghold write ssh-client-signer/sign/my-role -<<"EOH" { "extensions": { "permit-pty": "" } // ... } EOH

No port forwarding

If port forwarding from the guest to the host is not working, the signed certificate may not have the permit-port-forwarding extension. Add the extension as part of the role creation or signing process to enable port forwarding. See no prompt after login for examples.

{
  "default_extensions": {
    "permit-port-forwarding": ""
  }
}

No x11 forwarding

If X11 forwarding from the guest to the host is not working, the signed certificate may not have the permit-X11-forwarding extension. Add the extension as part of the role creation or signing process to enable X11 forwarding. See no prompt after login for examples.

{
  "default_extensions": {
    "permit-X11-forwarding": ""
  }
}

No agent forwarding

If agent forwarding from the guest to the host is not working, the signed certificate may not have the permit-agent-forwarding extension. Add the extension as part of the role creation or signing process to enable agent forwarding. See no prompt after login for examples.

{
  "default_extensions": {
    "permit-agent-forwarding": ""
  }
}

Key comments

There are additional steps needed to preserve comment attributes in keys which ought to be considered if they are required. Private and public key may have comments applied to them and for example where ssh-keygen is used with its -C parameter - similar to:

ssh-keygen -C "...Comments" -N "" -t rsa -b 4096 -f host-ca

Adapted key values containing comments must be provided with the key related parameters as per the Stronghold CLI and API steps demonstrated below.

# Using CLI:
d8 stronghold secrets enable -path=hosts-ca ssh
KEY_PRI=$(cat ~/.ssh/id_rsa | sed -z 's/\n/\\n/g')
KEY_PUB=$(cat ~/.ssh/id_rsa.pub | sed -z 's/\n/\\n/g')
# Create / update keypair in Stronghold
d8 stronghold write ssh-client-signer/config/ca \
  generate_signing_key=false \
  private_key="${KEY_PRI}" \
  public_key="${KEY_PUB}"

# Using API:
curl -X POST -H "X-Vault-Token: ..." -d '{"type":"ssh"}' http://127.0.0.1:8200/v1/sys/mounts/hosts-ca
KEY_PRI=$(cat ~/.ssh/id_rsa | sed -z 's/\n/\\n/g')
KEY_PUB=$(cat ~/.ssh/id_rsa.pub | sed -z 's/\n/\\n/g')
tee payload.json <<EOF
{
  "generate_signing_key" : false,
  "private_key"          : "${KEY_PRI}",
  "public_key"           : "${KEY_PUB}"
}
EOF
# Create / update keypair in Stronghold
curl -X POST -H "X-Vault-Token: ..." -d @payload.json http://127.0.0.1:8200/v1/hosts-ca/config/ca

:::warning

IMPORTANT: Do NOT add a private key password since Stronghold can't decrypt it. Destroy the keypair and payload.json from your hosts immediately after they have been confirmed as successfully uploaded.

:::

Known issues

• On SELinux-enforcing systems, you may need to adjust related types so that the SSH daemon is able to read it. For example, adjust the signed host certificate to be an sshd_key_t type.

• On some versions of SSH, you may get the following error:

text no separate private key for certificate

This is a bug introduced in OpenSSH version 7.2 and fixed in 7.5. See OpenSSH bug 2617 for details.

• On some versions of SSH, you may get the following error on target host:

text userauth_pubkey: certificate signature algorithm ssh-rsa: signature algorithm not supported [preauth]

Fix is to add below line to /etc/ssh/sshd_config

text CASignatureAlgorithms ^ssh-rsa

The ssh-rsa algorithm is no longer supported in OpenSSH 8.2

API

The SSH secrets engine has a full HTTP API. Please see the SSH secrets engine API for more details.

Kubernetes

{% alert level="warning" %}

Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround. See the deprecation FAQ for more information.

{% endalert %} The Kubernetes Secrets Engine for Stronghold generates Kubernetes service account tokens, and optionally service accounts, role bindings, and roles. The created service account tokens have a configurable TTL and any objects created are automatically deleted when the Stronghold lease expires.

For each lease, Stronghold will create a service account token attached to the defined service account. The service account token is returned to the caller.

To learn more about service accounts in Kubernetes, visit the Kubernetes service account and Kubernetes RBAC documentation.

{% alert level="warning" %}

Note: We do not recommend using tokens created by the Kubernetes Secrets Engine to authenticate with the Stronghold Kubernetes Auth Method. This will generate many unique identities in Stronghold that will be hard to manage.

{% endalert %}

Setup

The Kubernetes Secrets Engine must be configured in advance before it can perform its functions. These steps are usually completed by an operator or configuration management tool.

1. By default, Stronghold will connect to Kubernetes using its own service account. If using the standard Helm chart, this service account is created automatically by default and named after the Helm release (often stronghold, but this can be configured via the Helm value server.serviceAccount.name).

It's necessary to ensure that the service account Stronghold uses will have permissions to manage service account tokens, and optionally manage service accounts, roles, and role bindings. These permissions can be managed using a Kubernetes role or cluster role. The role is attached to the Stronghold service account with a role binding or cluster role binding.

For example, a minimal cluster role to create service account tokens is:

yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: k8s-minimal-secrets-abilities rules: - apiGroups: [""] resources: ["serviceaccounts/token"] verbs: ["create"]

Similarly, you can create a more permissive cluster role with full permissions to manage tokens, service accounts, bindings, and roles.

yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: k8s-full-secrets-abilities rules: - apiGroups: [""] resources: ["serviceaccounts", "serviceaccounts/token"] verbs: ["create", "update", "delete"] - apiGroups: ["rbac.authorization.k8s.io"] resources: ["rolebindings", "clusterrolebindings"] verbs: ["create", "update", "delete"] - apiGroups: ["rbac.authorization.k8s.io"] resources: ["roles", "clusterroles"] verbs: ["bind", "escalate", "create", "update", "delete"]

Create this role in Kubernetes (e.g., with kubectl apply -f).

Moreover, if you want to use label selection to configure the namespaces on which a role can act, you will need to grant Stronghold permissions to read namespaces.

yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: k8s-full-secrets-abilities-with-labels rules: - apiGroups: [""] resources: ["namespaces"] verbs: ["get"] - apiGroups: [""] resources: ["serviceaccounts", "serviceaccounts/token"] verbs: ["create", "update", "delete"] - apiGroups: ["rbac.authorization.k8s.io"] resources: ["rolebindings", "clusterrolebindings"] verbs: ["create", "update", "delete"] - apiGroups: ["rbac.authorization.k8s.io"] resources: ["roles", "clusterroles"] verbs: ["bind", "escalate", "create", "update", "delete"]

{% alert level="warning" %}

Note: Getting the right permissions for Stronghold will require some trial and error most likely since Kubernetes has strict protections against privilege escalation. You can read more in the Kubernetes RBAC documentation.

{% endalert %}

Note: Protect the Stronghold service account, especially if you use broader permissions for it, as it is essentially a cluster administrator account.

{% endalert %} 1. Create a role binding to bind the role to Stronghold's service account and grant Stronghold permission to manage tokens.

yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: stronghold-token-creator-binding roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: k8s-minimal-secrets-abilities subjects: - kind: ServiceAccount name: stronghold namespace: stronghold

For more information on Kubernetes roles, service accounts, bindings, and tokens, visit the Kubernetes RBAC documentation.

1. If Stronghold will not be automatically managing roles or service accounts (see Automatically Managing Roles and Service Accounts), then you will need to set up a service account that Stronghold will issue tokens for.

{% alert level="warning" %}

Note: It is highly recommended that the service account that Stronghold issues tokens for is NOT the same service account that Stronghold itself uses.

{% endalert %} The examples we will use will under the namespace test, which you can create if it does not already exist.

shell-session $ kubectl create namespace test namespace/test created

Here is a simple set up of a service account, role, and role binding in the Kubernetes test namespace with basic permissions we will use for this document:

```yaml apiVersion: v1 kind: ServiceAccount metadata: name: test-service-account-with-generated-token namespace: test

---

apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: test-role-list-pods namespace: test rules: - apiGroups: [""] resources: ["pods"] verbs: ["list"]

---

apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: test-role-abilities namespace: test roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: test-role-list-pods subjects: - kind: ServiceAccount name: test-service-account-with-generated-token namespace: test ```

You can create these objects with kubectl apply -f.

1. Enable the Kubernetes Secrets Engine:

shell-session $ d8 stronghold secrets enable kubernetes Success! Enabled the kubernetes Secrets Engine at: kubernetes/

By default, the secrets engine will mount at the same name as the engine, i.e., kubernetes/ here. This can be changed by passing the -path argument when enabling.

1. Configure the mount point. An empty config is allowed.

shell-session d8 stronghold write -f kubernetes/config

Configuration options are available as specified in the API docs.

1. You can now configure Kubernetes Secrets Engine to create an Stronghold role (not the same as a Kubernetes role) that can generate service account tokens for the given service account:

shell-session $ d8 stronghold write kubernetes/roles/my-role \ allowed_kubernetes_namespaces="*" \ service_account_name="test-service-account-with-generated-token" \ token_default_ttl="10m"

Generating credentials

After a user has authenticated to Stronghold and has sufficient permissions, a write to the creds endpoint for the Stronghold role will generate and return a new service account token.

$ d8 stronghold write kubernetes/creds/my-role \
    kubernetes_namespace=test

Key                        Value
–--                        -----
lease_id                   kubernetes/creds/my-role/31d771a6-...
lease_duration             10m0s
lease_renwable             false
service_account_name       test-service-account-with-generated-token
service_account_namespace  test
service_account_token      eyJHbGci0iJSUzI1NiIsImtpZCI6ImlrUEE...

You can use the service account token above (eyJHbG...) with any Kubernetes API request that its service account is authorized for (through role bindings).

$ curl -sk $(kubectl config view --minify -o 'jsonpath={.clusters[].cluster.server}')/api/v1/namespaces/test/pods \
    --header "Authorization: Bearer eyJHbGci0iJSUzI1Ni..."
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion": "1624"
  },
  "items": []
}

When the lease expires, you can verify that the token has been revoked.

$ curl -sk $(kubectl config view --minify -o 'jsonpath={.clusters[].cluster.server}')/api/v1/namespaces/test/pods \
    --header "Authorization: Bearer eyJHbGci0iJSUzI1Ni..."
{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {},
  "status": "Failure",
  "message": "Unauthorized",
  "reason": "Unauthorized",
  "code": 401
}

TTL

Kubernetes service account tokens have a time-to-live (TTL). When a token expires it is automatically revoked.

You can set a default (token_default_ttl) and a maximum TTL (token_max_ttl) when creating or tuning the Stronghold role.

$ d8 stronghold write kubernetes/roles/my-role \
    allowed_kubernetes_namespaces="*" \
    service_account_name="new-service-account-with-generated-token" \
    token_default_ttl="10m" \
    token_max_ttl="2h"

You can also set a TTL (ttl) when you generate the token from the credentials endpoint. The TTL of the token will be given the default if not specified (and cannot exceed the maximum TTL of the role, if present).

$ d8 stronghold write kubernetes/creds/my-role \
    kubernetes_namespace=test \
    ttl=20m

Key                        Value
–--                        -----
lease_id                   kubernetes/creds/my-role/31d771a6-...
lease_duration             20m0s
lease_renwable             false
service_account_name       new-service-account-with-generated-token
service_account_namespace  test
service_account_token      eyJHbGci0iJSUzI1NiIsImtpZCI6ImlrUEE...

You can verify the token's TTL by decoding the JWT token and extracting the iat (issued at) and exp (expiration time) claims.

$ echo 'eyJhbGc...' | cut -d'.' -f2 | base64 -d  | jq -r '.iat,.exp|todate'
2022-05-20T17:14:50Z
2022-05-20T17:34:50Z

Audiences

Kubernetes service account tokens have audiences.

You can set default audiences (token_default_audiences) when creating or tuning the Stronghold role. The Kubernetes cluster default audiences for service account tokens will be used if not specified.

$ d8 stronghold write kubernetes/roles/my-role \
    allowed_kubernetes_namespaces="*" \
    service_account_name="new-service-account-with-generated-token" \
    token_default_audiences="custom-audience"

You can also set audiences (audiences) when you generate the token from the credentials endpoint. The audiences of the token will be given the default audiences if not specified.

$ d8 stronghold write kubernetes/creds/my-role \
    kubernetes_namespace=test \
    audiences="another-custom-audience"

Key                        Value
–--                        -----
lease_id                   kubernetes/creds/my-role/SriWQf0bPZ...
lease_duration             768h
lease_renwable             false
service_account_name       new-service-account-with-generated-token
service_account_namespace  test
service_account_token      eyJHbGci0iJSUzI1NiIsImtpZCI6ImlrUEE...

You can verify the token's audiences by decoding the JWT.

$ echo 'eyJhbGc...' | cut -d'.' -f2 | base64 -d
{"aud":["another-custom-audience"]...

Automatically managing roles and service accounts

When configuring the Stronghold role, you can pass in parameters to specify that you want to automatically generate the Kubernetes service account and role binding, and optionally generate the Kubernetes role itself.

If you want to configure the Stronghold role to use a pre-existing Kubernetes role, but generate the service account and role binding automatically, you can set the kubernetes_role_name parameter.

$ d8 stronghold write kubernetes/roles/auto-managed-sa-role \
    allowed_kubernetes_namespaces="test" \
    kubernetes_role_name="test-role-list-pods"

{% alert level="warning" %}

Note: Stronghold's service account will also need access to the resources it is granting access to. This can be done for the examples above with kubectl -n test create rolebinding --role test-role-list-pods --serviceaccount=d8-stronghold:stronghold stronghold-test-role-abilities. This is how Kubernetes prevents privilege escalation. You can read more in the Kubernetes RBAC documentation.

{% endalert %} You can then get credentials with the automatically generated service account.

$ d8 stronghold write kubernetes/creds/auto-managed-sa-role \
    kubernetes_namespace=test
Key                          Value
---                          -----
lease_id                     kubernetes/creds/auto-managed-sa-role/cujRLYjKZUMQk6dkHBGGWm67
lease_duration               768h
lease_renewable              false
service_account_name         v-token-auto-man-1653001548-5z6hrgsxnmzncxejztml4arz
service_account_namespace    test
service_account_token        eyJHbGci0iJSUzI1Ni...

Furthermore, Stronghold can also automatically create the role in addition to the service account and role binding by specifying the generated_role_rules parameter, which accepts a set of JSON or YAML rules for the generated role.

$ d8 stronghold write kubernetes/roles/auto-managed-sa-and-role \
    allowed_kubernetes_namespaces="test" \
    generated_role_rules='{"rules":[{"apiGroups":[""],"resources":["pods"],"verbs":["list"]}]}'

You can then get credentials in the same way as before.

$ d8 stronghold write kubernetes/creds/auto-managed-sa-and-role \
    kubernetes_namespace=test
Key                          Value
---                          -----
lease_id                     kubernetes/creds/auto-managed-sa-and-role/pehLtegoTP8vCkcaQozUqOHf
lease_duration               768h
lease_renewable              false
service_account_name         v-token-auto-man-1653002096-4imxf3ytjh5hbyro9s1oqdo3
service_account_namespace    test
service_account_token        eyJHbGci0iJSUzI1Ni...

API

The Kubernetes Secrets Engine has a full HTTP API. Please see the Kubernetes Secrets Engine API docs for more details.

Transit

Механизм транзитных секретов выполняет криптографические операции с данными в процессе передачи. Stronghold не хранит данные, отправляемые в этот механизм. Его также можно рассматривать как "криптографию как услугу" или "шифрование как услугу". Механизм транзитных секретов также может подписывать и проверять данные, генерировать хеши и HMAC, а также выступать в качестве источника случайных байтов.

Основной сценарий использования transit — шифрование данных из приложений с последующим хранением этих зашифрованных данных в основном хранилище. Это снимает с разработчиков приложений ответственность за правильное шифрования/дешифрования и перекладывает его на Stronghold.

Поддерживается производство ключей, что позволяет использовать один и тот же ключ для разных целей путем создания нового ключа на основе предоставленного пользователем контекста. В этом режиме также может быть включена конвергентная криптография, позволяющая одинаковым входным значениям давать одинаковый шифротекст.

Генерация ключей данных позволяет процессам запрашивать высокоэнтропийный ключ заданной длины, который возвращается в зашифрованном виде с использованием указанного ключа. Обычно ключ также возвращается в открытом виде для немедленного использования, но эту возможность можно отключить в соответствии с требованиями аудита.

Управление рабочим набором

Механизм Transit поддерживает версионирование ключей. Версии ключей, более ранние, чем заданное значение min_decryption_version ключа, архивируются, а остальные версии ключей попадают в рабочий набор. Это важно как для производительности для быстрой загрузки ключей, а так и для безопасности: запрещая расшифровку старыми версиями ключей, найденный шифротекст, соответствующий устаревшим (но конфиденциальные) данным, не может быть расшифрован большинством пользователей, но в экстренных случаях min_decryption_version может быть сдвинут назад, чтобы позволить легитимную расшифровку.

В настоящее время архив хранится в одной записи хранилища. В некоторых бэкендах, особенно тех, что используют Raft или Paxos для обеспечения высокой доступности (HA), частая ротация ключей может привести к увеличению размера записи архива сверх допустимого предела. Для сценариев с частой ротацией хорошей альтернативой может быть использование именованных ключей, привязанных к временным интервалам (например, 5-минутные периоды, округлённые до ближайшего, кратного пяти). Это позволяет одновременно использовать несколько ключей и детерминированно выбирать нужный ключ в любой момент времени.

Рекомендации NIST по ротации ключей

Периодическая ротация ключей шифрования рекомендуется, даже если не было компрометации. Для ключей AES-GCM ротацию следует проводить до достижения примерно 2<sup>32</sup> операций шифрования на одну версию ключа, в соответствии с рекомендациями NIST 800-38D. Операторам следует оценить интенсивность использования ключа и установить частоту ротации, чтобы не превысить указанные лимиты. Например, если ключ используется примерно 40 миллионов раз в день, то ротация раз в три месяца будет достаточной.

Типы ключей

На данный момент механизм транзитных секретов поддерживает следующие типы ключей (все типы ключей также генерируют отдельные ключи HMAC):

• aes128-gcm96: AES-GCM с 128-битным ключом AES и 96-битным nonce; поддерживает шифрование, дешифрование, производные ключи и конвергентное шифрование
• aes256-gcm96: AES-GCM с 256-битным ключом AES и 96-битным nonce; поддерживает шифрование, дешифрование, производные ключи и конвергентное шифрование (по умолчанию)
• chacha20-poly1305: ChaCha20-Poly1305 с 256-битным ключом; поддерживает шифрование, дешифрование, производные ключи и конвергентное шифрование
• ed25519: Ed25519; поддерживает подпись, проверку подписи и производные ключи
• ecdsa-p256: ECDSA с использованием кривой P-256; поддерживает подпись и проверку подписи
• ecdsa-p384: ECDSA с использованием кривой P-384; поддерживает подпись и проверку подписи
• ecdsa-p521: ECDSA с использованием кривой P-521; поддерживает подпись и проверку подписи
• rsa-2048: 2048-битный RSA ключ; поддерживает шифрование, дешифрование, подпись и проверку подписи
• rsa-3072: 3072-битный RSA ключ; поддерживает шифрование, дешифрование, подпись и проверку подписи
• rsa-4096: 4096-битный RSA ключ; поддерживает шифрование, дешифрование, подпись и проверку подписи
• hmac: HMAC; поддерживает генерацию и проверку HMAC.

{% alert %}Все типы ключей поддерживают операции HMAC через использование второго случайно сгенерированного ключа, создаваемого при инициализации или ротации ключа. Тип ключа HMAC поддерживает только операции HMAC и ведет себя идентично другим алгоритмам в отношении операций HMAC, но поддерживает импорт ключей. По умолчанию, тип ключа HMAC использует 256-битный ключ.

Операции RSA используют один из следующих методов:

• OAEP (шифрование, дешифрование), с хеш-функцией SHA-256 и MGF,
• PSS (подпись, проверка), с настраиваемой хеш-функцией, также используемой для MGF, и
• PKCS#1v1.5: (подпись, проверка), с настраиваемой хеш-функцией.

Конвергентное шифрование

Конвергентное шифрование — это режим, при котором один и тот же набор открытого текста и контекста всегда приводит к одному и тому же шифротексту. Это достигается путём получения ключа с использованием функции вывода ключа, а также детерминированного получения одноразового значения (nonce). Поскольку эти параметры различаются для любой комбинации открытого текста и шифротекста в ключевом пространстве размером 2^256, риск повторного использования nonce практически равен нулю.

У этого подхода есть множество практических применений. Одним из распространённых сценариев является хранение шифротекста в базе данных с ограниченной поддержкой поиска/запросов, так что строки с одинаковым значением для конкретного поля могут быть возвращены по результатам запроса.

Чтобы обеспечить возможность обновления алгоритма при необходимости, исторически поддерживались различные версии конвергентного шифрования:

• Version 1 требовала от клиента самостоятельного предоставления nonce, что даёт высокую гибкость, но может быть опасным при неправильной реализации. Ключи, использующие эту версию, не могут быть обновлены.
• Version 2 использовала алгоритмический подход для вычисления параметров. Однако применяемый алгоритм был уязвим к офлайн-атакам подтверждения открытого текста, что позволяло злоумышленникам выполнять перебор для расшифровки, если размер открытого текста был небольшим. Ключи с версией 2 можно обновить путём выполнения операции поворота (rotate) до новой версии ключа; после чего существующие значения могут быть повторно обёрнуты с использованием новой версии ключа и будут использовать алгоритм версии 3.
• Versionя 3 использует иной алгоритм, разработанный с учётом устойчивости к офлайн-атакам подтверждения открытого текста. Он схож с AES-SIV тем, что использует псевдослучайную функцию (PRF) для генерации nonce на основе открытого текста.

Настройка

Большинство движков секретов требуют предварительной настройки перед использованием. Эти шаги обычно выполняются оператором или системой управления конфигурацией.

Включите Transit secrets engine:

$ stronghold secrets enable transit
Success! Enabled the transit secrets engine at: transit/

По умолчанию движок монтируется по имени движка. Чтобы указать другой путь, используйте аргумент -path.

Создайте именованный ключ шифрования:

$ stronghold write -f transit/keys/my-key
Success! Data written to: transit/keys/my-key

Обычно каждое приложение использует собственный ключ шифрования.

Использование

После настройки механизма и получения пользователем или системой токена Stronghold с соответствующими разрешениями можно генерировать учетные данные.

Шифрование данных с помощью /encrypt и указанного ключа:

Примечание Все данные должны быть закодированы в base64. Это связано с тем, что Stronghold не требует, чтобы передаваемый plaintext был текстом — это может быть бинарный файл (PDF, изображение и т.д.). Самый безопасный способ передачи таких данных в JSON — кодирование в base64.

$ stronghold write transit/encrypt/my-key plaintext=$(echo "my secret data" | base64)

Key           Value
---           -----
ciphertext    vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==

Возвращаемый шифротекст начинается с vault:v1:. Префикс (stronghold) обозначает, что данные зашифрованы Stronghold. Версия v1 указывает, что использовалась первая версия ключа. Это важно при ротации, так как Stronghold использует правильную версию ключа для расшифровки.

Обратите внимание: Stronghold не хранит шифротекст. Ответственность за их сохранение лежит на вызывающей стороне. Чтобы расшифровать данные, необходимо снова передать шифротекст в Stronghold.

{% alert level="warning" %}Stronghold HTTP API ограничивает размер запроса до 32MB во избежание атак типа DoS. Этот лимит можно изменить в блоке listener конфигурации Stronghold.

Расшифровка данных с использованием /decrypt:

$ stronghold write transit/decrypt/my-key ciphertext=vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==

Key          Value
---          -----
plaintext    bXkgc2VjcmV0IGRhdGEK

Результат — строка в base64. Декодируйте её, чтобы получить исходные данные:

$ base64 --decode <<< "bXkgc2VjcmV0IGRhdGEK"
my secret data

Или в одну команду:

$ stronghold write -field=plaintext transit/decrypt/my-key ciphertext=... | base64 --decode
my secret data

Через ACL можно ограничить доступ: доверенным операторам — управление ключами, а приложениям — только шифрование/дешифровку с нужными ключами.

Ротация базового ключа шифрования. В результате будет сгенерирован новый ключ шифрования и добавлен в связку ключей для именованного ключа:

$ stronghold write -f transit/keys/my-key/rotate
Success! Data written to: transit/keys/my-key/rotate

В последующих шифрованиях будет использоваться этот новый ключ. Старые данные все еще могут быть расшифрованы благодаря использованию связки ключей.

Обновление уже зашифрованных данных на новый ключ. Stronghold расшифрует значение, используя соответствующий ключ в связке ключей, а затем зашифрует полученный открытый текст с помощью новейшего ключа в связке ключей:

$ stronghold write transit/rewrap/my-key ciphertext=vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==

Key           Value
---           -----
ciphertext    vault:v2:...

Этот процесс не раскрывает исходные данные. Поэтому политика Stronghold может позволить даже недоверенным процессам выполнять "rewrap", не выдавая им доступ к самим данным.

Импорт собственного ключа (Bring your own key BYOK)

{% alert level="warning" %}Импорт ключей нужен в случаях, когда необходимо перенести ключ из HSM или другой системы. Однако, безопаснее, если ключ будет сгенерирован и управляться внутри Stronghold.

Сначала получите wrapping key из Transit:

stronghold read transit/wrapping_key

Этот ключ будет 4096 битным публичным RSA-ключом.

Далее этот ключ используется для создания шифрованного значения для import, как описано ниже. Ниже под целевым ключом подразумевается импортируемый ключ.

HSM

Если ключ импортируется из HSM, поддерживающего PKCS#11, возможны два сценария:

• Если HSM поддерживает механизм CKM_RSA_AES_KEY_WRAP, его можно использовать для обертывания целевого ключа с помощью обертывающего ключа.

• В противном случае для обертывания целевого ключа можно использовать два механизма. Сначала нужно сгенерировать 256-битный ключ AES, а затем использовать его для обертывания целевого ключа с помощью механизма CKM_AES_KEY_WRAP_KWP. Затем ключ AES должен быть обернут под обертывающий ключ с помощью механизма CKM_RSA_PKCS_OAEP с использованием MGF1 и либо SHA-1, SHA-224, SHA-256, SHA-384, либо SHA-512.

Шифротекст создается путем добавления обернутого целевого ключа к обернутому ключу AES.

Байты шифротекста должны быть закодированы в base64.

Процесс вручную

Если целевой ключ не хранится в HSM или KMS, то для создания шифротекста на входе конечной точки import можно использовать следующие шаги:

• Сгенерируйте эфемерный 256-битный ключ AES.

• Оберните целевой ключ эфемерным ключом AES с помощью AES-KWP.

{% alert level="warning" %}При обертывании симметричного ключа (например, ключа AES или ChaCha20) оберните необработанные байты ключа. Например, для 128-битного ключа AES это будет байтовый массив длиной 16 символов, который будет непосредственно обернут без base64 или других кодировок. При обертывании асимметричного ключа (например, ключа RSA или ECDSA) оберните PKCS8 закодированный формат этого ключа в сырой DER/бинарной форме. Не применяйте PEM-кодировку перед шифрованием и не кодируйте base64.

• Оберните ключ AES в ключ обертки Stronghold с помощью RSAES-OAEP с MGF1 и SHA-1, SHA-224, SHA-256, SHA-384 или SHA-512.

• Удалите эфемерный ключ AES.

• Добавьте обернутый целевой ключ к обернутому ключу AES.

• Закодируйте результат в Base64.

Базы данных

Обзор

Databases

The database secrets engine generates database credentials dynamically based on configured roles. It works with a number of different databases through a plugin interface. There are a number of built-in database types, and an exposed framework for running custom database types for extendability. This means that services that need to access a database no longer need to hardcode credentials: they can request them from Stronghold, and use Stronghold's leasing mechanism to more easily roll keys. These are referred to as "dynamic roles" or "dynamic secrets".

Since every service is accessing the database with unique credentials, it makes auditing much easier when questionable data access is discovered. You can track it down to the specific instance of a service based on the SQL username.

Stronghold makes use of its own internal revocation system to ensure that users become invalid within a reasonable time of the lease expiring.

Static roles

With dynamic secrets, Stronghold generates a unique username and password pair for each unique credential request. Stronghold also supports static roles for some database secrets engines. Static roles are a 1-to-1 mapping of Stronghold roles to usernames in a database. With static roles, Stronghold stores, and automatically rotates, passwords for the associated database user based on a configurable period of time.

When a client requests credentials for the static role, Stronghold returns the current password for whichever database user is mapped to the requested role. With static roles, anyone with the proper Stronghold policies can access the associated user account in the database.

{% alert level="warning" %}[Do not use static roles for root database credentials] Do not manage the same root database credentials that you provide to Stronghold in config/ with static roles.

Stronghold does not distinguish between standard credentials and root credentials when rotating passwords. If you assign your root credentials to a static role, any dynamic or static users managed by that database configuration will fail after rotation because the password for config/ is no longer valid.

If you need to rotate root credentials, use the Rotate root credentials API endpoint.

{% endalert %} Consult the database capabilities table to determine if your chosen database backend supports static roles.

Setup

Most secrets engines must be configured in advance before they can perform their functions. These steps are usually completed by an operator or configuration management tool.

1. Enable the database secrets engine:

shell-session $ d8 stronghold secrets enable database Success! Enabled the database secrets engine at: database/

By default, the secrets engine will enable at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

1. Configure Stronghold with the proper plugin and connection information:

shell-session $ d8 stronghold write database/config/my-database \ plugin_name="..." \ connection_url="..." \ allowed_roles="..." \ username="..." \ password="..." \

{% alert level="warning" %}

It is highly recommended a user within the database is created specifically for Stronghold to use. This user will be used to manipulate dynamic and static users within the database. This user is called the "root" user within the documentation.

{% endalert %} Stronghold will use the user specified here to create/update/revoke database credentials. That user must have the appropriate permissions to perform actions upon other database users (create, update credentials, delete, etc.).

This secrets engine can configure multiple database connections. For details on the specific configuration options, please see the database-specific documentation.

1. After configuring the root user, it is highly recommended you rotate that user's password such that the stronghold user is not accessible by any users other than Stronghold itself:

shell-session d8 stronghold write -force database/rotate-root/my-database

{% alert level="critical" %}

When this is done, the password for the user specified in the previous step is no longer accessible. Because of this, it is highly recommended that a user is created specifically for Stronghold to use to manage database users.

{% endalert %}

1. Configure a role that maps a name in Stronghold to a set of creation statements to create the database credential:

shell-session $ d8 stronghold write database/roles/my-role \ db_name=my-database \ creation_statements="..." \ default_ttl="1h" \ max_ttl="24h" Success! Data written to: database/roles/my-role

The {{username}} and {{password}} fields will be populated by the plugin with dynamically generated values. In some plugins the {{expiration}} field is also supported.

Usage

After the secrets engine is configured and a user/machine has an Stronghold token with the proper permission, it can generate credentials.

1. Generate a new credential by reading from the /creds endpoint with the name of the role:

   shell-session $ d8 stronghold read database/creds/my-role Key Value --- ----- lease_id database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6 lease_duration 1h lease_renewable true password FSREZ1S0kFsZtLat-y94 username v-strongholduser-e2978cd0-ugp7iqI2hdlff5hfjylJ-1602537260

Database capabilities

All databases support dynamic roles and static roles. All plugins support rotating the root user's credentials.

Database	Root Credential Rotation	Dynamic Roles	Static Roles	Username Customization	Credential Types
Cassandra	Yes	Yes	Yes	Yes	password
InfluxDB	Yes	Yes	Yes	Yes	password
MySQL/MariaDB	Yes	Yes	Yes	Yes	password
PostgreSQL	Yes	Yes	Yes	Yes	password

Custom plugins

This secrets engine allows custom database types to be run through the exposed plugin interface. Please see the custom database plugin for more information.

Credential types

Database systems support a variety of authentication methods and credential types. The database secrets engine supports management of credentials alternative to usernames and passwords. The credential_type and credential_config parameters of dynamic and static roles configure the credential that Stronghold will generate and make available to database plugins. See the documentation of individual database plugins for the credential types they support and usage examples.

Password generation

Passwords are generated via Password Policies. Databases can optionally set a password policy for use across all roles or at the individual role level for that database. For example, each time you call d8 stronghold write database/config/my-database you can specify a password policy for all roles using my-database. Each database has a default password policy defined as: 20 characters with at least 1 uppercase character, at least 1 lowercase character, at least 1 number, and at least 1 dash character.

The default password generation can be represented as the following password policy:

length = 20

rule "charset" {
 charset = "abcdefghijklmnopqrstuvwxyz"
 min-chars = 1
}
rule "charset" {
 charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
 min-chars = 1
}
rule "charset" {
 charset = "0123456789"
 min-chars = 1
}
rule "charset" {
 charset = "-"
 min-chars = 1
}

Disable character escaping

You can specify the option disable_escaping with a value of true in some secrets engines to prevent Stronghold from escaping special characters in the username and password fields. This is necessary for some alternate connection string formats. See the databases secrets engine API docs and reference individual plugin documentation to determine support for this parameter.

For example, when the password contains URL-escaped characters like # or % they will remain as so instead of becoming %23 and %25 respectively.

$ d8 stronghold write database/config/my-mysql-database \
plugin_name="mysql-database-plugin" \
connection_url='server=localhost;port=3306;user id={{username}};password={{password}};database=mydb;' \
username="root" \
password='your#StrongPassword%' \
disable_escaping="true"

API

The database secrets engine has a full HTTP API. Please see the Database secret secrets engine API for more details.

Postgresql

PostgreSQL database secrets engine

PostgreSQL is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on configured roles for the PostgreSQL database, and also supports Static Roles.

See the database secrets engine docs for more information about setting up the database secrets engine.

The PostgreSQL secrets engine uses pgx. Connection string options, including SSL options, can be found in the pgx and PostgreSQL connection string documentation.

Capabilities

Plugin Name	Root Credential Rotation	Dynamic Roles	Static Roles	Username Customization
postgresql-database-plugin	Yes	Yes	Yes	Yes (1.7+)

Setup

1. Enable the database secrets engine if it is not already enabled:

   shell-session $ d8 stronghold secrets enable database Success! Enabled the database secrets engine at: database/

   By default, the secrets engine will enable at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

2. Configure Stronghold with the proper plugin and connection information:

   shell-session $ d8 stronghold write database/config/my-postgresql-database \ plugin_name="postgresql-database-plugin" \ allowed_roles="my-role" \ connection_url="postgresql://{{username}}:{{password}}@localhost:5432/database-name" \ username="strongholduser" \ password="strongholdpass" \ password_authentication="scram-sha-256"

3. Configure a role that maps a name in Stronghold to an SQL statement to execute to create the database credential:

   shell-session $ d8 stronghold write database/roles/my-role \ db_name="my-postgresql-database" \ creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; \ GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \ default_ttl="1h" \ max_ttl="24h" Success! Data written to: database/roles/my-role

Usage

After the secrets engine is configured and a user/machine has an Stronghold token with the proper permission, it can generate credentials.

1. Generate a new credential by reading from the /creds endpoint with the name of the role:

   shell-session $ d8 stronghold read database/creds/my-role Key Value --- ----- lease_id database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6 lease_duration 1h lease_renewable true password SsnoaA-8Tv4t34f41baD username v-strongholduse-my-role-x

API

The full list of configurable options can be seen in the PostgreSQL database plugin API page.

For more information on the database secrets engine's HTTP API please see the Database secrets engine API page.

Mysql/Maria

MySQL/MariaDB database secrets engine

{% alert level="warning" %}

Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround. See the deprecation FAQ for more information.

{% endalert %} MySQL is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on configured roles for the MySQL database, and also supports Static Roles.

This plugin has a few different instances built into Stronghold, each instance is for a slightly different MySQL driver. The only difference between these plugins is the length of usernames generated by the plugin as different versions of mysql accept different lengths. The available plugins are:

• mysql-database-plugin
• mysql-aurora-database-plugin
• mysql-rds-database-plugin
• mysql-legacy-database-plugin

See the database secrets engine docs for more information about setting up the database secrets engine.

Capabilities

Plugin Name	Root Credential Rotation	Dynamic Roles	Static Roles	Username Customization
Depends (see: above)	Yes	Yes	Yes	Yes (1.7+)

Setup

1. Enable the database secrets engine if it is not already enabled:

text $ d8 stronghold secrets enable database Success! Enabled the database secrets engine at: database/

By default, the secrets engine will enable at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

1. Configure Stronghold with the proper plugin and connection information:

text $ d8 stronghold write database/config/my-mysql-database \ plugin_name=mysql-database-plugin \ connection_url="{{username}}:{{password}}@tcp(127.0.0.1:3306)/" \ allowed_roles="my-role" \ username="strongholduser" \ password="strongholdpass"

1. Configure a role that maps a name in Stronghold to an SQL statement to execute to create the database credential:

text $ d8 stronghold write database/roles/my-role \ db_name=my-mysql-database \ creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';GRANT SELECT ON *.* TO '{{name}}'@'%';" \ default_ttl="1h" \ max_ttl="24h" Success! Data written to: database/roles/my-role

Usage

After the secrets engine is configured and a user/machine has an Stronghold token with the proper permission, it can generate credentials.

1. Generate a new credential by reading from the /creds endpoint with the name of the role:

text $ d8 stronghold read database/creds/my-role Key Value --- ----- lease_id database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6 lease_duration 1h lease_renewable true password yY-57n3X5UQhxnmFRP3f username v_strongholduser_my-role_crBWVqVh2Hc1

Client x509 certificate authentication

This plugin supports using MySQL's x509 Client-side Certificate Authentication

To use this authentication mechanism, configure the plugin:

$ d8 stronghold write database/config/my-mysql-database \
    plugin_name=mysql-database-plugin \
    allowed_roles="my-role" \
    connection_url="user:password@tcp(localhost:3306)/test" \
    tls_certificate_key=@/path/to/client.pem \
    tls_ca=@/path/to/client.ca

Note: tls_certificate_key and tls_ca map to ssl-cert (combined with ssl-key) and ssl-ca configuration options from MySQL with the exception that the Stronghold parameters are the contents of those files, not filenames. As such, the two options are independent of each other. See the MySQL Connection Options for more information.

Examples

Using wildcards in grant statements

MySQL supports using wildcards in grant statements. These are sometimes needed by applications which expect access to a large number of databases inside MySQL. This can be realized by using a wildcard in the grant statement. For example if you want the user created by Stronghold to have access to all databases starting with fooapp_ you could use the following creation statement:

CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'; GRANT SELECT ON `fooapp\_%`.* TO '{{name}}'@'%';

MySQL expects the part in which the wildcards are to be placed inside backticks. If you want to add this creation statement to Stronghold via the Stronghold CLI you cannot simply paste the above statement on the CLI because the shell will interpret the text between the backticks as something that must be executed. The easiest way to get around this is to encode the creation statement as Base64 and feed this to Stronghold. For example:

$ d8 stronghold write database/roles/my-role \
    db_name=mysql \
    creation_statements="Q1JFQVRFIFVTRVIgJ3t7bmFtZX19J0AnJScgSURFTlRJRklFRCBCWSAne3twYXNzd29yZH19JzsgR1JBTlQgU0VMRUNUIE9OIGBmb29hcHBcXyVgLiogVE8gJ3t7bmFtZX19J0AnJSc7" \
    default_ttl="1h" \
    max_ttl="24h"

Rotating root credentials in MySQL 5.6

The default root rotation setup for MySQL uses the ALTER USER syntax present in MySQL 5.7 and up. For MySQL 5.6, the root rotation statements must be configured to use the old SET PASSWORD syntax. For example:

$ d8 stronghold write database/config/my-mysql-database \
    plugin_name=mysql-database-plugin \
    connection_url="{{username}}:{{password}}@tcp(127.0.0.1:3306)/" \
    root_rotation_statements="SET PASSWORD = PASSWORD('{{password}}')" \
    allowed_roles="my-role" \
    username="root" \
    password="mysql"

API

The full list of configurable options can be seen in the MySQL database plugin API page.

For more information on the database secrets engine's HTTP API please see the Database secrets engine API page.

Identity

Сущности

The Identity secrets engine is the identity management solution for Stronghold. It internally maintains the clients who are recognized by Stronghold. Each client is internally termed as an Entity. An entity can have multiple Aliases. For example, a single user who has accounts in both GitLab and LDAP, can be mapped to a single entity in Stronghold that has 2 aliases, one of type GitLab and one of type LDAP. When a client authenticates via any of the credential backends (except the Token backend), Stronghold creates a new entity and attaches a new alias to it, if a corresponding entity doesn't already exist. The entity identifier will be tied to the authenticated token. When such tokens are put to use, their entity identifiers are audit logged, marking a trail of actions performed by specific users.

Identity store allows operators to manage the entities in Stronghold. Entities can be created and aliases can be tied to entities, via the ACL'd API. There can be policies set on the entities which adds capabilities to the tokens that are tied to entity identifiers. The capabilities granted to tokens via the entities are an addition to the existing capabilities of the token and not a replacement. The capabilities of the token that get inherited from entities are computed dynamically at request time. This provides flexibility in controlling the access of tokens that are already issued.

{% alert level="warning" %}

NOTE: This secrets engine will be mounted by default. This secrets engine cannot be disabled or moved. For more conceptual overview on identity, refer to the Identity documentation.

{% endalert %}

The Stronghold Identity secrets engine supports several different features. Each one is individually documented on its own page.

• Identity tokens
• OIDC Identity Provider

API

The Identity secrets engine has a full HTTP API. Please see the Identity secrets engine API for more details.

Additionally, Stronghold can be configured as an OIDC identity provider. Please see the OIDC identity provider API for more details.

Токены сущностей

Introduction

Identity information is used throughout Stronghold, but it can also be exported for use by other applications. An authorized user/application can request a token that encapsulates identity information for their associated entity. These tokens are signed JWTs following the OIDC ID token structure. The public keys used to authenticate the tokens are published by Stronghold on an unauthenticated endpoint following OIDC discovery and JWKS conventions, which should be directly usable by JWT/OIDC libraries. An introspection endpoint is also provided by Stronghold for token verification.

Roles and keys

OIDC-compliant ID tokens are generated against a role which allows configuration of token claims via a templating system, token ttl, and a way to specify which "key" will be used to sign the token. The role template is an optional parameter to customize the token contents and is described in the next section. Token TTL controls the expiration time of the token, after which verification libraries will consider the token invalid. All roles have an associated client_id that will be added to the token's aud parameter. JWT/OIDC libraries will usually require this value. The parameter may be set by the operator to a chosen value, or a Stronghold-generated value will be used if left unconfigured.

A role's key parameter links a role to an existing named key (multiple roles may refer to the same key). It is not possible to generate an unsigned ID token.

A named key is a public/private key pair generated by Stronghold. The private key is used to sign the identity tokens, and the public key is used by clients to verify the signature. Keys are regularly rotated, whereby a new key pair is generated and the previous public key is retained for a limited time for verification purposes.

A named key's configuration specifies a rotation period, a verification ttl, signing algorithm and allowed client IDs. Rotation period specifies the frequency at which a new signing key is generated and the private portion of the previous signing key is deleted. Verification ttl is the time a public key is retained for verification after being rotated. By default, keys are rotated every 24 hours, and continue to be available for verification for 24 hours after their rotation.

A key's list of allowed client IDs limits which roles may reference the key. The parameter may be set to * to allow all roles. The validity evaluation is made when a token is requested, not during configuration.

Token contents and templates

Identity tokens will always contain, at a minimum, the claims required by OIDC:

• iss - Issuer URL
• sub - Requester's entity ID
• aud - client_id for the role
• iat - Time of issue
• exp - Expiration time for the token

In addition, the operator may configure per-role templates that allow a variety of other entity information to be added to the token. The templates are structured as JSON with replaceable parameters. The parameter syntax is the same as that used for ACL Path Templating.

For example:

{
  "color": {{identity.entity.metadata.color}},
  "userinfo": {
     "username": {{identity.entity.aliases.usermap_123.metadata.username}},
     "groups": {{identity.entity.groups.names}}
  },
  "nbf": {{time.now}}
}

When a token is requested, the resulting template might be populated as:

{
  "color": "green",
  "userinfo": {
     "username": "bob",
     "groups": ["web", "engr", "default"]
  },
  "nbf": 1561411915
}

which would be merged with the base OIDC claims into the final token:

{
  "iss": "https://10.1.1.45:8200/v1/identity/oidc",
  "sub": "a2cd63d3-5364-406f-980e-8d71bb0692f5",
  "aud": "SxSouteCYPBoaTFy94hFghmekos",
  "iat": 1561411915,
  "exp": 1561412215,
  "color": "green",
  "userinfo": {
    "username": "bob",
    "groups": ["web", "engr", "default"]
  },
  "nbf": 1561411915
}

Note how the template is merged, with top level template keys becoming top level token keys. For this reason, templates may not contain top level keys that overwrite the standard OIDC claims.

Template parameters that are not present for an entity, such as a metadata that isn't present, or an alias accessor which doesn't exist, are simply empty strings or objects, depending on the data type.

Templates are configured on the role and may be optionally encoded as base64.

The full list of template parameters is shown below:

Name	Description
identity.entity.id	The entity's ID
identity.entity.name	The entity's name
identity.entity.groups.ids	The IDs of the groups the entity is a member of
identity.entity.groups.names	The names of the groups the entity is a member of
identity.entity.metadata	Metadata associated with the entity
identity.entity.metadata.<metadata key>	Metadata associated with the entity for the given key
identity.entity.aliases.<mount accessor>.id	Entity alias ID for the given mount
identity.entity.aliases.<mount accessor>.name	Entity alias name for the given mount
identity.entity.aliases.<mount accessor>.metadata	Metadata associated with the alias for the given mount
identity.entity.aliases.<mount accessor>.metadata.<metadata key>	Metadata associated with the alias for the given mount and metadata key
identity.entity.aliases.<mount accessor>.custom_metadata	Custom metadata associated with the alias for the given mount
identity.entity.aliases.<mount accessor>.custom_metadata.<custom_metadata key>	Custom metadata associated with the alias for the given mount and custom metadata key
time.now	Current time as integral seconds since the Epoch
time.now.plus.<duration>	Current time plus a duration format string
time.now.minus.<duration>	Current time minus a duration format string

Token generation

An authenticated client may request a token using the token generation endpoint. The token will be generated per the requested role's specifications, for the requester's entity. It is not possible to generate tokens for an arbitrary entity.

Verifying authenticity of ID tokens generated by Stronghold

An identity token may be verified by the client party using the public keys published by Stronghold, or via an Stronghold-provided introspection endpoint.

Stronghold will serve standard ".well-known" endpoints that allow easy integration with OIDC verification libraries. Configuring the libraries will typically involve providing an issuer URL and client ID. The library will then handle key requests and can validate the signature and claims requirements on tokens. This approach has the advantage of only requiring access to Stronghold, not authorization, as the .well-known endpoints are unauthenticated.

Alternatively, the token may be sent to Stronghold for verification via an introspection endpoint. The response will indicate whether the token is "active" or not, as well as any errors that occurred during validation. Beyond simply allowing the client to delegate verification to Stronghold, using this endpoint incorporates the additional check of whether the entity is still active or not, which is something that cannot be determined from the token alone. Unlike the .well-known endpoint, accessing the introspection endpoint does require a valid Stronghold token and sufficient authorization.

Issuer considerations

The identity token system has one configurable parameter: issuer. The issuer iss claim is particularly important for proper validation of the token by clients. Consumers of the token will request public keys from Stronghold using the issuer URL, so it must be network reachable. Furthermore, the returned set of keys will include an issuer that must match the request.

By default Stronghold will set the issuer to the Stronghold instance's api_addr. This means that tokens issued in a given cluster should be validated within that same cluster. Alternatively, the issuer parameter may be configured explicitly. This address must point to the identity/oidc path for the Stronghold instance (e.g. https://stronghold.example.com:8200/v1/identity/oidc) and should be reachable by any client trying to validate identity tokens.

API

The Identity secrets engine has a full HTTP API. Please see the Identity secrets engine API for more details.

OIDC провайдер

Stronghold is an OpenID Connect (OIDC) identity provider. This enables client applications that speak the OIDC protocol to leverage Stronghold's source of identity and wide range of authentication methods when authenticating end-users. Client applications can configure their authentication logic to talk to Stronghold. Once enabled, Stronghold will act as the bridge to other identity providers via its existing authentication methods. Client applications can also obtain identity information for their end-users by leveraging custom templating of Stronghold identity information.

{% alert level="info" %}

Note: For more detailed information on the configuration resources and OIDC endpoints, please visit the OIDC provider concepts page.

{% endalert %}

Setup

The Stronghold OIDC provider system is built on top of the identity secrets engine. This secrets engine is mounted by default and cannot be disabled or moved.

Each Stronghold namespace has a default OIDC provider and key. This built-in configuration enables client applications to begin using Stronghold as a source of identity with minimal configuration. For details on the built-in configuration and advanced options, see the OIDC provider concepts page.

The following steps show a minimal configuration that allows a client application to use Stronghold as an OIDC provider.

1. Enable an Stronghold auth method:

text $ d8 stronghold auth enable userpass Success! Enabled userpass auth method at: userpass/

Any Stronghold auth method may be used within the OIDC flow. For simplicity, enable the userpass auth method.

1. Create a user:

text $ d8 stronghold write auth/userpass/users/end-user password="securepassword" Success! Data written to: auth/userpass/users/end-user

This user will authenticate to Stronghold through a client application, otherwise known as an OIDC relying party.

1. Create a client application:

text $ d8 stronghold write identity/oidc/client/my-webapp \ redirect_uris="https://localhost:9702/auth/oidc-callback" \ assignments="allow_all" Success! Data written to: identity/oidc/client/my-webapp

This operation creates a client application which can be used to configure an OIDC relying party. See the client applications section for details on different client types, including confidential and public clients.

The assignments parameter limits the Stronghold entities and groups that are allowed to authenticate through the client application. By default, no Stronghold entities are allowed. To allow all Stronghold entities to authenticate, the built-in allow_all assignment is provided.

1. Read client credentials:

```text $ d8 stronghold read identity/oidc/client/my-webapp

Key Value --- ----- access_token_ttl 24h assignments [allow_all] client_id GSDTnn3KaOrLpNlVGlYLS9TVsZgOTweO client_secret hvo_secret_gBKHcTP58C4aq7FqPWsuqKgpiiegd7ahpifGae9WGkHRCwFEJTZA9KGdNVpzE0r8 client_type confidential id_token_ttl 24h key default redirect_uris [https://localhost:9702/auth/oidc-callback] ```

The client_id and client_secret are the client application's credentials. These values are typically required when configuring an OIDC relying party.

1. Read OIDC discovery configuration:

text $ curl -s http://127.0.0.1:8200/v1/identity/oidc/provider/default/.well-known/openid-configuration { "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/default", "jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/.well-known/keys", "authorization_endpoint": "http://127.0.0.1:8200/ui/vault/identity/oidc/provider/default/authorize", "token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/token", "userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/userinfo", "request_parameter_supported": false, "request_uri_parameter_supported": false, "id_token_signing_alg_values_supported": [ "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "EdDSA" ], "response_types_supported": [ "code" ], "scopes_supported": [ "openid" ], "subject_types_supported": [ "public" ], "grant_types_supported": [ "authorization_code" ], "token_endpoint_auth_methods_supported": [ "none", "client_secret_basic", "client_secret_post" ] }

Each Stronghold OIDC provider publishes discovery metadata. The issuer value is typically required when configuring an OIDC relying party.

Usage

After configuring an Stronghold auth method and client application, the following details can be used to configure an OIDC relying party to delegate end-user authentication to Stronghold.

• client_id - The ID of the client application
• client_secret - The secret of the client application
• issuer - The issuer of the Stronghold OIDC provider

Otherwise, refer to the documentation of the specific OIDC relying party for usage details.

Supported flows

The Stronghold OIDC provider feature currently supports the following authentication flow:

• Authorization Code Flow.

API

The Stronghold OIDC provider feature has a full HTTP API. Please see the OIDC identity provider API for more details.

LDAP

{% alert level="warning" %} This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround. See the deprecation FAQ for more information. {% endalert %}

The LDAP secrets engine provides management of LDAP credentials as well as dynamic creation of credentials. It supports integration with implementations of the LDAP v3 protocol, including OpenLDAP, Active Directory, and IBM Resource Access Control Facility (RACF).

The secrets engine has three primary features: - Static Credentials - Dynamic Credentials - Service Account Check-Out

Setup

1. Enable the LDAP secret engine:

sh d8 stronghold secrets enable ldap

By default, the secrets engine will mount at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

1. Configure the credentials that Stronghold uses to communicate with LDAP to generate passwords:

sh $ d8 stronghold write ldap/config \ binddn=$USERNAME \ bindpass=$PASSWORD \ url=ldaps://138.91.247.105

Note: it's recommended a dedicated entry management account be created specifically for Stronghold.

1. Rotate the root password so only Stronghold knows the credentials:

sh d8 stronghold write -f ldap/rotate-root

Note: it's not possible to retrieve the generated password once rotated by Stronghold. It's recommended a dedicated entry management account be created specifically for Stronghold.

Schemas

The LDAP Secret Engine supports three different schemas:

• openldap (default)
• racf
• ad

OpenLDAP

By default, the LDAP Secret Engine assumes the entry password is stored in userPassword. There are many object classes that provide userPassword including for example:

• organization
• organizationalUnit
• organizationalRole
• inetOrgPerson
• person
• posixAccount

Resource access control facility (RACF)

For managing IBM's Resource Access Control Facility (RACF) security system, the secret engine must be configured to use the schema racf.

Generated passwords must be 8 characters or less to support RACF. The length of the password can be configured using a password policy:

$ d8 stronghold write ldap/config \
 binddn=$USERNAME \
 bindpass=$PASSWORD \
 url=ldaps://138.91.247.105 \
 schema=racf \
 password_policy=racf_password_policy

Active directory (AD)

For managing Active Directory instances, the secret engine must be configured to use the schema ad.

$ d8 stronghold write ldap/config \
 binddn=$USERNAME \
 bindpass=$PASSWORD \
 url=ldaps://138.91.247.105 \
 schema=ad

Static credentials

Setup

1. Configure a static role that maps a name in Stronghold to an entry in LDAP. Password rotation settings will be managed by this role.

sh $ d8 stronghold write ldap/static-role/lf-edge\ dn='uid=lf-edge,ou=users,dc=lf-edge,dc=com' \ username='stronghold'\ rotation_period="24h"

1. Request credentials for the "stronghold" role:

sh d8 stronghold read ldap/static-cred/lf-edge

Password rotation

Passwords can be managed in two ways:

• automatic time based rotation
• manual rotation

Auto password rotation

Passwords will automatically be rotated based on the rotation_period configured in the static role (minimum of 5 seconds). When requesting credentials for a static role, the response will include the time before the next rotation (ttl).

Auto-rotation is currently only supported for static roles. The binddn account used by Stronghold should be rotated using the rotate-root endpoint to generate a password only Stronghold will know.

Manual rotation

Static roles can be manually rotated using the rotate-role endpoint. When manually rotated the rotation period will start over.

Deleting static roles

Passwords are not rotated upon deletion of a static role. The password should be manually rotated prior to deleting the role or revoking access to the static role.

Dynamic credentials

Setup

Dynamic credentials can be configured by calling the /role/:role_name endpoint:

$ d8 stronghold write ldap/role/dynamic-role \
  creation_ldif=@/path/to/creation.ldif \
  deletion_ldif=@/path/to/deletion.ldif \
  rollback_ldif=@/path/to/rollback.ldif \
  default_ttl=1h \
  max_ttl=24h

{% endraw %} {% alert level="info" %} The rollback_ldif argument is optional, but recommended. The statements within rollback_ldif will be executed if the creation fails for any reason. This ensures any entities are removed in the event of a failure. {% endalert %}

To generate credentials:

$ d8 stronghold read ldap/creds/dynamic-role
Key                    Value
---                    -----
lease_id               ldap/creds/dynamic-role/HFgd6uKaDomVMvJpYbn9q4q5
lease_duration         1h
lease_renewable        true
distinguished_names    [cn=v_token_dynamic-role_FfH2i1c4dO_1611952635,ou=users,dc=learn,dc=example]
password               xWMjkIFMerYttEbzfnBVZvhRQGmhpAA0yeTya8fdmDB3LXDzGrjNEPV2bCPE9CW6
username               v_token_testrole_FfH2i1c4dO_1611952635

The distinguished_names field is an array of DNs that are created from the creation_ldif statements. If more than one LDIF entry is included, the DN from each statement will be included in this field. Each entry in this field corresponds to a single LDIF statement. No de-duplication occurs and order is maintained.

LDIF entries

User account management is provided through LDIF entries. The LDIF entries may be a base64-encoded version of the LDIF string. The string will be parsed and validated to ensure that it adheres to LDIF syntax. A good reference for proper LDIF syntax can be found here.

Some important things to remember when crafting your LDIF entries:

• There should not be any trailing spaces on any line, including empty lines
• Each modify block needs to be preceded with an empty line
• Multiple modifications for a dn can be defined in a single modify block. Each modification needs to close with a single dash (-)

Active directory (AD)

For Active Directory, there are a few additional details that are important to remember:

To create a user programmatically in AD, you first add a user object and then modify that user to provide a password and enable the account.

• Passwords in AD are set using the unicodePwd field. This must be proceeded by two (2) colons (::).

• When setting a password programmatically in AD, the following criteria must be met:

• The password must be enclosed in double quotes (" ")

• The password must be in UTF16LE format
• The password must be base64-encoded

• Additional details can be found here

• Once a user's password has been set, it can be enabled. AD uses the userAccountControl field for this purpose:

• To enable the account, set userAccountControl to 512
• You will likely also want to disable AD's password expiration for this dynamic user account. The userAccountControl value for this is: 65536
• userAccountControl flags are cumulative, so to set both of the above two flags, add up the two values (512 + 65536 = 66048): set userAccountControl to 66048
• See here for details on userAccountControl flags

sAMAccountName is a common field when working with AD users. It is used to provide compatibility with legacy Windows NT systems and has a limit of 20 characters. Keep this in mind when defining your username_template. See here for additional details.

Since the default username_template is longer than 20 characters which follows the template of v_{{.DisplayName}}_{{.RoleName}}_{{random 10}}_{{unix_time}}, we recommend customising the username_template on the role configuration to generate accounts with names less than 20 characters. Please refer to the username templating document for more information.

With regard to adding dynamic users to groups, AD doesn't let you directly modify a user's memberOf attribute. The member attribute of a group and memberOf attribute of a user are linked attributes. Linked attributes are forward link/back link pairs, with the forward link able to be modified. In the case of AD group membership, the group's member attribute is the forward link. In order to add a newly-created dynamic user to a group, we also need to issue a modify request to the desired group and update the group membership with the new user.

Active directory LDIF example

The various *_ldif parameters are templates that use the go template language. A complete LDIF example for creating an Active Directory user account is provided here for reference:

dn: CN={{.Username}},OU=Stronghold,DC=adtesting,DC=lab
changetype: add
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
userPrincipalName: {{.Username}}@adtesting.lab
sAMAccountName: {{.Username}}

dn: CN={{.Username}},OU=Stronghold,DC=adtesting,DC=lab
changetype: modify
replace: unicodePwd
unicodePwd::{{ printf "%q" .Password | utf16le | base64 }}
-
replace: userAccountControl
userAccountControl: 66048
-

dn: CN=test-group,OU=Stronghold,DC=adtesting,DC=lab
changetype: modify
add: member
member: CN={{.Username}},OU=Stronghold,DC=adtesting,DC=lab
-

Service account Check-Out

Service account check-out provides a library of service accounts that can be checked out by a person or by machines. Stronghold will automatically rotate the password each time a service account is checked in. Service accounts can be voluntarily checked in, or Stronghold will check them in when their lending period (or, "ttl", in Stronghold's language) ends.

The service account check-out functionality works with various schemas, including OpenLDAP, Active Directory, and RACF. In the following usage example, the secrets engine is configured to manage a library of service accounts in an Active Directory instance.

First we'll need to enable the LDAP secrets engine and tell it how to securely connect to an AD server.

$ d8 stronghold secrets enable ldap
Success! Enabled the ad secrets engine at: ldap/

$ d8 stronghold write ldap/config \
    binddn=$USERNAME \
    bindpass=$PASSWORD \
    url=ldaps://138.91.247.105 \
    userdn='dc=example,dc=com'

Our next step is to designate a set of service accounts for check-out.

$ d8 stronghold write ldap/library/accounting-team \
    service_account_names=fizz@example.com,buzz@example.com \
    ttl=10h \
    max_ttl=20h \
    disable_check_in_enforcement=false

In this example, the service account names of fizz@example.com and buzz@example.com have already been created on the remote AD server. They've been set aside solely for Stronghold to handle. The ttl is how long each check-out will last before Stronghold checks in a service account, rotating its password during check-in. The max_ttl is the maximum amount of time it can live if it's renewed. These default to 24h, and both use duration format strings. Also by default, a service account must be checked in by the same Stronghold entity or client token that checked it out. However, if this behavior causes problems, set disable_check_in_enforcement=true.

When a library of service accounts has been created, view their status at any time to see if they're available or checked out.

$ d8 stronghold read ldap/library/accounting-team/status
Key                 Value
---                 -----
buzz@example.com    map[available:true]
fizz@example.com    map[available:true]

To check out any service account that's available, simply execute:

$ d8 stronghold write -f ldap/library/accounting-team/check-out
Key                     Value
---                     -----
lease_id                ldap/library/accounting-team/check-out/EpuS8cX7uEsDzOwW9kkKOyGW
lease_duration          10h
lease_renewable         true
password                ?@09AZKh03hBORZPJcTDgLfntlHqxLy29tcQjPVThzuwWAx/Twx4a2ZcRQRqrZ1w
service_account_name    fizz@example.com

If the default ttl for the check-out is higher than needed, set the check-out to last for a shorter time by using:

$ d8 stronghold write ldap/library/accounting-team/check-out ttl=30m
Key                     Value
---                     -----
lease_id                ldap/library/accounting-team/check-out/gMonJ2jB6kYs6d3Vw37WFDCY
lease_duration          30m
lease_renewable         true
password                ?@09AZerLLuJfEMbRqP+3yfQYDSq6laP48TCJRBJaJu/kDKLsq9WxL9szVAvL/E1
service_account_name    buzz@example.com

This can be a nice way to say, "Although I can have a check-out for 24 hours, if I haven't checked it in after 30 minutes, I forgot or I'm a dead instance, so you can just check it back in."

If no service accounts are available for check-out, Stronghold will return a 400 Bad Request.

$ d8 stronghold write -f ldap/library/accounting-team/check-out
Error writing data to ldap/library/accounting-team/check-out: Error making API request.

URL: POST http://localhost:8200/v1/ldap/library/accounting-team/check-out
Code: 400. Errors:

* No service accounts available for check-out.

To extend a check-out, renew its lease.

$ d8 stronghold lease renew ldap/library/accounting-team/check-out/0C2wmeaDmsToVFc0zDiX9cMq
Key                Value
---                -----
lease_id           ldap/library/accounting-team/check-out/0C2wmeaDmsToVFc0zDiX9cMq
lease_duration     10h
lease_renewable    true

Renewing a check-out means its current password will live longer, since passwords are rotated anytime a password is checked in either by a caller, or by Stronghold because the check-out ttl ends.

To check a service account back in for others to use, call:

$ d8 stronghold write -f ldap/library/accounting-team/check-in
Key          Value
---          -----
check_ins    [fizz@example.com]

Most of the time this will just work, but if multiple service accounts are checked out by the same caller, Stronghold will need to know which one(s) to check in.

$ d8 stronghold write ldap/library/accounting-team/check-in service_account_names=fizz@example.com
Key          Value
---          -----
check_ins    [fizz@example.com]

To perform a check-in, Stronghold verifies that the caller should be able to check in a given service account. To do this, Stronghold looks for either the same entity ID used to check out the service account, or the same client token.

If a caller is unable to check in a service account, or simply doesn't try, Stronghold will check it back in automatically when the ttl expires. However, if that is too long, service accounts can be forcibly checked in by a highly privileged user through:

$ d8 stronghold write -f ldap/library/manage/accounting-team/check-in
Key          Value
---          -----
check_ins    [fizz@example.com]

Or, alternatively, revoking the secret's lease has the same effect.

$ d8 stronghold lease revoke ldap/library/accounting-team/check-out/PvBVG0m7pEg2940Cb3Jw3KpJ
All revocation operations queued successfully!

LDAP password policy

The LDAP secret engine does not hash or encrypt passwords prior to modifying values in LDAP. This behavior can cause plaintext passwords to be stored in LDAP.

To avoid having plaintext passwords stored, the LDAP server should be configured with an LDAP password policy (ppolicy, not to be confused with an Stronghold password policy). A ppolicy can enforce rules such as hashing plaintext passwords by default.

The following is an example of an LDAP password policy to enforce hashing on the data information tree (DIT) dc=example,dc=com:

dn: cn=module{0},cn=config
changetype: modify
add: olcModuleLoad
olcModuleLoad: ppolicy

dn: olcOverlay={2}ppolicy,olcDatabase={1}mdb,cn=config
changetype: add
objectClass: olcPPolicyConfig
objectClass: olcOverlayConfig
olcOverlay: {2}ppolicy
olcPPolicyDefault: cn=default,ou=pwpolicies,dc=example,dc=com
olcPPolicyForwardUpdates: FALSE
olcPPolicyHashCleartext: TRUE
olcPPolicyUseLockout: TRUE

API

The LDAP secrets engine has a full HTTP API. Please see the LDAP secrets engine API docs for more details.

TOTP

The TOTP secrets engine generates time-based credentials according to the TOTP standard. The secrets engine can also be used to generate a new key and validate passwords generated by that key.

The TOTP secrets engine can act as both a generator (like Google Authenticator) and a provider (like the Google.com sign in service).

As a generator

The TOTP secrets engine can act as a TOTP code generator. In this mode, it can replace traditional TOTP generators like Google Authenticator. It provides an added layer of security since the ability to generate codes is guarded by policies and the entire process is audited.

Setup

Most secrets engines must be configured in advance before they can perform their functions. These steps are usually completed by an operator or configuration management tool.

1. Enable the TOTP secrets engine:

   text $ d8 stronghold secrets enable totp Success! Enabled the totp secrets engine at: totp/

   By default, the secrets engine will mount at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

2. Configure a named key. The name of this key will be a human identifier as to its purpose.

   text $ d8 stronghold write totp/keys/my-key \ url="otpauth://totp/Stronghold:test@test.com?secret=Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G&issuer=Stronghold" Success! Data written to: totp/keys/my-key

   The url corresponds to the secret key or value from the barcode provided by the third-party service.

Usage

After the secrets engine is configured and a user/machine has an Stronghold token with the proper permission, it can generate credentials.

1. Generate a new time-based OTP by reading from the /code endpoint with the name of the key:

   text $ d8 stronghold read totp/code/my-key Key Value --- ----- code 260610

   Using ACLs, it is possible to restrict using the TOTP secrets engine such that trusted operators can manage the key definitions, and both users and applications are restricted in the credentials they are allowed to read.

As a provider

The TOTP secrets engine can also act as a TOTP provider. In this mode, it can be used to generate new keys and validate passwords generated using those keys.

Setup

Most secrets engines must be configured in advance before they can perform their functions. These steps are usually completed by an operator or configuration management tool.

1. Enable the TOTP secrets engine:

   text $ d8 stronghold secrets enable totp Success! Enabled the totp secrets engine at: totp/

   By default, the secrets engine will mount at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

2. Create a named key, using the generate option. This tells Stronghold to be the provider:

   ```text $ d8 stronghold write totp/keys/my-user \ generate=true \ issuer=Stronghold \ account_name=user@test.com

   Key Value --- ----- barcode iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BA... url otpauth://totp/Stronghold:user@test.com?algorithm=SHA1&digits=6&issuer=Stronghold&period=30&secret=V7MBSK324I7KF6KVW34NDFH2GYHIF6JY ```

   The response includes a base64-encoded barcode and OTP url. Both are equivalent. Give these to the user who is authenticating with TOTP.

Usage

1. As a user, validate a TOTP code generated by a third-party app:

text $ d8 stronghold write totp/code/my-user code=886531 Key Value --- ----- valid true

API

The TOTP secrets engine has a full HTTP API. Please see the TOTP secrets engine API for more details.

Cubbyhole

The cubbyhole secrets engine is used to store arbitrary secrets within the configured physical storage for Stronghold namespaced to a token. In cubbyhole, paths are scoped per token. No token can access another token's cubbyhole. When the token expires, its cubbyhole is destroyed.

Also unlike the kv secrets engine, because the cubbyhole's lifetime is linked to that of an authentication token, there is no concept of a TTL or refresh interval for values contained in the token's cubbyhole.

Writing to a key in the cubbyhole secrets engine will completely replace the old value.

Setup

Most secrets engines must be configured in advance before they can perform their functions. These steps are usually completed by an operator or configuration management tool.

The cubbyhole secrets engine is enabled by default. It cannot be disabled, moved, or enabled multiple times.

Usage

After the secrets engine is configured and a user/machine has an Stronghold token with the proper permission, it can generate credentials. The cubbyhole secrets engine allows for writing keys with arbitrary values.

1. Write arbitrary data:

text $ d8 stronghold write cubbyhole/my-secret my-value=s3cr3t Success! Data written to: cubbyhole/my-secret

1. Read arbitrary data:

text $ d8 stronghold read cubbyhole/my-secret Key Value --- ----- my-value s3cr3t

Stronghold API

Version: 1.16.0

HTTP API that gives you full access to Stronghold. All API routes are prefixed with /v1/.

---

auth

GET /auth/token/accessors

Operation ID: token-list-accessors

List token accessors, which can then be be used to iterate and discover their properties or revoke them. Because this can be used to cause a denial of service, this endpoint requires 'sudo' capability in addition to 'list'.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

POST /auth/token/create

Operation ID: token-create

The token create path is used to create new tokens.

Request body parameters

Parameter	Type	Required	Description
display_name	string	no	Name to associate with this token
entity_alias	string	no	Name of the entity alias to associate with this token
explicit_max_ttl	string	no	Explicit Max TTL of this token
id	string	no	Value for the token
lease	string	no	⚠️ Deprecated. Use 'ttl' instead
meta	object	no	Arbitrary key=value metadata to associate with the token
no_default_policy	boolean	no	Do not include default policy for this token
no_parent	boolean	no	Create the token with no parent
num_uses	integer	no	Max number of uses for this token
period	string	no	Renew period
policies	array	no	List of policies for the token
renewable	boolean (default: True)	no	Allow token to be renewed past its initial TTL up to system/mount maximum TTL
ttl	string	no	Time to live for this token
type	string	no	Token type

Responses

200: OK

POST /auth/token/create-orphan

Operation ID: token-create-orphan

The token create path is used to create new orphan tokens.

Request body parameters

Parameter	Type	Required	Description
display_name	string	no	Name to associate with this token
entity_alias	string	no	Name of the entity alias to associate with this token
explicit_max_ttl	string	no	Explicit Max TTL of this token
id	string	no	Value for the token
lease	string	no	⚠️ Deprecated. Use 'ttl' instead
meta	object	no	Arbitrary key=value metadata to associate with the token
no_default_policy	boolean	no	Do not include default policy for this token
no_parent	boolean	no	Create the token with no parent
num_uses	integer	no	Max number of uses for this token
period	string	no	Renew period
policies	array	no	List of policies for the token
renewable	boolean (default: True)	no	Allow token to be renewed past its initial TTL up to system/mount maximum TTL
ttl	string	no	Time to live for this token
type	string	no	Token type

Responses

200: OK

POST /auth/token/create/{role_name}

Operation ID: token-create-against-role

This token create path is used to create new tokens adhering to the given role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role

Request body parameters

Parameter	Type	Required	Description
display_name	string	no	Name to associate with this token
entity_alias	string	no	Name of the entity alias to associate with this token
explicit_max_ttl	string	no	Explicit Max TTL of this token
id	string	no	Value for the token
lease	string	no	⚠️ Deprecated. Use 'ttl' instead
meta	object	no	Arbitrary key=value metadata to associate with the token
no_default_policy	boolean	no	Do not include default policy for this token
no_parent	boolean	no	Create the token with no parent
num_uses	integer	no	Max number of uses for this token
period	string	no	Renew period
policies	array	no	List of policies for the token
renewable	boolean (default: True)	no	Allow token to be renewed past its initial TTL up to system/mount maximum TTL
ttl	string	no	Time to live for this token
type	string	no	Token type

Responses

200: OK

GET /auth/token/lookup

Operation ID: token-look-up-2

This endpoint will lookup a token and its properties.

Responses

200: OK

POST /auth/token/lookup

Operation ID: token-look-up

This endpoint will lookup a token and its properties.

Request body parameters

Parameter	Type	Required	Description
token	string	no	Token to lookup (POST request body)

Responses

200: OK

POST /auth/token/lookup-accessor

Operation ID: token-look-up-accessor

This endpoint will lookup a token associated with the given accessor and its properties. Response will not contain the token ID.

Request body parameters

Parameter	Type	Required	Description
accessor	string	no	Accessor of the token to look up (request body)

Responses

200: OK

GET /auth/token/lookup-self

Operation ID: token-look-up-self

This endpoint will lookup a token and its properties.

Responses

200: OK

POST /auth/token/lookup-self

Operation ID: token-look-up-self2

This endpoint will lookup a token and its properties.

Request body parameters

Parameter	Type	Required	Description
token	string	no	Token to look up (unused, does not need to be set)

Responses

200: OK

POST /auth/token/renew

Operation ID: token-renew

This endpoint will renew the given token and prevent expiration.

Request body parameters

Parameter	Type	Required	Description
increment	integer (default: 0)	no	The desired increment in seconds to the token expiration
token	string	no	Token to renew (request body)

Responses

200: OK

POST /auth/token/renew-accessor

Operation ID: token-renew-accessor

This endpoint will renew a token associated with the given accessor and its properties. Response will not contain the token ID.

Request body parameters

Parameter	Type	Required	Description
accessor	string	no	Accessor of the token to renew (request body)
increment	integer (default: 0)	no	The desired increment in seconds to the token expiration

Responses

200: OK

POST /auth/token/renew-self

Operation ID: token-renew-self

This endpoint will renew the token used to call it and prevent expiration.

Request body parameters

Parameter	Type	Required	Description
increment	integer (default: 0)	no	The desired increment in seconds to the token expiration
token	string	no	Token to renew (unused, does not need to be set)

Responses

200: OK

POST /auth/token/revoke

Operation ID: token-revoke

This endpoint will delete the given token and all of its child tokens.

Request body parameters

Parameter	Type	Required	Description
token	string	no	Token to revoke (request body)

Responses

200: OK

POST /auth/token/revoke-accessor

Operation ID: token-revoke-accessor

This endpoint will delete the token associated with the accessor and all of its child tokens.

Request body parameters

Parameter	Type	Required	Description
accessor	string	no	Accessor of the token (request body)

Responses

200: OK

POST /auth/token/revoke-orphan

Operation ID: token-revoke-orphan

This endpoint will delete the token and orphan its child tokens.

Request body parameters

Parameter	Type	Required	Description
token	string	no	Token to revoke (request body)

Responses

200: OK

POST /auth/token/revoke-self

Operation ID: token-revoke-self

This endpoint will delete the token used to call it and all of its child tokens.

Responses

200: OK

GET /auth/token/roles

Operation ID: token-list-roles

This endpoint lists configured roles.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /auth/token/roles/{role_name}

Operation ID: token-read-role

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role

Responses

200: OK

POST /auth/token/roles/{role_name}

Operation ID: token-write-role

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role

Request body parameters

Parameter	Type	Required	Description
allowed_entity_aliases	array	no	String or JSON list of allowed entity aliases. If set, specifies the entity aliases which are allowed to be used during token generation. This field supports globbing.
allowed_policies	array	no	If set, tokens can be created with any subset of the policies in this list, rather than the normal semantics of tokens being a subset of the calling token's policies. The parameter is a comma-delimited string of policy names.
allowed_policies_glob	array	no	If set, tokens can be created with any subset of glob matched policies in this list, rather than the normal semantics of tokens being a subset of the calling token's policies. The parameter is a comma-delimited string of policy name globs.
bound_cidrs	array	no	⚠️ Deprecated. Use 'token_bound_cidrs' instead.
disallowed_policies	array	no	If set, successful token creation via this role will require that no policies in the given list are requested. The parameter is a comma-delimited string of policy names.
disallowed_policies_glob	array	no	If set, successful token creation via this role will require that no requested policies glob match any of policies in this list. The parameter is a comma-delimited string of policy name globs.
explicit_max_ttl	integer	no	⚠️ Deprecated. Use 'token_explicit_max_ttl' instead.
orphan	boolean	no	If true, tokens created via this role will be orphan tokens (have no parent)
path_suffix	string	no	If set, tokens created via this role will contain the given suffix as a part of their path. This can be used to assist use of the 'revoke-prefix' endpoint later on. The given suffix must match the regular expression.\w[\w-.]+\w
period	integer	no	⚠️ Deprecated. Use 'token_period' instead.
renewable	boolean (default: True)	no	Tokens created via this role will be renewable or not according to this value. Defaults to "true".
token_bound_cidrs	array	no	Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.
token_explicit_max_ttl	integer	no	If set, tokens created via this role carry an explicit maximum TTL. During renewal, the current maximum TTL values of the role and the mount are not checked for changes, and any updates to these values will have no effect on the token being renewed.
token_no_default_policy	boolean	no	If true, the 'default' policy will not automatically be added to generated tokens
token_num_uses	integer	no	The maximum number of times a token may be used, a value of zero means unlimited
token_period	integer	no	If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").
token_type	string (default: default-service)	no	The type of token to generate, service or batch

Responses

200: OK

DELETE /auth/token/roles/{role_name}

Operation ID: token-delete-role

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role

Responses

204: empty body

POST /auth/token/tidy

Operation ID: token-tidy

This endpoint performs cleanup tasks that can be run if certain error conditions have occurred.

Responses

200: OK

POST /auth/{approle_mount_path}/login

Operation ID: app-role-login

Issue a token based on the credentials supplied

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
role_id	string	no	Unique identifier of the Role. Required to be supplied when the 'bind_secret_id' constraint is set.
secret_id	string (default: )	no	SecretID belong to the App role

Responses

200: OK

GET /auth/{approle_mount_path}/role

Operation ID: app-role-list-roles

Lists all the roles registered with the backend.

Parameters

Parameter	Type	Location	Required	Description
approle_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no

GET /auth/{approle_mount_path}/role/{role_name}

Operation ID: app-role-read-role

Register an role with the backend.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
bind_secret_id	boolean	no	Impose secret ID to be presented when logging in using this role.
local_secret_ids	boolean	no	If true, the secret identifiers generated using this role will be cluster local. This can only be set during role creation and once set, it can't be reset later
period	integer	no	⚠️ Deprecated. Use "token_period" instead. If this and "token_period" are both specified, only "token_period" will be used.
policies	array	no	⚠️ Deprecated. Use "token_policies" instead. If this and "token_policies" are both specified, only "token_policies" will be used.
secret_id_bound_cidrs	array	no	Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can perform the login operation.
secret_id_num_uses	integer	no	Number of times a secret ID can access the role, after which the secret ID will expire.
secret_id_ttl	integer	no	Duration in seconds after which the issued secret ID expires.
token_bound_cidrs	array	no	Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.
token_explicit_max_ttl	integer	no	If set, tokens created via this role carry an explicit maximum TTL. During renewal, the current maximum TTL values of the role and the mount are not checked for changes, and any updates to these values will have no effect on the token being renewed.
token_max_ttl	integer	no	The maximum lifetime of the generated token
token_no_default_policy	boolean	no	If true, the 'default' policy will not automatically be added to generated tokens
token_num_uses	integer	no	The maximum number of times a token may be used, a value of zero means unlimited
token_period	integer	no	If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value.
token_policies	array	no	Comma-separated list of policies
token_ttl	integer	no	The initial ttl of the token to generate
token_type	string (default: default-service)	no	The type of token to generate, service or batch

POST /auth/{approle_mount_path}/role/{role_name}

Operation ID: app-role-write-role

Register an role with the backend.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bind_secret_id	boolean (default: True)	no	Impose secret_id to be presented when logging in using this role. Defaults to 'true'.
bound_cidr_list	array	no	⚠️ Deprecated. Use "secret_id_bound_cidrs" instead.
local_secret_ids	boolean	no	If set, the secret IDs generated using this role will be cluster local. This can only be set during role creation and once set, it can't be reset later.
period	integer	no	⚠️ Deprecated. Use "token_period" instead. If this and "token_period" are both specified, only "token_period" will be used.
policies	array	no	⚠️ Deprecated. Use "token_policies" instead. If this and "token_policies" are both specified, only "token_policies" will be used.
role_id	string	no	Identifier of the role. Defaults to a UUID.
secret_id_bound_cidrs	array	no	Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can perform the login operation.
secret_id_num_uses	integer	no	Number of times a SecretID can access the role, after which the SecretID will expire. Defaults to 0 meaning that the the secret_id is of unlimited use.
secret_id_ttl	integer	no	Duration in seconds after which the issued SecretID should expire. Defaults to 0, meaning no expiration.
token_bound_cidrs	array	no	Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.
token_explicit_max_ttl	integer	no	If set, tokens created via this role carry an explicit maximum TTL. During renewal, the current maximum TTL values of the role and the mount are not checked for changes, and any updates to these values will have no effect on the token being renewed.
token_max_ttl	integer	no	The maximum lifetime of the generated token
token_no_default_policy	boolean	no	If true, the 'default' policy will not automatically be added to generated tokens
token_num_uses	integer	no	The maximum number of times a token may be used, a value of zero means unlimited
token_period	integer	no	If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").
token_policies	array	no	Comma-separated list of policies
token_ttl	integer	no	The initial ttl of the token to generate
token_type	string (default: default-service)	no	The type of token to generate, service or batch

Responses

200: OK

DELETE /auth/{approle_mount_path}/role/{role_name}

Operation ID: app-role-delete-role

Register an role with the backend.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/bind-secret-id

Operation ID: app-role-read-bind-secret-id

Impose secret_id to be presented during login using this role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
bind_secret_id	boolean	no	Impose secret_id to be presented when logging in using this role. Defaults to 'true'.

POST /auth/{approle_mount_path}/role/{role_name}/bind-secret-id

Operation ID: app-role-write-bind-secret-id

Impose secret_id to be presented during login using this role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bind_secret_id	boolean (default: True)	no	Impose secret_id to be presented when logging in using this role.

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/bind-secret-id

Operation ID: app-role-delete-bind-secret-id

Impose secret_id to be presented during login using this role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/bound-cidr-list

Operation ID: app-role-read-bound-cidr-list

Deprecated: Comma separated list of CIDR blocks, if set, specifies blocks of IP addresses which can perform the login operation

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
bound_cidr_list	array	no	⚠️ Deprecated. Deprecated: Please use "secret_id_bound_cidrs" instead. Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can perform the login operation.

POST /auth/{approle_mount_path}/role/{role_name}/bound-cidr-list

Operation ID: app-role-write-bound-cidr-list

Deprecated: Comma separated list of CIDR blocks, if set, specifies blocks of IP addresses which can perform the login operation

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bound_cidr_list	array	no	Deprecated: Please use "secret_id_bound_cidrs" instead. Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can perform the login operation.

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/bound-cidr-list

Operation ID: app-role-delete-bound-cidr-list

Deprecated: Comma separated list of CIDR blocks, if set, specifies blocks of IP addresses which can perform the login operation

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

POST /auth/{approle_mount_path}/role/{role_name}/custom-secret-id

Operation ID: app-role-write-custom-secret-id

Assign a SecretID of choice against the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
cidr_list	array	no	Comma separated string or list of CIDR blocks enforcing secret IDs to be used from specific set of IP addresses. If 'bound_cidr_list' is set on the role, then the list of CIDR blocks listed here should be a subset of the CIDR blocks listed on the role.
metadata	string	no	Metadata to be tied to the SecretID. This should be a JSON formatted string containing metadata in key value pairs.
num_uses	integer	no	Number of times this SecretID can be used, after which the SecretID expires. Overrides secret_id_num_uses role option when supplied. May not be higher than role's secret_id_num_uses.
secret_id	string	no	SecretID to be attached to the role.
token_bound_cidrs	array	no	Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can use the returned token. Should be a subset of the token CIDR blocks listed on the role, if any.
ttl	integer	no	Duration in seconds after which this SecretID expires. Overrides secret_id_ttl role option when supplied. May not be longer than role's secret_id_ttl.

Responses

200: OK

Parameter	Type	Required	Description
secret_id	string	no	Secret ID attached to the role.
secret_id_accessor	string	no	Accessor of the secret ID
secret_id_num_uses	integer	no	Number of times a secret ID can access the role, after which the secret ID will expire.
secret_id_ttl	integer	no	Duration in seconds after which the issued secret ID expires.

GET /auth/{approle_mount_path}/role/{role_name}/local-secret-ids

Operation ID: app-role-read-local-secret-ids

Enables cluster local secret IDs

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
local_secret_ids	boolean	no	If true, the secret identifiers generated using this role will be cluster local. This can only be set during role creation and once set, it can't be reset later

GET /auth/{approle_mount_path}/role/{role_name}/period

Operation ID: app-role-read-period

Updates the value of 'period' on the role

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
period	integer	no	⚠️ Deprecated. Use "token_period" instead. If this and "token_period" are both specified, only "token_period" will be used.
token_period	integer	no	If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").

POST /auth/{approle_mount_path}/role/{role_name}/period

Operation ID: app-role-write-period

Updates the value of 'period' on the role

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
period	integer	no	⚠️ Deprecated. Use "token_period" instead. If this and "token_period" are both specified, only "token_period" will be used.
token_period	integer	no	If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/period

Operation ID: app-role-delete-period

Updates the value of 'period' on the role

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/policies

Operation ID: app-role-read-policies

Policies of the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
policies	array	no	⚠️ Deprecated. Use "token_policies" instead. If this and "token_policies" are both specified, only "token_policies" will be used.
token_policies	array	no	Comma-separated list of policies

POST /auth/{approle_mount_path}/role/{role_name}/policies

Operation ID: app-role-write-policies

Policies of the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
policies	array	no	⚠️ Deprecated. Use "token_policies" instead. If this and "token_policies" are both specified, only "token_policies" will be used.
token_policies	array	no	Comma-separated list of policies

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/policies

Operation ID: app-role-delete-policies

Policies of the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/role-id

Operation ID: app-role-read-role-id

Returns the 'role_id' of the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
role_id	string	no	Identifier of the role. Defaults to a UUID.

POST /auth/{approle_mount_path}/role/{role_name}/role-id

Operation ID: app-role-write-role-id

Returns the 'role_id' of the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
role_id	string	no	Identifier of the role. Defaults to a UUID.

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/secret-id

Operation ID: app-role-list-secret-ids

Generate a SecretID against this role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no

POST /auth/{approle_mount_path}/role/{role_name}/secret-id

Operation ID: app-role-write-secret-id

Generate a SecretID against this role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
cidr_list	array	no	Comma separated string or list of CIDR blocks enforcing secret IDs to be used from specific set of IP addresses. If 'bound_cidr_list' is set on the role, then the list of CIDR blocks listed here should be a subset of the CIDR blocks listed on the role.
metadata	string	no	Metadata to be tied to the SecretID. This should be a JSON formatted string containing the metadata in key value pairs.
num_uses	integer	no	Number of times this SecretID can be used, after which the SecretID expires. Overrides secret_id_num_uses role option when supplied. May not be higher than role's secret_id_num_uses.
token_bound_cidrs	array	no	Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.
ttl	integer	no	Duration in seconds after which this SecretID expires. Overrides secret_id_ttl role option when supplied. May not be longer than role's secret_id_ttl.

Responses

200: OK

Parameter	Type	Required	Description
secret_id	string	no	Secret ID attached to the role.
secret_id_accessor	string	no	Accessor of the secret ID
secret_id_num_uses	integer	no	Number of times a secret ID can access the role, after which the secret ID will expire.
secret_id_ttl	integer	no	Duration in seconds after which the issued secret ID expires.

POST /auth/{approle_mount_path}/role/{role_name}/secret-id-accessor/destroy

Operation ID: app-role-destroy-secret-id-by-accessor

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
secret_id_accessor	string	no	Accessor of the SecretID

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/secret-id-accessor/destroy

Operation ID: app-role-destroy-secret-id-by-accessor2

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

POST /auth/{approle_mount_path}/role/{role_name}/secret-id-accessor/lookup

Operation ID: app-role-look-up-secret-id-by-accessor

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
secret_id_accessor	string	no	Accessor of the SecretID

Responses

200: OK

Parameter	Type	Required	Description
cidr_list	array	no	List of CIDR blocks enforcing secret IDs to be used from specific set of IP addresses. If 'bound_cidr_list' is set on the role, then the list of CIDR blocks listed here should be a subset of the CIDR blocks listed on the role.
creation_time	string	no
expiration_time	string	no
last_updated_time	string	no
metadata	object	no
secret_id_accessor	string	no	Accessor of the secret ID
secret_id_num_uses	integer	no	Number of times a secret ID can access the role, after which the secret ID will expire.
secret_id_ttl	integer	no	Duration in seconds after which the issued secret ID expires.
token_bound_cidrs	array	no	List of CIDR blocks. If set, specifies the blocks of IP addresses which can use the returned token. Should be a subset of the token CIDR blocks listed on the role, if any.

GET /auth/{approle_mount_path}/role/{role_name}/secret-id-bound-cidrs

Operation ID: app-role-read-secret-id-bound-cidrs

Comma separated list of CIDR blocks, if set, specifies blocks of IP addresses which can perform the login operation

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
secret_id_bound_cidrs	array	no	Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can perform the login operation.

POST /auth/{approle_mount_path}/role/{role_name}/secret-id-bound-cidrs

Operation ID: app-role-write-secret-id-bound-cidrs

Comma separated list of CIDR blocks, if set, specifies blocks of IP addresses which can perform the login operation

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
secret_id_bound_cidrs	array	no	Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can perform the login operation.

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/secret-id-bound-cidrs

Operation ID: app-role-delete-secret-id-bound-cidrs

Comma separated list of CIDR blocks, if set, specifies blocks of IP addresses which can perform the login operation

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/secret-id-num-uses

Operation ID: app-role-read-secret-id-num-uses

Use limit of the SecretID generated against the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
secret_id_num_uses	integer	no	Number of times a secret ID can access the role, after which the SecretID will expire. Defaults to 0 meaning that the secret ID is of unlimited use.

POST /auth/{approle_mount_path}/role/{role_name}/secret-id-num-uses

Operation ID: app-role-write-secret-id-num-uses

Use limit of the SecretID generated against the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
secret_id_num_uses	integer	no	Number of times a SecretID can access the role, after which the SecretID will expire.

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/secret-id-num-uses

Operation ID: app-role-delete-secret-id-num-uses

Use limit of the SecretID generated against the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/secret-id-ttl

Operation ID: app-role-read-secret-id-ttl

Duration in seconds of the SecretID generated against the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
secret_id_ttl	integer	no	Duration in seconds after which the issued secret ID should expire. Defaults to 0, meaning no expiration.

POST /auth/{approle_mount_path}/role/{role_name}/secret-id-ttl

Operation ID: app-role-write-secret-id-ttl

Duration in seconds of the SecretID generated against the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
secret_id_ttl	integer	no	Duration in seconds after which the issued SecretID should expire. Defaults to 0, meaning no expiration.

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/secret-id-ttl

Operation ID: app-role-delete-secret-id-ttl

Duration in seconds of the SecretID generated against the role.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

POST /auth/{approle_mount_path}/role/{role_name}/secret-id/destroy

Operation ID: app-role-destroy-secret-id

Invalidate an issued secret_id

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
secret_id	string	no	SecretID attached to the role.

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/secret-id/destroy

Operation ID: app-role-destroy-secret-id2

Invalidate an issued secret_id

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

POST /auth/{approle_mount_path}/role/{role_name}/secret-id/lookup

Operation ID: app-role-look-up-secret-id

Read the properties of an issued secret_id

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
secret_id	string	no	SecretID attached to the role.

Responses

200: OK

Parameter	Type	Required	Description
cidr_list	array	no	List of CIDR blocks enforcing secret IDs to be used from specific set of IP addresses. If 'bound_cidr_list' is set on the role, then the list of CIDR blocks listed here should be a subset of the CIDR blocks listed on the role.
creation_time	string	no
expiration_time	string	no
last_updated_time	string	no
metadata	object	no
secret_id_accessor	string	no	Accessor of the secret ID
secret_id_num_uses	integer	no	Number of times a secret ID can access the role, after which the secret ID will expire.
secret_id_ttl	integer	no	Duration in seconds after which the issued secret ID expires.
token_bound_cidrs	array	no	List of CIDR blocks. If set, specifies the blocks of IP addresses which can use the returned token. Should be a subset of the token CIDR blocks listed on the role, if any.

GET /auth/{approle_mount_path}/role/{role_name}/token-bound-cidrs

Operation ID: app-role-read-token-bound-cidrs

Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can use the returned token.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
token_bound_cidrs	array	no	Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can use the returned token. Should be a subset of the token CIDR blocks listed on the role, if any.

POST /auth/{approle_mount_path}/role/{role_name}/token-bound-cidrs

Operation ID: app-role-write-token-bound-cidrs

Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can use the returned token.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
token_bound_cidrs	array	no	Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/token-bound-cidrs

Operation ID: app-role-delete-token-bound-cidrs

Comma separated string or list of CIDR blocks. If set, specifies the blocks of IP addresses which can use the returned token.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/token-max-ttl

Operation ID: app-role-read-token-max-ttl

Duration in seconds, the maximum lifetime of the tokens issued by using the SecretIDs that were generated against this role, after which the tokens are not allowed to be renewed.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
token_max_ttl	integer	no	The maximum lifetime of the generated token

POST /auth/{approle_mount_path}/role/{role_name}/token-max-ttl

Operation ID: app-role-write-token-max-ttl

Duration in seconds, the maximum lifetime of the tokens issued by using the SecretIDs that were generated against this role, after which the tokens are not allowed to be renewed.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
token_max_ttl	integer	no	The maximum lifetime of the generated token

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/token-max-ttl

Operation ID: app-role-delete-token-max-ttl

Duration in seconds, the maximum lifetime of the tokens issued by using the SecretIDs that were generated against this role, after which the tokens are not allowed to be renewed.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/token-num-uses

Operation ID: app-role-read-token-num-uses

Number of times issued tokens can be used

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
token_num_uses	integer	no	The maximum number of times a token may be used, a value of zero means unlimited

POST /auth/{approle_mount_path}/role/{role_name}/token-num-uses

Operation ID: app-role-write-token-num-uses

Number of times issued tokens can be used

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
token_num_uses	integer	no	The maximum number of times a token may be used, a value of zero means unlimited

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/token-num-uses

Operation ID: app-role-delete-token-num-uses

Number of times issued tokens can be used

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /auth/{approle_mount_path}/role/{role_name}/token-ttl

Operation ID: app-role-read-token-ttl

Duration in seconds, the lifetime of the token issued by using the SecretID that is generated against this role, before which the token needs to be renewed.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
token_ttl	integer	no	The initial ttl of the token to generate

POST /auth/{approle_mount_path}/role/{role_name}/token-ttl

Operation ID: app-role-write-token-ttl

Duration in seconds, the lifetime of the token issued by using the SecretID that is generated against this role, before which the token needs to be renewed.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
token_ttl	integer	no	The initial ttl of the token to generate

Responses

204: No Content

DELETE /auth/{approle_mount_path}/role/{role_name}/token-ttl

Operation ID: app-role-delete-token-ttl

Duration in seconds, the lifetime of the token issued by using the SecretID that is generated against this role, before which the token needs to be renewed.

Parameters

Parameter	Type	Location	Required	Description
role_name	string	path	yes	Name of the role. Must be less than 4096 bytes.
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

POST /auth/{approle_mount_path}/tidy/secret-id

Operation ID: app-role-tidy-secret-id

Trigger the clean-up of expired SecretID entries.

Parameters

Parameter	Type	Location	Required	Description
approle_mount_path	string	path	yes	Path that the backend was mounted at

Responses

202: Accepted

GET /auth/{jwt_mount_path}/config

Operation ID: jwt-read-configuration

Read the current JWT authentication backend configuration.

Parameters

Parameter	Type	Location	Required	Description
jwt_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /auth/{jwt_mount_path}/config

Operation ID: jwt-configure

Configure the JWT authentication backend.

Parameters

Parameter	Type	Location	Required	Description
jwt_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bound_issuer	string	no	The value against which to match the 'iss' claim in a JWT. Optional.
default_role	string	no	The default role to use if none is provided during login. If not set, a role is required during login.
jwks_ca_pem	string	no	The CA certificate or chain of certificates, in PEM format, to use to validate connections to the JWKS URL. If not set, system certificates are used.
jwks_pairs	array	no	Set of JWKS Url and CA certificate (or chain of certificates) pairs. CA certificates must be in PEM format. Cannot be used with "jwks_url" or "jwks_ca_pem".
jwks_url	string	no	JWKS URL to use to authenticate signatures. Cannot be used with "oidc_discovery_url" or "jwt_validation_pubkeys".
jwt_supported_algs	array	no	A list of supported signing algorithms. Defaults to RS256.
jwt_validation_pubkeys	array	no	A list of PEM-encoded public keys to use to authenticate signatures locally. Cannot be used with "jwks_url" or "oidc_discovery_url".
namespace_in_state	boolean	no	Pass namespace in the OIDC state parameter instead of as a separate query parameter. With this setting, the allowed redirect URL(s) in Vault and on the provider side should not contain a namespace query parameter. This means only one redirect URL entry needs to be maintained on the provider side for all vault namespaces that will be authenticating against it. Defaults to true for new configs.
oidc_client_id	string	no	The OAuth Client ID configured with your OIDC provider.
oidc_client_secret	string	no	The OAuth Client Secret configured with your OIDC provider.
oidc_discovery_ca_pem	string	no	The CA certificate or chain of certificates, in PEM format, to use to validate connections to the OIDC Discovery URL. If not set, system certificates are used.
oidc_discovery_url	string	no	OIDC Discovery URL, without any .well-known component (base path). Cannot be used with "jwks_url" or "jwt_validation_pubkeys".
oidc_response_mode	string	no	The response mode to be used in the OAuth2 request. Allowed values are 'query' and 'form_post'.
oidc_response_types	array	no	The response types to request. Allowed values are 'code' and 'id_token'. Defaults to 'code'.
provider_config	object	no	Provider-specific configuration. Optional.
unsupported_critical_cert_extensions	array	no	A list of ASN1 OIDs of certificate extensions marked Critical that are unsupported by Vault and should be ignored. This option should very rarely be needed except in specialized PKI environments.

Responses

200: OK

POST /auth/{jwt_mount_path}/login

Operation ID: jwt-login

Authenticates to Vault using a JWT (or OIDC) token.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
jwt_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
distributed_claim_access_token	string	no	An optional token used to fetch group memberships specified by the distributed claim source in the jwt. This is supported only on Azure/Entra ID
jwt	string	no	The signed JWT to validate.
role	string	no	The role to log in against.

Responses

200: OK

POST /auth/{jwt_mount_path}/oidc/auth_url

Operation ID: jwt-oidc-request-authorization-url

Request an authorization URL to start an OIDC login flow.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
jwt_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
client_nonce	string	no	Optional client-provided nonce that must match during callback, if present.
redirect_uri	string	no	The OAuth redirect_uri to use in the authorization URL.
role	string	no	The role to issue an OIDC authorization URL against.

Responses

200: OK

GET /auth/{jwt_mount_path}/oidc/callback

Operation ID: jwt-oidc-callback

Callback endpoint to complete an OIDC login.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
client_nonce	string	query	no
code	string	query	no
state	string	query	no
jwt_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /auth/{jwt_mount_path}/oidc/callback

Operation ID: jwt-oidc-callback-form-post

Callback endpoint to handle form_posts.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
client_nonce	string	query	no
code	string	query	no
state	string	query	no
jwt_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
id_token	string	no

Responses

200: OK

GET /auth/{jwt_mount_path}/role

Operation ID: jwt-list-roles

Lists all the roles registered with the backend.

Parameters

Parameter	Type	Location	Required	Description
jwt_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /auth/{jwt_mount_path}/role/{name}

Operation ID: jwt-read-role

Read an existing role.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
jwt_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /auth/{jwt_mount_path}/role/{name}

Operation ID: jwt-write-role

Register an role with the backend.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
jwt_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
allowed_redirect_uris	array	no	Comma-separated list of allowed values for redirect_uri
bound_audiences	array	no	Comma-separated list of 'aud' claims that are valid for login. Any match is sufficient
bound_cidrs	array	no	⚠️ Deprecated. Use "token_bound_cidrs" instead. If this and "token_bound_cidrs" are both specified, only "token_bound_cidrs" will be used.
bound_claims	object	no	Map of claims/values which must match for login
bound_claims_type	string (default: string)	no	How to interpret values in the map of claims/values (which must match for login): allowed values are 'string' or 'glob'
bound_subject	string	no	The 'sub' claim that is valid for login. Optional.
claim_mappings	object	no	Mappings of claims (key) that will be copied to a metadata field (value)
clock_skew_leeway	integer (default: 60000000000)	no	Duration in seconds of leeway when validating all claims to account for clock skew. Defaults to 60 (1 minute) if set to 0 and can be disabled if set to -1.
expiration_leeway	integer (default: 150)	no	Duration in seconds of leeway when validating expiration of a token to account for clock skew. Defaults to 150 (2.5 minutes) if set to 0 and can be disabled if set to -1.
groups_claim	string	no	The claim to use for the Identity group alias names
max_age	integer	no	Specifies the allowable elapsed time in seconds since the last time the user was actively authenticated.
max_ttl	integer	no	⚠️ Deprecated. Use "token_max_ttl" instead. If this and "token_max_ttl" are both specified, only "token_max_ttl" will be used.
not_before_leeway	integer (default: 150)	no	Duration in seconds of leeway when validating not before values of a token to account for clock skew. Defaults to 150 (2.5 minutes) if set to 0 and can be disabled if set to -1.
num_uses	integer	no	⚠️ Deprecated. Use "token_num_uses" instead. If this and "token_num_uses" are both specified, only "token_num_uses" will be used.
oidc_scopes	array	no	Comma-separated list of OIDC scopes
period	integer	no	⚠️ Deprecated. Use "token_period" instead. If this and "token_period" are both specified, only "token_period" will be used.
policies	array	no	⚠️ Deprecated. Use "token_policies" instead. If this and "token_policies" are both specified, only "token_policies" will be used.
role_type	string	no	Type of the role, either 'jwt' or 'oidc'.
token_bound_cidrs	array	no	Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.
token_explicit_max_ttl	integer	no	If set, tokens created via this role carry an explicit maximum TTL. During renewal, the current maximum TTL values of the role and the mount are not checked for changes, and any updates to these values will have no effect on the token being renewed.
token_max_ttl	integer	no	The maximum lifetime of the generated token
token_no_default_policy	boolean	no	If true, the 'default' policy will not automatically be added to generated tokens
token_num_uses	integer	no	The maximum number of times a token may be used, a value of zero means unlimited
token_period	integer	no	If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").
token_policies	array	no	Comma-separated list of policies
token_ttl	integer	no	The initial ttl of the token to generate
token_type	string (default: default-service)	no	The type of token to generate, service or batch
ttl	integer	no	⚠️ Deprecated. Use "token_ttl" instead. If this and "token_ttl" are both specified, only "token_ttl" will be used.
user_claim	string	no	The claim to use for the Identity entity alias name
user_claim_json_pointer	boolean	no	If true, the user_claim value will use JSON pointer syntax for referencing claims.
verbose_oidc_logging	boolean	no	Log received OIDC tokens and claims when debug-level logging is active. Not recommended in production since sensitive information may be present in OIDC responses.

Responses

200: OK

DELETE /auth/{jwt_mount_path}/role/{name}

Operation ID: jwt-delete-role

Delete an existing role.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
jwt_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

GET /auth/{kubernetes_mount_path}/config

Operation ID: kubernetes-read-auth-configuration

Configures the JWT Public Key and Kubernetes API information.

Parameters

Parameter	Type	Location	Required	Description
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /auth/{kubernetes_mount_path}/config

Operation ID: kubernetes-configure-auth

Configures the JWT Public Key and Kubernetes API information.

Parameters

Parameter	Type	Location	Required	Description
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
disable_iss_validation	boolean (default: True)	no	⚠️ Deprecated. Disable JWT issuer validation (Deprecated, will be removed in a future release)
disable_local_ca_jwt	boolean (default: False)	no	Disable defaulting to the local CA cert and service account JWT when running in a Kubernetes pod
issuer	string	no	⚠️ Deprecated. Optional JWT issuer. If no issuer is specified, then this plugin will use kubernetes.io/serviceaccount as the default issuer. (Deprecated, will be removed in a future release)
kubernetes_ca_cert	string	no	Optional PEM encoded CA cert for use by the TLS client used to talk with the API. If it is not set and disable_local_ca_jwt is true, the system's trusted CA certificate pool will be used.
kubernetes_host	string	no	Host must be a host string, a host:port pair, or a URL to the base of the Kubernetes API server.
pem_keys	array	no	Optional list of PEM-formated public keys or certificates used to verify the signatures of kubernetes service account JWTs. If a certificate is given, its public key will be extracted. Not every installation of Kubernetes exposes these keys.
token_reviewer_jwt	string	no	A service account JWT (or other token) used as a bearer token to access the TokenReview API to validate other JWTs during login. If not set the JWT used for login will be used to access the API.
use_annotations_as_alias_metadata	boolean (default: False)	no	Use annotations from the client token's associated service account as alias metadata for the Vault entity. Only annotations with the prefix "vault.hashicorp.com/alias-metadata-" will be used. Note that Vault will need permission to read service accounts from the Kubernetes API.

Responses

200: OK

POST /auth/{kubernetes_mount_path}/login

Operation ID: kubernetes-login

Authenticates Kubernetes service accounts with Vault.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
jwt	string	no	A signed JWT for authenticating a service account. This field is required.
role	string	no	Name of the role against which the login is being attempted. This field is required

Responses

200: OK

GET /auth/{kubernetes_mount_path}/role

Operation ID: kubernetes-list-auth-roles

Lists all the roles registered with the backend.

Parameters

Parameter	Type	Location	Required	Description
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /auth/{kubernetes_mount_path}/role/{name}

Operation ID: kubernetes-read-auth-role

Register an role with the backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /auth/{kubernetes_mount_path}/role/{name}

Operation ID: kubernetes-write-auth-role

Register an role with the backend.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alias_name_source	string (default: serviceaccount_uid)	no	Source to use when deriving the Alias name. valid choices: "serviceaccount_uid" : e.g. 474b11b5-0f20-4f9d-8ca5-65715ab325e0 (most secure choice) "serviceaccount_name" : / e.g. vault/vault-agent default: "serviceaccount_uid"
audience	string	no	Optional Audience claim to verify in the jwt.
bound_cidrs	array	no	⚠️ Deprecated. Use "token_bound_cidrs" instead. If this and "token_bound_cidrs" are both specified, only "token_bound_cidrs" will be used.
bound_service_account_names	array	no	List of service account names able to access this role. If set to "*" all names are allowed.
bound_service_account_namespace_selector	string	no	A label selector for Kubernetes namespaces which are allowed to access this role. Accepts either a JSON or YAML object. If set with bound_service_account_namespaces, the conditions are ORed.
bound_service_account_namespaces	array	no	List of namespaces allowed to access this role. If set to "*" all namespaces are allowed.
max_ttl	integer	no	⚠️ Deprecated. Use "token_max_ttl" instead. If this and "token_max_ttl" are both specified, only "token_max_ttl" will be used.
num_uses	integer	no	⚠️ Deprecated. Use "token_num_uses" instead. If this and "token_num_uses" are both specified, only "token_num_uses" will be used.
period	integer	no	⚠️ Deprecated. Use "token_period" instead. If this and "token_period" are both specified, only "token_period" will be used.
policies	array	no	⚠️ Deprecated. Use "token_policies" instead. If this and "token_policies" are both specified, only "token_policies" will be used.
token_bound_cidrs	array	no	Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.
token_explicit_max_ttl	integer	no	If set, tokens created via this role carry an explicit maximum TTL. During renewal, the current maximum TTL values of the role and the mount are not checked for changes, and any updates to these values will have no effect on the token being renewed.
token_max_ttl	integer	no	The maximum lifetime of the generated token
token_no_default_policy	boolean	no	If true, the 'default' policy will not automatically be added to generated tokens
token_num_uses	integer	no	The maximum number of times a token may be used, a value of zero means unlimited
token_period	integer	no	If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").
token_policies	array	no	Comma-separated list of policies
token_ttl	integer	no	The initial ttl of the token to generate
token_type	string (default: default-service)	no	The type of token to generate, service or batch
ttl	integer	no	⚠️ Deprecated. Use "token_ttl" instead. If this and "token_ttl" are both specified, only "token_ttl" will be used.

Responses

200: OK

DELETE /auth/{kubernetes_mount_path}/role/{name}

Operation ID: kubernetes-delete-auth-role

Register an role with the backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

GET /auth/{ldap_mount_path}/config

Operation ID: ldap-read-auth-configuration

Configure the LDAP server to connect to, along with its options.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /auth/{ldap_mount_path}/config

Operation ID: ldap-configure-auth

Configure the LDAP server to connect to, along with its options.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
anonymous_group_search	boolean (default: False)	no	Use anonymous binds when performing LDAP group searches (if true the initial credentials will still be used for the initial connection test).
binddn	string	no	LDAP DN for searching for the user DN (optional)
bindpass	string	no	LDAP password for searching for the user DN (optional)
case_sensitive_names	boolean	no	If true, case sensitivity will be used when comparing usernames and groups for matching policies.
certificate	string	no	CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded (optional)
client_tls_cert	string	no	Client certificate to provide to the LDAP server, must be x509 PEM encoded (optional)
client_tls_key	string	no	Client certificate key to provide to the LDAP server, must be x509 PEM encoded (optional)
connection_timeout	integer (default: 30s)	no	Timeout, in seconds, when attempting to connect to the LDAP server before trying the next URL in the configuration.
deny_null_bind	boolean (default: True)	no	Denies an unauthenticated LDAP bind request if the user's password is empty; defaults to true
dereference_aliases	string (never, finding, searching, always) (default: never)	no	When aliases should be dereferenced on search operations. Accepted values are 'never', 'finding', 'searching', 'always'. Defaults to 'never'.
discoverdn	boolean	no	Use anonymous bind to discover the bind DN of a user (optional)
groupattr	string (default: cn)	no	LDAP attribute to follow on objects returned by in order to enumerate user group membership. Examples: "cn" or "memberOf", etc. Default: cn
groupdn	string	no	LDAP search base to use for group membership search (eg: ou=Groups,dc=example,dc=org)
groupfilter	string (default: (	(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}})))	no
insecure_tls	boolean	no	Skip LDAP server SSL Certificate verification - VERY insecure (optional)
max_page_size	integer (default: 0)	no	If set to a value greater than 0, the LDAP backend will use the LDAP server's paged search control to request pages of up to the given size. This can be used to avoid hitting the LDAP server's maximum result size limit. Otherwise, the LDAP backend will not use the paged search control.
request_timeout	integer (default: 90s)	no	Timeout, in seconds, for the connection when making requests against the server before returning back an error.
starttls	boolean	no	Issue a StartTLS command after establishing unencrypted connection (optional)
tls_max_version	string (tls10, tls11, tls12, tls13) (default: tls12)	no	Maximum TLS version to use. Accepted values are 'tls10', 'tls11', 'tls12' or 'tls13'. Defaults to 'tls12'
tls_min_version	string (tls10, tls11, tls12, tls13) (default: tls12)	no	Minimum TLS version to use. Accepted values are 'tls10', 'tls11', 'tls12' or 'tls13'. Defaults to 'tls12'
token_bound_cidrs	array	no	Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.
token_explicit_max_ttl	integer	no	If set, tokens created via this role carry an explicit maximum TTL. During renewal, the current maximum TTL values of the role and the mount are not checked for changes, and any updates to these values will have no effect on the token being renewed.
token_max_ttl	integer	no	The maximum lifetime of the generated token
token_no_default_policy	boolean	no	If true, the 'default' policy will not automatically be added to generated tokens
token_num_uses	integer	no	The maximum number of times a token may be used, a value of zero means unlimited
token_period	integer	no	If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").
token_policies	array	no	Comma-separated list of policies. This will apply to all tokens generated by this auth method, in addition to any configured for specific users/groups.
token_ttl	integer	no	The initial ttl of the token to generate
token_type	string (default: default-service)	no	The type of token to generate, service or batch
upndomain	string	no	Enables userPrincipalDomain login with [username]@UPNDomain (optional)
url	string (default: ldap://127.0.0.1)	no	LDAP URL to connect to (default: ldap://127.0.0.1). Multiple URLs can be specified by concatenating them with commas; they will be tried in-order.
use_pre111_group_cn_behavior	boolean	no	In Vault 1.1.1 a fix for handling group CN values of different cases unfortunately introduced a regression that could cause previously defined groups to not be found due to a change in the resulting name. If set true, the pre-1.1.1 behavior for matching group CNs will be used. This is only needed in some upgrade scenarios for backwards compatibility. It is enabled by default if the config is upgraded but disabled by default on new configurations.
use_token_groups	boolean (default: False)	no	If true, use the Active Directory tokenGroups constructed attribute of the user to find the group memberships. This will find all security groups including nested ones.
userattr	string (default: cn)	no	Attribute used for users (default: cn)
userdn	string	no	LDAP domain to use for users (eg: ou=People,dc=example,dc=org)
userfilter	string (default: ({{.UserAttr}}={{.Username}}))	no	Go template for LDAP user search filer (optional) The template can access the following context variables: UserAttr, Username Default: ({{.UserAttr}}={{.Username}})
username_as_alias	boolean (default: False)	no	If true, sets the alias name to the username

Responses

200: OK

GET /auth/{ldap_mount_path}/groups

Operation ID: ldap-list-groups

Manage additional groups for users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /auth/{ldap_mount_path}/groups/{name}

Operation ID: ldap-read-group

Manage additional groups for users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the LDAP group.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /auth/{ldap_mount_path}/groups/{name}

Operation ID: ldap-write-group

Manage additional groups for users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the LDAP group.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
policies	array	no	Comma-separated list of policies associated to the group.

Responses

200: OK

DELETE /auth/{ldap_mount_path}/groups/{name}

Operation ID: ldap-delete-group

Manage additional groups for users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the LDAP group.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /auth/{ldap_mount_path}/login/{username}

Operation ID: ldap-login

Log in with a username and password.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
username	string	path	yes	DN (distinguished name) to be used for login.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
password	string	no	Password for this user.

Responses

200: OK

GET /auth/{ldap_mount_path}/users

Operation ID: ldap-list-users

Manage users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /auth/{ldap_mount_path}/users/{name}

Operation ID: ldap-read-user

Manage users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the LDAP user.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /auth/{ldap_mount_path}/users/{name}

Operation ID: ldap-write-user

Manage users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the LDAP user.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
groups	array	no	Comma-separated list of additional groups associated with the user.
policies	array	no	Comma-separated list of policies associated with the user.

Responses

200: OK

DELETE /auth/{ldap_mount_path}/users/{name}

Operation ID: ldap-delete-user

Manage users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the LDAP user.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /auth/{userpass_mount_path}/login/{username}

Operation ID: userpass-login

Log in with a username and password.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
username	string	path	yes	Username of the user.
userpass_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
password	string	no	Password for this user.

Responses

200: OK

POST /auth/{userpass_mount_path}/password_policy/{policy_name}

Operation ID: userpass-update-policies_password

Parameters

Parameter	Type	Location	Required	Description
policy_name	string	path	yes	Policy password name for userpass.
userpass_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /auth/{userpass_mount_path}/users

Operation ID: userpass-list-users

Manage users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
userpass_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /auth/{userpass_mount_path}/users/{username}

Operation ID: userpass-read-user

Manage users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
username	string	path	yes	Username for this user.
userpass_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /auth/{userpass_mount_path}/users/{username}

Operation ID: userpass-write-user

Manage users allowed to authenticate.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
username	string	path	yes	Username for this user.
userpass_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bound_cidrs	array	no	⚠️ Deprecated. Use "token_bound_cidrs" instead. If this and "token_bound_cidrs" are both specified, only "token_bound_cidrs" will be used.
max_ttl	integer	no	⚠️ Deprecated. Use "token_max_ttl" instead. If this and "token_max_ttl" are both specified, only "token_max_ttl" will be used.
password	string	no	Password for this user.
policies	array	no	⚠️ Deprecated. Use "token_policies" instead. If this and "token_policies" are both specified, only "token_policies" will be used.
token_bound_cidrs	array	no	Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.
token_explicit_max_ttl	integer	no	If set, tokens created via this role carry an explicit maximum TTL. During renewal, the current maximum TTL values of the role and the mount are not checked for changes, and any updates to these values will have no effect on the token being renewed.
token_max_ttl	integer	no	The maximum lifetime of the generated token
token_no_default_policy	boolean	no	If true, the 'default' policy will not automatically be added to generated tokens
token_num_uses	integer	no	The maximum number of times a token may be used, a value of zero means unlimited
token_period	integer	no	If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").
token_policies	array	no	Comma-separated list of policies
token_ttl	integer	no	The initial ttl of the token to generate
token_type	string (default: default-service)	no	The type of token to generate, service or batch
ttl	integer	no	⚠️ Deprecated. Use "token_ttl" instead. If this and "token_ttl" are both specified, only "token_ttl" will be used.

Responses

200: OK

DELETE /auth/{userpass_mount_path}/users/{username}

Operation ID: userpass-delete-user

Manage users allowed to authenticate.

Parameters

Parameter	Type	Location	Required	Description
username	string	path	yes	Username for this user.
userpass_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /auth/{userpass_mount_path}/users/{username}/password

Operation ID: userpass-reset-password

Reset user's password.

Parameters

Parameter	Type	Location	Required	Description
username	string	path	yes	Username for this user.
userpass_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
password	string	no	Password for this user.

Responses

200: OK

POST /auth/{userpass_mount_path}/users/{username}/policies

Operation ID: userpass-update-policies

Update the policies associated with the username.

Parameters

Parameter	Type	Location	Required	Description
username	string	path	yes	Username for this user.
userpass_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
policies	array	no	⚠️ Deprecated. Use "token_policies" instead. If this and "token_policies" are both specified, only "token_policies" will be used.
token_policies	array	no	Comma-separated list of policies

Responses

200: OK

---

identity

POST /identity/alias

Operation ID: alias-create

Create a new alias.

Request body parameters

Parameter	Type	Required	Description
canonical_id	string	no	Entity ID to which this alias belongs to
entity_id	string	no	Entity ID to which this alias belongs to. This field is deprecated in favor of 'canonical_id'.
id	string	no	ID of the alias
mount_accessor	string	no	Mount accessor to which this alias belongs to
name	string	no	Name of the alias

Responses

200: OK

GET /identity/alias/id

Operation ID: alias-list-by-id

List all the alias IDs.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/alias/id/{id}

Operation ID: alias-read-by-id

Update, read or delete an alias ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the alias

Responses

200: OK

POST /identity/alias/id/{id}

Operation ID: alias-update-by-id

Update, read or delete an alias ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the alias

Request body parameters

Parameter	Type	Required	Description
canonical_id	string	no	Entity ID to which this alias should be tied to
entity_id	string	no	Entity ID to which this alias should be tied to. This field is deprecated in favor of 'canonical_id'.
mount_accessor	string	no	Mount accessor to which this alias belongs to
name	string	no	Name of the alias

Responses

200: OK

DELETE /identity/alias/id/{id}

Operation ID: alias-delete-by-id

Update, read or delete an alias ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the alias

Responses

204: empty body

POST /identity/entity

Operation ID: entity-create

Create a new entity

Request body parameters

Parameter	Type	Required	Description
disabled	boolean	no	If set true, tokens tied to this identity will not be able to be used (but will not be revoked).
id	string	no	ID of the entity. If set, updates the corresponding existing entity.
metadata	object	no	Metadata to be associated with the entity. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: stronghold metadata=key1=value1 metadata=key2=value2
name	string	no	Name of the entity
policies	array	no	Policies to be tied to the entity.

Responses

200: OK

POST /identity/entity-alias

Operation ID: entity-create-alias

Create a new alias.

Request body parameters

Parameter	Type	Required	Description
canonical_id	string	no	Entity ID to which this alias belongs
custom_metadata	object	no	User provided key-value pairs
entity_id	string	no	Entity ID to which this alias belongs. This field is deprecated, use canonical_id.
id	string	no	ID of the entity alias. If set, updates the corresponding entity alias.
mount_accessor	string	no	Mount accessor to which this alias belongs to; unused for a modify
name	string	no	Name of the alias; unused for a modify

Responses

200: OK

GET /identity/entity-alias/id

Operation ID: entity-list-aliases-by-id

List all the alias IDs.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/entity-alias/id/{id}

Operation ID: entity-read-alias-by-id

Update, read or delete an alias ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the alias

Responses

200: OK

POST /identity/entity-alias/id/{id}

Operation ID: entity-update-alias-by-id

Update, read or delete an alias ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the alias

Request body parameters

Parameter	Type	Required	Description
canonical_id	string	no	Entity ID to which this alias should be tied to
custom_metadata	object	no	User provided key-value pairs
entity_id	string	no	Entity ID to which this alias belongs to. This field is deprecated, use canonical_id.
mount_accessor	string	no	(Unused)
name	string	no	(Unused)

Responses

200: OK

DELETE /identity/entity-alias/id/{id}

Operation ID: entity-delete-alias-by-id

Update, read or delete an alias ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the alias

Responses

204: empty body

POST /identity/entity/batch-delete

Operation ID: entity-batch-delete

Delete all of the entities provided

Request body parameters

Parameter	Type	Required	Description
entity_ids	array	no	Entity IDs to delete

Responses

200: OK

GET /identity/entity/id

Operation ID: entity-list-by-id

List all the entity IDs

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/entity/id/{id}

Operation ID: entity-read-by-id

Update, read or delete an entity using entity ID

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the entity. If set, updates the corresponding existing entity.

Responses

200: OK

POST /identity/entity/id/{id}

Operation ID: entity-update-by-id

Update, read or delete an entity using entity ID

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the entity. If set, updates the corresponding existing entity.

Request body parameters

Parameter	Type	Required	Description
disabled	boolean	no	If set true, tokens tied to this identity will not be able to be used (but will not be revoked).
metadata	object	no	Metadata to be associated with the entity. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: stronghold metadata=key1=value1 metadata=key2=value2
name	string	no	Name of the entity
policies	array	no	Policies to be tied to the entity.

Responses

200: OK

DELETE /identity/entity/id/{id}

Operation ID: entity-delete-by-id

Update, read or delete an entity using entity ID

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the entity. If set, updates the corresponding existing entity.

Responses

204: empty body

POST /identity/entity/merge

Operation ID: entity-merge

Merge two or more entities together

Request body parameters

Parameter	Type	Required	Description
conflicting_alias_ids_to_keep	array	no	Alias IDs to keep in case of conflicting aliases. Ignored if no conflicting aliases found
force	boolean	no	Setting this will follow the 'mine' strategy for merging MFA secrets. If there are secrets of the same type both in entities that are merged from and in entity into which all others are getting merged, secrets in the destination will be unaltered. If not set, this API will throw an error containing all the conflicts.
from_entity_ids	array	no	Entity IDs which need to get merged
to_entity_id	string	no	Entity ID into which all the other entities need to get merged

Responses

200: OK

GET /identity/entity/name

Operation ID: entity-list-by-name

List all the entity names

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/entity/name/{name}

Operation ID: entity-read-by-name

Update, read or delete an entity using entity name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the entity

Responses

200: OK

POST /identity/entity/name/{name}

Operation ID: entity-update-by-name

Update, read or delete an entity using entity name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the entity

Request body parameters

Parameter	Type	Required	Description
disabled	boolean	no	If set true, tokens tied to this identity will not be able to be used (but will not be revoked).
id	string	no	ID of the entity. If set, updates the corresponding existing entity.
metadata	object	no	Metadata to be associated with the entity. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: stronghold metadata=key1=value1 metadata=key2=value2
policies	array	no	Policies to be tied to the entity.

Responses

200: OK

DELETE /identity/entity/name/{name}

Operation ID: entity-delete-by-name

Update, read or delete an entity using entity name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the entity

Responses

204: empty body

POST /identity/group

Operation ID: group-create

Create a new group.

Request body parameters

Parameter	Type	Required	Description
id	string	no	ID of the group. If set, updates the corresponding existing group.
member_entity_ids	array	no	Entity IDs to be assigned as group members.
member_group_ids	array	no	Group IDs to be assigned as group members.
metadata	object	no	Metadata to be associated with the group. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: stronghold metadata=key1=value1 metadata=key2=value2
name	string	no	Name of the group.
policies	array	no	Policies to be tied to the group.
type	string	no	Type of the group, 'internal' or 'external'. Defaults to 'internal'

Responses

200: OK

POST /identity/group-alias

Operation ID: group-create-alias

Creates a new group alias, or updates an existing one.

Request body parameters

Parameter	Type	Required	Description
canonical_id	string	no	ID of the group to which this is an alias.
id	string	no	ID of the group alias.
mount_accessor	string	no	Mount accessor to which this alias belongs to.
name	string	no	Alias of the group.

Responses

200: OK

GET /identity/group-alias/id

Operation ID: group-list-aliases-by-id

List all the group alias IDs.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/group-alias/id/{id}

Operation ID: group-read-alias-by-id

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the group alias.

Responses

200: OK

POST /identity/group-alias/id/{id}

Operation ID: group-update-alias-by-id

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the group alias.

Request body parameters

Parameter	Type	Required	Description
canonical_id	string	no	ID of the group to which this is an alias.
mount_accessor	string	no	Mount accessor to which this alias belongs to.
name	string	no	Alias of the group.

Responses

200: OK

DELETE /identity/group-alias/id/{id}

Operation ID: group-delete-alias-by-id

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the group alias.

Responses

204: empty body

GET /identity/group/id

Operation ID: group-list-by-id

List all the group IDs.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/group/id/{id}

Operation ID: group-read-by-id

Update or delete an existing group using its ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the group. If set, updates the corresponding existing group.

Responses

200: OK

POST /identity/group/id/{id}

Operation ID: group-update-by-id

Update or delete an existing group using its ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the group. If set, updates the corresponding existing group.

Request body parameters

Parameter	Type	Required	Description
member_entity_ids	array	no	Entity IDs to be assigned as group members.
member_group_ids	array	no	Group IDs to be assigned as group members.
metadata	object	no	Metadata to be associated with the group. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: stronghold metadata=key1=value1 metadata=key2=value2
name	string	no	Name of the group.
policies	array	no	Policies to be tied to the group.
type	string	no	Type of the group, 'internal' or 'external'. Defaults to 'internal'

Responses

200: OK

DELETE /identity/group/id/{id}

Operation ID: group-delete-by-id

Update or delete an existing group using its ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the group. If set, updates the corresponding existing group.

Responses

204: empty body

GET /identity/group/name

Operation ID: group-list-by-name

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/group/name/{name}

Operation ID: group-read-by-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the group.

Responses

200: OK

POST /identity/group/name/{name}

Operation ID: group-update-by-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the group.

Request body parameters

Parameter	Type	Required	Description
id	string	no	ID of the group. If set, updates the corresponding existing group.
member_entity_ids	array	no	Entity IDs to be assigned as group members.
member_group_ids	array	no	Group IDs to be assigned as group members.
metadata	object	no	Metadata to be associated with the group. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: stronghold metadata=key1=value1 metadata=key2=value2
policies	array	no	Policies to be tied to the group.
type	string	no	Type of the group, 'internal' or 'external'. Defaults to 'internal'

Responses

200: OK

DELETE /identity/group/name/{name}

Operation ID: group-delete-by-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the group.

Responses

204: empty body

POST /identity/lookup/entity

Operation ID: entity-look-up

Query entities based on various properties.

Request body parameters

Parameter	Type	Required	Description
alias_id	string	no	ID of the alias.
alias_mount_accessor	string	no	Accessor of the mount to which the alias belongs to. This should be supplied in conjunction with 'alias_name'.
alias_name	string	no	Name of the alias. This should be supplied in conjunction with 'alias_mount_accessor'.
id	string	no	ID of the entity.
name	string	no	Name of the entity.

Responses

200: OK

POST /identity/lookup/group

Operation ID: group-look-up

Query groups based on various properties.

Request body parameters

Parameter	Type	Required	Description
alias_id	string	no	ID of the alias.
alias_mount_accessor	string	no	Accessor of the mount to which the alias belongs to. This should be supplied in conjunction with 'alias_name'.
alias_name	string	no	Name of the alias. This should be supplied in conjunction with 'alias_mount_accessor'.
id	string	no	ID of the group.
name	string	no	Name of the group.

Responses

200: OK

GET /identity/mfa/login-enforcement

Operation ID: mfa-list-login-enforcements

List login enforcements

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/mfa/login-enforcement/{name}

Operation ID: mfa-read-login-enforcement

Read the current login enforcement

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name for this login enforcement configuration

Responses

200: OK

POST /identity/mfa/login-enforcement/{name}

Operation ID: mfa-write-login-enforcement

Create or update a login enforcement

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name for this login enforcement configuration

Request body parameters

Parameter	Type	Required	Description
auth_method_accessors	array	no	Array of auth mount accessor IDs
auth_method_types	array	no	Array of auth mount types
identity_entity_ids	array	no	Array of identity entity IDs
identity_group_ids	array	no	Array of identity group IDs
mfa_method_ids	array	yes	Array of Method IDs that determine what methods will be enforced

Responses

200: OK

DELETE /identity/mfa/login-enforcement/{name}

Operation ID: mfa-delete-login-enforcement

Delete a login enforcement

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name for this login enforcement configuration

Responses

204: empty body

GET /identity/mfa/method

Operation ID: mfa-list-methods

List MFA method configurations for all MFA methods

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/mfa/method/duo

Operation ID: mfa-list-duo-methods

List MFA method configurations for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/mfa/method/duo/{method_id}

Operation ID: mfa-read-duo-method-configuration

Read the current configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Responses

200: OK

POST /identity/mfa/method/duo/{method_id}

Operation ID: mfa-configure-duo-method

Update or create a configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Request body parameters

Parameter	Type	Required	Description
api_hostname	string	no	API host name for Duo.
integration_key	string	no	Integration key for Duo.
method_name	string	no	The unique name identifier for this MFA method.
push_info	string	no	Push information for Duo.
secret_key	string	no	Secret key for Duo.
use_passcode	boolean	no	If true, the user is reminded to use the passcode upon MFA validation. This option does not enforce using the passcode. Defaults to false.
username_format	string	no	A template string for mapping Identity names to MFA method names. Values to subtitute should be placed in {{}}. For example, "{{alias.name}}@example.com". Currently-supported mappings: alias.name: The name returned by the mount configured via the mount_accessor parameter If blank, the Alias's name field will be used as-is.

Responses

200: OK

DELETE /identity/mfa/method/duo/{method_id}

Operation ID: mfa-delete-duo-method

Delete a configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Responses

204: empty body

GET /identity/mfa/method/okta

Operation ID: mfa-list-okta-methods

List MFA method configurations for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/mfa/method/okta/{method_id}

Operation ID: mfa-read-okta-method-configuration

Read the current configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Responses

200: OK

POST /identity/mfa/method/okta/{method_id}

Operation ID: mfa-configure-okta-method

Update or create a configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Request body parameters

Parameter	Type	Required	Description
api_token	string	no	Okta API key.
base_url	string	no	The base domain to use for the Okta API. When not specified in the configuration, "okta.com" is used.
method_name	string	no	The unique name identifier for this MFA method.
org_name	string	no	Name of the organization to be used in the Okta API.
primary_email	boolean	no	If true, the username will only match the primary email for the account. Defaults to false.
production	boolean	no	(DEPRECATED) Use base_url instead.
username_format	string	no	A template string for mapping Identity names to MFA method names. Values to substitute should be placed in {{}}. For example, "{{entity.name}}@example.com". If blank, the Entity's name field will be used as-is.

Responses

200: OK

DELETE /identity/mfa/method/okta/{method_id}

Operation ID: mfa-delete-okta-method

Delete a configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Responses

204: empty body

GET /identity/mfa/method/pingid

Operation ID: mfa-list-ping-id-methods

List MFA method configurations for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/mfa/method/pingid/{method_id}

Operation ID: mfa-read-ping-id-method-configuration

Read the current configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Responses

200: OK

POST /identity/mfa/method/pingid/{method_id}

Operation ID: mfa-configure-ping-id-method

Update or create a configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Request body parameters

Parameter	Type	Required	Description
method_name	string	no	The unique name identifier for this MFA method.
settings_file_base64	string	no	The settings file provided by Ping, Base64-encoded. This must be a settings file suitable for third-party clients, not the PingID SDK or PingFederate.
username_format	string	no	A template string for mapping Identity names to MFA method names. Values to subtitute should be placed in {{}}. For example, "{{alias.name}}@example.com". Currently-supported mappings: alias.name: The name returned by the mount configured via the mount_accessor parameter If blank, the Alias's name field will be used as-is.

Responses

200: OK

DELETE /identity/mfa/method/pingid/{method_id}

Operation ID: mfa-delete-ping-id-method

Delete a configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Responses

204: empty body

GET /identity/mfa/method/totp

Operation ID: mfa-list-totp-methods

List MFA method configurations for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

POST /identity/mfa/method/totp/admin-destroy

Operation ID: mfa-admin-destroy-totp-secret

Destroys a TOTP secret for the given MFA method ID on the given entity

Request body parameters

Parameter	Type	Required	Description
entity_id	string	yes	Identifier of the entity from which the MFA method secret needs to be removed.
method_id	string	yes	The unique identifier for this MFA method.

Responses

200: OK

POST /identity/mfa/method/totp/admin-generate

Operation ID: mfa-admin-generate-totp-secret

Update or create TOTP secret for the given method ID on the given entity.

Request body parameters

Parameter	Type	Required	Description
entity_id	string	yes	Entity ID on which the generated secret needs to get stored.
method_id	string	yes	The unique identifier for this MFA method.

Responses

200: OK

POST /identity/mfa/method/totp/generate

Operation ID: mfa-generate-totp-secret

Update or create TOTP secret for the given method ID on the given entity.

Request body parameters

Parameter	Type	Required	Description
method_id	string	yes	The unique identifier for this MFA method.

Responses

200: OK

GET /identity/mfa/method/totp/{method_id}

Operation ID: mfa-read-totp-method-configuration

Read the current configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Responses

200: OK

POST /identity/mfa/method/totp/{method_id}

Operation ID: mfa-configure-totp-method

Update or create a configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: SHA1)	no	The hashing algorithm used to generate the TOTP token. Options include SHA1, SHA256 and SHA512.
digits	integer (default: 6)	no	The number of digits in the generated TOTP token. This value can either be 6 or 8.
issuer	string	no	The name of the key's issuing organization.
key_size	integer (default: 20)	no	Determines the size in bytes of the generated key.
max_validation_attempts	integer	no	Max number of allowed validation attempts.
method_name	string	no	The unique name identifier for this MFA method.
period	integer (default: 30)	no	The length of time used to generate a counter for the TOTP token calculation.
qr_size	integer (default: 200)	no	The pixel size of the generated square QR code.
skew	integer (default: 1)	no	The number of delay periods that are allowed when validating a TOTP token. This value can either be 0 or 1.

Responses

200: OK

DELETE /identity/mfa/method/totp/{method_id}

Operation ID: mfa-delete-totp-method

Delete a configuration for the given MFA method

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Responses

204: empty body

GET /identity/mfa/method/{method_id}

Operation ID: mfa-read-method-configuration

Read the current configuration for the given ID regardless of the MFA method type

Parameters

Parameter	Type	Location	Required	Description
method_id	string	path	yes	The unique identifier for this MFA method.

Responses

200: OK

GET /identity/oidc/.well-known/keys

Operation ID: oidc-read-public-keys

Retrieve public keys

Available without authentication: yes

Responses

200: OK

GET /identity/oidc/.well-known/openid-configuration

Operation ID: oidc-read-open-id-configuration

Query OIDC configurations

Available without authentication: yes

Responses

200: OK

GET /identity/oidc/assignment

Operation ID: oidc-list-assignments

List OIDC assignments

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/oidc/assignment/{name}

Operation ID: oidc-read-assignment

CRUD operations for OIDC assignments.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the assignment

Responses

200: OK

POST /identity/oidc/assignment/{name}

Operation ID: oidc-write-assignment

CRUD operations for OIDC assignments.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the assignment

Request body parameters

Parameter	Type	Required	Description
entity_ids	array	no	Comma separated string or array of identity entity IDs
group_ids	array	no	Comma separated string or array of identity group IDs

Responses

200: OK

DELETE /identity/oidc/assignment/{name}

Operation ID: oidc-delete-assignment

CRUD operations for OIDC assignments.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the assignment

Responses

204: empty body

GET /identity/oidc/client

Operation ID: oidc-list-clients

List OIDC clients

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/oidc/client/{name}

Operation ID: oidc-read-client

CRUD operations for OIDC clients.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the client.

Responses

200: OK

POST /identity/oidc/client/{name}

Operation ID: oidc-write-client

CRUD operations for OIDC clients.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the client.

Request body parameters

Parameter	Type	Required	Description
access_token_ttl	integer (default: 24h)	no	The time-to-live for access tokens obtained by the client.
assignments	array	no	Comma separated string or array of assignment resources.
client_type	string (default: confidential)	no	The client type based on its ability to maintain confidentiality of credentials. The following client types are supported: 'confidential', 'public'. Defaults to 'confidential'.
id_token_ttl	integer (default: 24h)	no	The time-to-live for ID tokens obtained by the client.
key	string (default: default)	no	A reference to a named key resource. Cannot be modified after creation. Defaults to the 'default' key.
redirect_uris	array	no	Comma separated string or array of redirect URIs used by the client. One of these values must exactly match the redirect_uri parameter value used in each authentication request.

Responses

200: OK

DELETE /identity/oidc/client/{name}

Operation ID: oidc-delete-client

CRUD operations for OIDC clients.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the client.

Responses

204: empty body

GET /identity/oidc/config

Operation ID: oidc-read-configuration

OIDC configuration

Responses

200: OK

POST /identity/oidc/config

Operation ID: oidc-configure

OIDC configuration

Request body parameters

Parameter	Type	Required	Description
issuer	string	no	Issuer URL to be used in the iss claim of the token. If not set, app_addr will be used.

Responses

200: OK

POST /identity/oidc/introspect

Operation ID: oidc-introspect

Verify the authenticity of an OIDC token

Request body parameters

Parameter	Type	Required	Description
client_id	string	no	Optional client_id to verify
token	string	no	Token to verify

Responses

200: OK

GET /identity/oidc/key

Operation ID: oidc-list-keys

List OIDC keys

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/oidc/key/{name}

Operation ID: oidc-read-key

CRUD operations for OIDC keys.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key

Responses

200: OK

POST /identity/oidc/key/{name}

Operation ID: oidc-write-key

CRUD operations for OIDC keys.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: RS256)	no	Signing algorithm to use. This will default to RS256.
allowed_client_ids	array	no	Comma separated string or array of role client ids allowed to use this key for signing. If empty no roles are allowed. If "*" all roles are allowed.
rotation_period	integer (default: 24h)	no	How often to generate a new keypair.
verification_ttl	integer (default: 24h)	no	Controls how long the public portion of a key will be available for verification after being rotated.

Responses

200: OK

DELETE /identity/oidc/key/{name}

Operation ID: oidc-delete-key

CRUD operations for OIDC keys.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key

Responses

204: empty body

POST /identity/oidc/key/{name}/rotate

Operation ID: oidc-rotate-key

Rotate a named OIDC key.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key

Request body parameters

Parameter	Type	Required	Description
verification_ttl	integer	no	Controls how long the public portion of a key will be available for verification after being rotated. Setting verification_ttl here will override the verification_ttl set on the key.

Responses

200: OK

GET /identity/oidc/provider

Operation ID: oidc-list-providers

List OIDC providers

Parameters

Parameter	Type	Location	Required	Description
allowed_client_id	string	query	no	Filters the list of OIDC providers to those that allow the given client ID in their set of allowed_client_ids.
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/oidc/provider/{name}

Operation ID: oidc-read-provider

CRUD operations for OIDC providers.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Responses

200: OK

POST /identity/oidc/provider/{name}

Operation ID: oidc-write-provider

CRUD operations for OIDC providers.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Request body parameters

Parameter	Type	Required	Description
allowed_client_ids	array	no	The client IDs that are permitted to use the provider
issuer	string	no	Specifies what will be used for the iss claim of ID tokens.
scopes_supported	array	no	The scopes supported for requesting on the provider

Responses

200: OK

DELETE /identity/oidc/provider/{name}

Operation ID: oidc-delete-provider

CRUD operations for OIDC providers.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Responses

204: empty body

GET /identity/oidc/provider/{name}/.well-known/keys

Operation ID: oidc-read-provider-public-keys

Retrieve public keys

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Responses

200: OK

GET /identity/oidc/provider/{name}/.well-known/openid-configuration

Operation ID: oidc-read-provider-open-id-configuration

Query OIDC configurations

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Responses

200: OK

GET /identity/oidc/provider/{name}/authorize

Operation ID: oidc-provider-authorize

Provides the OIDC Authorization Endpoint.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Responses

200: OK

POST /identity/oidc/provider/{name}/authorize

Operation ID: oidc-provider-authorize-with-parameters

Provides the OIDC Authorization Endpoint.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Request body parameters

Parameter	Type	Required	Description
client_id	string	yes	The ID of the requesting client.
code_challenge	string	no	The code challenge derived from the code verifier.
code_challenge_method	string (default: plain)	no	The method that was used to derive the code challenge. The following methods are supported: 'S256', 'plain'. Defaults to 'plain'.
max_age	integer	no	The allowable elapsed time in seconds since the last time the end-user was actively authenticated.
nonce	string	no	The value that will be returned in the ID token nonce claim after a token exchange.
redirect_uri	string	yes	The redirection URI to which the response will be sent.
response_type	string	yes	The OIDC authentication flow to be used. The following response types are supported: 'code'
scope	string	yes	A space-delimited, case-sensitive list of scopes to be requested. The 'openid' scope is required.
state	string	no	The value used to maintain state between the authentication request and client.

Responses

200: OK

POST /identity/oidc/provider/{name}/token

Operation ID: oidc-provider-token

Provides the OIDC Token Endpoint.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Request body parameters

Parameter	Type	Required	Description
client_id	string	no	The ID of the requesting client.
client_secret	string	no	The secret of the requesting client.
code	string	yes	The authorization code received from the provider's authorization endpoint.
code_verifier	string	no	The code verifier associated with the authorization code.
grant_type	string	yes	The authorization grant type. The following grant types are supported: 'authorization_code'.
redirect_uri	string	yes	The callback location where the authentication response was sent.

Responses

200: OK

GET /identity/oidc/provider/{name}/userinfo

Operation ID: oidc-provider-user-info

Provides the OIDC UserInfo Endpoint.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Responses

200: OK

POST /identity/oidc/provider/{name}/userinfo

Operation ID: oidc-provider-user-info2

Provides the OIDC UserInfo Endpoint.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the provider

Responses

200: OK

GET /identity/oidc/role

Operation ID: oidc-list-roles

List configured OIDC roles

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/oidc/role/{name}

Operation ID: oidc-read-role

CRUD operations on OIDC Roles

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role

Responses

200: OK

POST /identity/oidc/role/{name}

Operation ID: oidc-write-role

CRUD operations on OIDC Roles

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role

Request body parameters

Parameter	Type	Required	Description
client_id	string	no	Optional client_id
key	string	yes	The OIDC key to use for generating tokens. The specified key must already exist.
template	string	no	The template string to use for generating tokens. This may be in string-ified JSON or base64 format.
ttl	integer (default: 24h)	no	TTL of the tokens generated against the role.

Responses

200: OK

DELETE /identity/oidc/role/{name}

Operation ID: oidc-delete-role

CRUD operations on OIDC Roles

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role

Responses

204: empty body

GET /identity/oidc/scope

Operation ID: oidc-list-scopes

List OIDC scopes

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/oidc/scope/{name}

Operation ID: oidc-read-scope

CRUD operations for OIDC scopes.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the scope

Responses

200: OK

POST /identity/oidc/scope/{name}

Operation ID: oidc-write-scope

CRUD operations for OIDC scopes.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the scope

Request body parameters

Parameter	Type	Required	Description
description	string	no	The description of the scope
template	string	no	The template string to use for the scope. This may be in string-ified JSON or base64 format.

Responses

200: OK

DELETE /identity/oidc/scope/{name}

Operation ID: oidc-delete-scope

CRUD operations for OIDC scopes.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the scope

Responses

204: empty body

GET /identity/oidc/token/{name}

Operation ID: oidc-generate-token

Generate an OIDC token

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role

Responses

200: OK

POST /identity/persona

Operation ID: persona-create

Create a new alias.

Request body parameters

Parameter	Type	Required	Description
entity_id	string	no	Entity ID to which this persona belongs to
id	string	no	ID of the persona
metadata	object	no	Metadata to be associated with the persona. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: stronghold metadata=key1=value1 metadata=key2=value2
mount_accessor	string	no	Mount accessor to which this persona belongs to
name	string	no	Name of the persona

Responses

200: OK

GET /identity/persona/id

Operation ID: persona-list-by-id

List all the alias IDs.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /identity/persona/id/{id}

Operation ID: persona-read-by-id

Update, read or delete an alias ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the persona

Responses

200: OK

POST /identity/persona/id/{id}

Operation ID: persona-update-by-id

Update, read or delete an alias ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the persona

Request body parameters

Parameter	Type	Required	Description
entity_id	string	no	Entity ID to which this persona should be tied to
metadata	object	no	Metadata to be associated with the persona. In CLI, this parameter can be repeated multiple times, and it all gets merged together. For example: stronghold metadata=key1=value1 metadata=key2=value2
mount_accessor	string	no	Mount accessor to which this persona belongs to
name	string	no	Name of the persona

Responses

200: OK

DELETE /identity/persona/id/{id}

Operation ID: persona-delete-by-id

Update, read or delete an alias ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	yes	ID of the persona

Responses

204: empty body

---

secrets

GET /cubbyhole/{path}

Operation ID: cubbyhole-read

Retrieve the secret at the specified location.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Specifies the path of the secret.
list	string	query	no	Return a list if true

Responses

200: OK

POST /cubbyhole/{path}

Operation ID: cubbyhole-write

Store a secret at the specified location.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Specifies the path of the secret.

Responses

200: OK

DELETE /cubbyhole/{path}

Operation ID: cubbyhole-delete

Deletes the secret at the specified location.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Specifies the path of the secret.

Responses

204: empty body

GET /{database_mount_path}/config

Operation ID: database-list-connections

Configure connection details to a database plugin.

Parameters

Parameter	Type	Location	Required	Description
database_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{database_mount_path}/config/{name}

Operation ID: database-read-connection-configuration

Configure connection details to a database plugin.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of this database connection
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{database_mount_path}/config/{name}

Operation ID: database-configure-connection

Configure connection details to a database plugin.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of this database connection
database_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
allowed_roles	array	no	Comma separated string or array of the role names allowed to get creds from this database connection. If empty no roles are allowed. If "*" all roles are allowed.
password_policy	string	no	Password policy to use when generating passwords.
plugin_name	string	no	The name of a builtin or previously registered plugin known to vault. This endpoint will create an instance of that plugin type.
plugin_version	string	no	The version of the plugin to use.
root_rotation_statements	array	no	Specifies the database statements to be executed to rotate the root user's credentials. See the plugin's API page for more information on support and formatting for this parameter.
verify_connection	boolean (default: True)	no	If true, the connection details are verified by actually connecting to the database. Defaults to true.

Responses

200: OK

DELETE /{database_mount_path}/config/{name}

Operation ID: database-delete-connection-configuration

Configure connection details to a database plugin.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of this database connection
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

GET /{database_mount_path}/creds/{name}

Operation ID: database-generate-credentials

Request database credentials for a certain role.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{database_mount_path}/reset/{name}

Operation ID: database-reset-connection

Resets a database plugin.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of this database connection
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{database_mount_path}/roles

Operation ID: database-list-roles

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
database_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{database_mount_path}/roles/{name}

Operation ID: database-read-role

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{database_mount_path}/roles/{name}

Operation ID: database-write-role

Manage the roles that can be created with this backend.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
database_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
creation_statements	array	no	Specifies the database statements executed to create and configure a user. See the plugin's API page for more information on support and formatting for this parameter.
credential_config	object	no	The configuration for the given credential_type.
credential_type	string (default: password)	no	The type of credential to manage. Options include: 'password', 'rsa_private_key'. Defaults to 'password'.
db_name	string	no	Name of the database this role acts on.
default_ttl	integer	no	Default ttl for role.
max_ttl	integer	no	Maximum time a credential is valid for
renew_statements	array	no	Specifies the database statements to be executed to renew a user. Not every plugin type will support this functionality. See the plugin's API page for more information on support and formatting for this parameter.
revocation_statements	array	no	Specifies the database statements to be executed to revoke a user. See the plugin's API page for more information on support and formatting for this parameter.
rollback_statements	array	no	Specifies the database statements to be executed rollback a create operation in the event of an error. Not every plugin type will support this functionality. See the plugin's API page for more information on support and formatting for this parameter.

Responses

200: OK

DELETE /{database_mount_path}/roles/{name}

Operation ID: database-delete-role

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{database_mount_path}/rotate-role/{name}

Operation ID: database-rotate-static-role-credentials

Request to rotate the credentials for a static user account.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the static role
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{database_mount_path}/rotate-root/{name}

Operation ID: database-rotate-root-credentials

Request to rotate the root credentials for a certain database connection.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of this database connection
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{database_mount_path}/static-creds/{name}

Operation ID: database-read-static-role-credentials

Request database credentials for a certain static role. These credentials are rotated periodically.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the static role.
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{database_mount_path}/static-roles

Operation ID: database-list-static-roles

Manage the static roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
database_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{database_mount_path}/static-roles/{name}

Operation ID: database-read-static-role

Manage the static roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{database_mount_path}/static-roles/{name}

Operation ID: database-write-static-role

Manage the static roles that can be created with this backend.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
database_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
credential_config	object	no	The configuration for the given credential_type.
credential_type	string (default: password)	no	The type of credential to manage. Options include: 'password', 'rsa_private_key'. Defaults to 'password'.
db_name	string	no	Name of the database this role acts on.
rotation_period	integer	no	Period for automatic credential rotation of the given username. Not valid unless used with "username".
rotation_statements	array	no	Specifies the database statements to be executed to rotate the accounts credentials. Not every plugin type will support this functionality. See the plugin's API page for more information on support and formatting for this parameter.
username	string	no	Name of the static user account for Vault to manage. Requires "rotation_period" to be specified

Responses

200: OK

DELETE /{database_mount_path}/static-roles/{name}

Operation ID: database-delete-static-role

Manage the static roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
database_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

GET /{kubernetes_mount_path}/check

Operation ID: kubernetes-check-configuration

Checks the Kubernetes configuration is valid.

Parameters

Parameter	Type	Location	Required	Description
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{kubernetes_mount_path}/config

Operation ID: kubernetes-read-configuration

Configure the Kubernetes secret engine plugin.

Parameters

Parameter	Type	Location	Required	Description
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{kubernetes_mount_path}/config

Operation ID: kubernetes-configure

Configure the Kubernetes secret engine plugin.

Parameters

Parameter	Type	Location	Required	Description
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
disable_local_ca_jwt	boolean (default: False)	no	Disable defaulting to the local CA certificate and service account JWT when running in a Kubernetes pod.
kubernetes_ca_cert	string	no	PEM encoded CA certificate to use to verify the Kubernetes API server certificate. Defaults to the local pod's CA if found.
kubernetes_host	string	no	Kubernetes API URL to connect to. Defaults to https://$KUBERNETES_SERVICE_HOST:KUBERNETES_SERVICE_PORT if those environment variables are set.
service_account_jwt	string	no	The JSON web token of the service account used by the secret engine to manage Kubernetes credentials. Defaults to the local pod's JWT if found.

Responses

200: OK

DELETE /{kubernetes_mount_path}/config

Operation ID: kubernetes-delete-configuration

Configure the Kubernetes secret engine plugin.

Parameters

Parameter	Type	Location	Required	Description
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{kubernetes_mount_path}/creds/{name}

Operation ID: kubernetes-generate-credentials

Request Kubernetes service account credentials for a given Vault role.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the Vault role
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
audiences	array	no	The intended audiences of the generated credentials
cluster_role_binding	boolean	no	If true, generate a ClusterRoleBinding to grant permissions across the whole cluster instead of within a namespace. Requires the Vault role to have kubernetes_role_type set to ClusterRole.
kubernetes_namespace	string	yes	The name of the Kubernetes namespace in which to generate the credentials
ttl	integer	no	The TTL of the generated credentials

Responses

200: OK

GET /{kubernetes_mount_path}/roles

Operation ID: kubernetes-list-roles

List the existing roles in this secrets engine.

Parameters

Parameter	Type	Location	Required	Description
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{kubernetes_mount_path}/roles/{name}

Operation ID: kubernetes-read-role

Manage the roles that can be created with this secrets engine.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{kubernetes_mount_path}/roles/{name}

Operation ID: kubernetes-write-role

Manage the roles that can be created with this secrets engine.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
allowed_kubernetes_namespace_selector	string	no	A label selector for Kubernetes namespaces in which credentials can be generated. Accepts either a JSON or YAML object. If set with allowed_kubernetes_namespaces, the conditions are conjuncted.
allowed_kubernetes_namespaces	array	no	A list of the Kubernetes namespaces in which credentials can be generated. If set to "*" all namespaces are allowed.
extra_annotations	object	no	Additional annotations to apply to all generated Kubernetes objects.
extra_labels	object	no	Additional labels to apply to all generated Kubernetes objects.
generated_role_rules	string	no	The Role or ClusterRole rules to use when generating a role. Accepts either a JSON or YAML object. If set, the entire chain of Kubernetes objects will be generated.
kubernetes_role_name	string	no	The pre-existing Role or ClusterRole to bind a generated service account to. If set, Kubernetes token, service account, and role binding objects will be created.
kubernetes_role_type	string (default: Role)	no	Specifies whether the Kubernetes role is a Role or ClusterRole.
name_template	string	no	The name template to use when generating service accounts, roles and role bindings. If unset, a default template is used.
service_account_name	string	no	The pre-existing service account to generate tokens for. Mutually exclusive with all role parameters. If set, only a Kubernetes service account token will be created.
token_default_audiences	array	no	The default audiences for generated Kubernetes service account tokens. If not set or set to "", will use k8s cluster default.
token_default_ttl	integer	no	The default ttl for generated Kubernetes service account tokens. If not set or set to 0, will use system default.
token_max_ttl	integer	no	The maximum ttl for generated Kubernetes service account tokens. If not set or set to 0, will use system default.

Responses

200: OK

DELETE /{kubernetes_mount_path}/roles/{name}

Operation ID: kubernetes-delete-role

Manage the roles that can be created with this secrets engine.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role
kubernetes_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

GET /{kv_v1_mount_path}/{path}

Operation ID: kv-v1-read

Pass-through secret storage to the storage backend, allowing you to read/write arbitrary data into secret storage.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v1_mount_path	string	path	yes	Path that the backend was mounted at
list	string	query	no	Return a list if true

Responses

200: OK

POST /{kv_v1_mount_path}/{path}

Operation ID: kv-v1-write

Pass-through secret storage to the storage backend, allowing you to read/write arbitrary data into secret storage.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v1_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

DELETE /{kv_v1_mount_path}/{path}

Operation ID: kv-v1-delete

Pass-through secret storage to the storage backend, allowing you to read/write arbitrary data into secret storage.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v1_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /{kv_v2_mount_path}/config

Operation ID: kv-v2-read-configuration

Read the backend level settings.

Parameters

Parameter	Type	Location	Required	Description
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
cas_required	boolean	no	If true, the backend will require the cas parameter to be set for each write
delete_version_after	integer	no	The length of time before a version is deleted.
max_versions	integer	no	The number of versions to keep for each key.

POST /{kv_v2_mount_path}/config

Operation ID: kv-v2-configure

Configure backend level settings that are applied to every key in the key-value store.

Parameters

Parameter	Type	Location	Required	Description
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
cas_required	boolean	no	If true, the backend will require the cas parameter to be set for each write
delete_version_after	integer	no	If set, the length of time before a version is deleted. A negative duration disables the use of delete_version_after on all keys. A zero duration clears the current setting. Accepts a Go duration format string.
max_versions	integer	no	The number of versions to keep for each key. Defaults to 10

Responses

204: No Content

GET /{kv_v2_mount_path}/data/{path}

Operation ID: kv-v2-read

Write, Patch, Read, and Delete data in the Key-Value Store.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
data	object	no
metadata	object	no

POST /{kv_v2_mount_path}/data/{path}

Operation ID: kv-v2-write

Write, Patch, Read, and Delete data in the Key-Value Store.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
data	object	no	The contents of the data map will be stored and returned on read.
options	object	no	Options for writing a KV entry. Set the "cas" value to use a Check-And-Set operation. If not set the write will be allowed. If set to 0 a write will only be allowed if the key doesn’t exist. If the index is non-zero the write will only be allowed if the key’s current version matches the version specified in the cas parameter.
override_version	integer	no	Only replication!!!!!!!!
version	integer	no	If provided during a read, the value at the version number will be returned

Responses

200: OK

Parameter	Type	Required	Description
created_time	string	no
custom_metadata	object	no
deletion_time	string	no
destroyed	boolean	no
version	integer	no

DELETE /{kv_v2_mount_path}/data/{path}

Operation ID: kv-v2-delete

Write, Patch, Read, and Delete data in the Key-Value Store.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

POST /{kv_v2_mount_path}/delete/{path}

Operation ID: kv-v2-delete-versions

Marks one or more versions as deleted in the KV store.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
versions	array	no	The versions to be archived. The versioned data will not be deleted, but it will no longer be returned in normal get requests.

Responses

204: No Content

POST /{kv_v2_mount_path}/destroy/{path}

Operation ID: kv-v2-destroy-versions

Permanently removes one or more versions in the KV store

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
versions	array	no	The versions to destroy. Their data will be permanently deleted.

Responses

204: No Content

GET /{kv_v2_mount_path}/metadata/{path}

Operation ID: kv-v2-read-metadata

Configures settings for the KV store

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at
list	string	query	no	Return a list if true

Responses

200: OK

Parameter	Type	Required	Description
cas_required	boolean	no
created_time	string	no
current_version	integer	no
custom_metadata	object	no	User-provided key-value pairs that are used to describe arbitrary and version-agnostic information about a secret.
delete_version_after	integer	no	The length of time before a version is deleted.
last_sync_time	string	no
max_versions	integer	no	The number of versions to keep
oldest_version	integer	no
updated_time	string	no
versions	object	no

POST /{kv_v2_mount_path}/metadata/{path}

Operation ID: kv-v2-write-metadata

Configures settings for the KV store

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
cas_required	boolean	no	If true the key will require the cas parameter to be set on all write requests. If false, the backend’s configuration will be used.
custom_metadata	object	no	User-provided key-value pairs that are used to describe arbitrary and version-agnostic information about a secret.
delete_version_after	integer	no	The length of time before a version is deleted. If not set, the backend's configured delete_version_after is used. Cannot be greater than the backend's delete_version_after. A zero duration clears the current setting. A negative duration will cause an error.
max_versions	integer	no	The number of versions to keep. If not set, the backend’s configured max version is used.

Responses

204: No Content

DELETE /{kv_v2_mount_path}/metadata/{path}

Operation ID: kv-v2-delete-metadata

Configures settings for the KV store

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /{kv_v2_mount_path}/subkeys/{path}

Operation ID: kv-v2-read-subkeys

Read the structure of a secret entry from the Key-Value store with the values removed.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
metadata	object	no
subkeys	object	no

POST /{kv_v2_mount_path}/undelete/{path}

Operation ID: kv-v2-undelete-versions

Undeletes one or more versions from the KV store.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Location of the secret.
kv_v2_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
versions	array	no	The versions to unarchive. The versions will be restored and their data will be returned on normal get requests.

Responses

204: No Content

GET /{ldap_mount_path}/config

Operation ID: ldap-read-configuration

Configure the LDAP secrets engine plugin.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{ldap_mount_path}/config

Operation ID: ldap-configure

Configure the LDAP secrets engine plugin.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
anonymous_group_search	boolean (default: False)	no	Use anonymous binds when performing LDAP group searches (if true the initial credentials will still be used for the initial connection test).
binddn	string	no	LDAP DN for searching for the user DN (optional)
bindpass	string	no	LDAP password for searching for the user DN (optional)
case_sensitive_names	boolean	no	If true, case sensitivity will be used when comparing usernames and groups for matching policies.
certificate	string	no	CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded (optional)
client_tls_cert	string	no	Client certificate to provide to the LDAP server, must be x509 PEM encoded (optional)
client_tls_key	string	no	Client certificate key to provide to the LDAP server, must be x509 PEM encoded (optional)
connection_timeout	integer (default: 30s)	no	Timeout, in seconds, when attempting to connect to the LDAP server before trying the next URL in the configuration.
deny_null_bind	boolean (default: True)	no	Denies an unauthenticated LDAP bind request if the user's password is empty; defaults to true
dereference_aliases	string (never, finding, searching, always) (default: never)	no	When aliases should be dereferenced on search operations. Accepted values are 'never', 'finding', 'searching', 'always'. Defaults to 'never'.
discoverdn	boolean	no	Use anonymous bind to discover the bind DN of a user (optional)
groupattr	string (default: cn)	no	LDAP attribute to follow on objects returned by in order to enumerate user group membership. Examples: "cn" or "memberOf", etc. Default: cn
groupdn	string	no	LDAP search base to use for group membership search (eg: ou=Groups,dc=example,dc=org)
groupfilter	string (default: (	(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}})))	no
insecure_tls	boolean	no	Skip LDAP server SSL Certificate verification - VERY insecure (optional)
length	integer	no	⚠️ Deprecated. The desired length of passwords that Vault generates.
max_page_size	integer (default: 0)	no	If set to a value greater than 0, the LDAP backend will use the LDAP server's paged search control to request pages of up to the given size. This can be used to avoid hitting the LDAP server's maximum result size limit. Otherwise, the LDAP backend will not use the paged search control.
max_ttl	integer	no	The maximum password time-to-live.
password_policy	string	no	Password policy to use to generate passwords
request_timeout	integer (default: 90s)	no	Timeout, in seconds, for the connection when making requests against the server before returning back an error.
schema	string (default: openldap)	no	The desired LDAP schema used when modifying user account passwords.
starttls	boolean	no	Issue a StartTLS command after establishing unencrypted connection (optional)
tls_max_version	string (tls10, tls11, tls12, tls13) (default: tls12)	no	Maximum TLS version to use. Accepted values are 'tls10', 'tls11', 'tls12' or 'tls13'. Defaults to 'tls12'
tls_min_version	string (tls10, tls11, tls12, tls13) (default: tls12)	no	Minimum TLS version to use. Accepted values are 'tls10', 'tls11', 'tls12' or 'tls13'. Defaults to 'tls12'
ttl	integer	no	The default password time-to-live.
upndomain	string	no	Enables userPrincipalDomain login with [username]@UPNDomain (optional)
url	string (default: ldap://127.0.0.1)	no	LDAP URL to connect to (default: ldap://127.0.0.1). Multiple URLs can be specified by concatenating them with commas; they will be tried in-order.
use_pre111_group_cn_behavior	boolean	no	In Vault 1.1.1 a fix for handling group CN values of different cases unfortunately introduced a regression that could cause previously defined groups to not be found due to a change in the resulting name. If set true, the pre-1.1.1 behavior for matching group CNs will be used. This is only needed in some upgrade scenarios for backwards compatibility. It is enabled by default if the config is upgraded but disabled by default on new configurations.
use_token_groups	boolean (default: False)	no	If true, use the Active Directory tokenGroups constructed attribute of the user to find the group memberships. This will find all security groups including nested ones.
userattr	string (default: cn)	no	Attribute used for users (default: cn)
userdn	string	no	LDAP domain to use for users (eg: ou=People,dc=example,dc=org)
userfilter	string (default: ({{.UserAttr}}={{.Username}}))	no	Go template for LDAP user search filer (optional) The template can access the following context variables: UserAttr, Username Default: ({{.UserAttr}}={{.Username}})
username_as_alias	boolean (default: False)	no	If true, sets the alias name to the username

Responses

200: OK

DELETE /{ldap_mount_path}/config

Operation ID: ldap-delete-configuration

Configure the LDAP secrets engine plugin.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

GET /{ldap_mount_path}/creds/{name}

Operation ID: ldap-request-dynamic-role-credentials

Request LDAP credentials for a dynamic role. These credentials are created within the LDAP system when querying this endpoint.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the dynamic role.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{ldap_mount_path}/library

Operation ID: ldap-library-list

List the name of each set of service accounts currently stored.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

POST /{ldap_mount_path}/library/manage/{name}/check-in

Operation ID: ldap-library-force-check-in

Check service accounts in to the library.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the set.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
service_account_names	array	no	The username/logon name for the service accounts to check in.

Responses

200: OK

GET /{ldap_mount_path}/library/{name}

Operation ID: ldap-library-read

Read a library set.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the set.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{ldap_mount_path}/library/{name}

Operation ID: ldap-library-configure

Update a library set.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the set.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
disable_check_in_enforcement	boolean (default: False)	no	Disable the default behavior of requiring that check-ins are performed by the entity that checked them out.
max_ttl	integer (default: 86400)	no	In seconds, the max amount of time a check-out's renewals should last. Defaults to 24 hours.
service_account_names	array	no	The username/logon name for the service accounts with which this set will be associated.
ttl	integer (default: 86400)	no	In seconds, the amount of time a check-out should last. Defaults to 24 hours.

Responses

200: OK

DELETE /{ldap_mount_path}/library/{name}

Operation ID: ldap-library-delete

Delete a library set.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the set.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{ldap_mount_path}/library/{name}/check-in

Operation ID: ldap-library-check-in

Check service accounts in to the library.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the set.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
service_account_names	array	no	The username/logon name for the service accounts to check in.

Responses

200: OK

POST /{ldap_mount_path}/library/{name}/check-out

Operation ID: ldap-library-check-out

Check a service account out from the library.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the set
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
ttl	integer	no	The length of time before the check-out will expire, in seconds.

Responses

200: OK

GET /{ldap_mount_path}/library/{name}/status

Operation ID: ldap-library-check-status

Check the status of the service accounts in a library set.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the set.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{ldap_mount_path}/role

Operation ID: ldap-list-dynamic-roles

List all the dynamic roles Vault is currently managing in LDAP.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{ldap_mount_path}/role/{name}

Operation ID: ldap-read-dynamic-role

Manage the static roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role (lowercase)
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{ldap_mount_path}/role/{name}

Operation ID: ldap-write-dynamic-role

Manage the static roles that can be created with this backend.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role (lowercase)
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
creation_ldif	string	yes	LDIF string used to create new entities within the LDAP system. This LDIF can be templated.
default_ttl	integer	no	Default TTL for dynamic credentials
deletion_ldif	string	yes	LDIF string used to delete entities created within the LDAP system. This LDIF can be templated.
max_ttl	integer	no	Max TTL a dynamic credential can be extended to
rollback_ldif	string	no	LDIF string used to rollback changes in the event of a failure to create credentials. This LDIF can be templated.
username_template	string	no	The template used to create a username

Responses

200: OK

DELETE /{ldap_mount_path}/role/{name}

Operation ID: ldap-delete-dynamic-role

Manage the static roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role (lowercase)
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{ldap_mount_path}/rotate-role/{name}

Operation ID: ldap-rotate-static-role

Request to rotate the credentials for a static user account.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the static role
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{ldap_mount_path}/rotate-root

Operation ID: ldap-rotate-root-credentials

Request to rotate the root credentials Vault uses for the LDAP administrator account.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{ldap_mount_path}/static-cred/{name}

Operation ID: ldap-request-static-role-credentials

Request LDAP credentials for a certain static role. These credentials are rotated periodically.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the static role.
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{ldap_mount_path}/static-role

Operation ID: ldap-list-static-roles

This path lists all the static roles Vault is currently managing within the LDAP system.

Parameters

Parameter	Type	Location	Required	Description
ldap_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{ldap_mount_path}/static-role/{name}

Operation ID: ldap-read-static-role

Manage the static roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{ldap_mount_path}/static-role/{name}

Operation ID: ldap-write-static-role

Manage the static roles that can be created with this backend.

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
dn	string	no	The distinguished name of the entry to manage.
rotation_period	integer	no	Period for automatic credential rotation of the given entry.
username	string	no	The username/logon name for the entry with which this role will be associated.

Responses

200: OK

DELETE /{ldap_mount_path}/static-role/{name}

Operation ID: ldap-delete-static-role

Manage the static roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role
ldap_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{pki_mount_path}/acme/account/{kid}

Operation ID: pki-write-acme-account-kid

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
kid	string	path	yes	The key identifier provided by the CA
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/acme/authorization/{auth_id}

Operation ID: pki-write-acme-authorization-auth_id

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
auth_id	string	path	yes	ACME authorization identifier value
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/acme/challenge/{auth_id}/{challenge_type}

Operation ID: pki-write-acme-challenge-auth_id-challenge_type

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
auth_id	string	path	yes	ACME authorization identifier value
challenge_type	string	path	yes	ACME challenge type
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

GET /{pki_mount_path}/acme/directory

Operation ID: pki-read-acme-directory

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/acme/new-account

Operation ID: pki-write-acme-new-account

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/acme/new-eab

Operation ID: pki-generate-eab-key

Generate external account bindings to be used for ACME

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
acme_directory	string	no	The ACME directory to which the key belongs
created_on	string	no	An RFC3339 formatted date time when the EAB token was created
id	string	no	The EAB key identifier
key	string	no	The EAB hmac key
key_type	string	no	The EAB key type

GET /{pki_mount_path}/acme/new-nonce

Operation ID: pki-read-acme-new-nonce

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/acme/new-order

Operation ID: pki-write-acme-new-order

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/acme/order/{order_id}

Operation ID: pki-write-acme-order-order_id

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
order_id	string	path	yes	The ACME order identifier to fetch
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/acme/order/{order_id}/cert

Operation ID: pki-write-acme-order-order_id-cert

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
order_id	string	path	yes	The ACME order identifier to fetch
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/acme/order/{order_id}/finalize

Operation ID: pki-write-acme-order-order_id-finalize

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
order_id	string	path	yes	The ACME order identifier to fetch
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/acme/orders

Operation ID: pki-write-acme-orders

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/acme/revoke-cert

Operation ID: pki-write-acme-revoke-cert

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

GET /{pki_mount_path}/ca

Operation ID: pki-read-ca-der

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/ca/pem

Operation ID: pki-read-ca-pem

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/ca_chain

Operation ID: pki-read-ca-chain-pem

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/cert/ca_chain

Operation ID: pki-read-cert-ca-chain

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/cert/crl

Operation ID: pki-read-cert-crl

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/cert/delta-crl

Operation ID: pki-read-cert-delta-crl

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/cert/unified-crl

Operation ID: pki-read-cert-unified-crl

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/cert/unified-delta-crl

Operation ID: pki-read-cert-unified-delta-crl

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/cert/{serial}

Operation ID: pki-read-cert

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
serial	string	path	yes	Certificate serial number, in colon- or hyphen-separated octal
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/cert/{serial}/raw

Operation ID: pki-read-cert-raw-der

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
serial	string	path	yes	Certificate serial number, in colon- or hyphen-separated octal
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/cert/{serial}/raw/pem

Operation ID: pki-read-cert-raw-pem

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
serial	string	path	yes	Certificate serial number, in colon- or hyphen-separated octal
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/certs

Operation ID: pki-list-certs

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no	A list of keys

GET /{pki_mount_path}/certs/revocation-queue

Operation ID: pki-list-certs-revocation-queue

List all pending, cross-cluster revocations known to the local cluster.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{pki_mount_path}/certs/revoked

Operation ID: pki-list-revoked-certs

List all revoked serial numbers within the local cluster

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no	List of Keys

GET /{pki_mount_path}/certs/unified-revoked

Operation ID: pki-list-unified-revoked-certs

List all revoked serial numbers within this cluster's unified storage area.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
key_info	string	no	Key information
keys	array	no	List of Keys

GET /{pki_mount_path}/config/acme

Operation ID: pki-read-acme-configuration

Configuration of ACME Endpoints

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/config/acme

Operation ID: pki-configure-acme

Configuration of ACME Endpoints

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
allow_role_ext_key_usage	boolean (default: False)	no	whether the ExtKeyUsage field from a role is used, defaults to false meaning that certificate will be signed with ServerAuth.
allowed_issuers	array (default: ['*'])	no	which issuers are allowed for use with ACME; by default, this will only be the primary (default) issuer
allowed_roles	array (default: ['*'])	no	which roles are allowed for use with ACME; by default via '*', these will be all roles including sign-verbatim; when concrete role names are specified, any default_directory_policy role must be included to allow usage of the default acme directories under /pki/acme/directory and /pki/issuer/:issuer_id/acme/directory.
default_directory_policy	string (default: sign-verbatim)	no	the policy to be used for non-role-qualified ACME requests; by default ACME issuance will be otherwise unrestricted, equivalent to the sign-verbatim endpoint; one may also specify a role to use as this policy, as "role:", the specified role must be allowed by allowed_roles
dns_resolver	string (default: )	no	DNS resolver to use for domain resolution on this mount. Defaults to using the default system resolver. Must be in the format :, with both parts mandatory.
eab_policy	string (default: always-required)	no	Specify the policy to use for external account binding behaviour, 'not-required', 'new-account-required' or 'always-required'
enabled	boolean (default: False)	no	whether ACME is enabled, defaults to false meaning that clusters will by default not get ACME support

Responses

200: OK

GET /{pki_mount_path}/config/auto-tidy

Operation ID: pki-read-auto-tidy-configuration

Modifies the current configuration for automatic tidy execution.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
acme_account_safety_buffer	integer	no	Safety buffer after creation after which accounts lacking orders are revoked
enabled	boolean	no	Specifies whether automatic tidy is enabled or not
interval_duration	integer	no	Specifies the duration between automatic tidy operation
issuer_safety_buffer	integer	no	Issuer safety buffer
maintain_stored_certificate_counts	boolean	no
pause_duration	string	no	Duration to pause between tidying certificates
publish_stored_certificate_count_metrics	boolean	no
revocation_queue_safety_buffer	integer	no
safety_buffer	integer	no	Safety buffer time duration
tidy_acme	boolean	no	Tidy Unused Acme Accounts, and Orders
tidy_cert_store	boolean	no	Specifies whether to tidy up the certificate store
tidy_cross_cluster_revoked_certs	boolean	no
tidy_expired_issuers	boolean	no	Specifies whether tidy expired issuers
tidy_move_legacy_ca_bundle	boolean	no
tidy_revocation_queue	boolean	no
tidy_revoked_cert_issuer_associations	boolean	no	Specifies whether to associate revoked certificates with their corresponding issuers
tidy_revoked_certs	boolean	no	Specifies whether to remove all invalid and expired certificates from storage

POST /{pki_mount_path}/config/auto-tidy

Operation ID: pki-configure-auto-tidy

Modifies the current configuration for automatic tidy execution.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
acme_account_safety_buffer	integer (default: 2592000)	no	The amount of time that must pass after creation that an account with no orders is marked revoked, and the amount of time after being marked revoked or deactivated.
enabled	boolean	no	Set to true to enable automatic tidy operations.
interval_duration	integer (default: 43200)	no	Interval at which to run an auto-tidy operation. This is the time between tidy invocations (after one finishes to the start of the next). Running a manual tidy will reset this duration.
issuer_safety_buffer	integer (default: 31536000)	no	The amount of extra time that must have passed beyond issuer's expiration before it is removed from the backend storage. Defaults to 8760 hours (1 year).
maintain_stored_certificate_counts	boolean (default: False)	no	This configures whether stored certificates are counted upon initialization of the backend, and whether during normal operation, a running count of certificates stored is maintained.
pause_duration	string (default: 0s)	no	The amount of time to wait between processing certificates. This allows operators to change the execution profile of tidy to take consume less resources by slowing down how long it takes to run. Note that the entire list of certificates will be stored in memory during the entire tidy operation, but resources to read/process/update existing entries will be spread out over a greater period of time. By default this is zero seconds.
publish_stored_certificate_count_metrics	boolean (default: False)	no	This configures whether the stored certificate count is published to the metrics consumer. It does not affect if the stored certificate count is maintained, and if maintained, it will be available on the tidy-status endpoint.
revocation_queue_safety_buffer	integer (default: 172800)	no	The amount of time that must pass from the cross-cluster revocation request being initiated to when it will be slated for removal. Setting this too low may remove valid revocation requests before the owning cluster has a chance to process them, especially if the cluster is offline.
safety_buffer	integer (default: 259200)	no	The amount of extra time that must have passed beyond certificate expiration before it is removed from the backend storage and/or revocation list. Defaults to 72 hours.
tidy_acme	boolean (default: False)	no	Set to true to enable tidying ACME accounts, orders and authorizations. ACME orders are tidied (deleted) safety_buffer after the certificate associated with them expires, or after the order and relevant authorizations have expired if no certificate was produced. Authorizations are tidied with the corresponding order. When a valid ACME Account is at least acme_account_safety_buffer old, and has no remaining orders associated with it, the account is marked as revoked. After another acme_account_safety_buffer has passed from the revocation or deactivation date, a revoked or deactivated ACME account is deleted.
tidy_cert_store	boolean	no	Set to true to enable tidying up the certificate store
tidy_cross_cluster_revoked_certs	boolean	no	Set to true to enable tidying up the cross-cluster revoked certificate store. Only runs on the active primary node.
tidy_expired_issuers	boolean	no	Set to true to automatically remove expired issuers past the issuer_safety_buffer. No keys will be removed as part of this operation.
tidy_move_legacy_ca_bundle	boolean	no	Set to true to move the legacy ca_bundle from /config/ca_bundle to /config/ca_bundle.bak. This prevents downgrades to pre-Vault 1.11 versions (as older PKI engines do not know about the new multi-issuer storage layout), but improves the performance on seal wrapped PKI mounts. This will only occur if at least issuer_safety_buffer time has occurred after the initial storage migration. This backup is saved in case of an issue in future migrations. Operators may consider removing it via sys/raw if they desire. The backup will be removed via a DELETE /root call, but note that this removes ALL issuers within the mount (and is thus not desirable in most operational scenarios).
tidy_revocation_list	boolean	no	Deprecated; synonym for 'tidy_revoked_certs
tidy_revocation_queue	boolean (default: False)	no	Set to true to remove stale revocation queue entries that haven't been confirmed by any active cluster. Only runs on the active primary node
tidy_revoked_cert_issuer_associations	boolean	no	Set to true to validate issuer associations on revocation entries. This helps increase the performance of CRL building and OCSP responses.
tidy_revoked_certs	boolean	no	Set to true to expire all revoked and expired certificates, removing them both from the CRL and from storage. The CRL will be rotated if this causes any values to be removed.

Responses

200: OK

Parameter	Type	Required	Description
acme_account_safety_buffer	integer	no	Safety buffer after creation after which accounts lacking orders are revoked
enabled	boolean	no	Specifies whether automatic tidy is enabled or not
interval_duration	integer	no	Specifies the duration between automatic tidy operation
issuer_safety_buffer	integer	no	Issuer safety buffer
maintain_stored_certificate_counts	boolean	no
pause_duration	string	no	Duration to pause between tidying certificates
publish_stored_certificate_count_metrics	boolean	no
revocation_queue_safety_buffer	integer	no
safety_buffer	integer	no	Safety buffer time duration
tidy_acme	boolean	no	Tidy Unused Acme Accounts, and Orders
tidy_cert_store	boolean	no	Specifies whether to tidy up the certificate store
tidy_cross_cluster_revoked_certs	boolean	no	Tidy the cross-cluster revoked certificate store
tidy_expired_issuers	boolean	no	Specifies whether tidy expired issuers
tidy_move_legacy_ca_bundle	boolean	no
tidy_revocation_queue	boolean	no
tidy_revoked_cert_issuer_associations	boolean	no	Specifies whether to associate revoked certificates with their corresponding issuers
tidy_revoked_certs	boolean	no	Specifies whether to remove all invalid and expired certificates from storage

POST /{pki_mount_path}/config/ca

Operation ID: pki-configure-ca

Set the CA certificate and private key used for generated credentials.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
pem_bundle	string	no	PEM-format, concatenated unencrypted secret key and certificate.

Responses

200: OK

Parameter	Type	Required	Description
existing_issuers	array	no	Existing issuers specified as part of the import bundle of this request
existing_keys	array	no	Existing keys specified as part of the import bundle of this request
imported_issuers	array	no	Net-new issuers imported as a part of this request
imported_keys	array	no	Net-new keys imported as a part of this request
mapping	object	no	A mapping of issuer_id to key_id for all issuers included in this request

GET /{pki_mount_path}/config/cluster

Operation ID: pki-read-cluster-configuration

Set cluster-local configuration, including address to this PR cluster.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
aia_path	string	no	Optional URI to this mount's AIA distribution point; may refer to an external non-Vault responder. This is for resolving AIA URLs and providing the {{cluster_aia_path}} template parameter and will not be used for other purposes. As such, unlike path above, this could safely be an insecure transit mechanism (like HTTP without TLS). For example: http://cdn.example.com/pr1/pki
path	string	no	Canonical URI to this mount on this performance replication cluster's external address. This is for resolving AIA URLs and providing the {{cluster_path}} template parameter but might be used for other purposes in the future. This should only point back to this particular PR replica and should not ever point to another PR cluster. It may point to any node in the PR replica, including standby nodes, and need not always point to the active node. For example: https://pr1.vault.example.com:8200/v1/pki

POST /{pki_mount_path}/config/cluster

Operation ID: pki-configure-cluster

Set cluster-local configuration, including address to this PR cluster.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
aia_path	string	no	Optional URI to this mount's AIA distribution point; may refer to an external non-Vault responder. This is for resolving AIA URLs and providing the {{cluster_aia_path}} template parameter and will not be used for other purposes. As such, unlike path above, this could safely be an insecure transit mechanism (like HTTP without TLS). For example: http://cdn.example.com/pr1/pki
path	string	no	Canonical URI to this mount on this performance replication cluster's external address. This is for resolving AIA URLs and providing the {{cluster_path}} template parameter but might be used for other purposes in the future. This should only point back to this particular PR replica and should not ever point to another PR cluster. It may point to any node in the PR replica, including standby nodes, and need not always point to the active node. For example: https://pr1.vault.example.com:8200/v1/pki

Responses

200: OK

Parameter	Type	Required	Description
aia_path	string	no	Optional URI to this mount's AIA distribution point; may refer to an external non-Vault responder. This is for resolving AIA URLs and providing the {{cluster_aia_path}} template parameter and will not be used for other purposes. As such, unlike path above, this could safely be an insecure transit mechanism (like HTTP without TLS). For example: http://cdn.example.com/pr1/pki
path	string	no	Canonical URI to this mount on this performance replication cluster's external address. This is for resolving AIA URLs and providing the {{cluster_path}} template parameter but might be used for other purposes in the future. This should only point back to this particular PR replica and should not ever point to another PR cluster. It may point to any node in the PR replica, including standby nodes, and need not always point to the active node. For example: https://pr1.vault.example.com:8200/v1/pki

GET /{pki_mount_path}/config/crl

Operation ID: pki-read-crl-configuration

Configure the CRL expiration.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
auto_rebuild	boolean	no	If set to true, enables automatic rebuilding of the CRL
auto_rebuild_grace_period	string	no	The time before the CRL expires to automatically rebuild it, when enabled. Must be shorter than the CRL expiry. Defaults to 12h.
cross_cluster_revocation	boolean	no	Whether to enable a global, cross-cluster revocation queue. Must be used with auto_rebuild=true.
delta_rebuild_interval	string	no	The time between delta CRL rebuilds if a new revocation has occurred. Must be shorter than the CRL expiry. Defaults to 15m.
disable	boolean	no	If set to true, disables generating the CRL entirely.
enable_delta	boolean	no	Whether to enable delta CRLs between authoritative CRL rebuilds
expiry	string	no	The amount of time the generated CRL should be valid; defaults to 72 hours
ocsp_disable	boolean	no	If set to true, ocsp unauthorized responses will be returned.
ocsp_expiry	string	no	The amount of time an OCSP response will be valid (controls the NextUpdate field); defaults to 12 hours
unified_crl	boolean	no	If set to true enables global replication of revocation entries, also enabling unified versions of OCSP and CRLs if their respective features are enabled. disable for CRLs and ocsp_disable for OCSP.
unified_crl_on_existing_paths	boolean	no	If set to true, existing CRL and OCSP paths will return the unified CRL instead of a response based on cluster-local data

POST /{pki_mount_path}/config/crl

Operation ID: pki-configure-crl

Configure the CRL expiration.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
auto_rebuild	boolean	no	If set to true, enables automatic rebuilding of the CRL
auto_rebuild_grace_period	string (default: 12h)	no	The time before the CRL expires to automatically rebuild it, when enabled. Must be shorter than the CRL expiry. Defaults to 12h.
cross_cluster_revocation	boolean	no	Whether to enable a global, cross-cluster revocation queue. Must be used with auto_rebuild=true.
delta_rebuild_interval	string (default: 15m)	no	The time between delta CRL rebuilds if a new revocation has occurred. Must be shorter than the CRL expiry. Defaults to 15m.
disable	boolean	no	If set to true, disables generating the CRL entirely.
enable_delta	boolean	no	Whether to enable delta CRLs between authoritative CRL rebuilds
expiry	string (default: 72h)	no	The amount of time the generated CRL should be valid; defaults to 72 hours
ocsp_disable	boolean	no	If set to true, ocsp unauthorized responses will be returned.
ocsp_expiry	string (default: 1h)	no	The amount of time an OCSP response will be valid (controls the NextUpdate field); defaults to 12 hours
unified_crl	boolean (default: false)	no	If set to true enables global replication of revocation entries, also enabling unified versions of OCSP and CRLs if their respective features are enabled. disable for CRLs and ocsp_disable for OCSP.
unified_crl_on_existing_paths	boolean (default: false)	no	If set to true, existing CRL and OCSP paths will return the unified CRL instead of a response based on cluster-local data

Responses

200: OK

Parameter	Type	Required	Description
auto_rebuild	boolean	no	If set to true, enables automatic rebuilding of the CRL
auto_rebuild_grace_period	string (default: 12h)	no	The time before the CRL expires to automatically rebuild it, when enabled. Must be shorter than the CRL expiry. Defaults to 12h.
cross_cluster_revocation	boolean	no	Whether to enable a global, cross-cluster revocation queue. Must be used with auto_rebuild=true.
delta_rebuild_interval	string (default: 15m)	no	The time between delta CRL rebuilds if a new revocation has occurred. Must be shorter than the CRL expiry. Defaults to 15m.
disable	boolean	no	If set to true, disables generating the CRL entirely.
enable_delta	boolean	no	Whether to enable delta CRLs between authoritative CRL rebuilds
expiry	string (default: 72h)	no	The amount of time the generated CRL should be valid; defaults to 72 hours
ocsp_disable	boolean	no	If set to true, ocsp unauthorized responses will be returned.
ocsp_expiry	string (default: 1h)	no	The amount of time an OCSP response will be valid (controls the NextUpdate field); defaults to 12 hours
unified_crl	boolean	no	If set to true enables global replication of revocation entries, also enabling unified versions of OCSP and CRLs if their respective features are enabled. disable for CRLs and ocsp_disable for OCSP.
unified_crl_on_existing_paths	boolean	no	If set to true, existing CRL and OCSP paths will return the unified CRL instead of a response based on cluster-local data

GET /{pki_mount_path}/config/issuers

Operation ID: pki-read-issuers-configuration

Read and set the default issuer certificate for signing.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
default	string	no	Reference (name or identifier) to the default issuer.
default_follows_latest_issuer	boolean	no	Whether the default issuer should automatically follow the latest generated or imported issuer. Defaults to false.

POST /{pki_mount_path}/config/issuers

Operation ID: pki-configure-issuers

Read and set the default issuer certificate for signing.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
default	string	no	Reference (name or identifier) to the default issuer.
default_follows_latest_issuer	boolean (default: False)	no	Whether the default issuer should automatically follow the latest generated or imported issuer. Defaults to false.

Responses

200: OK

Parameter	Type	Required	Description
default	string	no	Reference (name or identifier) to the default issuer.
default_follows_latest_issuer	boolean	no	Whether the default issuer should automatically follow the latest generated or imported issuer. Defaults to false.

GET /{pki_mount_path}/config/keys

Operation ID: pki-read-keys-configuration

Read and set the default key used for signing

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
default	string	no	Reference (name or identifier) to the default issuer.

POST /{pki_mount_path}/config/keys

Operation ID: pki-configure-keys

Read and set the default key used for signing

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
default	string	no	Reference (name or identifier) of the default key.

Responses

200: OK

Parameter	Type	Required	Description
default	string	no	Reference (name or identifier) to the default issuer.

GET /{pki_mount_path}/config/urls

Operation ID: pki-read-urls-configuration

Set the URLs for the issuing CA, CRL distribution points, and OCSP servers.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl_distribution_points	array	no	Comma-separated list of URLs to be used for the CRL distribution points attribute. See also RFC 5280 Section 4.2.1.13.
enable_templating	boolean	no	Whether or not to enable templating of the above AIA fields. When templating is enabled the special values '{{issuer_id}}' and '{{cluster_path}}' are available, but the addresses are not checked for URI validity until issuance time. This requires /config/cluster's path to be set on all PR Secondary clusters.
issuing_certificates	array	no	Comma-separated list of URLs to be used for the issuing certificate attribute. See also RFC 5280 Section 4.2.2.1.
ocsp_servers	array	no	Comma-separated list of URLs to be used for the OCSP servers attribute. See also RFC 5280 Section 4.2.2.1.

POST /{pki_mount_path}/config/urls

Operation ID: pki-configure-urls

Set the URLs for the issuing CA, CRL distribution points, and OCSP servers.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
crl_distribution_points	array	no	Comma-separated list of URLs to be used for the CRL distribution points attribute. See also RFC 5280 Section 4.2.1.13.
enable_templating	boolean (default: False)	no	Whether or not to enabling templating of the above AIA fields. When templating is enabled the special values '{{issuer_id}}', '{{cluster_path}}', and '{{cluster_aia_path}}' are available, but the addresses are not checked for URI validity until issuance time. Using '{{cluster_path}}' requires /config/cluster's 'path' member to be set on all PR Secondary clusters and using '{{cluster_aia_path}}' requires /config/cluster's 'aia_path' member to be set on all PR secondary clusters.
issuing_certificates	array	no	Comma-separated list of URLs to be used for the issuing certificate attribute. See also RFC 5280 Section 4.2.2.1.
ocsp_servers	array	no	Comma-separated list of URLs to be used for the OCSP servers attribute. See also RFC 5280 Section 4.2.2.1.

Responses

200: OK

Parameter	Type	Required	Description
crl_distribution_points	array	no	Comma-separated list of URLs to be used for the CRL distribution points attribute. See also RFC 5280 Section 4.2.1.13.
enable_templating	boolean (default: False)	no	Whether or not to enabling templating of the above AIA fields. When templating is enabled the special values '{{issuer_id}}' and '{{cluster_path}}' are available, but the addresses are not checked for URI validity until issuance time. This requires /config/cluster's path to be set on all PR Secondary clusters.
issuing_certificates	array	no	Comma-separated list of URLs to be used for the issuing certificate attribute. See also RFC 5280 Section 4.2.2.1.
ocsp_servers	array	no	Comma-separated list of URLs to be used for the OCSP servers attribute. See also RFC 5280 Section 4.2.2.1.

GET /{pki_mount_path}/crl

Operation ID: pki-read-crl-der

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/crl/delta

Operation ID: pki-read-crl-delta

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/crl/delta/pem

Operation ID: pki-read-crl-delta-pem

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/crl/pem

Operation ID: pki-read-crl-pem

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	string	no	Issuing CA Chain
certificate	string	no	Certificate
issuer_id	string	no	ID of the issuer
revocation_time	integer	no	Revocation time
revocation_time_rfc3339	string	no	Revocation time RFC 3339 formatted

GET /{pki_mount_path}/crl/rotate

Operation ID: pki-rotate-crl

Force a rebuild of the CRL.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
success	boolean	no	Whether rotation was successful

GET /{pki_mount_path}/crl/rotate-delta

Operation ID: pki-rotate-delta-crl

Force a rebuild of the delta CRL.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
success	boolean	no	Whether rotation was successful

GET /{pki_mount_path}/eab

Operation ID: pki-list-eab-keys

list external account bindings to be used for ACME

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
key_info	object	no	EAB details keyed by the eab key id
keys	array	no	A list of unused eab keys

DELETE /{pki_mount_path}/eab/{key_id}

Operation ID: pki-delete-eab-key

Delete an external account binding id prior to its use within an ACME account

Parameters

Parameter	Type	Location	Required	Description
key_id	string	path	yes	EAB key identifier
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{pki_mount_path}/intermediate/cross-sign

Operation ID: pki-cross-sign-intermediate

Generate a new CSR and private key used for signing.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
add_basic_constraints	boolean	no	Whether to add a Basic Constraints extension with CA: true. Only needed as a workaround in some compatibility scenarios with Active Directory Certificate Services.
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. May contain both DNS names and email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If not specified when signing, the common name will be taken from the CSR; other names must still be specified in alt_names or ip_sans.
country	array	no	If set, Country will be set to this value.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
exported	string (internal, external, kms)	no	Must be "internal", "exported" or "kms". If set to "exported", the generated private key will be returned. This is your only chance to retrieve the private key!
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_name	string	no	Provide a name to the generated or existing key, the name must be unique across all keys and not be the reserved value 'default'
key_ref	string (default: default)	no	Reference to a existing key; either "default" for the configured default key, an identifier or the name assigned to the key.
key_type	string (rsa, ec, ed25519) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
locality	array	no	If set, Locality will be set to this value.
managed_key_id	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_name is required. Ignored for other types.
managed_key_name	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_id is required. Ignored for other types.
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
not_before_duration	integer (default: 30)	no	The duration before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value.
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value.
postal_code	array	no	If set, Postal Code will be set to this value.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
province	array	no	If set, Province will be set to this value.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
street_address	array	no	If set, Street Address will be set to this value.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the mount max TTL. Note: this only has an effect when generating a CA cert or signing a CA cert, not when generating a CSR for an intermediate CA.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.

Responses

200: OK

Parameter	Type	Required	Description
csr	string	no	Certificate signing request.
key_id	string	no	Id of the key.
private_key	string	no	Generated private key.
private_key_type	string	no	Specifies the format used for marshaling the private key.

POST /{pki_mount_path}/intermediate/generate/{exported}

Operation ID: pki-generate-intermediate

Generate a new CSR and private key used for signing.

Parameters

Parameter	Type	Location	Required	Description
exported	string (internal, external, kms)	path	yes	Must be "internal", "exported" or "kms". If set to "exported", the generated private key will be returned. This is your only chance to retrieve the private key!
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
add_basic_constraints	boolean	no	Whether to add a Basic Constraints extension with CA: true. Only needed as a workaround in some compatibility scenarios with Active Directory Certificate Services.
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. May contain both DNS names and email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If not specified when signing, the common name will be taken from the CSR; other names must still be specified in alt_names or ip_sans.
country	array	no	If set, Country will be set to this value.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_name	string	no	Provide a name to the generated or existing key, the name must be unique across all keys and not be the reserved value 'default'
key_ref	string (default: default)	no	Reference to a existing key; either "default" for the configured default key, an identifier or the name assigned to the key.
key_type	string (rsa, ec, ed25519) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
locality	array	no	If set, Locality will be set to this value.
managed_key_id	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_name is required. Ignored for other types.
managed_key_name	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_id is required. Ignored for other types.
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
not_before_duration	integer (default: 30)	no	The duration before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value.
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value.
postal_code	array	no	If set, Postal Code will be set to this value.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
province	array	no	If set, Province will be set to this value.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
street_address	array	no	If set, Street Address will be set to this value.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the mount max TTL. Note: this only has an effect when generating a CA cert or signing a CA cert, not when generating a CSR for an intermediate CA.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.

Responses

200: OK

Parameter	Type	Required	Description
csr	string	no	Certificate signing request.
key_id	string	no	Id of the key.
private_key	string	no	Generated private key.
private_key_type	string	no	Specifies the format used for marshaling the private key.

POST /{pki_mount_path}/intermediate/set-signed

Operation ID: pki-set-signed-intermediate

Provide the signed intermediate CA cert.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
certificate	string	no	PEM-format certificate. This must be a CA certificate with a public key matching the previously-generated key from the generation endpoint. Additional parent CAs may be optionally appended to the bundle.

Responses

200: OK

Parameter	Type	Required	Description
existing_issuers	array	no	Existing issuers specified as part of the import bundle of this request
existing_keys	array	no	Existing keys specified as part of the import bundle of this request
imported_issuers	array	no	Net-new issuers imported as a part of this request
imported_keys	array	no	Net-new keys imported as a part of this request
mapping	object	no	A mapping of issuer_id to key_id for all issuers included in this request

POST /{pki_mount_path}/issue/{role}

Operation ID: pki-issue-with-role

Request a certificate using a certain role with the provided details.

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role with configuration for this request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. If email protection is enabled for the role, this may contain email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If email protection is enabled in the role, this may be an email address.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
issuer_ref	string (default: default)	no	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
remove_roots_from_chain	boolean (default: False)	no	Whether or not to remove self-signed CA certificates in the output of the ca_chain field.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the role max TTL.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
user_ids	array	no	The requested user_ids value to place in the subject, if any, in a comma-delimited list. Restricted by allowed_user_ids. Any values are added with OID 0.9.2342.19200300.100.1.1.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	Certificate Chain
certificate	string	no	Certificate
expiration	integer	no	Time of expiration
issuing_ca	string	no	Issuing Certificate Authority
private_key	string	no	Private key
private_key_type	string	no	Private key type
serial_number	string	no	Serial Number

GET /{pki_mount_path}/issuer/{issuer_ref}

Operation ID: pki-read-issuer

Fetch a single issuer certificate.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	CA Chain
certificate	string	no	Certificate
crl_distribution_points	array	no	CRL Distribution Points
enable_aia_url_templating	boolean	no	Whether or not templating is enabled for AIA fields
issuer_id	string	no	Issuer Id
issuer_name	string	no	Issuer Name
issuing_certificates	array	no	Issuing Certificates
key_id	string	no	Key Id
leaf_not_after_behavior	string	no	Leaf Not After Behavior
manual_chain	array	no	Manual Chain
ocsp_servers	array	no	OCSP Servers
revocation_signature_algorithm	string	no	Revocation Signature Alogrithm
revocation_time	integer	no
revocation_time_rfc3339	string	no
revoked	boolean	no	Revoked
usage	string	no	Usage

POST /{pki_mount_path}/issuer/{issuer_ref}

Operation ID: pki-write-issuer

Fetch a single issuer certificate.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
crl_distribution_points	array	no	Comma-separated list of URLs to be used for the CRL distribution points attribute. See also RFC 5280 Section 4.2.1.13.
enable_aia_url_templating	boolean (default: False)	no	Whether or not to enabling templating of the above AIA fields. When templating is enabled the special values '{{issuer_id}}', '{{cluster_path}}', '{{cluster_aia_path}}' are available, but the addresses are not checked for URL validity until issuance time. Using '{{cluster_path}}' requires /config/cluster's 'path' member to be set on all PR Secondary clusters and using '{{cluster_aia_path}}' requires /config/cluster's 'aia_path' member to be set on all PR secondary clusters.
issuer_name	string	no	Provide a name to the generated or existing issuer, the name must be unique across all issuers and not be the reserved value 'default'
issuing_certificates	array	no	Comma-separated list of URLs to be used for the issuing certificate attribute. See also RFC 5280 Section 4.2.2.1.
leaf_not_after_behavior	string (default: err)	no	Behavior of leaf's NotAfter fields: "err" to error if the computed NotAfter date exceeds that of this issuer; "truncate" to silently truncate to that of this issuer; or "permit" to allow this issuance to succeed (with NotAfter exceeding that of an issuer). Note that not all values will results in certificates that can be validated through the entire validity period. It is suggested to use "truncate" for intermediate CAs and "permit" only for root CAs.
manual_chain	array	no	Chain of issuer references to use to build this issuer's computed CAChain field, when non-empty.
ocsp_servers	array	no	Comma-separated list of URLs to be used for the OCSP servers attribute. See also RFC 5280 Section 4.2.2.1.
revocation_signature_algorithm	string (default: )	no	Which x509.SignatureAlgorithm name to use for signing CRLs. This parameter allows differentiation between PKCS#1v1.5 and PSS keys and choice of signature hash algorithm. The default (empty string) value is for Go to select the signature algorithm. This can fail if the underlying key does not support the requested signature algorithm, which may not be known at modification time (such as with PKCS#11 managed RSA keys).
usage	array (default: ['read-only', 'issuing-certificates', 'crl-signing', 'ocsp-signing'])	no	Comma-separated list (or string slice) of usages for this issuer; valid values are "read-only", "issuing-certificates", "crl-signing", and "ocsp-signing". Multiple values may be specified. Read-only is implicit and always set.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	CA Chain
certificate	string	no	Certificate
crl_distribution_points	array	no	CRL Distribution Points
enable_aia_url_templating	boolean	no	Whether or not templating is enabled for AIA fields
issuer_id	string	no	Issuer Id
issuer_name	string	no	Issuer Name
issuing_certificates	array	no	Issuing Certificates
key_id	string	no	Key Id
leaf_not_after_behavior	string	no	Leaf Not After Behavior
manual_chain	array	no	Manual Chain
ocsp_servers	array	no	OCSP Servers
revocation_signature_algorithm	string	no	Revocation Signature Alogrithm
revocation_time	integer	no
revocation_time_rfc3339	string	no
revoked	boolean	no	Revoked
usage	string	no	Usage

DELETE /{pki_mount_path}/issuer/{issuer_ref}

Operation ID: pki-delete-issuer

Fetch a single issuer certificate.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/account/{kid}

Operation ID: pki-write-issuer-issuer_ref-acme-account-kid

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
kid	string	path	yes	The key identifier provided by the CA
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/authorization/{auth_id}

Operation ID: pki-write-issuer-issuer_ref-acme-authorization-auth_id

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
auth_id	string	path	yes	ACME authorization identifier value
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/challenge/{auth_id}/{challenge_type}

Operation ID: pki-write-issuer-issuer_ref-acme-challenge-auth_id-challenge_type

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
auth_id	string	path	yes	ACME authorization identifier value
challenge_type	string	path	yes	ACME challenge type
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

GET /{pki_mount_path}/issuer/{issuer_ref}/acme/directory

Operation ID: pki-read-issuer-issuer_ref-acme-directory

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/new-account

Operation ID: pki-write-issuer-issuer_ref-acme-new-account

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/new-eab

Operation ID: pki-generate-eab-key-for-issuer

Generate external account bindings to be used for ACME

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
acme_directory	string	no	The ACME directory to which the key belongs
created_on	string	no	An RFC3339 formatted date time when the EAB token was created
id	string	no	The EAB key identifier
key	string	no	The EAB hmac key
key_type	string	no	The EAB key type

GET /{pki_mount_path}/issuer/{issuer_ref}/acme/new-nonce

Operation ID: pki-read-issuer-issuer_ref-acme-new-nonce

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/new-order

Operation ID: pki-write-issuer-issuer_ref-acme-new-order

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/order/{order_id}

Operation ID: pki-write-issuer-issuer_ref-acme-order-order_id

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
order_id	string	path	yes	The ACME order identifier to fetch
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/order/{order_id}/cert

Operation ID: pki-write-issuer-issuer_ref-acme-order-order_id-cert

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
order_id	string	path	yes	The ACME order identifier to fetch
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/order/{order_id}/finalize

Operation ID: pki-write-issuer-issuer_ref-acme-order-order_id-finalize

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
order_id	string	path	yes	The ACME order identifier to fetch
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/orders

Operation ID: pki-write-issuer-issuer_ref-acme-orders

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/acme/revoke-cert

Operation ID: pki-write-issuer-issuer_ref-acme-revoke-cert

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

GET /{pki_mount_path}/issuer/{issuer_ref}/crl

Operation ID: pki-issuer-read-crl

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/crl/delta

Operation ID: pki-issuer-read-crl-delta

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/crl/delta/der

Operation ID: pki-issuer-read-crl-delta-der

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/crl/delta/pem

Operation ID: pki-issuer-read-crl-delta-pem

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/crl/der

Operation ID: pki-issuer-read-crl-der

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/crl/pem

Operation ID: pki-issuer-read-crl-pem

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/der

Operation ID: pki-read-issuer-der

Fetch a single issuer certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	CA Chain
certificate	string	no	Certificate
issuer_id	string	no	Issuer Id
issuer_name	string	no	Issuer Name

304: Not Modified

POST /{pki_mount_path}/issuer/{issuer_ref}/issue/{role}

Operation ID: pki-issuer-issue-with-role

Request a certificate using a certain role with the provided details.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
role	string	path	yes	The desired role with configuration for this request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. If email protection is enabled for the role, this may contain email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If email protection is enabled in the role, this may be an email address.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
remove_roots_from_chain	boolean (default: False)	no	Whether or not to remove self-signed CA certificates in the output of the ca_chain field.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the role max TTL.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
user_ids	array	no	The requested user_ids value to place in the subject, if any, in a comma-delimited list. Restricted by allowed_user_ids. Any values are added with OID 0.9.2342.19200300.100.1.1.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	Certificate Chain
certificate	string	no	Certificate
expiration	integer	no	Time of expiration
issuing_ca	string	no	Issuing Certificate Authority
private_key	string	no	Private key
private_key_type	string	no	Private key type
serial_number	string	no	Serial Number

GET /{pki_mount_path}/issuer/{issuer_ref}/json

Operation ID: pki-read-issuer-json

Fetch a single issuer certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	CA Chain
certificate	string	no	Certificate
issuer_id	string	no	Issuer Id
issuer_name	string	no	Issuer Name

304: Not Modified

GET /{pki_mount_path}/issuer/{issuer_ref}/pem

Operation ID: pki-read-issuer-pem

Fetch a single issuer certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	CA Chain
certificate	string	no	Certificate
issuer_id	string	no	Issuer Id
issuer_name	string	no	Issuer Name

304: Not Modified

POST /{pki_mount_path}/issuer/{issuer_ref}/resign-crls

Operation ID: pki-issuer-resign-crls

Combine and sign with the provided issuer different CRLs

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
crl_number	integer	no	The sequence number to be written within the CRL Number extension.
crls	array	no	A list of PEM encoded CRLs to combine, originally signed by the requested issuer.
delta_crl_base_number	integer (default: -1)	no	Using a zero or greater value specifies the base CRL revision number to encode within a Delta CRL indicator extension, otherwise the extension will not be added.
format	string (default: pem)	no	The format of the combined CRL, can be "pem" or "der". If "der", the value will be base64 encoded. Defaults to "pem".
next_update	string (default: 72h)	no	The amount of time the generated CRL should be valid; defaults to 72 hours.

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no	CRL

POST /{pki_mount_path}/issuer/{issuer_ref}/revoke

Operation ID: pki-revoke-issuer

Revoke the specified issuer certificate.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	Certificate Authority Chain
certificate	string	no	Certificate
crl_distribution_points	array	no	Specifies the URL values for the CRL Distribution Points field
issuer_id	string	no	ID of the issuer
issuer_name	string	no	Name of the issuer
issuing_certificates	array	no	Specifies the URL values for the Issuing Certificate field
key_id	string	no	ID of the Key
leaf_not_after_behavior	string	no
manual_chain	array	no	Manual Chain
ocsp_servers	array	no	Specifies the URL values for the OCSP Servers field
revocation_signature_algorithm	string	no	Which signature algorithm to use when building CRLs
revocation_time	integer	no	Time of revocation
revocation_time_rfc3339	string	no	RFC formatted time of revocation
revoked	boolean	no	Whether the issuer was revoked
usage	string	no	Allowed usage

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/account/{kid}

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-account-kid

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
kid	string	path	yes	The key identifier provided by the CA
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/authorization/{auth_id}

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-authorization-auth_id

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
auth_id	string	path	yes	ACME authorization identifier value
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/challenge/{auth_id}/{challenge_type}

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-challenge-auth_id-challenge_type

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
auth_id	string	path	yes	ACME authorization identifier value
challenge_type	string	path	yes	ACME challenge type
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

GET /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/directory

Operation ID: pki-read-issuer-issuer_ref-roles-role-acme-directory

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/new-account

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-new-account

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/new-eab

Operation ID: pki-generate-eab-key-for-issuer-and-role

Generate external account bindings to be used for ACME

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
acme_directory	string	no	The ACME directory to which the key belongs
created_on	string	no	An RFC3339 formatted date time when the EAB token was created
id	string	no	The EAB key identifier
key	string	no	The EAB hmac key
key_type	string	no	The EAB key type

GET /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/new-nonce

Operation ID: pki-read-issuer-issuer_ref-roles-role-acme-new-nonce

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/new-order

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-new-order

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/order/{order_id}

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-order-order_id

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
order_id	string	path	yes	The ACME order identifier to fetch
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/order/{order_id}/cert

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-order-order_id-cert

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
order_id	string	path	yes	The ACME order identifier to fetch
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/order/{order_id}/finalize

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-order-order_id-finalize

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
order_id	string	path	yes	The ACME order identifier to fetch
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/orders

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-orders

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/roles/{role}/acme/revoke-cert

Operation ID: pki-write-issuer-issuer_ref-roles-role-acme-revoke-cert

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to an existing issuer name or issuer id
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/issuer/{issuer_ref}/sign-intermediate

Operation ID: pki-issuer-sign-intermediate

Issue an intermediate CA certificate based on the provided CSR.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. May contain both DNS names and email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If not specified when signing, the common name will be taken from the CSR; other names must still be specified in alt_names or ip_sans.
country	array	no	If set, Country will be set to this value.
csr	string (default: )	no	PEM-format CSR to be signed.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
issuer_name	string	no	Provide a name to the generated or existing issuer, the name must be unique across all issuers and not be the reserved value 'default'
locality	array	no	If set, Locality will be set to this value.
max_path_length	integer (default: -1)	no	The maximum allowable path length
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
not_before_duration	integer (default: 30)	no	The duration before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value.
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value.
permitted_dns_domains	array	no	Domains for which this certificate is allowed to sign or issue child certificates. If set, all DNS names (subject and alt) on child certs must be exact matches or subsets of the given domains (see https://tools.ietf.org/html/rfc5280#section-4.2.1.10).
postal_code	array	no	If set, Postal Code will be set to this value.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
province	array	no	If set, Province will be set to this value.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
skid	string (default: )	no	Value for the Subject Key Identifier field (RFC 5280 Section 4.2.1.2). This value should ONLY be used when cross-signing to mimic the existing certificate's SKID value; this is necessary to allow certain TLS implementations (such as OpenSSL) which use SKID/AKID matches in chain building to restrict possible valid chains. Specified as a string in hex format. Default is empty, allowing Vault to automatically calculate the SKID according to method one in the above RFC section.
street_address	array	no	If set, Street Address will be set to this value.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the mount max TTL. Note: this only has an effect when generating a CA cert or signing a CA cert, not when generating a CSR for an intermediate CA.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
use_csr_values	boolean (default: False)	no	If true, then: 1) Subject information, including names and alternate names, will be preserved from the CSR rather than using values provided in the other parameters to this path; 2) Any key usages requested in the CSR will be added to the basic set of key usages used for CA certs signed by this path; for instance, the non-repudiation flag; 3) Extensions requested in the CSR will be copied into the issued certificate.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	CA Chain
certificate	string	no	Certificate
expiration	integer	no	Expiration Time
issuing_ca	string	no	Issuing CA
serial_number	string	no	Serial Number

POST /{pki_mount_path}/issuer/{issuer_ref}/sign-revocation-list

Operation ID: pki-issuer-sign-revocation-list

Generate and sign a CRL based on the provided parameters.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
crl_number	integer	no	The sequence number to be written within the CRL Number extension.
delta_crl_base_number	integer (default: -1)	no	Using a zero or greater value specifies the base CRL revision number to encode within a Delta CRL indicator extension, otherwise the extension will not be added.
extensions	array	no	A list of maps containing extensions with keys id (string), critical (bool), value (string)
format	string (default: pem)	no	The format of the combined CRL, can be "pem" or "der". If "der", the value will be base64 encoded. Defaults to "pem".
next_update	string (default: 72h)	no	The amount of time the generated CRL should be valid; defaults to 72 hours.
revoked_certs	array	no	A list of maps containing the keys serial_number (string), revocation_time (string), and extensions (map with keys id (string), critical (bool), value (string))

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no	CRL

POST /{pki_mount_path}/issuer/{issuer_ref}/sign-self-issued

Operation ID: pki-issuer-sign-self-issued

Re-issue a self-signed certificate based on the provided certificate.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
certificate	string	no	PEM-format self-issued certificate to be signed.
require_matching_certificate_algorithms	boolean (default: False)	no	If true, require the public key algorithm of the signer to match that of the self issued certificate.

Responses

200: OK

Parameter	Type	Required	Description
certificate	string	no	Certificate
issuing_ca	string	no	Issuing CA

POST /{pki_mount_path}/issuer/{issuer_ref}/sign-verbatim

Operation ID: pki-issuer-sign-verbatim

Issue a certificate directly based on the provided CSR.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. If email protection is enabled for the role, this may contain email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If email protection is enabled in the role, this may be an email address.
csr	string (default: )	no	PEM-format CSR to be signed. Values will be taken verbatim from the CSR, except for basic constraints.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
ext_key_usage	array (default: [])	no	A comma-separated string or list of extended key usages. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage -- simply drop the "ExtKeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list.
ext_key_usage_oids	array	no	A comma-separated string or list of extended key usage oids.
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
key_usage	array (default: ['DigitalSignature', 'KeyAgreement', 'KeyEncipherment'])	no	A comma-separated string or list of key usages (not extended key usages). Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the "KeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list.
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
remove_roots_from_chain	boolean (default: False)	no	Whether or not to remove self-signed CA certificates in the output of the ca_chain field.
role	string	no	The desired role with configuration for this request
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the role max TTL.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.
user_ids	array	no	The requested user_ids value to place in the subject, if any, in a comma-delimited list. Restricted by allowed_user_ids. Any values are added with OID 0.9.2342.19200300.100.1.1.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	Certificate Chain
certificate	string	no	Certificate
expiration	integer	no	Time of expiration
issuing_ca	string	no	Issuing Certificate Authority
private_key	string	no	Private key
private_key_type	string	no	Private key type
serial_number	string	no	Serial Number

POST /{pki_mount_path}/issuer/{issuer_ref}/sign-verbatim/{role}

Operation ID: pki-issuer-sign-verbatim-with-role

Issue a certificate directly based on the provided CSR.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
role	string	path	yes	The desired role with configuration for this request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. If email protection is enabled for the role, this may contain email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If email protection is enabled in the role, this may be an email address.
csr	string (default: )	no	PEM-format CSR to be signed. Values will be taken verbatim from the CSR, except for basic constraints.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
ext_key_usage	array (default: [])	no	A comma-separated string or list of extended key usages. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage -- simply drop the "ExtKeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list.
ext_key_usage_oids	array	no	A comma-separated string or list of extended key usage oids.
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
key_usage	array (default: ['DigitalSignature', 'KeyAgreement', 'KeyEncipherment'])	no	A comma-separated string or list of key usages (not extended key usages). Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the "KeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list.
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
remove_roots_from_chain	boolean (default: False)	no	Whether or not to remove self-signed CA certificates in the output of the ca_chain field.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the role max TTL.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.
user_ids	array	no	The requested user_ids value to place in the subject, if any, in a comma-delimited list. Restricted by allowed_user_ids. Any values are added with OID 0.9.2342.19200300.100.1.1.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	Certificate Chain
certificate	string	no	Certificate
expiration	integer	no	Time of expiration
issuing_ca	string	no	Issuing Certificate Authority
private_key	string	no	Private key
private_key_type	string	no	Private key type
serial_number	string	no	Serial Number

POST /{pki_mount_path}/issuer/{issuer_ref}/sign/{role}

Operation ID: pki-issuer-sign-with-role

Request certificates using a certain role with the provided details.

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
role	string	path	yes	The desired role with configuration for this request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. If email protection is enabled for the role, this may contain email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If email protection is enabled in the role, this may be an email address.
csr	string (default: )	no	PEM-format CSR to be signed.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
remove_roots_from_chain	boolean (default: False)	no	Whether or not to remove self-signed CA certificates in the output of the ca_chain field.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the role max TTL.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
user_ids	array	no	The requested user_ids value to place in the subject, if any, in a comma-delimited list. Restricted by allowed_user_ids. Any values are added with OID 0.9.2342.19200300.100.1.1.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	Certificate Chain
certificate	string	no	Certificate
expiration	integer	no	Time of expiration
issuing_ca	string	no	Issuing Certificate Authority
private_key	string	no	Private key
private_key_type	string	no	Private key type
serial_number	string	no	Serial Number

GET /{pki_mount_path}/issuer/{issuer_ref}/unified-crl

Operation ID: pki-issuer-read-unified-crl

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/unified-crl/delta

Operation ID: pki-issuer-read-unified-crl-delta

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/unified-crl/delta/der

Operation ID: pki-issuer-read-unified-crl-delta-der

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/unified-crl/delta/pem

Operation ID: pki-issuer-read-unified-crl-delta-pem

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/unified-crl/der

Operation ID: pki-issuer-read-unified-crl-der

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuer/{issuer_ref}/unified-crl/pem

Operation ID: pki-issuer-read-unified-crl-pem

Fetch an issuer's Certificate Revocation Log (CRL).

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
issuer_ref	string	path	yes	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
crl	string	no

GET /{pki_mount_path}/issuers

Operation ID: pki-list-issuers

Fetch a list of CA certificates.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
key_info	object	no	Key info with issuer name
keys	array	no	A list of keys

POST /{pki_mount_path}/issuers/generate/intermediate/{exported}

Operation ID: pki-issuers-generate-intermediate

Generate a new CSR and private key used for signing.

Parameters

Parameter	Type	Location	Required	Description
exported	string (internal, external, kms)	path	yes	Must be "internal", "exported" or "kms". If set to "exported", the generated private key will be returned. This is your only chance to retrieve the private key!
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
add_basic_constraints	boolean	no	Whether to add a Basic Constraints extension with CA: true. Only needed as a workaround in some compatibility scenarios with Active Directory Certificate Services.
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. May contain both DNS names and email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If not specified when signing, the common name will be taken from the CSR; other names must still be specified in alt_names or ip_sans.
country	array	no	If set, Country will be set to this value.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_name	string	no	Provide a name to the generated or existing key, the name must be unique across all keys and not be the reserved value 'default'
key_ref	string (default: default)	no	Reference to a existing key; either "default" for the configured default key, an identifier or the name assigned to the key.
key_type	string (rsa, ec, ed25519) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
locality	array	no	If set, Locality will be set to this value.
managed_key_id	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_name is required. Ignored for other types.
managed_key_name	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_id is required. Ignored for other types.
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
not_before_duration	integer (default: 30)	no	The duration before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value.
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value.
postal_code	array	no	If set, Postal Code will be set to this value.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
province	array	no	If set, Province will be set to this value.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
street_address	array	no	If set, Street Address will be set to this value.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the mount max TTL. Note: this only has an effect when generating a CA cert or signing a CA cert, not when generating a CSR for an intermediate CA.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.

Responses

200: OK

Parameter	Type	Required	Description
csr	string	no	Certificate signing request.
key_id	string	no	Id of the key.
private_key	string	no	Generated private key.
private_key_type	string	no	Specifies the format used for marshaling the private key.

POST /{pki_mount_path}/issuers/generate/root/{exported}

Operation ID: pki-issuers-generate-root

Generate a new CA certificate and private key used for signing.

Parameters

Parameter	Type	Location	Required	Description
exported	string (internal, external, kms)	path	yes	Must be "internal", "exported" or "kms". If set to "exported", the generated private key will be returned. This is your only chance to retrieve the private key!
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. May contain both DNS names and email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If not specified when signing, the common name will be taken from the CSR; other names must still be specified in alt_names or ip_sans.
country	array	no	If set, Country will be set to this value.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
issuer_name	string	no	Provide a name to the generated or existing issuer, the name must be unique across all issuers and not be the reserved value 'default'
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_name	string	no	Provide a name to the generated or existing key, the name must be unique across all keys and not be the reserved value 'default'
key_ref	string (default: default)	no	Reference to a existing key; either "default" for the configured default key, an identifier or the name assigned to the key.
key_type	string (rsa, ec, ed25519) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
locality	array	no	If set, Locality will be set to this value.
managed_key_id	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_name is required. Ignored for other types.
managed_key_name	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_id is required. Ignored for other types.
max_path_length	integer (default: -1)	no	The maximum allowable path length
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
not_before_duration	integer (default: 30)	no	The duration before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value.
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value.
permitted_dns_domains	array	no	Domains for which this certificate is allowed to sign or issue child certificates. If set, all DNS names (subject and alt) on child certs must be exact matches or subsets of the given domains (see https://tools.ietf.org/html/rfc5280#section-4.2.1.10).
postal_code	array	no	If set, Postal Code will be set to this value.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
province	array	no	If set, Province will be set to this value.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
street_address	array	no	If set, Street Address will be set to this value.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the mount max TTL. Note: this only has an effect when generating a CA cert or signing a CA cert, not when generating a CSR for an intermediate CA.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.

Responses

200: OK

Parameter	Type	Required	Description
certificate	string	no	The generated self-signed CA certificate.
expiration	integer	no	The expiration of the given issuer.
issuer_id	string	no	The ID of the issuer
issuer_name	string	no	The name of the issuer.
issuing_ca	string	no	The issuing certificate authority.
key_id	string	no	The ID of the key.
key_name	string	no	The key name if given.
private_key	string	no	The private key if exported was specified.
serial_number	string	no	The requested Subject's named serial number.

POST /{pki_mount_path}/issuers/import/bundle

Operation ID: pki-issuers-import-bundle

Import the specified issuing certificates.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
pem_bundle	string	no	PEM-format, concatenated unencrypted secret-key (optional) and certificates.

Responses

200: OK

Parameter	Type	Required	Description
existing_issuers	array	no	Existing issuers specified as part of the import bundle of this request
existing_keys	array	no	Existing keys specified as part of the import bundle of this request
imported_issuers	array	no	Net-new issuers imported as a part of this request
imported_keys	array	no	Net-new keys imported as a part of this request
mapping	object	no	A mapping of issuer_id to key_id for all issuers included in this request

POST /{pki_mount_path}/issuers/import/cert

Operation ID: pki-issuers-import-cert

Import the specified issuing certificates.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
pem_bundle	string	no	PEM-format, concatenated unencrypted secret-key (optional) and certificates.

Responses

200: OK

Parameter	Type	Required	Description
existing_issuers	array	no	Existing issuers specified as part of the import bundle of this request
existing_keys	array	no	Existing keys specified as part of the import bundle of this request
imported_issuers	array	no	Net-new issuers imported as a part of this request
imported_keys	array	no	Net-new keys imported as a part of this request
mapping	object	no	A mapping of issuer_id to key_id for all issuers included in this request

GET /{pki_mount_path}/key/{key_ref}

Operation ID: pki-read-key

Fetch a single issuer key

Parameters

Parameter	Type	Location	Required	Description
key_ref	string	path	yes	Reference to key; either "default" for the configured default key, an identifier of a key, or the name assigned to the key.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
key_id	string	no	Key Id
key_name	string	no	Key Name
key_type	string	no	Key Type
managed_key_id	string	no	Managed Key Id
managed_key_name	string	no	Managed Key Name
subject_key_id	string	no	RFC 5280 Subject Key Identifier of the public counterpart

POST /{pki_mount_path}/key/{key_ref}

Operation ID: pki-write-key

Fetch a single issuer key

Parameters

Parameter	Type	Location	Required	Description
key_ref	string	path	yes	Reference to key; either "default" for the configured default key, an identifier of a key, or the name assigned to the key.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
key_name	string	no	Human-readable name for this key.

Responses

204: OK

Parameter	Type	Required	Description
key_id	string	no	Key Id
key_name	string	no	Key Name
key_type	string	no	Key Type

DELETE /{pki_mount_path}/key/{key_ref}

Operation ID: pki-delete-key

Fetch a single issuer key

Parameters

Parameter	Type	Location	Required	Description
key_ref	string	path	yes	Reference to key; either "default" for the configured default key, an identifier of a key, or the name assigned to the key.
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

GET /{pki_mount_path}/keys

Operation ID: pki-list-keys

Fetch a list of all issuer keys

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
key_info	object	no	Key info with issuer name
keys	array	no	A list of keys

POST /{pki_mount_path}/keys/generate/exported

Operation ID: pki-generate-exported-key

Generate a new private key used for signing.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_name	string	no	Optional name to be used for this key
key_type	string (rsa, ec, ed25519) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
managed_key_id	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_name is required. Ignored for other types.
managed_key_name	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_id is required. Ignored for other types.

Responses

200: OK

Parameter	Type	Required	Description
key_id	string	no	ID assigned to this key.
key_name	string	no	Name assigned to this key.
key_type	string	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
private_key	string	no	The private key string

POST /{pki_mount_path}/keys/generate/internal

Operation ID: pki-generate-internal-key

Generate a new private key used for signing.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_name	string	no	Optional name to be used for this key
key_type	string (rsa, ec, ed25519) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
managed_key_id	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_name is required. Ignored for other types.
managed_key_name	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_id is required. Ignored for other types.

Responses

200: OK

Parameter	Type	Required	Description
key_id	string	no	ID assigned to this key.
key_name	string	no	Name assigned to this key.
key_type	string	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
private_key	string	no	The private key string

POST /{pki_mount_path}/keys/generate/kms

Operation ID: pki-generate-kms-key

Generate a new private key used for signing.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_name	string	no	Optional name to be used for this key
key_type	string (rsa, ec, ed25519) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
managed_key_id	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_name is required. Ignored for other types.
managed_key_name	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_id is required. Ignored for other types.

Responses

200: OK

Parameter	Type	Required	Description
key_id	string	no	ID assigned to this key.
key_name	string	no	Name assigned to this key.
key_type	string	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
private_key	string	no	The private key string

POST /{pki_mount_path}/keys/import

Operation ID: pki-import-key

Import the specified key.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
key_name	string	no	Optional name to be used for this key
pem_bundle	string	no	PEM-format, unencrypted secret key

Responses

200: OK

Parameter	Type	Required	Description
key_id	string	no	ID assigned to this key.
key_name	string	no	Name assigned to this key.
key_type	string	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.

POST /{pki_mount_path}/ocsp

Operation ID: pki-query-ocsp

Query a certificate's revocation status through OCSP'

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{pki_mount_path}/ocsp/{req}

Operation ID: pki-query-ocsp-with-get-req

Query a certificate's revocation status through OCSP'

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
req	string	path	yes	base-64 encoded ocsp request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/revoke

Operation ID: pki-revoke

Revoke a certificate by serial number or with explicit certificate. When calling /revoke-with-key, the private key corresponding to the certificate must be provided to authenticate the request.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
certificate	string	no	Certificate to revoke in PEM format; must be signed by an issuer in this mount.
serial_number	string	no	Certificate serial number, in colon- or hyphen-separated octal

Responses

200: OK

Parameter	Type	Required	Description
revocation_time	integer	no	Revocation Time
revocation_time_rfc3339	string	no	Revocation Time
state	string	no	Revocation State

POST /{pki_mount_path}/revoke-with-key

Operation ID: pki-revoke-with-key

Revoke a certificate by serial number or with explicit certificate. When calling /revoke-with-key, the private key corresponding to the certificate must be provided to authenticate the request.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
certificate	string	no	Certificate to revoke in PEM format; must be signed by an issuer in this mount.
private_key	string	no	Key to use to verify revocation permission; must be in PEM format.
serial_number	string	no	Certificate serial number, in colon- or hyphen-separated octal

Responses

200: OK

Parameter	Type	Required	Description
revocation_time	integer	no	Revocation Time
revocation_time_rfc3339	string	no	Revocation Time
state	string	no	Revocation State

GET /{pki_mount_path}/roles

Operation ID: pki-list-roles

List the existing roles in this backend

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no	List of roles

GET /{pki_mount_path}/roles/{name}

Operation ID: pki-read-role

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
allow_any_name	boolean	no	If set, clients can request certificates for any domain, regardless of allowed_domains restrictions. See the documentation for more information.
allow_bare_domains	boolean	no	If set, clients can request certificates for the base domains themselves, e.g. "example.com" of domains listed in allowed_domains. This is a separate option as in some cases this can be considered a security threat. See the documentation for more information.
allow_glob_domains	boolean	no	If set, domains specified in allowed_domains can include shell-style glob patterns, e.g. "ftp*.example.com". See the documentation for more information.
allow_ip_sans	boolean	no	If set, IP Subject Alternative Names are allowed. Any valid IP is accepted and No authorization checking is performed.
allow_localhost	boolean	no	Whether to allow "localhost" and "localdomain" as a valid common name in a request, independent of allowed_domains value.
allow_subdomains	boolean	no	If set, clients can request certificates for subdomains of domains listed in allowed_domains, including wildcard subdomains. See the documentation for more information.
allow_token_displayname	boolean	no	Whether to allow "localhost" and "localdomain" as a valid common name in a request, independent of allowed_domains value.
allow_wildcard_certificates	boolean	no	If set, allows certificates with wildcards in the common name to be issued, conforming to RFC 6125's Section 6.4.3; e.g., ".example.net" or "bz.example.net". See the documentation for more information.
allowed_domains	array	no	Specifies the domains this role is allowed to issue certificates for. This is used with the allow_bare_domains, allow_subdomains, and allow_glob_domains to determine matches for the common name, DNS-typed SAN entries, and Email-typed SAN entries of certificates. See the documentation for more information. This parameter accepts a comma-separated string or list of domains.
allowed_domains_template	boolean	no	If set, Allowed domains can be specified using identity template policies. Non-templated domains are also permitted.
allowed_other_sans	array	no	If set, an array of allowed other names to put in SANs. These values support globbing and must be in the format ;:. Currently only "utf8" is a valid type. All values, including globbing values, must use this syntax, with the exception being a single "*" which allows any OID and any value (but type must still be utf8).
allowed_serial_numbers	array	no	If set, an array of allowed serial numbers to put in Subject. These values support globbing.
allowed_uri_sans	array	no	If set, an array of allowed URIs for URI Subject Alternative Names. Any valid URI is accepted, these values support globbing.
allowed_uri_sans_template	boolean	no	If set, Allowed URI SANs can be specified using identity template policies. Non-templated URI SANs are also permitted.
allowed_user_ids	array	no	If set, an array of allowed user-ids to put in user system login name specified here: https://www.rfc-editor.org/rfc/rfc1274#section-9.3.1
basic_constraints_valid_for_non_ca	boolean	no	Mark Basic Constraints valid when issuing non-CA certificates.
client_flag	boolean	no	If set, certificates are flagged for client auth use. Defaults to true. See also RFC 5280 Section 4.2.1.12.
cn_validations	array	no	List of allowed validations to run against the Common Name field. Values can include 'email' to validate the CN is a email address, 'hostname' to validate the CN is a valid hostname (potentially including wildcards). When multiple validations are specified, these take OR semantics (either email OR hostname are allowed). The special value 'disabled' allows disabling all CN name validations, allowing for arbitrary non-Hostname, non-Email address CNs.
code_signing_flag	boolean	no	If set, certificates are flagged for code signing use. Defaults to false. See also RFC 5280 Section 4.2.1.12.
country	array	no	If set, Country will be set to this value in certificates issued by this role.
email_protection_flag	boolean	no	If set, certificates are flagged for email protection use. Defaults to false. See also RFC 5280 Section 4.2.1.12.
enforce_hostnames	boolean	no	If set, only valid host names are allowed for CN and DNS SANs, and the host part of email addresses. Defaults to true.
ext_key_usage	array	no	A comma-separated string or list of extended key usages. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage -- simply drop the "ExtKeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list. See also RFC 5280 Section 4.2.1.12.
ext_key_usage_oids	array	no	A comma-separated string or list of extended key usage oids.
generate_lease	boolean	no	If set, certificates issued/signed against this role will have Vault leases attached to them. Defaults to "false". Certificates can be added to the CRL by "vault revoke " when certificates are associated with leases. It can also be done using the "pki/revoke" endpoint. However, when lease generation is disabled, invoking "pki/revoke" would be the only way to add the certificates to the CRL. When large number of certificates are generated with long lifetimes, it is recommended that lease generation be disabled, as large amount of leases adversely affect the startup time of Vault.
issuer_ref	string	no	Reference to the issuer used to sign requests serviced by this role.
key_bits	integer	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_type	string	no	The type of key to use; defaults to RSA. "rsa" "ec", "ed25519" and "any" are the only valid values.
key_usage	array	no	A comma-separated string or list of key usages (not extended key usages). Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the "KeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list. See also RFC 5280 Section 4.2.1.3.
locality	array	no	If set, Locality will be set to this value in certificates issued by this role.
max_ttl	integer	no	The maximum allowed lease duration. If not set, defaults to the system maximum lease TTL.
no_store	boolean	no	If set, certificates issued/signed against this role will not be stored in the storage backend. This can improve performance when issuing large numbers of certificates. However, certificates issued in this way cannot be enumerated or revoked, so this option is recommended only for certificates that are non-sensitive, or extremely short-lived. This option implies a value of "false" for "generate_lease".
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ.
not_before_duration	integer	no	The duration in seconds before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value in certificates issued by this role.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value in certificates issued by this role.
policy_identifiers	array	no	A comma-separated string or list of policy OIDs, or a JSON list of qualified policy information, which must include an oid, and may include a notice and/or cps url, using the form [{"oid"="1.3.6.1.4.1.7.8","notice"="I am a user Notice"}, {"oid"="1.3.6.1.4.1.44947.1.2.4 ","cps"="https://example.com"}].
postal_code	array	no	If set, Postal Code will be set to this value in certificates issued by this role.
province	array	no	If set, Province will be set to this value in certificates issued by this role.
require_cn	boolean	no	If set to false, makes the 'common_name' field optional while generating a certificate.
server_flag	boolean (default: True)	no	If set, certificates are flagged for server auth use. Defaults to true. See also RFC 5280 Section 4.2.1.12.
signature_bits	integer	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
street_address	array	no	If set, Street Address will be set to this value in certificates issued by this role.
ttl	integer	no	The lease duration (validity period of the certificate) if no specific lease duration is requested. The lease duration controls the expiration of certificates issued by this backend. Defaults to the system default value or the value of max_ttl, whichever is shorter.
use_csr_common_name	boolean	no	If set, when used with a signing profile, the common name in the CSR will be used. This does not include any requested Subject Alternative Names; use use_csr_sans for that. Defaults to true.
use_csr_sans	boolean	no	If set, when used with a signing profile, the SANs in the CSR will be used. This does not include the Common Name (cn); use use_csr_common_name for that. Defaults to true.
use_pss	boolean	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.

POST /{pki_mount_path}/roles/{name}

Operation ID: pki-write-role

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
allow_any_name	boolean	no	If set, clients can request certificates for any domain, regardless of allowed_domains restrictions. See the documentation for more information.
allow_bare_domains	boolean	no	If set, clients can request certificates for the base domains themselves, e.g. "example.com" of domains listed in allowed_domains. This is a separate option as in some cases this can be considered a security threat. See the documentation for more information.
allow_glob_domains	boolean	no	If set, domains specified in allowed_domains can include shell-style glob patterns, e.g. "ftp*.example.com". See the documentation for more information.
allow_ip_sans	boolean (default: True)	no	If set, IP Subject Alternative Names are allowed. Any valid IP is accepted and No authorization checking is performed.
allow_localhost	boolean (default: True)	no	Whether to allow "localhost" and "localdomain" as a valid common name in a request, independent of allowed_domains value.
allow_subdomains	boolean	no	If set, clients can request certificates for subdomains of domains listed in allowed_domains, including wildcard subdomains. See the documentation for more information.
allow_wildcard_certificates	boolean (default: True)	no	If set, allows certificates with wildcards in the common name to be issued, conforming to RFC 6125's Section 6.4.3; e.g., ".example.net" or "bz.example.net". See the documentation for more information.
allowed_domains	array	no	Specifies the domains this role is allowed to issue certificates for. This is used with the allow_bare_domains, allow_subdomains, and allow_glob_domains to determine matches for the common name, DNS-typed SAN entries, and Email-typed SAN entries of certificates. See the documentation for more information. This parameter accepts a comma-separated string or list of domains.
allowed_domains_template	boolean (default: False)	no	If set, Allowed domains can be specified using identity template policies. Non-templated domains are also permitted.
allowed_other_sans	array	no	If set, an array of allowed other names to put in SANs. These values support globbing and must be in the format ;:. Currently only "utf8" is a valid type. All values, including globbing values, must use this syntax, with the exception being a single "*" which allows any OID and any value (but type must still be utf8).
allowed_serial_numbers	array	no	If set, an array of allowed serial numbers to put in Subject. These values support globbing.
allowed_uri_sans	array	no	If set, an array of allowed URIs for URI Subject Alternative Names. Any valid URI is accepted, these values support globbing.
allowed_uri_sans_template	boolean (default: False)	no	If set, Allowed URI SANs can be specified using identity template policies. Non-templated URI SANs are also permitted.
allowed_user_ids	array	no	If set, an array of allowed user-ids to put in user system login name specified here: https://www.rfc-editor.org/rfc/rfc1274#section-9.3.1
backend	string	no	Backend Type
basic_constraints_valid_for_non_ca	boolean	no	Mark Basic Constraints valid when issuing non-CA certificates.
client_flag	boolean (default: True)	no	If set, certificates are flagged for client auth use. Defaults to true. See also RFC 5280 Section 4.2.1.12.
cn_validations	array (default: ['email', 'hostname'])	no	List of allowed validations to run against the Common Name field. Values can include 'email' to validate the CN is a email address, 'hostname' to validate the CN is a valid hostname (potentially including wildcards). When multiple validations are specified, these take OR semantics (either email OR hostname are allowed). The special value 'disabled' allows disabling all CN name validations, allowing for arbitrary non-Hostname, non-Email address CNs.
code_signing_flag	boolean	no	If set, certificates are flagged for code signing use. Defaults to false. See also RFC 5280 Section 4.2.1.12.
country	array	no	If set, Country will be set to this value in certificates issued by this role.
email_protection_flag	boolean	no	If set, certificates are flagged for email protection use. Defaults to false. See also RFC 5280 Section 4.2.1.12.
enforce_hostnames	boolean (default: True)	no	If set, only valid host names are allowed for CN and DNS SANs, and the host part of email addresses. Defaults to true.
ext_key_usage	array (default: [])	no	A comma-separated string or list of extended key usages. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage -- simply drop the "ExtKeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list. See also RFC 5280 Section 4.2.1.12.
ext_key_usage_oids	array	no	A comma-separated string or list of extended key usage oids.
generate_lease	boolean	no	If set, certificates issued/signed against this role will have Vault leases attached to them. Defaults to "false". Certificates can be added to the CRL by "vault revoke " when certificates are associated with leases. It can also be done using the "pki/revoke" endpoint. However, when lease generation is disabled, invoking "pki/revoke" would be the only way to add the certificates to the CRL. When large number of certificates are generated with long lifetimes, it is recommended that lease generation be disabled, as large amount of leases adversely affect the startup time of Vault.
issuer_ref	string (default: default)	no	Reference to the issuer used to sign requests serviced by this role.
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_type	string (rsa, ec, ed25519, any) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec", "ed25519" and "any" are the only valid values.
key_usage	array (default: ['DigitalSignature', 'KeyAgreement', 'KeyEncipherment'])	no	A comma-separated string or list of key usages (not extended key usages). Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the "KeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list. See also RFC 5280 Section 4.2.1.3.
locality	array	no	If set, Locality will be set to this value in certificates issued by this role.
max_ttl	integer	no	The maximum allowed lease duration. If not set, defaults to the system maximum lease TTL.
no_store	boolean	no	If set, certificates issued/signed against this role will not be stored in the storage backend. This can improve performance when issuing large numbers of certificates. However, certificates issued in this way cannot be enumerated or revoked, so this option is recommended only for certificates that are non-sensitive, or extremely short-lived. This option implies a value of "false" for "generate_lease".
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ.
not_before_duration	integer (default: 30)	no	The duration before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value in certificates issued by this role.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value in certificates issued by this role.
policy_identifiers	array	no	A comma-separated string or list of policy OIDs, or a JSON list of qualified policy information, which must include an oid, and may include a notice and/or cps url, using the form [{"oid"="1.3.6.1.4.1.7.8","notice"="I am a user Notice"}, {"oid"="1.3.6.1.4.1.44947.1.2.4 ","cps"="https://example.com"}].
postal_code	array	no	If set, Postal Code will be set to this value in certificates issued by this role.
province	array	no	If set, Province will be set to this value in certificates issued by this role.
require_cn	boolean (default: True)	no	If set to false, makes the 'common_name' field optional while generating a certificate.
server_flag	boolean (default: True)	no	If set, certificates are flagged for server auth use. Defaults to true. See also RFC 5280 Section 4.2.1.12.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
street_address	array	no	If set, Street Address will be set to this value in certificates issued by this role.
ttl	integer	no	The lease duration (validity period of the certificate) if no specific lease duration is requested. The lease duration controls the expiration of certificates issued by this backend. Defaults to the system default value or the value of max_ttl, whichever is shorter.
use_csr_common_name	boolean (default: True)	no	If set, when used with a signing profile, the common name in the CSR will be used. This does not include any requested Subject Alternative Names; use use_csr_sans for that. Defaults to true.
use_csr_sans	boolean (default: True)	no	If set, when used with a signing profile, the SANs in the CSR will be used. This does not include the Common Name (cn); use use_csr_common_name for that. Defaults to true.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.

Responses

200: OK

Parameter	Type	Required	Description
allow_any_name	boolean	no	If set, clients can request certificates for any domain, regardless of allowed_domains restrictions. See the documentation for more information.
allow_bare_domains	boolean	no	If set, clients can request certificates for the base domains themselves, e.g. "example.com" of domains listed in allowed_domains. This is a separate option as in some cases this can be considered a security threat. See the documentation for more information.
allow_glob_domains	boolean	no	If set, domains specified in allowed_domains can include shell-style glob patterns, e.g. "ftp*.example.com". See the documentation for more information.
allow_ip_sans	boolean	no	If set, IP Subject Alternative Names are allowed. Any valid IP is accepted and No authorization checking is performed.
allow_localhost	boolean	no	Whether to allow "localhost" and "localdomain" as a valid common name in a request, independent of allowed_domains value.
allow_subdomains	boolean	no	If set, clients can request certificates for subdomains of domains listed in allowed_domains, including wildcard subdomains. See the documentation for more information.
allow_token_displayname	boolean	no	Whether to allow "localhost" and "localdomain" as a valid common name in a request, independent of allowed_domains value.
allow_wildcard_certificates	boolean	no	If set, allows certificates with wildcards in the common name to be issued, conforming to RFC 6125's Section 6.4.3; e.g., ".example.net" or "bz.example.net". See the documentation for more information.
allowed_domains	array	no	Specifies the domains this role is allowed to issue certificates for. This is used with the allow_bare_domains, allow_subdomains, and allow_glob_domains to determine matches for the common name, DNS-typed SAN entries, and Email-typed SAN entries of certificates. See the documentation for more information. This parameter accepts a comma-separated string or list of domains.
allowed_domains_template	boolean	no	If set, Allowed domains can be specified using identity template policies. Non-templated domains are also permitted.
allowed_other_sans	array	no	If set, an array of allowed other names to put in SANs. These values support globbing and must be in the format ;:. Currently only "utf8" is a valid type. All values, including globbing values, must use this syntax, with the exception being a single "*" which allows any OID and any value (but type must still be utf8).
allowed_serial_numbers	array	no	If set, an array of allowed serial numbers to put in Subject. These values support globbing.
allowed_uri_sans	array	no	If set, an array of allowed URIs for URI Subject Alternative Names. Any valid URI is accepted, these values support globbing.
allowed_uri_sans_template	boolean	no	If set, Allowed URI SANs can be specified using identity template policies. Non-templated URI SANs are also permitted.
allowed_user_ids	array	no	If set, an array of allowed user-ids to put in user system login name specified here: https://www.rfc-editor.org/rfc/rfc1274#section-9.3.1
basic_constraints_valid_for_non_ca	boolean	no	Mark Basic Constraints valid when issuing non-CA certificates.
client_flag	boolean	no	If set, certificates are flagged for client auth use. Defaults to true. See also RFC 5280 Section 4.2.1.12.
cn_validations	array	no	List of allowed validations to run against the Common Name field. Values can include 'email' to validate the CN is a email address, 'hostname' to validate the CN is a valid hostname (potentially including wildcards). When multiple validations are specified, these take OR semantics (either email OR hostname are allowed). The special value 'disabled' allows disabling all CN name validations, allowing for arbitrary non-Hostname, non-Email address CNs.
code_signing_flag	boolean	no	If set, certificates are flagged for code signing use. Defaults to false. See also RFC 5280 Section 4.2.1.12.
country	array	no	If set, Country will be set to this value in certificates issued by this role.
email_protection_flag	boolean	no	If set, certificates are flagged for email protection use. Defaults to false. See also RFC 5280 Section 4.2.1.12.
enforce_hostnames	boolean	no	If set, only valid host names are allowed for CN and DNS SANs, and the host part of email addresses. Defaults to true.
ext_key_usage	array	no	A comma-separated string or list of extended key usages. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage -- simply drop the "ExtKeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list. See also RFC 5280 Section 4.2.1.12.
ext_key_usage_oids	array	no	A comma-separated string or list of extended key usage oids.
generate_lease	boolean	no	If set, certificates issued/signed against this role will have Vault leases attached to them. Defaults to "false". Certificates can be added to the CRL by "vault revoke " when certificates are associated with leases. It can also be done using the "pki/revoke" endpoint. However, when lease generation is disabled, invoking "pki/revoke" would be the only way to add the certificates to the CRL. When large number of certificates are generated with long lifetimes, it is recommended that lease generation be disabled, as large amount of leases adversely affect the startup time of Vault.
issuer_ref	string	no	Reference to the issuer used to sign requests serviced by this role.
key_bits	integer	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_type	string	no	The type of key to use; defaults to RSA. "rsa" "ec", "ed25519" and "any" are the only valid values.
key_usage	array	no	A comma-separated string or list of key usages (not extended key usages). Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the "KeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list. See also RFC 5280 Section 4.2.1.3.
locality	array	no	If set, Locality will be set to this value in certificates issued by this role.
max_ttl	integer	no	The maximum allowed lease duration. If not set, defaults to the system maximum lease TTL.
no_store	boolean	no	If set, certificates issued/signed against this role will not be stored in the storage backend. This can improve performance when issuing large numbers of certificates. However, certificates issued in this way cannot be enumerated or revoked, so this option is recommended only for certificates that are non-sensitive, or extremely short-lived. This option implies a value of "false" for "generate_lease".
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ.
not_before_duration	integer	no	The duration in seconds before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value in certificates issued by this role.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value in certificates issued by this role.
policy_identifiers	array	no	A comma-separated string or list of policy OIDs, or a JSON list of qualified policy information, which must include an oid, and may include a notice and/or cps url, using the form [{"oid"="1.3.6.1.4.1.7.8","notice"="I am a user Notice"}, {"oid"="1.3.6.1.4.1.44947.1.2.4 ","cps"="https://example.com"}].
postal_code	array	no	If set, Postal Code will be set to this value in certificates issued by this role.
province	array	no	If set, Province will be set to this value in certificates issued by this role.
require_cn	boolean	no	If set to false, makes the 'common_name' field optional while generating a certificate.
server_flag	boolean (default: True)	no	If set, certificates are flagged for server auth use. Defaults to true. See also RFC 5280 Section 4.2.1.12.
signature_bits	integer	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
street_address	array	no	If set, Street Address will be set to this value in certificates issued by this role.
ttl	integer	no	The lease duration (validity period of the certificate) if no specific lease duration is requested. The lease duration controls the expiration of certificates issued by this backend. Defaults to the system default value or the value of max_ttl, whichever is shorter.
use_csr_common_name	boolean	no	If set, when used with a signing profile, the common name in the CSR will be used. This does not include any requested Subject Alternative Names; use use_csr_sans for that. Defaults to true.
use_csr_sans	boolean	no	If set, when used with a signing profile, the SANs in the CSR will be used. This does not include the Common Name (cn); use use_csr_common_name for that. Defaults to true.
use_pss	boolean	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.

DELETE /{pki_mount_path}/roles/{name}

Operation ID: pki-delete-role

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: No Content

POST /{pki_mount_path}/roles/{role}/acme/account/{kid}

Operation ID: pki-write-roles-role-acme-account-kid

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
kid	string	path	yes	The key identifier provided by the CA
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/authorization/{auth_id}

Operation ID: pki-write-roles-role-acme-authorization-auth_id

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
auth_id	string	path	yes	ACME authorization identifier value
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/challenge/{auth_id}/{challenge_type}

Operation ID: pki-write-roles-role-acme-challenge-auth_id-challenge_type

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
auth_id	string	path	yes	ACME authorization identifier value
challenge_type	string	path	yes	ACME challenge type
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

GET /{pki_mount_path}/roles/{role}/acme/directory

Operation ID: pki-read-roles-role-acme-directory

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/new-account

Operation ID: pki-write-roles-role-acme-new-account

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/new-eab

Operation ID: pki-generate-eab-key-for-role

Generate external account bindings to be used for ACME

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
acme_directory	string	no	The ACME directory to which the key belongs
created_on	string	no	An RFC3339 formatted date time when the EAB token was created
id	string	no	The EAB key identifier
key	string	no	The EAB hmac key
key_type	string	no	The EAB key type

GET /{pki_mount_path}/roles/{role}/acme/new-nonce

Operation ID: pki-read-roles-role-acme-new-nonce

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/new-order

Operation ID: pki-write-roles-role-acme-new-order

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/order/{order_id}

Operation ID: pki-write-roles-role-acme-order-order_id

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
order_id	string	path	yes	The ACME order identifier to fetch
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/order/{order_id}/cert

Operation ID: pki-write-roles-role-acme-order-order_id-cert

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
order_id	string	path	yes	The ACME order identifier to fetch
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/order/{order_id}/finalize

Operation ID: pki-write-roles-role-acme-order-order_id-finalize

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
order_id	string	path	yes	The ACME order identifier to fetch
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/orders

Operation ID: pki-write-roles-role-acme-orders

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

POST /{pki_mount_path}/roles/{role}/acme/revoke-cert

Operation ID: pki-write-roles-role-acme-revoke-cert

An endpoint implementing the standard ACME protocol

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role for the acme request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
payload	string	no	ACME request 'payload' value
protected	string	no	ACME request 'protected' value
signature	string	no	ACME request 'signature' value

Responses

200: OK

DELETE /{pki_mount_path}/root

Operation ID: pki-delete-root

Deletes the root CA key to allow a new one to be generated.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/root/generate/{exported}

Operation ID: pki-generate-root

Generate a new CA certificate and private key used for signing.

Parameters

Parameter	Type	Location	Required	Description
exported	string (internal, external, kms)	path	yes	Must be "internal", "exported" or "kms". If set to "exported", the generated private key will be returned. This is your only chance to retrieve the private key!
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. May contain both DNS names and email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If not specified when signing, the common name will be taken from the CSR; other names must still be specified in alt_names or ip_sans.
country	array	no	If set, Country will be set to this value.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
issuer_name	string	no	Provide a name to the generated or existing issuer, the name must be unique across all issuers and not be the reserved value 'default'
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_name	string	no	Provide a name to the generated or existing key, the name must be unique across all keys and not be the reserved value 'default'
key_ref	string (default: default)	no	Reference to a existing key; either "default" for the configured default key, an identifier or the name assigned to the key.
key_type	string (rsa, ec, ed25519) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
locality	array	no	If set, Locality will be set to this value.
managed_key_id	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_name is required. Ignored for other types.
managed_key_name	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_id is required. Ignored for other types.
max_path_length	integer (default: -1)	no	The maximum allowable path length
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
not_before_duration	integer (default: 30)	no	The duration before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value.
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value.
permitted_dns_domains	array	no	Domains for which this certificate is allowed to sign or issue child certificates. If set, all DNS names (subject and alt) on child certs must be exact matches or subsets of the given domains (see https://tools.ietf.org/html/rfc5280#section-4.2.1.10).
postal_code	array	no	If set, Postal Code will be set to this value.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
province	array	no	If set, Province will be set to this value.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
street_address	array	no	If set, Street Address will be set to this value.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the mount max TTL. Note: this only has an effect when generating a CA cert or signing a CA cert, not when generating a CSR for an intermediate CA.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.

Responses

200: OK

Parameter	Type	Required	Description
certificate	string	no	The generated self-signed CA certificate.
expiration	integer	no	The expiration of the given issuer.
issuer_id	string	no	The ID of the issuer
issuer_name	string	no	The name of the issuer.
issuing_ca	string	no	The issuing certificate authority.
key_id	string	no	The ID of the key.
key_name	string	no	The key name if given.
private_key	string	no	The private key if exported was specified.
serial_number	string	no	The requested Subject's named serial number.

POST /{pki_mount_path}/root/replace

Operation ID: pki-replace-root

Read and set the default issuer certificate for signing.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
default	string (default: next)	no	Reference (name or identifier) to the default issuer.

Responses

200: OK

Parameter	Type	Required	Description
default	string	no	Reference (name or identifier) to the default issuer.
default_follows_latest_issuer	boolean	no	Whether the default issuer should automatically follow the latest generated or imported issuer. Defaults to false.

POST /{pki_mount_path}/root/rotate/{exported}

Operation ID: pki-rotate-root

Generate a new CA certificate and private key used for signing.

Parameters

Parameter	Type	Location	Required	Description
exported	string (internal, external, kms)	path	yes	Must be "internal", "exported" or "kms". If set to "exported", the generated private key will be returned. This is your only chance to retrieve the private key!
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. May contain both DNS names and email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If not specified when signing, the common name will be taken from the CSR; other names must still be specified in alt_names or ip_sans.
country	array	no	If set, Country will be set to this value.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
issuer_name	string	no	Provide a name to the generated or existing issuer, the name must be unique across all issuers and not be the reserved value 'default'
key_bits	integer (default: 0)	no	The number of bits to use. Allowed values are 0 (universal default); with rsa key_type: 2048 (default), 3072, or 4096; with ec key_type: 224, 256 (default), 384, or 521; ignored with ed25519.
key_name	string	no	Provide a name to the generated or existing key, the name must be unique across all keys and not be the reserved value 'default'
key_ref	string (default: default)	no	Reference to a existing key; either "default" for the configured default key, an identifier or the name assigned to the key.
key_type	string (rsa, ec, ed25519) (default: rsa)	no	The type of key to use; defaults to RSA. "rsa" "ec" and "ed25519" are the only valid values.
locality	array	no	If set, Locality will be set to this value.
managed_key_id	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_name is required. Ignored for other types.
managed_key_name	string	no	The name of the managed key to use when the exported type is kms. When kms type is the key type, this field or managed_key_id is required. Ignored for other types.
max_path_length	integer (default: -1)	no	The maximum allowable path length
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
not_before_duration	integer (default: 30)	no	The duration before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value.
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value.
permitted_dns_domains	array	no	Domains for which this certificate is allowed to sign or issue child certificates. If set, all DNS names (subject and alt) on child certs must be exact matches or subsets of the given domains (see https://tools.ietf.org/html/rfc5280#section-4.2.1.10).
postal_code	array	no	If set, Postal Code will be set to this value.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
province	array	no	If set, Province will be set to this value.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
street_address	array	no	If set, Street Address will be set to this value.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the mount max TTL. Note: this only has an effect when generating a CA cert or signing a CA cert, not when generating a CSR for an intermediate CA.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.

Responses

200: OK

Parameter	Type	Required	Description
certificate	string	no	The generated self-signed CA certificate.
expiration	integer	no	The expiration of the given issuer.
issuer_id	string	no	The ID of the issuer
issuer_name	string	no	The name of the issuer.
issuing_ca	string	no	The issuing certificate authority.
key_id	string	no	The ID of the key.
key_name	string	no	The key name if given.
private_key	string	no	The private key if exported was specified.
serial_number	string	no	The requested Subject's named serial number.

POST /{pki_mount_path}/root/sign-intermediate

Operation ID: pki-root-sign-intermediate

Issue an intermediate CA certificate based on the provided CSR.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. May contain both DNS names and email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If not specified when signing, the common name will be taken from the CSR; other names must still be specified in alt_names or ip_sans.
country	array	no	If set, Country will be set to this value.
csr	string (default: )	no	PEM-format CSR to be signed.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
issuer_name	string	no	Provide a name to the generated or existing issuer, the name must be unique across all issuers and not be the reserved value 'default'
issuer_ref	string (default: default)	no	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
locality	array	no	If set, Locality will be set to this value.
max_path_length	integer (default: -1)	no	The maximum allowable path length
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
not_before_duration	integer (default: 30)	no	The duration before now which the certificate needs to be backdated by.
organization	array	no	If set, O (Organization) will be set to this value.
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
ou	array	no	If set, OU (OrganizationalUnit) will be set to this value.
permitted_dns_domains	array	no	Domains for which this certificate is allowed to sign or issue child certificates. If set, all DNS names (subject and alt) on child certs must be exact matches or subsets of the given domains (see https://tools.ietf.org/html/rfc5280#section-4.2.1.10).
postal_code	array	no	If set, Postal Code will be set to this value.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
province	array	no	If set, Province will be set to this value.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
skid	string (default: )	no	Value for the Subject Key Identifier field (RFC 5280 Section 4.2.1.2). This value should ONLY be used when cross-signing to mimic the existing certificate's SKID value; this is necessary to allow certain TLS implementations (such as OpenSSL) which use SKID/AKID matches in chain building to restrict possible valid chains. Specified as a string in hex format. Default is empty, allowing Vault to automatically calculate the SKID according to method one in the above RFC section.
street_address	array	no	If set, Street Address will be set to this value.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the mount max TTL. Note: this only has an effect when generating a CA cert or signing a CA cert, not when generating a CSR for an intermediate CA.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
use_csr_values	boolean (default: False)	no	If true, then: 1) Subject information, including names and alternate names, will be preserved from the CSR rather than using values provided in the other parameters to this path; 2) Any key usages requested in the CSR will be added to the basic set of key usages used for CA certs signed by this path; for instance, the non-repudiation flag; 3) Extensions requested in the CSR will be copied into the issued certificate.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	CA Chain
certificate	string	no	Certificate
expiration	integer	no	Expiration Time
issuing_ca	string	no	Issuing CA
serial_number	string	no	Serial Number

POST /{pki_mount_path}/root/sign-self-issued

Operation ID: pki-root-sign-self-issued

Re-issue a self-signed certificate based on the provided certificate.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
certificate	string	no	PEM-format self-issued certificate to be signed.
issuer_ref	string (default: default)	no	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
require_matching_certificate_algorithms	boolean (default: False)	no	If true, require the public key algorithm of the signer to match that of the self issued certificate.

Responses

200: OK

Parameter	Type	Required	Description
certificate	string	no	Certificate
issuing_ca	string	no	Issuing CA

POST /{pki_mount_path}/sign-verbatim

Operation ID: pki-sign-verbatim

Issue a certificate directly based on the provided CSR.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. If email protection is enabled for the role, this may contain email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If email protection is enabled in the role, this may be an email address.
csr	string (default: )	no	PEM-format CSR to be signed. Values will be taken verbatim from the CSR, except for basic constraints.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
ext_key_usage	array (default: [])	no	A comma-separated string or list of extended key usages. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage -- simply drop the "ExtKeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list.
ext_key_usage_oids	array	no	A comma-separated string or list of extended key usage oids.
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
issuer_ref	string (default: default)	no	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
key_usage	array (default: ['DigitalSignature', 'KeyAgreement', 'KeyEncipherment'])	no	A comma-separated string or list of key usages (not extended key usages). Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the "KeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list.
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
remove_roots_from_chain	boolean (default: False)	no	Whether or not to remove self-signed CA certificates in the output of the ca_chain field.
role	string	no	The desired role with configuration for this request
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the role max TTL.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.
user_ids	array	no	The requested user_ids value to place in the subject, if any, in a comma-delimited list. Restricted by allowed_user_ids. Any values are added with OID 0.9.2342.19200300.100.1.1.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	Certificate Chain
certificate	string	no	Certificate
expiration	integer	no	Time of expiration
issuing_ca	string	no	Issuing Certificate Authority
private_key	string	no	Private key
private_key_type	string	no	Private key type
serial_number	string	no	Serial Number

POST /{pki_mount_path}/sign-verbatim/{role}

Operation ID: pki-sign-verbatim-with-role

Issue a certificate directly based on the provided CSR.

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role with configuration for this request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. If email protection is enabled for the role, this may contain email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If email protection is enabled in the role, this may be an email address.
csr	string (default: )	no	PEM-format CSR to be signed. Values will be taken verbatim from the CSR, except for basic constraints.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
ext_key_usage	array (default: [])	no	A comma-separated string or list of extended key usages. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage -- simply drop the "ExtKeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list.
ext_key_usage_oids	array	no	A comma-separated string or list of extended key usage oids.
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
issuer_ref	string (default: default)	no	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
key_usage	array (default: ['DigitalSignature', 'KeyAgreement', 'KeyEncipherment'])	no	A comma-separated string or list of key usages (not extended key usages). Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the "KeyUsage" part of the name. To remove all key usages from being set, set this value to an empty list.
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
remove_roots_from_chain	boolean (default: False)	no	Whether or not to remove self-signed CA certificates in the output of the ca_chain field.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
signature_bits	integer (default: 0)	no	The number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the role max TTL.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
use_pss	boolean (default: False)	no	Whether or not to use PSS signatures when using a RSA key-type issuer. Defaults to false.
user_ids	array	no	The requested user_ids value to place in the subject, if any, in a comma-delimited list. Restricted by allowed_user_ids. Any values are added with OID 0.9.2342.19200300.100.1.1.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	Certificate Chain
certificate	string	no	Certificate
expiration	integer	no	Time of expiration
issuing_ca	string	no	Issuing Certificate Authority
private_key	string	no	Private key
private_key_type	string	no	Private key type
serial_number	string	no	Serial Number

POST /{pki_mount_path}/sign/{role}

Operation ID: pki-sign-with-role

Request certificates using a certain role with the provided details.

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role with configuration for this request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
alt_names	string	no	The requested Subject Alternative Names, if any, in a comma-delimited list. If email protection is enabled for the role, this may contain email addresses.
common_name	string	no	The requested common name; if you want more than one, specify the alternative names in the alt_names map. If email protection is enabled in the role, this may be an email address.
csr	string (default: )	no	PEM-format CSR to be signed.
exclude_cn_from_sans	boolean (default: False)	no	If true, the Common Name will not be included in DNS or Email Subject Alternate Names. Defaults to false (CN is included).
format	string (pem, der, pem_bundle) (default: pem)	no	Format for returned data. Can be "pem", "der", or "pem_bundle". If "pem_bundle", any private key and issuing cert will be appended to the certificate pem. If "der", the value will be base64 encoded. Defaults to "pem".
ip_sans	array	no	The requested IP SANs, if any, in a comma-delimited list
issuer_ref	string (default: default)	no	Reference to a existing issuer; either "default" for the configured default issuer, an identifier or the name assigned to the issuer.
not_after	string	no	Set the not after field of the certificate with specified date value. The value format should be given in UTC format YYYY-MM-ddTHH:MM:SSZ
other_sans	array	no	Requested other SANs, in an array with the format ;UTF8: for each entry.
private_key_format	string (, der, pem, pkcs8) (default: der)	no	Format for the returned private key. Generally the default will be controlled by the "format" parameter as either base64-encoded DER or PEM-encoded DER. However, this can be set to "pkcs8" to have the returned private key contain base64-encoded pkcs8 or PEM-encoded pkcs8 instead. Defaults to "der".
remove_roots_from_chain	boolean (default: False)	no	Whether or not to remove self-signed CA certificates in the output of the ca_chain field.
serial_number	string	no	The Subject's requested serial number, if any. See RFC 4519 Section 2.31 'serialNumber' for a description of this field. If you want more than one, specify alternative names in the alt_names map using OID 2.5.4.5. This has no impact on the final certificate's Serial Number field.
ttl	integer	no	The requested Time To Live for the certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be larger than the role max TTL.
uri_sans	array	no	The requested URI SANs, if any, in a comma-delimited list.
user_ids	array	no	The requested user_ids value to place in the subject, if any, in a comma-delimited list. Restricted by allowed_user_ids. Any values are added with OID 0.9.2342.19200300.100.1.1.

Responses

200: OK

Parameter	Type	Required	Description
ca_chain	array	no	Certificate Chain
certificate	string	no	Certificate
expiration	integer	no	Time of expiration
issuing_ca	string	no	Issuing Certificate Authority
private_key	string	no	Private key
private_key_type	string	no	Private key type
serial_number	string	no	Serial Number

POST /{pki_mount_path}/tidy

Operation ID: pki-tidy

Tidy up the backend by removing expired certificates, revocation information, or both.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
acme_account_safety_buffer	integer (default: 2592000)	no	The amount of time that must pass after creation that an account with no orders is marked revoked, and the amount of time after being marked revoked or deactivated.
issuer_safety_buffer	integer (default: 31536000)	no	The amount of extra time that must have passed beyond issuer's expiration before it is removed from the backend storage. Defaults to 8760 hours (1 year).
pause_duration	string (default: 0s)	no	The amount of time to wait between processing certificates. This allows operators to change the execution profile of tidy to take consume less resources by slowing down how long it takes to run. Note that the entire list of certificates will be stored in memory during the entire tidy operation, but resources to read/process/update existing entries will be spread out over a greater period of time. By default this is zero seconds.
revocation_queue_safety_buffer	integer (default: 172800)	no	The amount of time that must pass from the cross-cluster revocation request being initiated to when it will be slated for removal. Setting this too low may remove valid revocation requests before the owning cluster has a chance to process them, especially if the cluster is offline.
safety_buffer	integer (default: 259200)	no	The amount of extra time that must have passed beyond certificate expiration before it is removed from the backend storage and/or revocation list. Defaults to 72 hours.
tidy_acme	boolean (default: False)	no	Set to true to enable tidying ACME accounts, orders and authorizations. ACME orders are tidied (deleted) safety_buffer after the certificate associated with them expires, or after the order and relevant authorizations have expired if no certificate was produced. Authorizations are tidied with the corresponding order. When a valid ACME Account is at least acme_account_safety_buffer old, and has no remaining orders associated with it, the account is marked as revoked. After another acme_account_safety_buffer has passed from the revocation or deactivation date, a revoked or deactivated ACME account is deleted.
tidy_cert_store	boolean	no	Set to true to enable tidying up the certificate store
tidy_cross_cluster_revoked_certs	boolean	no	Set to true to enable tidying up the cross-cluster revoked certificate store. Only runs on the active primary node.
tidy_expired_issuers	boolean	no	Set to true to automatically remove expired issuers past the issuer_safety_buffer. No keys will be removed as part of this operation.
tidy_move_legacy_ca_bundle	boolean	no	Set to true to move the legacy ca_bundle from /config/ca_bundle to /config/ca_bundle.bak. This prevents downgrades to pre-Vault 1.11 versions (as older PKI engines do not know about the new multi-issuer storage layout), but improves the performance on seal wrapped PKI mounts. This will only occur if at least issuer_safety_buffer time has occurred after the initial storage migration. This backup is saved in case of an issue in future migrations. Operators may consider removing it via sys/raw if they desire. The backup will be removed via a DELETE /root call, but note that this removes ALL issuers within the mount (and is thus not desirable in most operational scenarios).
tidy_revocation_list	boolean	no	Deprecated; synonym for 'tidy_revoked_certs
tidy_revocation_queue	boolean (default: False)	no	Set to true to remove stale revocation queue entries that haven't been confirmed by any active cluster. Only runs on the active primary node
tidy_revoked_cert_issuer_associations	boolean	no	Set to true to validate issuer associations on revocation entries. This helps increase the performance of CRL building and OCSP responses.
tidy_revoked_certs	boolean	no	Set to true to expire all revoked and expired certificates, removing them both from the CRL and from storage. The CRL will be rotated if this causes any values to be removed.

Responses

202: Accepted

POST /{pki_mount_path}/tidy-cancel

Operation ID: pki-tidy-cancel

Cancels a currently running tidy operation.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
acme_account_deleted_count	integer	no	The number of revoked acme accounts removed
acme_account_revoked_count	integer	no	The number of unused acme accounts revoked
acme_account_safety_buffer	integer	no	Safety buffer after creation after which accounts lacking orders are revoked
acme_orders_deleted_count	integer	no	The number of expired, unused acme orders removed
cert_store_deleted_count	integer	no	The number of certificate storage entries deleted
cross_revoked_cert_deleted_count	integer	no
current_cert_store_count	integer	no	The number of revoked certificate entries deleted
current_revoked_cert_count	integer	no	The number of revoked certificate entries deleted
error	string	no	The error message
internal_backend_uuid	string	no
issuer_safety_buffer	integer	no	Issuer safety buffer
last_auto_tidy_finished	string	no	Time the last auto-tidy operation finished
message	string	no	Message of the operation
missing_issuer_cert_count	integer	no
pause_duration	string	no	Duration to pause between tidying certificates
revocation_queue_deleted_count	integer	no
revocation_queue_safety_buffer	integer	no	Revocation queue safety buffer
revoked_cert_deleted_count	integer	no	The number of revoked certificate entries deleted
safety_buffer	integer	no	Safety buffer time duration
state	string	no	One of Inactive, Running, Finished, or Error
tidy_acme	boolean	no	Tidy Unused Acme Accounts, and Orders
tidy_cert_store	boolean	no	Tidy certificate store
tidy_cross_cluster_revoked_certs	boolean	no	Tidy the cross-cluster revoked certificate store
tidy_expired_issuers	boolean	no	Tidy expired issuers
tidy_move_legacy_ca_bundle	boolean	no
tidy_revocation_queue	boolean	no
tidy_revoked_cert_issuer_associations	boolean	no	Tidy revoked certificate issuer associations
tidy_revoked_certs	boolean	no	Tidy revoked certificates
time_finished	string	no	Time the operation finished
time_started	string	no	Time the operation started
total_acme_account_count	integer	no	Total number of acme accounts iterated over

GET /{pki_mount_path}/tidy-status

Operation ID: pki-tidy-status

Returns the status of the tidy operation.

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

Parameter	Type	Required	Description
acme_account_deleted_count	integer	no	The number of revoked acme accounts removed
acme_account_revoked_count	integer	no	The number of unused acme accounts revoked
acme_account_safety_buffer	integer	no	Safety buffer after creation after which accounts lacking orders are revoked
acme_orders_deleted_count	integer	no	The number of expired, unused acme orders removed
cert_store_deleted_count	integer	no	The number of certificate storage entries deleted
cross_revoked_cert_deleted_count	integer	no
current_cert_store_count	integer	no	The number of revoked certificate entries deleted
current_revoked_cert_count	integer	no	The number of revoked certificate entries deleted
error	string	no	The error message
internal_backend_uuid	string	no
issuer_safety_buffer	integer	no	Issuer safety buffer
last_auto_tidy_finished	string	no	Time the last auto-tidy operation finished
message	string	no	Message of the operation
missing_issuer_cert_count	integer	no
pause_duration	string	no	Duration to pause between tidying certificates
revocation_queue_deleted_count	integer	no
revocation_queue_safety_buffer	integer	no	Revocation queue safety buffer
revoked_cert_deleted_count	integer	no	The number of revoked certificate entries deleted
safety_buffer	integer	no	Safety buffer time duration
state	string	no	One of Inactive, Running, Finished, or Error
tidy_acme	boolean	no	Tidy Unused Acme Accounts, and Orders
tidy_cert_store	boolean	no	Tidy certificate store
tidy_cross_cluster_revoked_certs	boolean	no	Tidy the cross-cluster revoked certificate store
tidy_expired_issuers	boolean	no	Tidy expired issuers
tidy_move_legacy_ca_bundle	boolean	no
tidy_revocation_queue	boolean	no
tidy_revoked_cert_issuer_associations	boolean	no	Tidy revoked certificate issuer associations
tidy_revoked_certs	boolean	no	Tidy revoked certificates
time_finished	string	no	Time the operation finished
time_started	string	no	Time the operation started
total_acme_account_count	integer	no	Total number of acme accounts iterated over

GET /{pki_mount_path}/unified-crl

Operation ID: pki-read-unified-crl-der

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{pki_mount_path}/unified-crl/delta

Operation ID: pki-read-unified-crl-delta

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{pki_mount_path}/unified-crl/delta/pem

Operation ID: pki-read-unified-crl-delta-pem

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{pki_mount_path}/unified-crl/pem

Operation ID: pki-read-unified-crl-pem

Fetch a CA, CRL, CA Chain, or non-revoked certificate.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{pki_mount_path}/unified-ocsp

Operation ID: pki-query-unified-ocsp

Query a certificate's revocation status through OCSP'

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{pki_mount_path}/unified-ocsp/{req}

Operation ID: pki-query-unified-ocsp-with-get-req

Query a certificate's revocation status through OCSP'

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
req	string	path	yes	base-64 encoded ocsp request
pki_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{rabbitmq_mount_path}/config/connection

Operation ID: rabbit-mq-configure-connection

Configure the connection URI, username, and password to talk to RabbitMQ management HTTP API.

Parameters

Parameter	Type	Location	Required	Description
rabbitmq_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
connection_uri	string	no	RabbitMQ Management URI
password	string	no	Password of the provided RabbitMQ management user
password_policy	string	no	Name of the password policy to use to generate passwords for dynamic credentials.
username	string	no	Username of a RabbitMQ management administrator
username_template	string	no	Template describing how dynamic usernames are generated.
verify_connection	boolean (default: True)	no	If set, connection_uri is verified by actually connecting to the RabbitMQ management API

Responses

200: OK

GET /{rabbitmq_mount_path}/config/lease

Operation ID: rabbit-mq-read-lease-configuration

Configure the lease parameters for generated credentials

Parameters

Parameter	Type	Location	Required	Description
rabbitmq_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{rabbitmq_mount_path}/config/lease

Operation ID: rabbit-mq-configure-lease

Configure the lease parameters for generated credentials

Parameters

Parameter	Type	Location	Required	Description
rabbitmq_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
max_ttl	integer (default: 0)	no	Duration after which the issued credentials should not be allowed to be renewed
ttl	integer (default: 0)	no	Duration before which the issued credentials needs renewal

Responses

200: OK

GET /{rabbitmq_mount_path}/creds/{name}

Operation ID: rabbit-mq-request-credentials

Request RabbitMQ credentials for a certain role.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
rabbitmq_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{rabbitmq_mount_path}/roles

Operation ID: rabbit-mq-list-roles

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
rabbitmq_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{rabbitmq_mount_path}/roles/{name}

Operation ID: rabbit-mq-read-role

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
rabbitmq_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{rabbitmq_mount_path}/roles/{name}

Operation ID: rabbit-mq-write-role

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
rabbitmq_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
tags	string	no	Comma-separated list of tags for this role.
vhost_topics	string	no	A nested map of virtual hosts and exchanges to topic permissions.
vhosts	string	no	A map of virtual hosts to permissions.

Responses

200: OK

DELETE /{rabbitmq_mount_path}/roles/{name}

Operation ID: rabbit-mq-delete-role

Manage the roles that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the role.
rabbitmq_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

GET /{ssh_mount_path}/config/ca

Operation ID: ssh-read-ca-configuration

Set the SSH private key used for signing certificates.

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{ssh_mount_path}/config/ca

Operation ID: ssh-configure-ca

Set the SSH private key used for signing certificates.

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
generate_signing_key	boolean (default: True)	no	Generate SSH key pair internally rather than use the private_key and public_key fields.
key_bits	integer (default: 0)	no	Specifies the desired key bits when generating variable-length keys (such as when key_type="ssh-rsa") or which NIST P-curve to use when key_type="ec" (256, 384, or 521).
key_type	string (default: ssh-rsa)	no	Specifies the desired key type when generating; could be a OpenSSH key type identifier (ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, or ssh-ed25519) or an algorithm (rsa, ec, ed25519).
private_key	string	no	Private half of the SSH key that will be used to sign certificates.
public_key	string	no	Public half of the SSH key that will be used to sign certificates.

Responses

200: OK

DELETE /{ssh_mount_path}/config/ca

Operation ID: ssh-delete-ca-configuration

Set the SSH private key used for signing certificates.

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

GET /{ssh_mount_path}/config/zeroaddress

Operation ID: ssh-read-zero-address-configuration

Assign zero address as default CIDR block for select roles.

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{ssh_mount_path}/config/zeroaddress

Operation ID: ssh-configure-zero-address

Assign zero address as default CIDR block for select roles.

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
roles	array	no	[Required] Comma separated list of role names which allows credentials to be requested for any IP address. CIDR blocks previously registered under these roles will be ignored.

Responses

200: OK

DELETE /{ssh_mount_path}/config/zeroaddress

Operation ID: ssh-delete-zero-address-configuration

Assign zero address as default CIDR block for select roles.

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{ssh_mount_path}/creds/{role}

Operation ID: ssh-generate-credentials

Creates a credential for establishing SSH connection with the remote host.

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	[Required] Name of the role
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
ip	string	no	[Required] IP of the remote host
username	string	no	[Optional] Username in remote host

Responses

200: OK

POST /{ssh_mount_path}/issue/{role}

Operation ID: ssh-issue-certificate

Request a certificate using a certain role with the provided details.

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role with configuration for this request.
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
cert_type	string (default: user)	no	Type of certificate to be created; either "user" or "host".
critical_options	object	no	Critical options that the certificate should be signed for.
extensions	object	no	Extensions that the certificate should be signed for.
key_bits	integer (default: 0)	no	Specifies the number of bits to use for the generated keys.
key_id	string	no	Key id that the created certificate should have. If not specified, the display name of the token will be used.
key_type	string (default: rsa)	no	Specifies the desired key type; must be rsa, ed25519 or ec
ttl	integer	no	The requested Time To Live for the SSH certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be later than the role max TTL.
valid_principals	string	no	Valid principals, either usernames or hostnames, that the certificate should be signed for.

Responses

200: OK

POST /{ssh_mount_path}/lookup

Operation ID: ssh-list-roles-by-ip

List all the roles associated with the given IP address.

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
ip	string	no	[Required] IP address of remote host

Responses

200: OK

GET /{ssh_mount_path}/public_key

Operation ID: ssh-read-public-key

Retrieve the public key.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{ssh_mount_path}/roles

Operation ID: ssh-list-roles

Manage the 'roles' that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{ssh_mount_path}/roles/{role}

Operation ID: ssh-read-role

Manage the 'roles' that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	[Required for all types] Name of the role being created.
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{ssh_mount_path}/roles/{role}

Operation ID: ssh-write-role

Manage the 'roles' that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	[Required for all types] Name of the role being created.
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
algorithm_signer	string (, default, ssh-rsa, rsa-sha2-256, rsa-sha2-512)	no	[Not applicable for OTP type] [Optional for CA type] When supplied, this value specifies a signing algorithm for the key. Possible values: ssh-rsa, rsa-sha2-256, rsa-sha2-512, default, or the empty string.
allow_bare_domains	boolean	no	[Not applicable for OTP type] [Optional for CA type] If set, host certificates that are requested are allowed to use the base domains listed in "allowed_domains", e.g. "example.com". This is a separate option as in some cases this can be considered a security threat.
allow_host_certificates	boolean (default: False)	no	[Not applicable for OTP type] [Optional for CA type] If set, certificates are allowed to be signed for use as a 'host'.
allow_subdomains	boolean	no	[Not applicable for OTP type] [Optional for CA type] If set, host certificates that are requested are allowed to use subdomains of those listed in "allowed_domains".
allow_user_certificates	boolean (default: False)	no	[Not applicable for OTP type] [Optional for CA type] If set, certificates are allowed to be signed for use as a 'user'.
allow_user_key_ids	boolean	no	[Not applicable for OTP type] [Optional for CA type] If true, users can override the key ID for a signed certificate with the "key_id" field. When false, the key ID will always be the token display name. The key ID is logged by the SSH server and can be useful for auditing.
allowed_critical_options	string	no	[Not applicable for OTP type] [Optional for CA type] A comma-separated list of critical options that certificates can have when signed. To allow any critical options, set this to an empty string.
allowed_domains	string	no	[Not applicable for OTP type] [Optional for CA type] If this option is not specified, client can request for a signed certificate for any valid host. If only certain domains are allowed, then this list enforces it.
allowed_domains_template	boolean (default: False)	no	[Not applicable for OTP type] [Optional for CA type] If set, Allowed domains can be specified using identity template policies. Non-templated domains are also permitted.
allowed_extensions	string	no	[Not applicable for OTP type] [Optional for CA type] A comma-separated list of extensions that certificates can have when signed. An empty list means that no extension overrides are allowed by an end-user; explicitly specify '*' to allow any extensions to be set.
allowed_user_key_lengths	object	no	[Not applicable for OTP type] [Optional for CA type] If set, allows the enforcement of key types and minimum key sizes to be signed.
allowed_users	string	no	[Optional for all types] [Works differently for CA type] If this option is not specified, or is '', client can request a credential for any valid user at the remote host, including the admin user. If only certain usernames are to be allowed, then this list enforces it. If this field is set, then credentials can only be created for default_user and usernames present in this list. Setting this option will enable all the users with access to this role to fetch credentials for all other usernames in this list. Use with caution. N.B.: with the CA type, an empty list means that no users are allowed; explicitly specify '' to allow any user.
allowed_users_template	boolean (default: False)	no	[Not applicable for OTP type] [Optional for CA type] If set, Allowed users can be specified using identity template policies. Non-templated users are also permitted.
cidr_list	string	no	[Optional for OTP type] [Not applicable for CA type] Comma separated list of CIDR blocks for which the role is applicable for. CIDR blocks can belong to more than one role.
default_critical_options	object	no	[Not applicable for OTP type] [Optional for CA type] Critical options certificates should have if none are provided when signing. This field takes in key value pairs in JSON format. Note that these are not restricted by "allowed_critical_options". Defaults to none.
default_extensions	object	no	[Not applicable for OTP type] [Optional for CA type] Extensions certificates should have if none are provided when signing. This field takes in key value pairs in JSON format. Note that these are not restricted by "allowed_extensions". Defaults to none.
default_extensions_template	boolean (default: False)	no	[Not applicable for OTP type] [Optional for CA type] If set, Default extension values can be specified using identity template policies. Non-templated extension values are also permitted.
default_user	string	no	[Required for OTP type] [Optional for CA type] Default username for which a credential will be generated. When the endpoint 'creds/' is used without a username, this value will be used as default username.
default_user_template	boolean (default: False)	no	[Not applicable for OTP type] [Optional for CA type] If set, Default user can be specified using identity template policies. Non-templated users are also permitted.
exclude_cidr_list	string	no	[Optional for OTP type] [Not applicable for CA type] Comma separated list of CIDR blocks. IP addresses belonging to these blocks are not accepted by the role. This is particularly useful when big CIDR blocks are being used by the role and certain parts of it needs to be kept out.
key_id_format	string	no	[Not applicable for OTP type] [Optional for CA type] When supplied, this value specifies a custom format for the key id of a signed certificate. The following variables are available for use: '{{token_display_name}}' - The display name of the token used to make the request. '{{role_name}}' - The name of the role signing the request. '{{public_key_hash}}' - A SHA256 checksum of the public key that is being signed.
key_type	string (otp, ca)	no	[Required for all types] Type of key used to login to hosts. It can be either 'otp' or 'ca'. 'otp' type requires agent to be installed in remote hosts.
max_ttl	integer	no	[Not applicable for OTP type] [Optional for CA type] The maximum allowed lease duration
not_before_duration	integer (default: 30)	no	[Not applicable for OTP type] [Optional for CA type] The duration that the SSH certificate should be backdated by at issuance.
port	integer	no	[Optional for OTP type] [Not applicable for CA type] Port number for SSH connection. Default is '22'. Port number does not play any role in creation of OTP. For 'otp' type, this is just a way to inform client about the port number to use. Port number will be returned to client by Vault server along with OTP.
ttl	integer	no	[Not applicable for OTP type] [Optional for CA type] The lease duration if no specific lease duration is requested. The lease duration controls the expiration of certificates issued by this backend. Defaults to the value of max_ttl.

Responses

200: OK

DELETE /{ssh_mount_path}/roles/{role}

Operation ID: ssh-delete-role

Manage the 'roles' that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	[Required for all types] Name of the role being created.
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{ssh_mount_path}/sign/{role}

Operation ID: ssh-sign-certificate

Request signing an SSH key using a certain role with the provided details.

Parameters

Parameter	Type	Location	Required	Description
role	string	path	yes	The desired role with configuration for this request.
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
cert_type	string (default: user)	no	Type of certificate to be created; either "user" or "host".
critical_options	object	no	Critical options that the certificate should be signed for.
extensions	object	no	Extensions that the certificate should be signed for.
key_id	string	no	Key id that the created certificate should have. If not specified, the display name of the token will be used.
public_key	string	no	SSH public key that should be signed.
ttl	integer	no	The requested Time To Live for the SSH certificate; sets the expiration date. If not specified the role default, backend default, or system default TTL is used, in that order. Cannot be later than the role max TTL.
valid_principals	string	no	Valid principals, either usernames or hostnames, that the certificate should be signed for.

Responses

200: OK

DELETE /{ssh_mount_path}/tidy/dynamic-keys

Operation ID: ssh-tidy-dynamic-host-keys

This endpoint removes the stored host keys used for the removed Dynamic Key feature, if present.

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{ssh_mount_path}/verify

Operation ID: ssh-verify-otp

Validate the OTP provided by Vault SSH Agent.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
ssh_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
otp	string	no	[Required] One-Time-Key that needs to be validated

Responses

200: OK

GET /{totp_mount_path}/code/{name}

Operation ID: totp-generate-code

Request time-based one-time use password or validate a password for a certain key .

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key.
totp_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{totp_mount_path}/code/{name}

Operation ID: totp-validate-code

Request time-based one-time use password or validate a password for a certain key .

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key.
totp_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
code	string	no	TOTP code to be validated.

Responses

200: OK

GET /{totp_mount_path}/keys

Operation ID: totp-list-keys

Manage the keys that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
totp_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{totp_mount_path}/keys/{name}

Operation ID: totp-read-key

Manage the keys that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key.
totp_mount_path	string	path	yes	Path that the backend was mounted at
list	string	query	no	Return a list if true

Responses

200: OK

POST /{totp_mount_path}/keys/{name}

Operation ID: totp-create-key

Manage the keys that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key.
totp_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
account_name	string	no	The name of the account associated with the key. Required if generate is true.
algorithm	string (default: SHA1)	no	The hashing algorithm used to generate the TOTP token. Options include SHA1, SHA256 and SHA512.
digits	integer (default: 6)	no	The number of digits in the generated TOTP token. This value can either be 6 or 8.
exported	boolean (default: True)	no	Determines if a QR code and url are returned upon generating a key. Only used if generate is true.
generate	boolean (default: False)	no	Determines if a key should be generated by Vault or if a key is being passed from another service.
issuer	string	no	The name of the key's issuing organization. Required if generate is true.
key	string	no	The shared master key used to generate a TOTP token. Only used if generate is false.
key_size	integer (default: 20)	no	Determines the size in bytes of the generated key. Only used if generate is true.
period	integer (default: 30)	no	The length of time used to generate a counter for the TOTP token calculation.
qr_size	integer (default: 200)	no	The pixel size of the generated square QR code. Only used if generate is true and exported is true. If this value is 0, a QR code will not be returned.
skew	integer (default: 1)	no	The number of delay periods that are allowed when validating a TOTP token. This value can either be 0 or 1. Only used if generate is true.
url	string	no	A TOTP url string containing all of the parameters for key setup. Only used if generate is false.

Responses

200: OK

DELETE /{totp_mount_path}/keys/{name}

Operation ID: totp-delete-key

Manage the keys that can be created with this backend.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key.
totp_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

GET /{transit_mount_path}/backup/{name}

Operation ID: transit-back-up-key

Backup the named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{transit_mount_path}/byok-export/{destination}/{source}

Operation ID: transit-byok-key

Securely export named encryption or signing key

Parameters

Parameter	Type	Location	Required	Description
destination	string	path	yes	Destination key to export to; usually the public wrapping key of another Transit instance.
source	string	path	yes	Source key to export; could be any present key within Transit.
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{transit_mount_path}/byok-export/{destination}/{source}/{version}

Operation ID: transit-byok-key-version

Securely export named encryption or signing key

Parameters

Parameter	Type	Location	Required	Description
destination	string	path	yes	Destination key to export to; usually the public wrapping key of another Transit instance.
source	string	path	yes	Source key to export; could be any present key within Transit.
version	string	path	yes	Optional version of the key to export, else all key versions are exported.
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{transit_mount_path}/cache-config

Operation ID: transit-read-cache-configuration

Returns the size of the active cache

Parameters

Parameter	Type	Location	Required	Description
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{transit_mount_path}/cache-config

Operation ID: transit-configure-cache

Configures a new cache of the specified size

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
size	integer (default: 0)	no	Size of cache, use 0 for an unlimited cache size, defaults to 0

Responses

200: OK

GET /{transit_mount_path}/config/keys

Operation ID: transit-read-keys-configuration

Configuration common across all keys

Parameters

Parameter	Type	Location	Required	Description
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{transit_mount_path}/config/keys

Operation ID: transit-configure-keys

Configuration common across all keys

Parameters

Parameter	Type	Location	Required	Description
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
disable_upsert	boolean	no	Whether to allow automatic upserting (creation) of keys on the encrypt endpoint.

Responses

200: OK

POST /{transit_mount_path}/datakey/{plaintext}/{name}

Operation ID: transit-generate-data-key

Generate a data key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The backend key used for encrypting the data key
plaintext	string	path	yes	"plaintext" will return the key in both plaintext and ciphertext; "wrapped" will return the ciphertext only.
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bits	integer (default: 256)	no	Number of bits for the key; currently 128, 256, and 512 bits are supported. Defaults to 256.
context	string	no	Context for key derivation. Required for derived keys.
key_version	integer	no	The version of the Vault key to use for encryption of the data key. Must be 0 (for latest) or a value greater than or equal to the min_encryption_version configured on the key.
nonce	string	no	Nonce for when convergent encryption v1 is used (only in Vault 0.6.1)

Responses

200: OK

POST /{transit_mount_path}/decrypt/{name}

Operation ID: transit-decrypt

Decrypt a ciphertext value using a named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
associated_data	string	no	When using an AEAD cipher mode, such as AES-GCM, this parameter allows passing associated data (AD/AAD) into the encryption function; this data must be passed on subsequent decryption requests but can be transited in plaintext. On successful decryption, both the ciphertext and the associated data are attested not to have been tampered with.
batch_input	array	no	Specifies a list of items to be decrypted in a single batch. When this parameter is set, if the parameters 'ciphertext', 'context' and 'nonce' are also set, they will be ignored. Any batch output will preserve the order of the batch input.
ciphertext	string	no	The ciphertext to decrypt, provided as returned by encrypt.
context	string	no	Base64 encoded context for key derivation. Required if key derivation is enabled.
nonce	string	no	Base64 encoded nonce value used during encryption. Must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+.
partial_failure_response_code	integer	no	Ordinarily, if a batch item fails to decrypt due to a bad input, but other batch items succeed, the HTTP response code is 400 (Bad Request). Some applications may want to treat partial failures differently. Providing the parameter returns the given response code integer instead of a 400 in this case. If all values fail HTTP 400 is still returned.

Responses

200: OK

POST /{transit_mount_path}/encrypt/{name}

Operation ID: transit-encrypt

Encrypt a plaintext value or a batch of plaintext blocks using a named key

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
associated_data	string	no	When using an AEAD cipher mode, such as AES-GCM, this parameter allows passing associated data (AD/AAD) into the encryption function; this data must be passed on subsequent decryption requests but can be transited in plaintext. On successful decryption, both the ciphertext and the associated data are attested not to have been tampered with.
batch_input	array	no	Specifies a list of items to be encrypted in a single batch. When this parameter is set, if the parameters 'plaintext', 'context' and 'nonce' are also set, they will be ignored. Any batch output will preserve the order of the batch input.
context	string	no	Base64 encoded context for key derivation. Required if key derivation is enabled
convergent_encryption	boolean	no	This parameter will only be used when a key is expected to be created. Whether to support convergent encryption. This is only supported when using a key with key derivation enabled and will require all requests to carry both a context and 96-bit (12-byte) nonce. The given nonce will be used in place of a randomly generated nonce. As a result, when the same context and nonce are supplied, the same ciphertext is generated. It is very important when using this mode that you ensure that all nonces are unique for a given context. Failing to do so will severely impact the ciphertext's security.
key_version	integer	no	The version of the key to use for encryption. Must be 0 (for latest) or a value greater than or equal to the min_encryption_version configured on the key.
nonce	string	no	Base64 encoded nonce value. Must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The value must be exactly 96 bits (12 bytes) long and the user must ensure that for any given context (and thus, any given encryption key) this nonce value is never reused.
partial_failure_response_code	integer	no	Ordinarily, if a batch item fails to encrypt due to a bad input, but other batch items succeed, the HTTP response code is 400 (Bad Request). Some applications may want to treat partial failures differently. Providing the parameter returns the given response code integer instead of a 400 in this case. If all values fail HTTP 400 is still returned.
plaintext	string	no	Base64 encoded plaintext value to be encrypted
type	string (default: aes256-gcm96)	no	This parameter is required when encryption key is expected to be created. When performing an upsert operation, the type of key to create. Currently, "aes128-gcm96" (symmetric) and "aes256-gcm96" (symmetric) are the only types supported. Defaults to "aes256-gcm96".

Responses

200: OK

GET /{transit_mount_path}/export/{type}/{name}

Operation ID: transit-export-key

Export named encryption or signing key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
type	string	path	yes	Type of key to export (encryption-key, signing-key, hmac-key, public-key)
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

GET /{transit_mount_path}/export/{type}/{name}/{version}

Operation ID: transit-export-key-version

Export named encryption or signing key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
type	string	path	yes	Type of key to export (encryption-key, signing-key, hmac-key, public-key)
version	string	path	yes	Version of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{transit_mount_path}/hash

Operation ID: transit-hash

Generate a hash sum for input data

Parameters

Parameter	Type	Location	Required	Description
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Algorithm to use (POST body parameter). Valid values are: * sha2-224 * sha2-256 * sha2-384 * sha2-512 * sha3-224 * sha3-256 * sha3-384 * sha3-512 Defaults to "sha2-256".
format	string (default: hex)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "hex".
input	string	no	The base64-encoded input data
urlalgorithm	string	no	Algorithm to use (POST URL parameter)

Responses

200: OK

POST /{transit_mount_path}/hash/{urlalgorithm}

Operation ID: transit-hash-with-algorithm

Generate a hash sum for input data

Parameters

Parameter	Type	Location	Required	Description
urlalgorithm	string	path	yes	Algorithm to use (POST URL parameter)
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Algorithm to use (POST body parameter). Valid values are: * sha2-224 * sha2-256 * sha2-384 * sha2-512 * sha3-224 * sha3-256 * sha3-384 * sha3-512 Defaults to "sha2-256".
format	string (default: hex)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "hex".
input	string	no	The base64-encoded input data

Responses

200: OK

POST /{transit_mount_path}/hmac/{name}

Operation ID: transit-generate-hmac

Generate an HMAC for input data using the named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The key to use for the HMAC function
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Algorithm to use (POST body parameter). Valid values are: * sha2-224 * sha2-256 * sha2-384 * sha2-512 * sha3-224 * sha3-256 * sha3-384 * sha3-512 Defaults to "sha2-256".
batch_input	array	no	Specifies a list of items to be processed in a single batch. When this parameter is set, if the parameter 'input' is also set, it will be ignored. Any batch output will preserve the order of the batch input.
input	string	no	The base64-encoded input data
key_version	integer	no	The version of the key to use for generating the HMAC. Must be 0 (for latest) or a value greater than or equal to the min_encryption_version configured on the key.
urlalgorithm	string	no	Algorithm to use (POST URL parameter)

Responses

200: OK

POST /{transit_mount_path}/hmac/{name}/{urlalgorithm}

Operation ID: transit-generate-hmac-with-algorithm

Generate an HMAC for input data using the named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The key to use for the HMAC function
urlalgorithm	string	path	yes	Algorithm to use (POST URL parameter)
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Algorithm to use (POST body parameter). Valid values are: * sha2-224 * sha2-256 * sha2-384 * sha2-512 * sha3-224 * sha3-256 * sha3-384 * sha3-512 Defaults to "sha2-256".
batch_input	array	no	Specifies a list of items to be processed in a single batch. When this parameter is set, if the parameter 'input' is also set, it will be ignored. Any batch output will preserve the order of the batch input.
input	string	no	The base64-encoded input data
key_version	integer	no	The version of the key to use for generating the HMAC. Must be 0 (for latest) or a value greater than or equal to the min_encryption_version configured on the key.

Responses

200: OK

GET /{transit_mount_path}/keys

Operation ID: transit-list-keys

Managed named encryption keys

Parameters

Parameter	Type	Location	Required	Description
transit_mount_path	string	path	yes	Path that the backend was mounted at
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /{transit_mount_path}/keys/{name}

Operation ID: transit-read-key

Managed named encryption keys

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

POST /{transit_mount_path}/keys/{name}

Operation ID: transit-create-key

Managed named encryption keys

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
allow_plaintext_backup	boolean	no	Enables taking a backup of the named key in plaintext format. Once set, this cannot be disabled.
auto_rotate_period	integer (default: 0)	no	Amount of time the key should live before being automatically rotated. A value of 0 (default) disables automatic rotation for the key.
context	string	no	Base64 encoded context for key derivation. When reading a key with key derivation enabled, if the key type supports public keys, this will return the public key for the given context.
convergent_encryption	boolean	no	Whether to support convergent encryption. This is only supported when using a key with key derivation enabled and will require all requests to carry both a context and 96-bit (12-byte) nonce. The given nonce will be used in place of a randomly generated nonce. As a result, when the same context and nonce are supplied, the same ciphertext is generated. It is very important when using this mode that you ensure that all nonces are unique for a given context. Failing to do so will severely impact the ciphertext's security.
derived	boolean	no	Enables key derivation mode. This allows for per-transaction unique keys for encryption operations.
exportable	boolean	no	Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported.
key_size	integer (default: 0)	no	The key size in bytes for the algorithm. Only applies to HMAC and must be no fewer than 32 bytes and no more than 512
managed_key_id	string	no	The UUID of the managed key to use for this transit key
managed_key_name	string	no	The name of the managed key to use for this transit key
type	string (default: aes256-gcm96)	no	The type of key to create. Currently, "aes128-gcm96" (symmetric), "aes256-gcm96" (symmetric), "ecdsa-p256" (asymmetric), "ecdsa-p384" (asymmetric), "ecdsa-p521" (asymmetric), "ed25519" (asymmetric), "rsa-2048" (asymmetric), "rsa-3072" (asymmetric), "rsa-4096" (asymmetric) are supported. Defaults to "aes256-gcm96".

Responses

200: OK

DELETE /{transit_mount_path}/keys/{name}

Operation ID: transit-delete-key

Managed named encryption keys

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

204: empty body

POST /{transit_mount_path}/keys/{name}/config

Operation ID: transit-configure-key

Configure a named encryption key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
allow_plaintext_backup	boolean	no	Enables taking a backup of the named key in plaintext format. Once set, this cannot be disabled.
auto_rotate_period	integer	no	Amount of time the key should live before being automatically rotated. A value of 0 disables automatic rotation for the key.
deletion_allowed	boolean	no	Whether to allow deletion of the key
exportable	boolean	no	Enables export of the key. Once set, this cannot be disabled.
min_decryption_version	integer	no	If set, the minimum version of the key allowed to be decrypted. For signing keys, the minimum version allowed to be used for verification.
min_encryption_version	integer	no	If set, the minimum version of the key allowed to be used for encryption; or for signing keys, to be used for signing. If set to zero, only the latest version of the key is allowed.

Responses

200: OK

POST /{transit_mount_path}/keys/{name}/import

Operation ID: transit-import-key

Imports an externally-generated key into a new transit key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
allow_plaintext_backup	boolean	no	Enables taking a backup of the named key in plaintext format. Once set, this cannot be disabled.
allow_rotation	boolean	no	True if the imported key may be rotated within Vault; false otherwise.
auto_rotate_period	integer (default: 0)	no	Amount of time the key should live before being automatically rotated. A value of 0 (default) disables automatic rotation for the key.
ciphertext	string	no	The base64-encoded ciphertext of the keys. The AES key should be encrypted using OAEP with the wrapping key and then concatenated with the import key, wrapped by the AES key.
context	string	no	Base64 encoded context for key derivation. When reading a key with key derivation enabled, if the key type supports public keys, this will return the public key for the given context.
derived	boolean	no	Enables key derivation mode. This allows for per-transaction unique keys for encryption operations.
exportable	boolean	no	Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported.
hash_function	string (default: SHA256)	no	The hash function used as a random oracle in the OAEP wrapping of the user-generated, ephemeral AES key. Can be one of "SHA1", "SHA224", "SHA256" (default), "SHA384", or "SHA512"
public_key	string	no	The plaintext PEM public key to be imported. If "ciphertext" is set, this field is ignored.
type	string (default: aes256-gcm96)	no	The type of key being imported. Currently, "aes128-gcm96" (symmetric), "aes256-gcm96" (symmetric), "ecdsa-p256" (asymmetric), "ecdsa-p384" (asymmetric), "ecdsa-p521" (asymmetric), "ed25519" (asymmetric), "rsa-2048" (asymmetric), "rsa-3072" (asymmetric), "rsa-4096" (asymmetric) are supported. Defaults to "aes256-gcm96".

Responses

200: OK

POST /{transit_mount_path}/keys/{name}/import_version

Operation ID: transit-import-key-version

Imports an externally-generated key into an existing imported key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
ciphertext	string	no	The base64-encoded ciphertext of the keys. The AES key should be encrypted using OAEP with the wrapping key and then concatenated with the import key, wrapped by the AES key.
hash_function	string (default: SHA256)	no	The hash function used as a random oracle in the OAEP wrapping of the user-generated, ephemeral AES key. Can be one of "SHA1", "SHA224", "SHA256" (default), "SHA384", or "SHA512"
public_key	string	no	The plaintext public key to be imported. If "ciphertext" is set, this field is ignored.
version	integer	no	Key version to be updated, if left empty, a new version will be created unless a private key is specified and the 'Latest' key is missing a private key.

Responses

200: OK

POST /{transit_mount_path}/keys/{name}/rotate

Operation ID: transit-rotate-key

Rotate named encryption key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
managed_key_id	string	no	The UUID of the managed key to use for the new version of this transit key
managed_key_name	string	no	The name of the managed key to use for the new version of this transit key

Responses

200: OK

POST /{transit_mount_path}/keys/{name}/trim

Operation ID: transit-trim-key

Trim key versions of a named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
min_available_version	integer	no	The minimum available version for the key ring. All versions before this version will be permanently deleted. This value can at most be equal to the lesser of 'min_decryption_version' and 'min_encryption_version'. This is not allowed to be set when either 'min_encryption_version' or 'min_decryption_version' is set to zero.

Responses

200: OK

POST /{transit_mount_path}/random

Operation ID: transit-generate-random

Generate random bytes

Parameters

Parameter	Type	Location	Required	Description
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bytes	integer (default: 32)	no	The number of bytes to generate (POST body parameter). Defaults to 32 (256 bits).
format	string (default: base64)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "base64".
source	string (default: platform)	no	Which system to source random data from, ether "platform", "seal", or "all".
urlbytes	string	no	The number of bytes to generate (POST URL parameter)

Responses

200: OK

POST /{transit_mount_path}/random/{source}

Operation ID: transit-generate-random-with-source

Generate random bytes

Parameters

Parameter	Type	Location	Required	Description
source	string	path	yes	Which system to source random data from, ether "platform", "seal", or "all".
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bytes	integer (default: 32)	no	The number of bytes to generate (POST body parameter). Defaults to 32 (256 bits).
format	string (default: base64)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "base64".
urlbytes	string	no	The number of bytes to generate (POST URL parameter)

Responses

200: OK

POST /{transit_mount_path}/random/{source}/{urlbytes}

Operation ID: transit-generate-random-with-source-and-bytes

Generate random bytes

Parameters

Parameter	Type	Location	Required	Description
source	string	path	yes	Which system to source random data from, ether "platform", "seal", or "all".
urlbytes	string	path	yes	The number of bytes to generate (POST URL parameter)
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bytes	integer (default: 32)	no	The number of bytes to generate (POST body parameter). Defaults to 32 (256 bits).
format	string (default: base64)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "base64".

Responses

200: OK

POST /{transit_mount_path}/random/{urlbytes}

Operation ID: transit-generate-random-with-bytes

Generate random bytes

Parameters

Parameter	Type	Location	Required	Description
urlbytes	string	path	yes	The number of bytes to generate (POST URL parameter)
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
bytes	integer (default: 32)	no	The number of bytes to generate (POST body parameter). Defaults to 32 (256 bits).
format	string (default: base64)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "base64".
source	string (default: platform)	no	Which system to source random data from, ether "platform", "seal", or "all".

Responses

200: OK

POST /{transit_mount_path}/restore

Operation ID: transit-restore-key

Restore the named key

Parameters

Parameter	Type	Location	Required	Description
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
backup	string	no	Backed up key data to be restored. This should be the output from the 'backup/' endpoint.
force	boolean (default: False)	no	If set and a key by the given name exists, force the restore operation and override the key.
name	string	no	If set, this will be the name of the restored key.

Responses

200: OK

POST /{transit_mount_path}/restore/{name}

Operation ID: transit-restore-and-rename-key

Restore the named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	If set, this will be the name of the restored key.
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
backup	string	no	Backed up key data to be restored. This should be the output from the 'backup/' endpoint.
force	boolean (default: False)	no	If set and a key by the given name exists, force the restore operation and override the key.

Responses

200: OK

POST /{transit_mount_path}/rewrap/{name}

Operation ID: transit-rewrap

Rewrap ciphertext

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the key
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
batch_input	array	no	Specifies a list of items to be re-encrypted in a single batch. When this parameter is set, if the parameters 'ciphertext', 'context' and 'nonce' are also set, they will be ignored. Any batch output will preserve the order of the batch input.
ciphertext	string	no	Ciphertext value to rewrap
context	string	no	Base64 encoded context for key derivation. Required for derived keys.
key_version	integer	no	The version of the key to use for encryption. Must be 0 (for latest) or a value greater than or equal to the min_encryption_version configured on the key.
nonce	string	no	Nonce for when convergent encryption is used

Responses

200: OK

POST /{transit_mount_path}/sign/{name}

Operation ID: transit-sign

Generate a signature for input data using the named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The key to use
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Deprecated: use "hash_algorithm" instead.
batch_input	array	no	Specifies a list of items for processing. When this parameter is set, any supplied 'input' or 'context' parameters will be ignored. Responses are returned in the 'batch_results' array component of the 'data' element of the response. Any batch output will preserve the order of the batch input
context	string	no	Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
hash_algorithm	string (default: sha2-256)	no	Hash algorithm to use (POST body parameter). Valid values are: * sha1 * sha2-224 * sha2-256 * sha2-384 * sha2-512 * sha3-224 * sha3-256 * sha3-384 * sha3-512 * none Defaults to "sha2-256". Not valid for all key types, including ed25519. Using none requires setting prehashed=true and signature_algorithm=pkcs1v15, yielding a PKCSv1_5_NoOID instead of the usual PKCSv1_5_DERnull signature.
input	string	no	The base64-encoded input data
key_version	integer	no	The version of the key to use for signing. Must be 0 (for latest) or a value greater than or equal to the min_encryption_version configured on the key.
marshaling_algorithm	string (default: asn1)	no	The method by which to marshal the signature. The default is 'asn1' which is used by openssl and X.509. It can also be set to 'jws' which is used for JWT signatures; setting it to this will also cause the encoding of the signature to be url-safe base64 instead of using standard base64 encoding. Currently only valid for ECDSA P-256 key types".
prehashed	boolean	no	Set to 'true' when the input is already hashed. If the key type is 'rsa-2048', 'rsa-3072' or 'rsa-4096', then the algorithm used to hash the input should be indicated by the 'algorithm' parameter.
salt_length	string (default: auto)	no	The salt length used to sign. Currently only applies to the RSA PSS signature scheme. Options are 'auto' (the default used by Golang, causing the salt to be as large as possible when signing), 'hash' (causes the salt length to equal the length of the hash used in the signature), or an integer between the minimum and the maximum permissible salt lengths for the given RSA key size. Defaults to 'auto'.
signature_algorithm	string	no	The signature algorithm to use for signing. Currently only applies to RSA key types. Options are 'pss' or 'pkcs1v15'. Defaults to 'pss'
urlalgorithm	string	no	Hash algorithm to use (POST URL parameter)

Responses

200: OK

POST /{transit_mount_path}/sign/{name}/{urlalgorithm}

Operation ID: transit-sign-with-algorithm

Generate a signature for input data using the named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The key to use
urlalgorithm	string	path	yes	Hash algorithm to use (POST URL parameter)
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Deprecated: use "hash_algorithm" instead.
batch_input	array	no	Specifies a list of items for processing. When this parameter is set, any supplied 'input' or 'context' parameters will be ignored. Responses are returned in the 'batch_results' array component of the 'data' element of the response. Any batch output will preserve the order of the batch input
context	string	no	Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
hash_algorithm	string (default: sha2-256)	no	Hash algorithm to use (POST body parameter). Valid values are: * sha1 * sha2-224 * sha2-256 * sha2-384 * sha2-512 * sha3-224 * sha3-256 * sha3-384 * sha3-512 * none Defaults to "sha2-256". Not valid for all key types, including ed25519. Using none requires setting prehashed=true and signature_algorithm=pkcs1v15, yielding a PKCSv1_5_NoOID instead of the usual PKCSv1_5_DERnull signature.
input	string	no	The base64-encoded input data
key_version	integer	no	The version of the key to use for signing. Must be 0 (for latest) or a value greater than or equal to the min_encryption_version configured on the key.
marshaling_algorithm	string (default: asn1)	no	The method by which to marshal the signature. The default is 'asn1' which is used by openssl and X.509. It can also be set to 'jws' which is used for JWT signatures; setting it to this will also cause the encoding of the signature to be url-safe base64 instead of using standard base64 encoding. Currently only valid for ECDSA P-256 key types".
prehashed	boolean	no	Set to 'true' when the input is already hashed. If the key type is 'rsa-2048', 'rsa-3072' or 'rsa-4096', then the algorithm used to hash the input should be indicated by the 'algorithm' parameter.
salt_length	string (default: auto)	no	The salt length used to sign. Currently only applies to the RSA PSS signature scheme. Options are 'auto' (the default used by Golang, causing the salt to be as large as possible when signing), 'hash' (causes the salt length to equal the length of the hash used in the signature), or an integer between the minimum and the maximum permissible salt lengths for the given RSA key size. Defaults to 'auto'.
signature_algorithm	string	no	The signature algorithm to use for signing. Currently only applies to RSA key types. Options are 'pss' or 'pkcs1v15'. Defaults to 'pss'

Responses

200: OK

POST /{transit_mount_path}/verify/{name}

Operation ID: transit-verify

Verify a signature or HMAC for input data created using the named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The key to use
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Deprecated: use "hash_algorithm" instead.
batch_input	array	no	Specifies a list of items for processing. When this parameter is set, any supplied 'input', 'hmac' or 'signature' parameters will be ignored. Responses are returned in the 'batch_results' array component of the 'data' element of the response. Any batch output will preserve the order of the batch input
context	string	no	Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
hash_algorithm	string (default: sha2-256)	no	Hash algorithm to use (POST body parameter). Valid values are: * sha1 * sha2-224 * sha2-256 * sha2-384 * sha2-512 * sha3-224 * sha3-256 * sha3-384 * sha3-512 * none Defaults to "sha2-256". Not valid for all key types. See note about none on signing path.
hmac	string	no	The HMAC, including vault header/key version
input	string	no	The base64-encoded input data to verify
marshaling_algorithm	string (default: asn1)	no	The method by which to unmarshal the signature when verifying. The default is 'asn1' which is used by openssl and X.509; can also be set to 'jws' which is used for JWT signatures in which case the signature is also expected to be url-safe base64 encoding instead of standard base64 encoding. Currently only valid for ECDSA P-256 key types".
prehashed	boolean	no	Set to 'true' when the input is already hashed. If the key type is 'rsa-2048', 'rsa-3072' or 'rsa-4096', then the algorithm used to hash the input should be indicated by the 'algorithm' parameter.
salt_length	string (default: auto)	no	The salt length used to sign. Currently only applies to the RSA PSS signature scheme. Options are 'auto' (the default used by Golang, causing the salt to be as large as possible when signing), 'hash' (causes the salt length to equal the length of the hash used in the signature), or an integer between the minimum and the maximum permissible salt lengths for the given RSA key size. Defaults to 'auto'.
signature	string	no	The signature, including vault header/key version
signature_algorithm	string	no	The signature algorithm to use for signature verification. Currently only applies to RSA key types. Options are 'pss' or 'pkcs1v15'. Defaults to 'pss'
urlalgorithm	string	no	Hash algorithm to use (POST URL parameter)

Responses

200: OK

POST /{transit_mount_path}/verify/{name}/{urlalgorithm}

Operation ID: transit-verify-with-algorithm

Verify a signature or HMAC for input data created using the named key

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The key to use
urlalgorithm	string	path	yes	Hash algorithm to use (POST URL parameter)
transit_mount_path	string	path	yes	Path that the backend was mounted at

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Deprecated: use "hash_algorithm" instead.
batch_input	array	no	Specifies a list of items for processing. When this parameter is set, any supplied 'input', 'hmac' or 'signature' parameters will be ignored. Responses are returned in the 'batch_results' array component of the 'data' element of the response. Any batch output will preserve the order of the batch input
context	string	no	Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
hash_algorithm	string (default: sha2-256)	no	Hash algorithm to use (POST body parameter). Valid values are: * sha1 * sha2-224 * sha2-256 * sha2-384 * sha2-512 * sha3-224 * sha3-256 * sha3-384 * sha3-512 * none Defaults to "sha2-256". Not valid for all key types. See note about none on signing path.
hmac	string	no	The HMAC, including vault header/key version
input	string	no	The base64-encoded input data to verify
marshaling_algorithm	string (default: asn1)	no	The method by which to unmarshal the signature when verifying. The default is 'asn1' which is used by openssl and X.509; can also be set to 'jws' which is used for JWT signatures in which case the signature is also expected to be url-safe base64 encoding instead of standard base64 encoding. Currently only valid for ECDSA P-256 key types".
prehashed	boolean	no	Set to 'true' when the input is already hashed. If the key type is 'rsa-2048', 'rsa-3072' or 'rsa-4096', then the algorithm used to hash the input should be indicated by the 'algorithm' parameter.
salt_length	string (default: auto)	no	The salt length used to sign. Currently only applies to the RSA PSS signature scheme. Options are 'auto' (the default used by Golang, causing the salt to be as large as possible when signing), 'hash' (causes the salt length to equal the length of the hash used in the signature), or an integer between the minimum and the maximum permissible salt lengths for the given RSA key size. Defaults to 'auto'.
signature	string	no	The signature, including vault header/key version
signature_algorithm	string	no	The signature algorithm to use for signature verification. Currently only applies to RSA key types. Options are 'pss' or 'pkcs1v15'. Defaults to 'pss'

Responses

200: OK

GET /{transit_mount_path}/wrapping_key

Operation ID: transit-read-wrapping-key

Returns the public key to use for wrapping imported keys

Parameters

Parameter	Type	Location	Required	Description
transit_mount_path	string	path	yes	Path that the backend was mounted at

Responses

200: OK

---

system

GET /sys/audit

Operation ID: auditing-list-enabled-devices

List the enabled audit devices.

Required sudo: yes

Responses

200: OK

POST /sys/audit-hash/{path}

Operation ID: auditing-calculate-hash

The hash of the given string via the given audit backend

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The name of the backend. Cannot be delimited. Example: "mysql"

Request body parameters

Parameter	Type	Required	Description
input	string	no

Responses

200: OK

Parameter	Type	Required	Description
hash	string	no

POST /sys/audit/{path}

Operation ID: auditing-enable-device

Enable a new audit device at the supplied path.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The name of the backend. Cannot be delimited. Example: "mysql"

Request body parameters

Parameter	Type	Required	Description
description	string	no	User-friendly description for this audit backend.
local	boolean (default: False)	no	Mark the mount as a local mount, which is not replicated and is unaffected by replication.
options	object	no	Configuration options for the audit backend.
type	string	no	The type of the backend. Example: "mysql"

Responses

204: OK

DELETE /sys/audit/{path}

Operation ID: auditing-disable-device

Disable the audit device at the given path.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The name of the backend. Cannot be delimited. Example: "mysql"

Responses

204: OK

GET /sys/auth

Operation ID: auth-list-enabled-methods

List the currently enabled credential backends.

Responses

200: OK

GET /sys/auth/{path}

Operation ID: auth-read-configuration

Read the configuration of the auth engine at the given path.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Cannot be delimited. Example: "user"

Responses

200: OK

Parameter	Type	Required	Description
accessor	string	no
config	object	no
deprecation_status	string	no
description	string	no
external_entropy_access	boolean	no
local	boolean	no
options	object	no
plugin_version	string	no
running_plugin_version	string	no
running_sha256	string	no
seal_wrap	boolean	no
type	string	no
uuid	string	no

POST /sys/auth/{path}

Operation ID: auth-enable-method

Enables a new auth method.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Cannot be delimited. Example: "user"

Request body parameters

Parameter	Type	Required	Description
config	object	no	Configuration for this mount, such as plugin_name.
description	string	no	User-friendly description for this credential backend.
external_entropy_access	boolean (default: False)	no	Whether to give the mount access to Stronghold's external entropy.
local	boolean (default: False)	no	Mark the mount as a local mount, which is not replicated and is unaffected by replication.
options	object	no	The options to pass into the backend. Should be a json object with string keys and values.
plugin_name	string	no	Name of the auth plugin to use based from the name in the plugin catalog.
plugin_version	string	no	The semantic version of the plugin to use.
seal_wrap	boolean (default: False)	no	Whether to turn on seal wrapping for the mount.
type	string	no	The type of the backend. Example: "userpass"

Responses

204: OK

DELETE /sys/auth/{path}

Operation ID: auth-disable-method

Disable the auth method at the given auth path

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Cannot be delimited. Example: "user"

Responses

204: OK

GET /sys/auth/{path}/tune

Operation ID: auth-read-tuning-information

Reads the given auth path's configuration.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Tune the configuration parameters for an auth path.

Responses

200: OK

Parameter	Type	Required	Description
allowed_managed_keys	array	no
allowed_response_headers	array	no
audit_non_hmac_request_keys	array	no
audit_non_hmac_response_keys	array	no
default_lease_ttl	integer	no
description	string	no
external_entropy_access	boolean	no
force_no_cache	boolean	no
listing_visibility	string	no
max_lease_ttl	integer	no
options	object	no
passthrough_request_headers	array	no
plugin_version	string	no
token_type	string	no
user_lockout_counter_reset_duration	integer	no
user_lockout_disable	boolean	no
user_lockout_duration	integer	no
user_lockout_threshold	integer	no

POST /sys/auth/{path}/tune

Operation ID: auth-tune-configuration-parameters

Tune configuration parameters for a given auth path.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	Tune the configuration parameters for an auth path.

Request body parameters

Parameter	Type	Required	Description
allowed_response_headers	array	no	A list of headers to whitelist and allow a plugin to set on responses.
audit_non_hmac_request_keys	array	no	The list of keys in the request data object that will not be HMAC'ed by audit devices.
audit_non_hmac_response_keys	array	no	The list of keys in the response data object that will not be HMAC'ed by audit devices.
default_lease_ttl	string	no	The default lease TTL for this mount.
description	string	no	User-friendly description for this credential backend.
listing_visibility	string	no	Determines the visibility of the mount in the UI-specific listing endpoint. Accepted value are 'unauth' and 'hidden', with the empty default ('') behaving like 'hidden'.
max_lease_ttl	string	no	The max lease TTL for this mount.
options	object	no	The options to pass into the backend. Should be a json object with string keys and values.
passthrough_request_headers	array	no	A list of headers to whitelist and pass from the request to the plugin.
plugin_version	string	no	The semantic version of the plugin to use.
token_type	string	no	The type of token to issue (service or batch).
user_lockout_config	object	no	The user lockout configuration to pass into the backend. Should be a json object with string keys and values.

Responses

204: OK

POST /sys/capabilities

Operation ID: query-token-capabilities

Fetches the capabilities of the given token on the given path.

Request body parameters

Parameter	Type	Required	Description
path	array	no	⚠️ Deprecated. Use 'paths' instead.
paths	array	no	Paths on which capabilities are being queried.
token	string	no	Token for which capabilities are being queried.

Responses

200: OK

POST /sys/capabilities-accessor

Operation ID: query-token-accessor-capabilities

Fetches the capabilities of the token associated with the given token, on the given path.

Request body parameters

Parameter	Type	Required	Description
accessor	string	no	Accessor of the token for which capabilities are being queried.
path	array	no	⚠️ Deprecated. Use 'paths' instead.
paths	array	no	Paths on which capabilities are being queried.

Responses

200: OK

POST /sys/capabilities-self

Operation ID: query-token-self-capabilities

Fetches the capabilities of the given token on the given path.

Request body parameters

Parameter	Type	Required	Description
path	array	no	⚠️ Deprecated. Use 'paths' instead.
paths	array	no	Paths on which capabilities are being queried.
token	string	no	Token for which capabilities are being queried.

Responses

200: OK

GET /sys/config/auditing/request-headers

Operation ID: auditing-list-request-headers

List the request headers that are configured to be audited.

Required sudo: yes

Responses

200: OK

Parameter	Type	Required	Description
headers	object	no

GET /sys/config/auditing/request-headers/{header}

Operation ID: auditing-read-request-header-information

List the information for the given request header.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
header	string	path	yes

Responses

200: OK

POST /sys/config/auditing/request-headers/{header}

Operation ID: auditing-enable-request-header

Enable auditing of a header.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
header	string	path	yes

Request body parameters

Parameter	Type	Required	Description
hmac	boolean	no

Responses

204: OK

DELETE /sys/config/auditing/request-headers/{header}

Operation ID: auditing-disable-request-header

Disable auditing of the given request header.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
header	string	path	yes

Responses

204: OK

GET /sys/config/control-group

Operation ID: enterprise-stub-read-config-control-group

Responses

200: OK

POST /sys/config/control-group

Operation ID: enterprise-stub-write-config-control-group

Responses

200: OK

DELETE /sys/config/control-group

Operation ID: enterprise-stub-delete-config-control-group

Responses

204: empty body

GET /sys/config/cors

Operation ID: cors-read-configuration

Return the current CORS settings.

Required sudo: yes

Responses

200: OK

Parameter	Type	Required	Description
allowed_headers	array	no
allowed_origins	array	no
enabled	boolean	no

POST /sys/config/cors

Operation ID: cors-configure

Configure the CORS settings.

Required sudo: yes

Request body parameters

Parameter	Type	Required	Description
allowed_headers	array	no	A comma-separated string or array of strings indicating headers that are allowed on cross-origin requests.
allowed_origins	array	no	A comma-separated string or array of strings indicating origins that may make cross-origin requests.
enable	boolean	no	Enables or disables CORS headers on requests.

Responses

204: OK

DELETE /sys/config/cors

Operation ID: cors-delete-configuration

Remove any CORS settings.

Required sudo: yes

Responses

204: OK

GET /sys/config/group-policy-application

Operation ID: enterprise-stub-read-config-group-policy-application

Responses

200: OK

POST /sys/config/group-policy-application

Operation ID: enterprise-stub-write-config-group-policy-application

Responses

200: OK

POST /sys/config/reload/{subsystem}

Operation ID: reload-subsystem

Reload the given subsystem

Parameters

Parameter	Type	Location	Required	Description
subsystem	string	path	yes

Responses

204: OK

GET /sys/config/state/sanitized

Operation ID: read-sanitized-configuration-state

Return a sanitized version of the Stronghold server configuration.

Responses

200: OK

GET /sys/config/ui/headers

Operation ID: ui-headers-list

Return a list of configured UI headers.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200:

Parameter	Type	Required	Description
keys	array	no	Lists of configured UI headers. Omitted if list is empty

GET /sys/config/ui/headers/{header}

Operation ID: ui-headers-read-configuration

Return the given UI header's configuration

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
header	string	path	yes	The name of the header.

Responses

200: OK

Parameter	Type	Required	Description
value	string	no	returns the first header value when multivalue request parameter is false
values	array	no	returns all header values when multivalue request parameter is true

POST /sys/config/ui/headers/{header}

Operation ID: ui-headers-configure

Configure the values to be returned for the UI header.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
header	string	path	yes	The name of the header.

Request body parameters

Parameter	Type	Required	Description
multivalue	boolean	no	Returns multiple values if true
values	array	no	The values to set the header.

Responses

200: OK

DELETE /sys/config/ui/headers/{header}

Operation ID: ui-headers-delete-configuration

Remove a UI header.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
header	string	path	yes	The name of the header.

Responses

204: OK

POST /sys/control-group/authorize

Operation ID: enterprise-stub-write-control-group-authorize

Responses

200: OK

POST /sys/control-group/request

Operation ID: enterprise-stub-write-control-group-request

Responses

200: OK

POST /sys/decode-token

Operation ID: decode

Decodes the encoded token with the otp.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
encoded_token	string	no	Specifies the encoded token (result from generate-root).
otp	string	no	Specifies the otp code for decode.

Responses

200: OK

GET /sys/experiments

Operation ID: list-experimental-features

Returns the available and enabled experiments

Responses

200: OK

GET /sys/generate-root

Operation ID: root-token-generation-read-progress2

Read the configuration and progress of the current root generation attempt.

Responses

200: OK

Parameter	Type	Required	Description
complete	boolean	no
encoded_root_token	string	no
encoded_token	string	no
nonce	string	no
otp	string	no
otp_length	integer	no
pgp_fingerprint	string	no
progress	integer	no
required	integer	no
started	boolean	no

POST /sys/generate-root

Operation ID: root-token-generation-initialize-2

Initializes a new root generation attempt.

Request body parameters

Parameter	Type	Required	Description
pgp_key	string	no	Specifies a base64-encoded PGP public key.

Responses

200: OK

Parameter	Type	Required	Description
complete	boolean	no
encoded_root_token	string	no
encoded_token	string	no
nonce	string	no
otp	string	no
otp_length	integer	no
pgp_fingerprint	string	no
progress	integer	no
required	integer	no
started	boolean	no

DELETE /sys/generate-root

Operation ID: root-token-generation-cancel-2

Cancels any in-progress root generation attempt.

Responses

204: OK

GET /sys/generate-root/attempt

Operation ID: root-token-generation-read-progress

Read the configuration and progress of the current root generation attempt.

Available without authentication: yes

Responses

200: OK

Parameter	Type	Required	Description
complete	boolean	no
encoded_root_token	string	no
encoded_token	string	no
nonce	string	no
otp	string	no
otp_length	integer	no
pgp_fingerprint	string	no
progress	integer	no
required	integer	no
started	boolean	no

POST /sys/generate-root/attempt

Operation ID: root-token-generation-initialize

Initializes a new root generation attempt.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
pgp_key	string	no	Specifies a base64-encoded PGP public key.

Responses

200: OK

Parameter	Type	Required	Description
complete	boolean	no
encoded_root_token	string	no
encoded_token	string	no
nonce	string	no
otp	string	no
otp_length	integer	no
pgp_fingerprint	string	no
progress	integer	no
required	integer	no
started	boolean	no

DELETE /sys/generate-root/attempt

Operation ID: root-token-generation-cancel

Cancels any in-progress root generation attempt.

Available without authentication: yes

Responses

204: OK

POST /sys/generate-root/update

Operation ID: root-token-generation-update

Enter a single unseal key share to progress the root generation attempt.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
key	string	no	Specifies a single unseal key share.
nonce	string	no	Specifies the nonce of the attempt.

Responses

200: OK

Parameter	Type	Required	Description
complete	boolean	no
encoded_root_token	string	no
encoded_token	string	no
nonce	string	no
otp	string	no
otp_length	integer	no
pgp_fingerprint	string	no
progress	integer	no
required	integer	no
started	boolean	no

GET /sys/ha-status

Operation ID: ha-status

Check the HA status of a Stronghold cluster

Responses

200: OK

Parameter	Type	Required	Description
nodes	array	no

GET /sys/health

Operation ID: read-health-status

Returns the health status of Stronghold.

Available without authentication: yes

Responses

200: initialized, unsealed, and active

429: unsealed and standby

472: data recovery mode replication secondary and active

501: not initialized

503: sealed

GET /sys/host-info

Operation ID: collect-host-information

Information about the host instance that this Stronghold server is running on.

Responses

200: OK

Parameter	Type	Required	Description
cpu	array	no
cpu_times	array	no
disk	array	no
host	object	no
memory	object	no
timestamp	string	no

GET /sys/in-flight-req

Operation ID: collect-in-flight-request-information

reports in-flight requests

Responses

200: OK

GET /sys/init

Operation ID: read-initialization-status

Returns the initialization status of Stronghold.

Available without authentication: yes

Responses

200: OK

POST /sys/init

Operation ID: initialize

Initialize a new Stronghold.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
pgp_keys	array	no	Specifies an array of PGP public keys used to encrypt the output unseal keys. Ordering is preserved. The keys must be base64-encoded from their original binary representation. The size of this array must be the same as secret_shares.
recovery_pgp_keys	array	no	Specifies an array of PGP public keys used to encrypt the output recovery keys. Ordering is preserved. The keys must be base64-encoded from their original binary representation. The size of this array must be the same as recovery_shares.
recovery_shares	integer	no	Specifies the number of shares to split the recovery key into.
recovery_threshold	integer	no	Specifies the number of shares required to reconstruct the recovery key. This must be less than or equal to recovery_shares.
root_token_pgp_key	string	no	Specifies a PGP public key used to encrypt the initial root token. The key must be base64-encoded from its original binary representation.
secret_shares	integer	no	Specifies the number of shares to split the unseal key into.
secret_threshold	integer	no	Specifies the number of shares required to reconstruct the unseal key. This must be less than or equal secret_shares. If using Stronghold HSM with auto-unsealing, this value must be the same as secret_shares.
stored_shares	integer	no	Specifies the number of shares that should be encrypted by the HSM and stored for auto-unsealing. Currently must be the same as secret_shares.

Responses

200: OK

GET /sys/internal/counters/activity

Operation ID: internal-client-activity-report-counts

Report the client count metrics, for this namespace and all child namespaces.

Responses

200: OK

GET /sys/internal/counters/activity/export

Operation ID: internal-client-activity-export

Report the client count metrics, for this namespace and all child namespaces.

Responses

200: OK

GET /sys/internal/counters/activity/monthly

Operation ID: internal-client-activity-report-counts-this-month

Report the number of clients for this month, for this namespace and all child namespaces.

Responses

200: OK

GET /sys/internal/counters/config

Operation ID: internal-client-activity-read-configuration

Read the client count tracking configuration.

Responses

200: OK

POST /sys/internal/counters/config

Operation ID: internal-client-activity-configure

Enable or disable collection of client count, set retention period, or set default reporting period.

Request body parameters

Parameter	Type	Required	Description
default_report_months	integer (default: 12)	no	Number of months to report if no start date specified.
enabled	string (default: default)	no	Enable or disable collection of client count: enable, disable, or default.
retention_months	integer (default: 24)	no	Number of months of client data to retain. Setting to 0 will clear all existing data.

Responses

200: OK

GET /sys/internal/counters/entities

Operation ID: internal-count-entities

Backwards compatibility is not guaranteed for this API

Responses

200: OK

Parameter	Type	Required	Description
counters	object	no

GET /sys/internal/counters/requests

Operation ID: internal-count-requests

Backwards compatibility is not guaranteed for this API

Responses

200: OK

GET /sys/internal/counters/tokens

Operation ID: internal-count-tokens

Backwards compatibility is not guaranteed for this API

Responses

200: OK

Parameter	Type	Required	Description
counters	object	no

GET /sys/internal/inspect/router/{tag}

Operation ID: internal-inspect-router

Expose the route entry and mount entry tables present in the router

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
tag	string	path	yes	Name of subtree being observed

Responses

200: OK

GET /sys/internal/specs/openapi

Operation ID: internal-generate-open-api-document

Generate an OpenAPI 3 document of all mounted paths.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
generic_mount_paths	boolean	query	no	Use generic mount paths

Responses

200: OK

POST /sys/internal/specs/openapi

Operation ID: internal-generate-open-api-document-with-parameters

Generate an OpenAPI 3 document of all mounted paths.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
generic_mount_paths	boolean	query	no	Use generic mount paths

Request body parameters

Parameter	Type	Required	Description
context	string	no	Context string appended to every operationId

Responses

200: OK

GET /sys/internal/ui/feature-flags

Operation ID: internal-ui-list-enabled-feature-flags

Lists enabled feature flags.

Responses

200: OK

Parameter	Type	Required	Description
feature_flags	array	no

GET /sys/internal/ui/mounts

Operation ID: internal-ui-list-enabled-visible-mounts

Lists all enabled and visible auth and secrets mounts.

Available without authentication: yes

Responses

200: OK

Parameter	Type	Required	Description
auth	object	no	auth mounts
secret	object	no	secret mounts

GET /sys/internal/ui/mounts/{path}

Operation ID: internal-ui-read-mount-information

Return information about the given mount.

Available without authentication: yes

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path of the mount.

Responses

200: OK

Parameter	Type	Required	Description
accessor	string	no
config	object	no
description	string	no
external_entropy_access	boolean	no
local	boolean	no
options	object	no
path	string	no
plugin_version	string	no
running_plugin_version	string	no
running_sha256	string	no
seal_wrap	boolean	no
type	string	no
uuid	string	no

GET /sys/internal/ui/namespaces

Operation ID: internal-ui-list-namespaces

Backwards compatibility is not guaranteed for this API

Available without authentication: yes

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no	field is only returned if there are one or more namespaces

GET /sys/internal/ui/resultant-acl

Operation ID: internal-ui-read-resultant-acl

Backwards compatibility is not guaranteed for this API

Responses

200: OK

Parameter	Type	Required	Description
exact_paths	object	no
glob_paths	object	no
root	boolean	no

204: empty response returned if no client token

GET /sys/key-status

Operation ID: encryption-key-status

Provides information about the backend encryption key.

Responses

200: OK

GET /sys/leader

Operation ID: leader-status

Returns the high availability status and current leader instance of Stronghold.

Available without authentication: yes

Responses

200: OK

Parameter	Type	Required	Description
active_time	string	no
ha_enabled	boolean	no
is_self	boolean	no
last_wal	integer	no
leader_address	string	no
leader_cluster_address	string	no
performance_standby	boolean	no
performance_standby_last_remote_wal	integer	no
raft_applied_index	integer	no
raft_committed_index	integer	no

GET /sys/leases

Operation ID: leases-list

List leases associated with this Stronghold cluster

Required sudo: yes

Responses

200: OK

Parameter	Type	Required	Description
counts	integer	no	Number of matching leases per mount
lease_count	integer	no	Number of matching leases

GET /sys/leases/count

Operation ID: leases-count

Count of leases associated with this Stronghold cluster

Responses

200: OK

Parameter	Type	Required	Description
counts	integer	no	Number of matching leases per mount
lease_count	integer	no	Number of matching leases

POST /sys/leases/lookup

Operation ID: leases-read-lease

View or list lease metadata.

Request body parameters

Parameter	Type	Required	Description
lease_id	string	no	The lease identifier to renew. This is included with a lease.

Responses

200: OK

Parameter	Type	Required	Description
expire_time	string	no	Optional lease expiry time
id	string	no	Lease id
issue_time	string	no	Timestamp for the lease's issue time
last_renewal	string	no	Optional Timestamp of the last time the lease was renewed
renewable	boolean	no	True if the lease is able to be renewed
ttl	integer	no	Time to Live set for the lease, returns 0 if unset

GET /sys/leases/lookup/

Operation ID: leases-look-up

View or list lease metadata.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no	A list of lease ids

GET /sys/leases/lookup/{prefix}

Operation ID: leases-look-up-with-prefix

View or list lease metadata.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
prefix	string	path	yes	The path to list leases under. Example: "aws/creds/deploy"
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no	A list of lease ids

POST /sys/leases/renew

Operation ID: leases-renew-lease

Renews a lease, requesting to extend the lease.

Request body parameters

Parameter	Type	Required	Description
increment	integer	no	The desired increment in seconds to the lease
lease_id	string	no	The lease identifier to renew. This is included with a lease.
url_lease_id	string	no	The lease identifier to renew. This is included with a lease.

Responses

204: OK

POST /sys/leases/renew/{url_lease_id}

Operation ID: leases-renew-lease-with-id

Renews a lease, requesting to extend the lease.

Parameters

Parameter	Type	Location	Required	Description
url_lease_id	string	path	yes	The lease identifier to renew. This is included with a lease.

Request body parameters

Parameter	Type	Required	Description
increment	integer	no	The desired increment in seconds to the lease
lease_id	string	no	The lease identifier to renew. This is included with a lease.

Responses

204: OK

POST /sys/leases/revoke

Operation ID: leases-revoke-lease

Revokes a lease immediately.

Request body parameters

Parameter	Type	Required	Description
lease_id	string	no	The lease identifier to renew. This is included with a lease.
sync	boolean (default: True)	no	Whether or not to perform the revocation synchronously
url_lease_id	string	no	The lease identifier to renew. This is included with a lease.

Responses

204: OK

POST /sys/leases/revoke-force/{prefix}

Operation ID: leases-force-revoke-lease-with-prefix

Revokes all secrets or tokens generated under a given prefix immediately

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
prefix	string	path	yes	The path to revoke keys under. Example: "prod/aws/ops"

Responses

204: OK

POST /sys/leases/revoke-prefix/{prefix}

Operation ID: leases-revoke-lease-with-prefix

Revokes all secrets (via a lease ID prefix) or tokens (via the tokens' path property) generated under a given prefix immediately.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
prefix	string	path	yes	The path to revoke keys under. Example: "prod/aws/ops"

Request body parameters

Parameter	Type	Required	Description
sync	boolean (default: True)	no	Whether or not to perform the revocation synchronously

Responses

204: OK

POST /sys/leases/revoke/{url_lease_id}

Operation ID: leases-revoke-lease-with-id

Revokes a lease immediately.

Parameters

Parameter	Type	Location	Required	Description
url_lease_id	string	path	yes	The lease identifier to renew. This is included with a lease.

Request body parameters

Parameter	Type	Required	Description
lease_id	string	no	The lease identifier to renew. This is included with a lease.
sync	boolean (default: True)	no	Whether or not to perform the revocation synchronously

Responses

204: OK

POST /sys/leases/tidy

Operation ID: leases-tidy

This endpoint performs cleanup tasks that can be run if certain error conditions have occurred.

Responses

204: OK

GET /sys/locked-users

Operation ID: locked-users-list

Report the locked user count metrics, for this namespace and all child namespaces.

Responses

200: OK

POST /sys/locked-users/{mount_accessor}/unlock/{alias_identifier}

Operation ID: locked-users-unlock

Unlocks the user with given mount_accessor and alias_identifier

Parameters

Parameter	Type	Location	Required	Description
alias_identifier	string	path	yes	It is the name of the alias (user). For example, if the alias belongs to userpass backend, the name should be a valid username within userpass auth method. If the alias belongs to an approle auth method, the name should be a valid RoleID
mount_accessor	string	path	yes	MountAccessor is the identifier of the mount entry to which the user belongs

Responses

200: OK

GET /sys/loggers

Operation ID: loggers-read-verbosity-level

Read the log level for all existing loggers.

Responses

200: OK

POST /sys/loggers

Operation ID: loggers-update-verbosity-level

Modify the log level for all existing loggers.

Request body parameters

Parameter	Type	Required	Description
level	string	no	Log verbosity level. Supported values (in order of detail) are "trace", "debug", "info", "warn", and "error".

Responses

204: OK

DELETE /sys/loggers

Operation ID: loggers-revert-verbosity-level

Revert the all loggers to use log level provided in config.

Responses

204: OK

GET /sys/loggers/{name}

Operation ID: loggers-read-verbosity-level-for

Read the log level for a single logger.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the logger to be modified.

Responses

200: OK

POST /sys/loggers/{name}

Operation ID: loggers-update-verbosity-level-for

Modify the log level of a single logger.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the logger to be modified.

Request body parameters

Parameter	Type	Required	Description
level	string	no	Log verbosity level. Supported values (in order of detail) are "trace", "debug", "info", "warn", and "error".

Responses

204: OK

DELETE /sys/loggers/{name}

Operation ID: loggers-revert-verbosity-level-for

Revert a single logger to use log level provided in config.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the logger to be modified.

Responses

204: OK

GET /sys/managed-keys/{type}

Operation ID: enterprise-stub-list-managed-keys-type

Parameters

Parameter	Type	Location	Required	Description
type	string	path	yes
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /sys/managed-keys/{type}/{name}

Operation ID: enterprise-stub-read-managed-keys-type-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes
type	string	path	yes

Responses

200: OK

POST /sys/managed-keys/{type}/{name}

Operation ID: enterprise-stub-write-managed-keys-type-name

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes
type	string	path	yes

Responses

200: OK

DELETE /sys/managed-keys/{type}/{name}

Operation ID: enterprise-stub-delete-managed-keys-type-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes
type	string	path	yes

Responses

204: empty body

POST /sys/managed-keys/{type}/{name}/test/sign

Operation ID: enterprise-stub-write-managed-keys-type-name-test-sign

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes
type	string	path	yes

Responses

200: OK

GET /sys/metrics

Operation ID: metrics

Export the metrics aggregated for telemetry purpose.

Parameters

Parameter	Type	Location	Required	Description
format	string	query	no	Format to export metrics into. Currently accepts only "prometheus".

Responses

200: OK

POST /sys/mfa/validate

Operation ID: mfa-validate

Validates the login for the given MFA methods. Upon successful validation, it returns an auth response containing the client token

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
mfa_payload	object	yes	A map from MFA method ID to a slice of passcodes or an empty slice if the method does not use passcodes
mfa_request_id	string	yes	ID for this MFA request

Responses

200: OK

GET /sys/monitor

Operation ID: monitor

Parameters

Parameter	Type	Location	Required	Description
log_format	string	query	no	Output format of logs. Supported values are "standard" and "json". The default is "standard".
log_level	string	query	no	Log level to view system logs at. Currently supported values are "trace", "debug", "info", "warn", "error".

Responses

200: OK

GET /sys/mounts

Operation ID: mounts-list-secrets-engines

List the currently mounted backends.

Responses

200: OK

GET /sys/mounts/{path}

Operation ID: mounts-read-configuration

Read the configuration of the secret engine at the given path.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Example: "aws/east"

Responses

200: OK

Parameter	Type	Required	Description
accessor	string	no
config	object	no	Configuration for this mount, such as default_lease_ttl and max_lease_ttl.
deprecation_status	string	no
description	string	no	User-friendly description for this mount.
external_entropy_access	boolean	no
local	boolean (default: False)	no	Mark the mount as a local mount, which is not replicated and is unaffected by replication.
options	object	no	The options to pass into the backend. Should be a json object with string keys and values.
plugin_version	string	no	The semantic version of the plugin to use.
running_plugin_version	string	no
running_sha256	string	no
seal_wrap	boolean (default: False)	no	Whether to turn on seal wrapping for the mount.
type	string	no	The type of the backend. Example: "passthrough"
uuid	string	no

POST /sys/mounts/{path}

Operation ID: mounts-enable-secrets-engine

Enable a new secrets engine at the given path.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Example: "aws/east"

Request body parameters

Parameter	Type	Required	Description
config	object	no	Configuration for this mount, such as default_lease_ttl and max_lease_ttl.
description	string	no	User-friendly description for this mount.
external_entropy_access	boolean (default: False)	no	Whether to give the mount access to Stronghold's external entropy.
local	boolean (default: False)	no	Mark the mount as a local mount, which is not replicated and is unaffected by replication.
options	object	no	The options to pass into the backend. Should be a json object with string keys and values.
plugin_name	string	no	Name of the plugin to mount based from the name registered in the plugin catalog.
plugin_version	string	no	The semantic version of the plugin to use.
seal_wrap	boolean (default: False)	no	Whether to turn on seal wrapping for the mount.
type	string	no	The type of the backend. Example: "passthrough"

Responses

204: OK

DELETE /sys/mounts/{path}

Operation ID: mounts-disable-secrets-engine

Disable the mount point specified at the given path.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Example: "aws/east"

Responses

200: OK

GET /sys/mounts/{path}/tune

Operation ID: mounts-read-tuning-information

Tune backend configuration parameters for this mount.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Example: "aws/east"

Responses

200: OK

Parameter	Type	Required	Description
allowed_managed_keys	array	no
allowed_response_headers	array	no	A list of headers to whitelist and allow a plugin to set on responses.
audit_non_hmac_request_keys	array	no
audit_non_hmac_response_keys	array	no
default_lease_ttl	integer	no	The default lease TTL for this mount.
description	string	no	User-friendly description for this credential backend.
external_entropy_access	boolean	no
force_no_cache	boolean	no
listing_visibility	string	no
max_lease_ttl	integer	no	The max lease TTL for this mount.
options	object	no	The options to pass into the backend. Should be a json object with string keys and values.
passthrough_request_headers	array	no
plugin_version	string	no	The semantic version of the plugin to use.
token_type	string	no	The type of token to issue (service or batch).
user_lockout_counter_reset_duration	integer	no
user_lockout_disable	boolean	no
user_lockout_duration	integer	no
user_lockout_threshold	integer	no

POST /sys/mounts/{path}/tune

Operation ID: mounts-tune-configuration-parameters

Tune backend configuration parameters for this mount.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Example: "aws/east"

Request body parameters

Parameter	Type	Required	Description
allowed_managed_keys	array	no
allowed_response_headers	array	no	A list of headers to whitelist and allow a plugin to set on responses.
audit_non_hmac_request_keys	array	no	The list of keys in the request data object that will not be HMAC'ed by audit devices.
audit_non_hmac_response_keys	array	no	The list of keys in the response data object that will not be HMAC'ed by audit devices.
cmd_enable_repl	boolean	no	Enable the replication for this mount
default_lease_ttl	string	no	The default lease TTL for this mount.
description	string	no	User-friendly description for this credential backend.
listing_visibility	string	no	Determines the visibility of the mount in the UI-specific listing endpoint. Accepted value are 'unauth' and 'hidden', with the empty default ('') behaving like 'hidden'.
max_lease_ttl	string	no	The max lease TTL for this mount.
options	object	no	The options to pass into the backend. Should be a json object with string keys and values.
passthrough_request_headers	array	no	A list of headers to whitelist and pass from the request to the plugin.
plugin_version	string	no	The semantic version of the plugin to use.
src_ca_cert	string	no
src_secret_path	array	no
src_token	string	no
sync_period_min	integer	no
token_type	string	no	The type of token to issue (service or batch).
user_lockout_config	object	no	The user lockout configuration to pass into the backend. Should be a json object with string keys and values.

Responses

200: OK

GET /sys/namespaces/

Operation ID: namespaces-list-namespaces

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /sys/namespaces/{path}

Operation ID: namespaces-read-namespace

Read namespace info

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Example: "aws/east"

Responses

200: OK

POST /sys/namespaces/{path}

Operation ID: namespaces-create-namespace

Create a new namespace at the given path.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Example: "aws/east"

Request body parameters

Parameter	Type	Required	Description
custom_metadata	object	no	User-provided key-value pairs that are used to describe information about a secret.

Responses

204: OK

DELETE /sys/namespaces/{path}

Operation ID: namespaces-delete-namespace

Delete namespace specified at the given path.

Parameters

Parameter	Type	Location	Required	Description
path	string	path	yes	The path to mount to. Example: "aws/east"

Responses

200: OK

GET /sys/plugins/catalog

Operation ID: plugins-catalog-list-plugins

Lists all the plugins known to Stronghold

Responses

200: OK

Parameter	Type	Required	Description
detailed	object	no

GET /sys/plugins/catalog/{name}

Operation ID: plugins-catalog-read-plugin-configuration

Return the configuration data for the plugin with the given name.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the plugin

Responses

200: OK

Parameter	Type	Required	Description
args	array	no	The args passed to plugin command.
builtin	boolean	no
command	string	no	The command used to start the plugin. The executable defined in this command must exist in stronghold's plugin directory.
deprecation_status	string	no
name	string	no	The name of the plugin
sha256	string	no	The SHA256 sum of the executable used in the command field. This should be HEX encoded.
version	string	no	The semantic version of the plugin to use.

POST /sys/plugins/catalog/{name}

Operation ID: plugins-catalog-register-plugin

Register a new plugin, or updates an existing one with the supplied name.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the plugin

Request body parameters

Parameter	Type	Required	Description
args	array	no	The args passed to plugin command.
command	string	no	The command used to start the plugin. The executable defined in this command must exist in stronghold's plugin directory.
env	array	no	The environment variables passed to plugin command. Each entry is of the form "key=value".
sha256	string	no	The SHA256 sum of the executable used in the command field. This should be HEX encoded.
type	string	no	The type of the plugin, may be auth, secret, or database
version	string	no	The semantic version of the plugin to use.

Responses

200: OK

DELETE /sys/plugins/catalog/{name}

Operation ID: plugins-catalog-remove-plugin

Remove the plugin with the given name.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the plugin

Responses

200: OK

GET /sys/plugins/catalog/{type}

Operation ID: plugins-catalog-list-plugins-with-type

List the plugins in the catalog.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
type	string	path	yes	The type of the plugin, may be auth, secret, or database
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no	List of plugin names in the catalog

GET /sys/plugins/catalog/{type}/{name}

Operation ID: plugins-catalog-read-plugin-configuration-with-type

Return the configuration data for the plugin with the given name.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the plugin
type	string	path	yes	The type of the plugin, may be auth, secret, or database

Responses

200: OK

Parameter	Type	Required	Description
args	array	no	The args passed to plugin command.
builtin	boolean	no
command	string	no	The command used to start the plugin. The executable defined in this command must exist in stronghold's plugin directory.
deprecation_status	string	no
name	string	no	The name of the plugin
sha256	string	no	The SHA256 sum of the executable used in the command field. This should be HEX encoded.
version	string	no	The semantic version of the plugin to use.

POST /sys/plugins/catalog/{type}/{name}

Operation ID: plugins-catalog-register-plugin-with-type

Register a new plugin, or updates an existing one with the supplied name.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the plugin
type	string	path	yes	The type of the plugin, may be auth, secret, or database

Request body parameters

Parameter	Type	Required	Description
args	array	no	The args passed to plugin command.
command	string	no	The command used to start the plugin. The executable defined in this command must exist in stronghold's plugin directory.
env	array	no	The environment variables passed to plugin command. Each entry is of the form "key=value".
sha256	string	no	The SHA256 sum of the executable used in the command field. This should be HEX encoded.
version	string	no	The semantic version of the plugin to use.

Responses

200: OK

DELETE /sys/plugins/catalog/{type}/{name}

Operation ID: plugins-catalog-remove-plugin-with-type

Remove the plugin with the given name.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the plugin
type	string	path	yes	The type of the plugin, may be auth, secret, or database

Responses

200: OK

POST /sys/plugins/reload/backend

Operation ID: plugins-reload-backends

Reload mounted plugin backends.

Request body parameters

Parameter	Type	Required	Description
mounts	array	no	The mount paths of the plugin backends to reload.
plugin	string	no	The name of the plugin to reload, as registered in the plugin catalog.
scope	string	no

Responses

200: OK

Parameter	Type	Required	Description
reload_id	string	no

202: OK

Parameter	Type	Required	Description
reload_id	string	no

GET /sys/plugins/reload/backend/status

Operation ID: enterprise-stub-read-plugins-reload-backend-status

Responses

200: OK

GET /sys/policies/acl

Operation ID: policies-list-acl-policies

List the configured access control policies.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no
policies	array	no

GET /sys/policies/acl/{name}

Operation ID: policies-read-acl-policy

Retrieve information about the named ACL policy.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the policy. Example: "ops"

Responses

200: OK

Parameter	Type	Required	Description
name	string	no
policy	string	no
rules	string	no

POST /sys/policies/acl/{name}

Operation ID: policies-write-acl-policy

Add a new or update an existing ACL policy.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the policy. Example: "ops"

Request body parameters

Parameter	Type	Required	Description
policy	string	no	The rules of the policy.

Responses

204: OK

DELETE /sys/policies/acl/{name}

Operation ID: policies-delete-acl-policy

Delete the ACL policy with the given name.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the policy. Example: "ops"

Responses

204: OK

GET /sys/policies/egp

Operation ID: enterprise-stub-list-policies-egp

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /sys/policies/egp/{name}

Operation ID: enterprise-stub-read-policies-egp-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes

Responses

200: OK

POST /sys/policies/egp/{name}

Operation ID: enterprise-stub-write-policies-egp-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes

Responses

200: OK

DELETE /sys/policies/egp/{name}

Operation ID: enterprise-stub-delete-policies-egp-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes

Responses

204: empty body

GET /sys/policies/password

Operation ID: policies-list-password-policies

List the existing password policies.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no

GET /sys/policies/password/{name}

Operation ID: policies-read-password-policy

Retrieve an existing password policy.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the password policy.

Responses

204: OK

Parameter	Type	Required	Description
policy	string	no

POST /sys/policies/password/{name}

Operation ID: policies-write-password-policy

Add a new or update an existing password policy.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the password policy.

Request body parameters

Parameter	Type	Required	Description
policy	string	no	The password policy

Responses

204: OK

DELETE /sys/policies/password/{name}

Operation ID: policies-delete-password-policy

Delete a password policy.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the password policy.

Responses

204: OK

GET /sys/policies/password/{name}/generate

Operation ID: policies-generate-password-from-password-policy

Generate a password from an existing password policy.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the password policy.

Responses

200: OK

Parameter	Type	Required	Description
password	string	no

GET /sys/policies/rgp

Operation ID: enterprise-stub-list-policies-rgp

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /sys/policies/rgp/{name}

Operation ID: enterprise-stub-read-policies-rgp-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes

Responses

200: OK

POST /sys/policies/rgp/{name}

Operation ID: enterprise-stub-write-policies-rgp-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes

Responses

200: OK

DELETE /sys/policies/rgp/{name}

Operation ID: enterprise-stub-delete-policies-rgp-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes

Responses

204: empty body

GET /sys/policy

Operation ID: policies-list

List the configured access control policies.

Parameters

Parameter	Type	Location	Required	Description
list	string	query	no	Return a list if true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no
policies	array	no

GET /sys/policy/{name}

Operation ID: policies-read-acl-policy2

Retrieve the policy body for the named policy.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the policy. Example: "ops"

Responses

200: OK

Parameter	Type	Required	Description
name	string	no
policy	string	no
rules	string	no

POST /sys/policy/{name}

Operation ID: policies-write-acl-policy2

Add a new or update an existing policy.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the policy. Example: "ops"

Request body parameters

Parameter	Type	Required	Description
policy	string	no	The rules of the policy.
rules	string	no	⚠️ Deprecated. The rules of the policy.

Responses

204: OK

DELETE /sys/policy/{name}

Operation ID: policies-delete-acl-policy2

Delete the policy with the given name.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	The name of the policy. Example: "ops"

Responses

204: OK

GET /sys/pprof

Operation ID: pprof-index

Returns an HTML page listing the available profiles.

Responses

200: OK

GET /sys/pprof/allocs

Operation ID: pprof-memory-allocations

Returns a sampling of all past memory allocations.

Responses

200: OK

GET /sys/pprof/block

Operation ID: pprof-blocking

Returns stack traces that led to blocking on synchronization primitives

Responses

200: OK

GET /sys/pprof/cmdline

Operation ID: pprof-command-line

Returns the running program's command line.

Responses

200: OK

GET /sys/pprof/goroutine

Operation ID: pprof-goroutines

Returns stack traces of all current goroutines.

Responses

200: OK

GET /sys/pprof/heap

Operation ID: pprof-memory-allocations-live

Returns a sampling of memory allocations of live object.

Responses

200: OK

GET /sys/pprof/mutex

Operation ID: pprof-mutexes

Returns stack traces of holders of contended mutexes

Responses

200: OK

GET /sys/pprof/profile

Operation ID: pprof-cpu-profile

Returns a pprof-formatted cpu profile payload.

Responses

200: OK

GET /sys/pprof/symbol

Operation ID: pprof-symbols

Returns the program counters listed in the request.

Responses

200: OK

GET /sys/pprof/threadcreate

Operation ID: pprof-thread-creations

Returns stack traces that led to the creation of new OS threads

Responses

200: OK

GET /sys/pprof/trace

Operation ID: pprof-execution-trace

Returns the execution trace in binary form.

Responses

200: OK

GET /sys/quotas/config

Operation ID: rate-limit-quotas-read-configuration

Create, update and read the quota configuration.

Responses

200: OK

Parameter	Type	Required	Description
enable_rate_limit_audit_logging	boolean	no
enable_rate_limit_response_headers	boolean	no
rate_limit_exempt_paths	array	no

POST /sys/quotas/config

Operation ID: rate-limit-quotas-configure

Create, update and read the quota configuration.

Request body parameters

Parameter	Type	Required	Description
enable_rate_limit_audit_logging	boolean	no	If set, starts audit logging of requests that get rejected due to rate limit quota rule violations.
enable_rate_limit_response_headers	boolean	no	If set, additional rate limit quota HTTP headers will be added to responses.
rate_limit_exempt_paths	array	no	Specifies the list of exempt paths from all rate limit quotas. If empty no paths will be exempt.

Responses

204: OK

GET /sys/quotas/lease-count

Operation ID: enterprise-stub-list-quotas-lease-count

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /sys/quotas/lease-count/{name}

Operation ID: enterprise-stub-read-quotas-lease-count-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes

Responses

200: OK

POST /sys/quotas/lease-count/{name}

Operation ID: enterprise-stub-write-quotas-lease-count-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes

Responses

200: OK

DELETE /sys/quotas/lease-count/{name}

Operation ID: enterprise-stub-delete-quotas-lease-count-name

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes

Responses

204: empty body

GET /sys/quotas/rate-limit

Operation ID: rate-limit-quotas-list

Lists the names of all the rate limit quotas.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
keys	array	no

GET /sys/quotas/rate-limit/{name}

Operation ID: rate-limit-quotas-read

Get, create or update rate limit resource quota for an optional namespace or mount.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the quota rule.

Responses

200: OK

Parameter	Type	Required	Description
block_interval	integer	no
interval	integer	no
name	string	no
path	string	no
rate	number	no
role	string	no
type	string	no

POST /sys/quotas/rate-limit/{name}

Operation ID: rate-limit-quotas-write

Get, create or update rate limit resource quota for an optional namespace or mount.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the quota rule.

Request body parameters

Parameter	Type	Required	Description
block_interval	integer	no	If set, when a client reaches a rate limit threshold, the client will be prohibited from any further requests until after the 'block_interval' has elapsed.
interval	integer	no	The duration to enforce rate limiting for (default '1s').
path	string	no	Path of the mount or namespace to apply the quota. A blank path configures a global quota. For example namespace1/ adds a quota to a full namespace, namespace1/auth/userpass adds a quota to userpass in namespace1.
rate	number	no	The maximum number of requests in a given interval to be allowed by the quota rule. The 'rate' must be positive.
role	string	no	Login role to apply this quota to. Note that when set, path must be configured to a valid auth method with a concept of roles.
type	string	no	Type of the quota rule.

Responses

204: No Content

DELETE /sys/quotas/rate-limit/{name}

Operation ID: rate-limit-quotas-delete

Get, create or update rate limit resource quota for an optional namespace or mount.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the quota rule.

Responses

204: OK

GET /sys/rekey/backup

Operation ID: rekey-read-backup-key

Return the backup copy of PGP-encrypted unseal keys.

Responses

200: OK

Parameter	Type	Required	Description
keys	object	no
keys_base64	object	no
nonce	string	no

DELETE /sys/rekey/backup

Operation ID: rekey-delete-backup-key

Delete the backup copy of PGP-encrypted unseal keys.

Responses

204: OK

GET /sys/rekey/init

Operation ID: rekey-attempt-read-progress

Reads the configuration and progress of the current rekey attempt.

Available without authentication: yes

Responses

200: OK

Parameter	Type	Required	Description
backup	boolean	no
n	integer	no
nounce	string	no
pgp_fingerprints	array	no
progress	integer	no
required	integer	no
started	string	no
t	integer	no
verification_nonce	string	no
verification_required	boolean	no

POST /sys/rekey/init

Operation ID: rekey-attempt-initialize

Initializes a new rekey attempt.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
backup	boolean	no	Specifies if using PGP-encrypted keys, whether Stronghold should also store a plaintext backup of the PGP-encrypted keys.
pgp_keys	array	no	Specifies an array of PGP public keys used to encrypt the output unseal keys. Ordering is preserved. The keys must be base64-encoded from their original binary representation. The size of this array must be the same as secret_shares.
require_verification	boolean	no	Turns on verification functionality
secret_shares	integer	no	Specifies the number of shares to split the unseal key into.
secret_threshold	integer	no	Specifies the number of shares required to reconstruct the unseal key. This must be less than or equal secret_shares. If using Stronghold HSM with auto-unsealing, this value must be the same as secret_shares.

Responses

200: OK

Parameter	Type	Required	Description
backup	boolean	no
n	integer	no
nounce	string	no
pgp_fingerprints	array	no
progress	integer	no
required	integer	no
started	string	no
t	integer	no
verification_nonce	string	no
verification_required	boolean	no

DELETE /sys/rekey/init

Operation ID: rekey-attempt-cancel

Cancels any in-progress rekey.

Available without authentication: yes

Responses

200: OK

GET /sys/rekey/recovery-key-backup

Operation ID: rekey-read-backup-recovery-key

Allows fetching or deleting the backup of the rotated unseal keys.

Responses

200: OK

Parameter	Type	Required	Description
keys	object	no
keys_base64	object	no
nonce	string	no

DELETE /sys/rekey/recovery-key-backup

Operation ID: rekey-delete-backup-recovery-key

Allows fetching or deleting the backup of the rotated unseal keys.

Responses

204: OK

POST /sys/rekey/update

Operation ID: rekey-attempt-update

Enter a single unseal key share to progress the rekey of the Stronghold.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
key	string	no	Specifies a single unseal key share.
nonce	string	no	Specifies the nonce of the rekey attempt.

Responses

200: OK

Parameter	Type	Required	Description
backup	boolean	no
complete	boolean	no
keys	array	no
keys_base64	array	no
n	integer	no
nounce	string	no
pgp_fingerprints	array	no
progress	integer	no
required	integer	no
started	string	no
t	integer	no
verification_nonce	string	no
verification_required	boolean	no

GET /sys/rekey/verify

Operation ID: rekey-verification-read-progress

Read the configuration and progress of the current rekey verification attempt.

Available without authentication: yes

Responses

200: OK

Parameter	Type	Required	Description
n	integer	no
nounce	string	no
progress	integer	no
started	string	no
t	integer	no

POST /sys/rekey/verify

Operation ID: rekey-verification-update

Enter a single new key share to progress the rekey verification operation.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
key	string	no	Specifies a single unseal share key from the new set of shares.
nonce	string	no	Specifies the nonce of the rekey verification operation.

Responses

200: OK

Parameter	Type	Required	Description
complete	boolean	no
nounce	string	no

DELETE /sys/rekey/verify

Operation ID: rekey-verification-cancel

Cancel any in-progress rekey verification operation.

Available without authentication: yes

Responses

200: OK

Parameter	Type	Required	Description
n	integer	no
nounce	string	no
progress	integer	no
started	string	no
t	integer	no

POST /sys/remount

Operation ID: remount

Initiate a mount migration

Required sudo: yes

Request body parameters

Parameter	Type	Required	Description
from	string	no	The previous mount point.
to	string	no	The new mount point.

Responses

200: OK

Parameter	Type	Required	Description
migration_id	string	no

GET /sys/remount/status/{migration_id}

Operation ID: remount-status

Check status of a mount migration

Parameters

Parameter	Type	Location	Required	Description
migration_id	string	path	yes	The ID of the migration operation

Responses

200: OK

Parameter	Type	Required	Description
migration_id	string	no
migration_info	object	no

POST /sys/renew

Operation ID: leases-renew-lease2

Renews a lease, requesting to extend the lease.

Request body parameters

Parameter	Type	Required	Description
increment	integer	no	The desired increment in seconds to the lease
lease_id	string	no	The lease identifier to renew. This is included with a lease.
url_lease_id	string	no	The lease identifier to renew. This is included with a lease.

Responses

204: OK

POST /sys/renew/{url_lease_id}

Operation ID: leases-renew-lease-with-id2

Renews a lease, requesting to extend the lease.

Parameters

Parameter	Type	Location	Required	Description
url_lease_id	string	path	yes	The lease identifier to renew. This is included with a lease.

Request body parameters

Parameter	Type	Required	Description
increment	integer	no	The desired increment in seconds to the lease
lease_id	string	no	The lease identifier to renew. This is included with a lease.

Responses

204: OK

GET /sys/replication/status

Operation ID: system-read-replication-status

Available without authentication: yes

Responses

200: OK

POST /sys/revoke

Operation ID: leases-revoke-lease2

Revokes a lease immediately.

Request body parameters

Parameter	Type	Required	Description
lease_id	string	no	The lease identifier to renew. This is included with a lease.
sync	boolean (default: True)	no	Whether or not to perform the revocation synchronously
url_lease_id	string	no	The lease identifier to renew. This is included with a lease.

Responses

204: OK

POST /sys/revoke-force/{prefix}

Operation ID: leases-force-revoke-lease-with-prefix2

Revokes all secrets or tokens generated under a given prefix immediately

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
prefix	string	path	yes	The path to revoke keys under. Example: "prod/aws/ops"

Responses

204: OK

POST /sys/revoke-prefix/{prefix}

Operation ID: leases-revoke-lease-with-prefix2

Revokes all secrets (via a lease ID prefix) or tokens (via the tokens' path property) generated under a given prefix immediately.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
prefix	string	path	yes	The path to revoke keys under. Example: "prod/aws/ops"

Request body parameters

Parameter	Type	Required	Description
sync	boolean (default: True)	no	Whether or not to perform the revocation synchronously

Responses

204: OK

POST /sys/revoke/{url_lease_id}

Operation ID: leases-revoke-lease-with-id2

Revokes a lease immediately.

Parameters

Parameter	Type	Location	Required	Description
url_lease_id	string	path	yes	The lease identifier to renew. This is included with a lease.

Request body parameters

Parameter	Type	Required	Description
lease_id	string	no	The lease identifier to renew. This is included with a lease.
sync	boolean (default: True)	no	Whether or not to perform the revocation synchronously

Responses

204: OK

POST /sys/rotate

Operation ID: encryption-key-rotate

Rotates the backend encryption key used to persist data.

Required sudo: yes

Responses

204: OK

GET /sys/rotate/config

Operation ID: encryption-key-read-rotation-configuration

Configures settings related to the backend encryption key management.

Responses

200: OK

Parameter	Type	Required	Description
enabled	boolean	no
interval	integer	no
max_operations	integer	no

POST /sys/rotate/config

Operation ID: encryption-key-configure-rotation

Configures settings related to the backend encryption key management.

Request body parameters

Parameter	Type	Required	Description
enabled	boolean	no	Whether automatic rotation is enabled.
interval	integer	no	How long after installation of an active key term that the key will be automatically rotated.
max_operations	integer	no	The number of encryption operations performed before the barrier key is automatically rotated.

Responses

204: OK

POST /sys/seal

Operation ID: seal

Seal the Stronghold.

Responses

204: OK

GET /sys/seal-status

Operation ID: seal-status

Check the seal status of a Stronghold.

Available without authentication: yes

Responses

200:

Parameter	Type	Required	Description
build_date	string	no
cluster_id	string	no
cluster_name	string	no
hcp_link_resource_ID	string	no
hcp_link_status	string	no
initialized	boolean	no
migration	boolean	no
n	integer	no
nonce	string	no
progress	integer	no
recovery_seal	boolean	no
sealed	boolean	no
storage_type	string	no
t	integer	no
type	string	no
version	string	no

GET /sys/sealwrap/rewrap

Operation ID: system-read-sealwrap-rewrap

Responses

200: OK

POST /sys/sealwrap/rewrap

Operation ID: system-write-sealwrap-rewrap

Responses

200: OK

POST /sys/step-down

Operation ID: step-down-leader

Cause the node to give up active status.

Responses

204: empty body

GET /sys/storage/raft/autopilot/configuration

Operation ID: system-read-storage-raft-autopilot-configuration

Returns autopilot configuration.

Responses

200: OK

POST /sys/storage/raft/autopilot/configuration

Operation ID: system-write-storage-raft-autopilot-configuration

Returns autopilot configuration.

Request body parameters

Parameter	Type	Required	Description
cleanup_dead_servers	boolean	no	Controls whether to remove dead servers from the Raft peer list periodically or when a new server joins.
dead_server_last_contact_threshold	integer	no	Limit on the amount of time a server can go without leader contact before being considered failed. This takes effect only when cleanup_dead_servers is set.
disable_upgrade_migration	boolean	no	Whether or not to perform automated version upgrades.
dr_operation_token	string	no	DR operation token used to authorize this request (if a DR secondary node).
last_contact_threshold	integer	no	Limit on the amount of time a server can go without leader contact before being considered unhealthy.
max_trailing_logs	integer	no	Amount of entries in the Raft Log that a server can be behind before being considered unhealthy.
min_quorum	integer	no	Minimum number of servers allowed in a cluster before autopilot can prune dead servers. This should at least be 3.
server_stabilization_time	integer	no	Minimum amount of time a server must be in a stable, healthy state before it can be added to the cluster.

Responses

200: OK

GET /sys/storage/raft/autopilot/state

Operation ID: system-read-storage-raft-autopilot-state

Returns the state of the raft cluster under integrated storage as seen by autopilot.

Responses

200: OK

POST /sys/storage/raft/bootstrap/answer

Operation ID: system-write-storage-raft-bootstrap-answer

Accepts an answer from the peer to be joined to the fact cluster.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
answer	string	no
cluster_addr	string	no
non_voter	boolean	no
server_id	string	no

Responses

200: OK

POST /sys/storage/raft/bootstrap/challenge

Operation ID: system-write-storage-raft-bootstrap-challenge

Creates a challenge for the new peer to be joined to the raft cluster.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
server_id	string	no

Responses

200: OK

GET /sys/storage/raft/configuration

Operation ID: system-read-storage-raft-configuration

Returns the configuration of the raft cluster.

Responses

200: OK

POST /sys/storage/raft/configuration

Operation ID: system-write-storage-raft-configuration

Returns the configuration of the raft cluster in a DR secondary cluster.

Request body parameters

Parameter	Type	Required	Description
dr_operation_token	string	no	DR operation token used to authorize this request (if a DR secondary node).

Responses

200: OK

POST /sys/storage/raft/remove-peer

Operation ID: system-write-storage-raft-remove-peer

Remove a peer from the raft cluster.

Request body parameters

Parameter	Type	Required	Description
dr_operation_token	string	no	DR operation token used to authorize this request (if a DR secondary node).
server_id	string	no

Responses

200: OK

GET /sys/storage/raft/snapshot

Operation ID: system-read-storage-raft-snapshot

Returns a snapshot of the current state of vault.

Responses

200: OK

POST /sys/storage/raft/snapshot

Operation ID: system-write-storage-raft-snapshot

Installs the provided snapshot, returning the cluster to the state defined in it.

Responses

200: OK

GET /sys/storage/raft/snapshot-auto/config

Operation ID: system-list-storage-raft-snapshot-auto-config

Lists all automatic snapshot configuration names.

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

GET /sys/storage/raft/snapshot-auto/config/{name}

Operation ID: system-read-storage-raft-snapshot-auto-config-name

Gets the configuration of the automatic snapshot.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the configuration to modify.

Responses

200: OK

POST /sys/storage/raft/snapshot-auto/config/{name}

Operation ID: system-write-storage-raft-snapshot-auto-config-name

Updates the configuration of the automatic snapshot.

Required sudo: yes

Creation supported: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the configuration to modify.

Request body parameters

Parameter	Type	Required	Description
aws_access_key_id	string	no	S3 access key ID.
aws_s3_bucket	string	yes	S3 bucket to write snapshots to.
aws_s3_ca_certificate	string (default: )	no	S3 CA certificate PEM.
aws_s3_disable_tls	boolean (default: False)	no	Disable TLS for the S3 endpoint. This should only be used for testing purposes, typically in conjunction with s3_endpoint.
aws_s3_endpoint	string	no	S3 endpoint.
aws_s3_region	string (default: )	no	S3 region bucket is in.
aws_secret_access_key	string	no	S3 secret access key.
file_prefix	string (default: stronghold-snapshot)	no	Within the directory or bucket prefix given by path_prefix, the file or object name of snapshot files will start with this string.
interval	integer	yes	Time between snapshots. This can be either an integer number of seconds, or a Go duration format string (e.g. 24h).
local_max_space	integer (default: 0)	yes	For storage_type=local, the maximum space, in bytes, to use for all snapshots with the given file_prefix in the path_prefix directory. Snapshot attempts will fail if there is not enough space left in this allowance. Value 0 disables limit.
path_prefix	string	yes	For storage_type=local, the directory to write the snapshots in. For cloud storage types, the bucket prefix to use, also leading / is ignored. The trailing / is optional.
retain	integer (default: 3)	no	How many snapshots are to be kept; when writing a snapshot, if there are more snapshots already stored than this number, the oldest ones will be deleted.
storage_type	string (local, aws-s3)	yes	One of "local" or "s3". The remaining parameters described below are all specific to the selected storage_type and prefixed accordingly.

Responses

200: OK

DELETE /sys/storage/raft/snapshot-auto/config/{name}

Operation ID: system-delete-storage-raft-snapshot-auto-config-name

Deletes the configuration of the automatic snapshot.

Required sudo: yes

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the configuration to modify.

Responses

204: empty body

GET /sys/storage/raft/snapshot-auto/status/{name}

Operation ID: system-read-storage-raft-snapshot-auto-status-name

Shows the status of the automatic snapshot.

Parameters

Parameter	Type	Location	Required	Description
name	string	path	yes	Name of the status to get.

Responses

200: OK

POST /sys/storage/raft/snapshot-force

Operation ID: system-write-storage-raft-snapshot-force

Installs the provided snapshot, returning the cluster to the state defined in it. This bypasses checks ensuring the current Autounseal or Shamir keys are consistent with the snapshot data.

Responses

200: OK

POST /sys/tools/hash

Operation ID: generate-hash

Generate a hash sum for input data

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Algorithm to use (POST body parameter). Valid values are: * sha2-224 * sha2-256 * sha2-384 * sha2-512 Defaults to "sha2-256".
format	string (default: hex)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "hex".
input	string	no	The base64-encoded input data
urlalgorithm	string	no	Algorithm to use (POST URL parameter)

Responses

200: OK

Parameter	Type	Required	Description
sum	string	no

POST /sys/tools/hash/{urlalgorithm}

Operation ID: generate-hash-with-algorithm

Generate a hash sum for input data

Parameters

Parameter	Type	Location	Required	Description
urlalgorithm	string	path	yes	Algorithm to use (POST URL parameter)

Request body parameters

Parameter	Type	Required	Description
algorithm	string (default: sha2-256)	no	Algorithm to use (POST body parameter). Valid values are: * sha2-224 * sha2-256 * sha2-384 * sha2-512 Defaults to "sha2-256".
format	string (default: hex)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "hex".
input	string	no	The base64-encoded input data

Responses

200: OK

Parameter	Type	Required	Description
sum	string	no

POST /sys/tools/random

Operation ID: generate-random

Generate random bytes

Request body parameters

Parameter	Type	Required	Description
bytes	integer (default: 32)	no	The number of bytes to generate (POST body parameter). Defaults to 32 (256 bits).
format	string (default: base64)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "base64".
source	string (default: platform)	no	Which system to source random data from, ether "platform", "seal", or "all".
urlbytes	string	no	The number of bytes to generate (POST URL parameter)

Responses

200: OK

Parameter	Type	Required	Description
random_bytes	string	no

POST /sys/tools/random/{source}

Operation ID: generate-random-with-source

Generate random bytes

Parameters

Parameter	Type	Location	Required	Description
source	string	path	yes	Which system to source random data from, ether "platform", "seal", or "all".

Request body parameters

Parameter	Type	Required	Description
bytes	integer (default: 32)	no	The number of bytes to generate (POST body parameter). Defaults to 32 (256 bits).
format	string (default: base64)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "base64".
urlbytes	string	no	The number of bytes to generate (POST URL parameter)

Responses

200: OK

Parameter	Type	Required	Description
random_bytes	string	no

POST /sys/tools/random/{source}/{urlbytes}

Operation ID: generate-random-with-source-and-bytes

Generate random bytes

Parameters

Parameter	Type	Location	Required	Description
source	string	path	yes	Which system to source random data from, ether "platform", "seal", or "all".
urlbytes	string	path	yes	The number of bytes to generate (POST URL parameter)

Request body parameters

Parameter	Type	Required	Description
bytes	integer (default: 32)	no	The number of bytes to generate (POST body parameter). Defaults to 32 (256 bits).
format	string (default: base64)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "base64".

Responses

200: OK

Parameter	Type	Required	Description
random_bytes	string	no

POST /sys/tools/random/{urlbytes}

Operation ID: generate-random-with-bytes

Generate random bytes

Parameters

Parameter	Type	Location	Required	Description
urlbytes	string	path	yes	The number of bytes to generate (POST URL parameter)

Request body parameters

Parameter	Type	Required	Description
bytes	integer (default: 32)	no	The number of bytes to generate (POST body parameter). Defaults to 32 (256 bits).
format	string (default: base64)	no	Encoding format to use. Can be "hex" or "base64". Defaults to "base64".
source	string (default: platform)	no	Which system to source random data from, ether "platform", "seal", or "all".

Responses

200: OK

Parameter	Type	Required	Description
random_bytes	string	no

POST /sys/unseal

Operation ID: unseal

Unseal the Stronghold.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
key	string	no	Specifies a single unseal key share. This is required unless reset is true.
reset	boolean	no	Specifies if previously-provided unseal keys are discarded and the unseal process is reset.

Responses

200:

Parameter	Type	Required	Description
build_date	string	no
cluster_id	string	no
cluster_name	string	no
hcp_link_resource_ID	string	no
hcp_link_status	string	no
initialized	boolean	no
migration	boolean	no
n	integer	no
nonce	string	no
progress	integer	no
recovery_seal	boolean	no
sealed	boolean	no
storage_type	string	no
t	integer	no
type	string	no
version	string	no

GET /sys/version-history

Operation ID: version-history

Returns map of historical version change entries

Parameters

Parameter	Type	Location	Required	Description
list	string (true)	query	yes	Must be set to true

Responses

200: OK

Parameter	Type	Required	Description
key_info	object	no
keys	array	no

GET /sys/wrapping/lookup

Operation ID: read-wrapping-properties2

Look up wrapping properties for the requester's token.

Available without authentication: yes

Responses

200: OK

Parameter	Type	Required	Description
creation_path	string	no
creation_time	string	no
creation_ttl	integer	no

POST /sys/wrapping/lookup

Operation ID: read-wrapping-properties

Look up wrapping properties for the given token.

Available without authentication: yes

Request body parameters

Parameter	Type	Required	Description
token	string	no

Responses

200: OK

Parameter	Type	Required	Description
creation_path	string	no
creation_time	string	no
creation_ttl	integer	no

POST /sys/wrapping/rewrap

Operation ID: rewrap

Rotates a response-wrapped token.

Request body parameters

Parameter	Type	Required	Description
token	string	no

Responses

200: OK

POST /sys/wrapping/unwrap

Operation ID: unwrap

Unwraps a response-wrapped token.

Request body parameters

Parameter	Type	Required	Description
token	string	no

Responses

200: OK

204: No content

POST /sys/wrapping/wrap

Operation ID: wrap

Response-wraps an arbitrary JSON object.

Responses

200: OK

---