Для улучшения работы сайта мы используем файлы cookies. Оставаясь на сайте, вы соглашаетесь с политикой обработки персональных данных.

HTTP API

У StarVault есть HTTP API, который можно использовать для управления всеми аспектами StarVault.

HTTP API StarVault предоставляет вам полный доступ к StarVault, используя HTTP-методы как REST. С помощью API можно управлять каждым элементом StarVault. Интерфейс командной строки StarVault использует HTTP API для доступа к StarVault аналогично всем другим пользователям.

Все маршруты API имеют префикс /v1/.

Данная документация предназначена только для API версии v1, которая на данный момент является единственной версией.

Обратная совместимость: В текущей версии StarVault пока не дает обратную совместимость даже с префиксом v1. На данный момент базовый API (то есть маршруты sys/) меняется очень редко, но в различные механизмы управления секретами/методы аутентификации и т.д. иногда вносятся незначительные изменения для адаптации новых функций по мере их разработки.

1. Перемещение

Ожидается, что доступ к API будет осуществляться по TLS-соединению в любое время, при наличии действительного сертификата, который проверяется клиентом. Однако можно отключить проверку TLS для слушателей, поэтому клиентам API следует ожидать, что им придется выполнять и то, и другое в зависимости от пользовательских настроек.

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

После того, как хранилище распечатано, почти для каждой другой операции будет требоваться токен клиента. Пользователю может быть отправлен токен клиента либо как HTTP-заголовок X-Vault-Token, либо как HTTP-заголовок авторизации, используя Bearer <token>.

В противном случае токен клиента может быть получен с помощью методов аутентификации.

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

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

3. Ограничения параметров

Для некоторых API-интерфейсов StarVault требуется указать параметры path. Параметр path не может заканчиваться точками. В противном случае StarVault вернет сообщение об ошибке, например 404 unsupported path error.

4. Операции API

Обычно данные запроса, основная часть и данные ответа в StarVault и из StarVault передаются в формате JSON. StarVault устанавливает заголовок Content-Type соответствующим образом в своем ответе и не требует его от клиентского запроса.

В приведенной ниже демонстрации используется механизм секретов KVv1, который представляет собой простое хранилище значений ключей. Пожалуйста, ознакомьтесь с API документацией по механизму секретов KV для получения подробной информации о KVv1 по сравнению с KVv2 и о том, чем они отличаются по своим URI-путям, а также о функциях, доступных в версии 2 механизма секретов KV.

Для KVv1 чтение информации о секрете с помощью HTTP API выполняется путем выдачи команды GET:

/v1/secret/foo

Это сопоставляется с secret/foo, где foo - это ключ в точке монтирования secret/, который монтируется по умолчанию при новой установке хранилища и имеет тип kv.

Далее представлен пример чтения секрета с помощью cURL:

$ curl \
    -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
    -X GET \
    http://127.0.0.1:8200/v1/secret/foo

Некоторые конечные точки используют вызовы с параметрами строки запроса GET, но только в том случае, если эти параметры не являются конфиденциальными, тем более что некоторые средства балансировки нагрузки могут регистрировать их. Большинство конечных точек, которые принимают параметры строки запроса POST, ожидают, что эти параметры будут указаны в теле запроса.

Вы также можете вывести список секретов. Чтобы сделать это, либо выполните GET с параметром строки запроса list=true, либо используйте HTTP-команду LIST. Для механизма секретов kv вывод списка разрешен только для каталогов, что возвращает ключи по запрошенному пути:

curl \
    -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
    -X LIST \
    http://127.0.0.1:8200/v1/secret/

В документации по API в качестве HTTP метода используется LIST, но вы все равно можете использовать GET со строкой запроса ?list=true.

Если результатом list является пустой набор, StarVault выдает код состояния 404 и следующий JSON:

{"errors":[]}

Чтобы создать API с конкретными данными в теле запроса, отправьте POST:

/v1/secret/foo

с телом JSON, как на примере ниже:

{
  "value": "bar"
}

Далее пример написания секрета с помощью cURL:

curl \
    -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"data":{"value":"bar"}}' \
    http://127.0.0.1:8200/v1/secret/baz

В настоящее время StarVault рассматривает PUT и POST как синонимы. Вместо того, чтобы доверять заявленным намерениям клиента, модули StarVault могут выполнять проверку существования, чтобы определить, является ли операция на самом деле операцией создания или обновления, на основе данных, уже хранящихся в StarVault. Это делает управление разрешениями с помощью списков контроля доступа более гибким.

В примере KVv2 для пути к механизму секретов secret требуется, чтобы URI добавлялся с data/ перед именем секрета (baz), например:

curl \
    -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"data":{"value":"bar"}}' \
    http://127.0.0.1:8200/v1/secret/data/baz

5. Заголовок запроса X-Vault-Request

Запросы, отправляемые на прокси-сервер хранилища, настроенный на использование параметра require_request_header, должны содержать запись заголовка X-Vault-Request, например:

curl \
    -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
    -H "X-Vault-Request: true" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"value":"bar"}' \
    http://127.0.0.1:8200/v1/secret/baz

Интерфейс командной строки StarVault всегда добавляет этот заголовок к каждому запросу, независимо от того, отправляется ли запрос агенту StarVault или непосредственно на сервер StarVault. Кроме того, пакет SDK StarVault всегда добавляет этот заголовок к каждому запросу.

6. Помощь

Чтобы получить справку по любому API в StarVault, включая смонтированные механизмы секретов, методы аутентификации и т.д., добавьте ?help=1 к любому URL-адресу. Если у вас есть действительные права доступа к path, текст справки будет возвращен в виде блока в формате markdown в атрибуте help ответа.

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

Пример запроса:
curl \
    -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \
    http://127.0.0.1:8200/v1/secret?help=1
Пример вывода:
{
  "help": "## DESCRIPTION\n\nThe kv backend reads and writes arbitrary secrets to the backend.\nThe secrets are encrypted/decrypted by Vault: they are never stored\nunencrypted in the backend and the backend never has an opportunity to\nsee the unencrypted value.\n\nTTLs can be set on a per-secret basis. These TTLs will be sent down\nwhen that secret is read, and it is assumed that some outside process will\nrevoke and/or replace the secret at that path.\n\n## PATHS\n\nThe following paths are supported by this backend. To view help for\nany of the paths below, use the help command with any route matching\nthe path pattern. Note that depending on the policy of your auth token,\nyou may or may not be able to access certain paths.\n\n    ^(?P<path>.*)$\n        Pass-through secret storage to the storage backend, allowing you to\n        read/write arbitrary data into secret storage.",
  "openapi": {
    "openapi": "3.0.2",
    "info": {
      "title": "StarVault API",
      "description": "HTTP API that gives you full access to StarVault. All API routes are prefixed with `/v1/`.",
      "version": "1.1.0",
      "license": {
        "name": "Mozilla Public License 2.0",
        "url": "https://www.mozilla.org/en-US/MPL/2.0"
      }
    },
    "paths": {
      "/.*": {},
      "/config": {
        "description": "Configures settings for the KV store",
        "get": {
          "summary": "Read the backend level settings.",
          "tags": [
            "secrets"
          ],
          "responses": {
            "200": {
              "description": "OK"
            }
          }
        },
     ...[output truncated]...
     }
  }
}

7. Структура вывода ошибок

Для возврата ошибок всегда используется общая структура JSON:

{
  "errors": [
    "message",
    "another message"
  ]
}

Данная структура будет возвращена для любого HTTP-статуса, превышающего или равного 400.

8. Коды состояния HTTP

Следующие коды состояния HTTP используются во всем API.

  • 200 - данные получены успешно.

  • 204 - успешно, данные не возвращены.

  • 400 - неверный запрос, отсутствуют или некорректные данные.

  • 403 - запрещено, ваши данные для аутентификации либо неверны, у вас нет доступа к этой функции, либо - если CORS включен - вы отправили запрос из разных источников, из источника, которому запрещено отправлять такие запросы.

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

  • 405 - неподдерживаемая операция. Вы пытались использовать метод, не соответствующий пути запроса, например, POST на конечной точке, которая принимает только GET.

  • 429 - код возврата по умолчанию для состояния работоспособности резервных узлов. В будущем это, вероятно, изменится.

  • 472 - код возврата по умолчанию для вторичной и активной репликации в режиме аварийного восстановления.

  • 473 - код возврата по умолчанию для определения состояния работоспособности узлов.

  • 500 - внутренняя ошибка сервера. Произошла внутренняя ошибка, повторите попытку позже. Если ошибка повторяется, сообщите об ошибке.

  • 501 - хранилище не инициализировано.

  • 502 - для запроса к хранилищу необходимо, чтобы хранилище отправило запрос третьей стороне; третья сторона выдала сообщение о какой-либо ошибке.

  • 503 - хранилище закрыто на техническое обслуживание или в настоящее время запечатано. Попробуйте еще раз позже.

9. Ограничения

Максимальный размер запроса составляет 32 МБ, чтобы предотвратить атаку, например "отказ в обслуживании" с произвольно большими запросами; это значение можно настроить для каждого блока прослушивателя в файле конфигурации сервера StarVault.