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

Методы аутентификации. Токены (API)

В данном разделе представлена документация API для метода аутентификации StarVault по токенам. Для общего представления об использовании и работе метода токена читайте документацию по методу токена StarVault.

1. Список аксессоров

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

Метод Путь

LIST

/auth/token/accessors
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/token/accessors
Пример ответа:
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": [
      "476ea048-ded5-4d07-eeea-938c6b4e43ec",
      "bb00c093-b7d3-b0e9-69cc-c4d85081165b"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

2. Создание токена

Создает новый токен. Определенные параметры доступны только при вызове рут-токеном. Если используется конечная точка /auth/token/create-orphan, рут-токен не требуется для создания «сиротского» токена (иначе установленного с опцией no_parent). Если используется с именем роли в пути, токен будет создан против указанного имени роли; это может переопределить параметры, установленные в ходе этого вызова.

Метод Путь

POST

/auth/token/create

POST

/auth/token/create-orphan

POST

/auth/token/create/:role_name

2.1. Параметры

  • id (string: "") - идентификатор клиентского токена. Может быть указан только рут-токеном. Указанный идентификатор не может содержать символ .. В противном случае идентификатор токена будет случайно сгенерированным значением.

Идентификатор не должен начинаться с префикса s..

  • role_name (string: "") - имя роли токена.

  • policies (array: "") - список политик для токена. Это должно быть подмножеством политик, принадлежащих токену, производящему запрос, если только вызывающий токен не является рутом или не содержит возможностей sudo для auth/token/create. Если не указано, по умолчанию используются все политики вызывающего токена.

  • meta (map: {}) - карта метаданных, сопоставляющая строку со строковым значением. Это передается в устройства аудита.

  • no_parent (bool: false) - этот аргумент будет действовать только в случае использования рут- или sudo-вызовом. Когда установлен в true, созданный токен не будет иметь родителя.

  • no_default_policy (bool: false) - если true, политика default не будет содержаться в наборе политик этого токена.

  • renewable (bool: true) - установите в false, чтобы отключить возможность продления токена за пределами его начального TTL. Установка значения в true позволит токену быть обновляемым до максимального TTL системы/монтажной точки.

  • lease (string: "") - УСТАРЕЛО; используйте ttl вместо.

  • ttl (string: "") - период TTL токена, предоставленный как "1h", где час является наибольшим суффиксом. Если не указано, токен действителен на стандартный TTL аренды, или бессрочно, если используется корневая политика.

  • type (string: "") - Тип токена. Может быть "batch" или "service". По умолчанию соответствует типу, указанному в настройках роли, названной role_name.

  • explicit_max_ttl (string: "") - если установлено, токен будет иметь установленный явный максимальный TTL. Этот максимальный TTL токена не может быть изменен позже, и в отличие от обычных токенов, обновления значения максимального TTL системы/монтажа не будут иметь эффекта при времени продления - токен никогда не сможет быть продлен или использован за пределами значения, установленного в момент выпуска.

  • display_name (string: "token") - отображаемое имя токена.

  • num_uses (integer: 0) - максимальное количество использований данного токена. Это можно использовать для создания токена одноразового использования или ограниченного использования. Значение 0 не имеет ограничений на количество использований.

  • period (string: "") - если указано, токен будет периодическим; он не будет иметь максимального TTL (если только не установлен "explicit-max-ttl"), но каждое продление будет использовать данный период. Требует рут-токена или токена с возможностью sudo.

  • entity_alias (string: "") - имя сущностного алиаса, которое нужно связать во время создания токена. Работает только в сочетании с аргументом role_name, и использованный сущностный алиас должен быть указан в allowed_entity_aliases. Если это указано, сущность не будет унаследована от родителя.

Пример тела запроса:
{
  "policies": ["web", "stage"],
  "meta": {
    "user": "armon"
  },
  "ttl": "1h",
  "renewable": true
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/create
Пример ответа:
{
  "request_id": "f00341c1-fad5-f6e6-13fd-235617f858a1",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "wrap_info": null,
  "warnings": [
    "Policy \"stage\" does not exist",
    "Policy \"web\" does not exist"
  ],
  "auth": {
    "client_token": "s.wOrq9dO9kzOcuvB06CMviJhZ",
    "accessor": "B6oixijqmeR4bsLOJH88Ska9",
    "policies": ["default", "stage", "web"],
    "token_policies": ["default", "stage", "web"],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true,
    "entity_id": "",
    "token_type": "service",
    "orphan": false,
    "num_uses": 0
  }
}

3. Поиск токена

Возвращает информацию о клиентском токене.

Метод Путь

POST

/auth/token/lookup

3.1. Параметры

  • token (string: <required>) - токен для поиска.

Пример тела запроса:
{
  "token": "ClientToken"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/lookup
Пример ответа:
{
  "data": {
    "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
    "creation_time": 1523979354,
    "creation_ttl": 2764800,
    "display_name": "ldap2-tesla",
    "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "expire_time": "2018-05-19T11:35:54.466476215-04:00",
    "explicit_max_ttl": 0,
    "id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed",
    "identity_policies": ["dev-group-policy"],
    "issue_time": "2018-04-17T11:35:54.466476078-04:00",
    "meta": {
      "username": "tesla"
    },
    "num_uses": 0,
    "orphan": true,
    "path": "auth/ldap2/login/tesla",
    "policies": ["default", "testgroup2-policy"],
    "renewable": true,
    "ttl": 2764790
  }
}

4. Поиск токена (Самостоятельный)

Возвращает информацию о текущем клиентском токене.

Метод Путь

GET

/auth/token/lookup-self
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/token/lookup-self
Пример ответа:
{
  "data": {
    "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
    "creation_time": 1523979354,
    "creation_ttl": 2764800,
    "display_name": "ldap2-tesla",
    "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "expire_time": "2018-05-19T11:35:54.466476215-04:00",
    "explicit_max_ttl": 0,
    "id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed",
    "identity_policies": ["dev-group-policy"],
    "issue_time": "2018-04-17T11:35:54.466476078-04:00",
    "meta": {
      "username": "tesla"
    },
    "num_uses": 0,
    "orphan": true,
    "path": "auth/ldap2/login/tesla",
    "policies": ["default", "testgroup2-policy"],
    "renewable": true,
    "ttl": 2764790
  }
}

5. Поиск токена (Аксессор)

Возвращает информацию о клиентском токене по аксессору.

Метод Путь

POST

/auth/token/lookup-accessor

5.1. Параметры

  • accessor (string: <required>) - аксессор токена для поиска.

Пример тела запроса:
{
  "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/lookup-accessor
Пример ответа:
{
  "data": {
    "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
    "creation_time": 1523979354,
    "creation_ttl": 2764800,
    "display_name": "ldap2-tesla",
    "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "expire_time": "2018-05-19T11:35:54.466476215-04:00",
    "explicit_max_ttl": 0,
    "id": "",
    "identity_policies": ["dev-group-policy"],
    "issue_time": "2018-04-17T11:35:54.466476078-04:00",
    "meta": {
      "username": "tesla"
    },
    "num_uses": 0,
    "orphan": true,
    "path": "auth/ldap2/login/tesla",
    "policies": ["default", "testgroup2-policy"],
    "renewable": true,
    "ttl": 2763902
  }
}

6. Продление токена

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

Метод Путь

POST

/auth/token/renew

6.1. Параметры

  • token (string: <required>) - токен для продления. Это может быть частью URL или тела.

  • increment (string: "") - опциональная запрашиваемая длительность инкремента может быть предоставлена. Этот инкремент может не быть выполнен, например, в случае периодических токенов. Если не указано, StarVault использует стандартный TTL. Это указано как числовая строка с суффиксом, например "30s" или "5m".

Пример тела запроса:
{
  "token": "ClientToken"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/renew
Пример ответа:
{
  "auth": {
    "client_token": "ABCD",
    "policies": ["web", "stage"],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true
  }
}

7. Продление токена (самостоятельно)

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

Метод Путь

POST

/auth/token/renew-self

7.1. Параметры

  • increment (string: "") - опциональная запрашиваемая длительность инкремента может быть предоставлена. Этот инкремент может не быть выполнен, например, в случае периодических токенов. Если не указано, StarVault использует стандартный TTL. Это указано как числовая строка с суффиксом, например "30s" или "5m".

Пример тела запроса:
{
  "increment": "1h"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/renew-self
Пример ответа:
{
  "auth": {
    "client_token": "ABCD",
    "policies": ["web", "stage"],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true
  }
}

8. Продление токена (Аксессор)

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

Метод Путь

POST

/auth/token/renew-accessor

8.1. Параметры

  • accessor (string: <required>) - аксессор, связанный с токеном для продления.

  • increment (string: "") - опциональная запрашиваемая аренда может быть предоставлена. Этот инкремент может быть проигнорирован.

Пример тела запроса:
{
  "accessor": "7JFKXuXKXa2D44YfDiovZ9aq"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/renew-accessor
Пример ответа:
{
  "auth": {
    "client_token": "",
    "policies": ["web", "stage"],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true
  }
}

9. Отзыв токена

Отзывает токен и все дочерние токены. Когда токен отзывается, все динамические секреты, сгенерированные с его помощью, также отзываются.

Метод Путь

POST

/auth/token/revoke

9.1. Параметры

  • token (string: <required>) - Токен для отзыва.

Пример тела запроса:
{
  "token": "ClientToken"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/revoke

10. Отзыв токена (Самостоятельно)

Отзывает токен, использованный для вызова, и все дочерние токены. Когда токен отзывается, все динамические секреты, сгенерированные с его помощью, также отзываются.

Метод Путь

POST

/auth/token/revoke-self
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/auth/token/revoke-self

11. Отзыв токена по аксессору

Отзывает токен, связанный с аксессором, и все дочерние токены. Это предназначено для случаев, когда нет доступа к идентификатору токена, но нужно отозвать токен и его детей.

Метод Путь

POST

/auth/token/revoke-accessor

11.1. Параметры

  • accessor (string: <required>) - аксессор токена.

Пример тела запроса:
{
  "accessor": "2c84f488-2133-4ced-87b0-570f93a76830"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/revoke-accessor

12. Отзыв токена и дочерник

Отзывает токен, но не его дочерние токены. Когда токен отзывается, все секреты, сгенерированные с его помощью, также отзываются. Все дочерние токены становятся сиротами,но могут быть отозваны впоследствии с помощью /auth/token/revoke/. Это конечная точка, защищенная root-доступом.

Метод Путь

POST

/auth/token/revoke-orphan

12.1. Параметры

  • token (string: <required>) - токен для отзыва. Это может быть частью URL или тела.

Пример тела запроса:
{
  "token": "ClientToken"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/revoke-orphan

13. Чтение роли токена

Извлекает конфигурацию роли с заданным именем.

Метод Путь

GET

/auth/token/roles/:role_name

13.1. Параметры

  • role_name (string: <required>) - имя роли токена.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/token/roles/nomad
Пример ответа:
{
  "request_id": "075a19cd-4e56-a3ca-d956-7609819831ec",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "allowed_entity_aliases": [
      "my-entity-alias"
    ],
    "allowed_policies": [],
    "disallowed_policies": [],
    "allowed_policies_glob": [],
    "disallowed_policies_glob": [],
    "explicit_max_ttl": 0,
    "name": "nomad",
    "orphan": false,
    "path_suffix": "",
    "period": 0,
    "renewable": true,
    "token_explicit_max_ttl": 0,
    "token_no_default_policy": false,
    "token_period": 0,
    "token_type": "default-service"
  },
  "warnings": null
}

14. Список ролей токенов

Список доступных ролей токенов.

Метод Путь

LIST

/auth/token/roles
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST
    http://127.0.0.1:8200/v1/auth/token/roles
Пример ответа:
{
  "data": {
    "keys": ["role1", "role2"]
  }
}

15. Создание/Обновление роли токена

Создает (или заменяет) указанную роль. Роли обеспечивают специфическое поведение при создании токенов, которые позволяют функции токена, которая в противном случае не доступна или требует получения sudo/рут-привилегий для доступа. Параметры роли, когда установлены, переопределяют любые предоставленные опции для конечной точки create. Имя роли также включается в путь токена, что позволяет отзывать все токены, созданные против роли с помощью конечной точки /sys/leases/revoke-prefix.

Метод Путь

POST

/auth/token/roles/:role_name

15.1. Параметры

  • role_name (string: <required>) - имя роли токена.

  • allowed_policies (list: []) - если установлено, токены могут быть созданы с любым подмножеством политик из этого списка, а не с обычной семантикой токенов как подмножество политик вызывающего токена. Параметр представляет собой строку имен политик, разделенную запятыми. Если во время создания no_default_policy не установлено и "default" не содержится в disallowed_policies или не соответствует шаблону в disallowed_policies_glob, политика "default" будет автоматически добавлена к созданному токену.

  • disallowed_policies (list: []) - если установлено, успешное создание токена с помощью этой роли будет требовать, чтобы ни одна политика в заданном списке не была запрошена. Параметр представляет собой строку имен политик, разделенную запятыми. Добавление "default" в этот список предотвратит автоматическое добавление "default" к созданным токенам.

  • allowed_policies_glob (list: []) - если установлено, токены могут быть созданы с любым подмножеством политик, соответствующим шаблону в этом списке, а не с обычной семантикой токенов как подмножеством политик вызывающего токена. Параметр представляет собой строку имен политик с шаблонами, разделенными запятыми. Если во время создания no_default_policy не установлено и "default" не содержится в disallowed_policies или не соответствует шаблону в disallowed_policies_glob, политика "default" будет добавлена к созданному токену автоматически. Если объединить с allowed_policies, политики должны соответствовать только одному из двух списков, чтобы быть разрешенными. Обратите внимание, что, в отличие от allowed_policies, политики, перечисленные в allowed_policies_glob, не будут добавлены к токену, когда в вызове /auth/token/create/:role_name не указаны политики.

  • disallowed_policies_glob (list: []) - если установлено, успешное создание токена с помощью этой роли будет требовать, чтобы ни одна запрашиваемая политика не соответствовала ни одной из политик в этом списке. Параметр представляет собой строку имен политик с шаблонами, разделенными запятыми. Добавление любого шаблона, соответствующего "default" в этот список, предотвратит автоматическое добавление "default" к созданным токенам. Если объединить с disallowed_policies, политики должны соответствовать только одному из двух списков, чтобы быть заблокированными.

  • orphan (bool: false) - если true, токены, созданные против этой политики, будут сиротскими токенами (они не будут иметь родителя). Таким образом, они не будут автоматически отозваны при отзыве любого другого токена.

  • renewable (bool: true) - установите в false, чтобы отключить возможность продления токена за пределами его первоначального TTL. Установка значения в true позволит токену быть обновляемым до максимального TTL системы/монтажной точки.

  • path_suffix (string: "") - если установлено, токены, созданные против этой роли, будут иметь указанный суффикс в своем пути, дополнительно к имени роли. Это может быть полезно в определенных сценариях, таких как сохранение одного и того же имени роли в будущем, но отзыв всех токенов, созданных против него, до некоторого момента времени. Суффикс может быть изменен, позволяя новым вызывает иметь новый суффикс как часть их пути, а старые токены с предыдущим суффиксом могут быть отозваны через /sys/leases/revoke-prefix.

  • allowed_entity_aliases (string: "", or list: []) - строка или JSON-список разрешенных сущностных алиасов. Если установлено, указывает сущностные алиасы, которые разрешены для использования во время генерации токенов. Это поле поддерживает использование шаблонов. Обратите внимание, что allowed_entity_aliases не является чувствительным к регистру.

Пример тела запроса:
{
  "allowed_policies": [
    "dev"
  ],
  "name": "nomad",
  "orphan": false,
  "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"],
  "renewable": true,
  "allowed_entity_aliases": ["web-entity-alias", "app-entity-*"]
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/roles/nomad

16. Удаление роли токена

Эта конечная точка удаляет указанную роль токена.

Метод Путь

DELETE

/auth/token/roles/:role_name

16.1. Параметры

  • role_name (string: <required>) - имя роли токена.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/auth/token/roles/admins

17. Упорядочение токенов

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

  • Это выполнит много операций чтения I/O к методу хранения, так как фактически загрузит всё хранилище токенов в память. В зависимости от того, сколько очистки требуется (как правило, очень мало),также может произойти много записей.

  • Это приведёт к увеличению использования памяти StarVault, так как кэш StarVault по умолчанию не имеет ограничения по размеру, и каждое значение, загруженное из хранилища, будет кэшироваться. Перечисление конечной точки /auth/token/accessors - хороший способ оценить потенциальное влияние: упорядочивание делает это и больше, так что если этот вызов создает проблемы для вашего кластера, будет разумно предоставить StarVault больше ресурсов перед попыткой упорядочивания.

Обратите внимание, что запрос может истечь в зависимости от максимальной продолжительности и конфигурации тайм-аутов вашего клиента. Убедитесь, что вам разрешено завершить его для правильного оценивания воздействия.

Упорядочивание загрузит каждый токен-аксессор и куббихол, а также все вторичные индексы, которые используются для группировки токенов в деревья, чтобы отзыв родительских токенов также отзывал детские токены.

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

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

Наконец, любые записи куббихолов, связанные с токенами, которые не были признаны действительными на вышеуказанных этапах, будут удалены.

Метод Путь

POST

/auth/token/tidy
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/auth/token/tidy
Пример ответа:
{
  "request_id": "84437c7f-36a1-6c1d-381d-14ec99217e94",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "wrap_info": null,
  "warnings": [
    "Tidy operation successfully started. Any information from the operation will be printed to OpenBao's server logs."
  ],
  "auth": null
}