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

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

В данной документации предполагается, что метод AppRole подключен по пути /auth/approle в StarVault. Поскольку возможно включать методы аутентификации по любому пути, пожалуйста, обновите ваши вызовы API соответственно.

1. Список ролей

Данная конечная точка возвращает список существующих AppRoles в методе.

Метод Путь

Метод	Путь
`LIST`	`/auth/approle/role`

LIST

/auth/approle/role

1.1. Параметры

after (string: "") - необязательная запись, с которой следует начинать перечисление для постраничной навигации;
limit (int: 0) - необязательное количество записей для возврата; по умолчанию возвращаются все записи.

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/approle/role

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

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": ["dev", "prod", "test"]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

2. Создание/Обновление AppRole

Создает новый AppRole или обновляет существующий AppRole. Эта конечная точка поддерживает как метод create, так и update. На роли могут быть включены один или несколько ограничений. Обязательно должно быть включено хотя бы одно из них при создании или обновлении роли.

Метод Путь

Метод	Путь
`POST`	`/auth/approle/role/:role_name`

POST

/auth/approle/role/:role_name

2.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт, принимаются символы a-z, 0-9, пробел, дефис, подчеркивание и точки.
bind_secret_id (bool: true) - требуется наличие secret_id при входе с использованием этого AppRole.
secret_id_bound_cidrs (array: []) - строка, разделенная запятыми, или список блоков CIDR; если установлено, указывает блоки IP-адресов, которые могут выполнять операцию входа.
secret_id_num_uses (integer: 0) - количество раз, когда конкретный SecretID может быть использован для получения токена из этого AppRole, после чего SecretID по умолчанию истечет. Значение ноль разрешает неограниченное использование. Однако, эта опция может быть переопределена полем num_uses в запросе при генерации SecretID.
secret_id_ttl (string: "") - длительность в виде целого числа секунд (3600) или целой единицы времени (60m), после чего по умолчанию любой SecretID истечет. Значение ноль позволит SecretID не истекать. Однако, эта опция может быть переопределена полем ttl в запросе при генерации SecretID.
local_secret_ids (bool: false) - если установлено, Secret ID, созданные с использованием этой роли, будут локальными для кластера. Это можно установить только во время создания роли, и после установки нельзя сбросить.

Пример тела запроса:

{
  "token_ttl": "10m",
  "token_max_ttl": "15m",
  "token_policies": ["default"],
  "period": 0,
  "bind_secret_id": true
}

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/role/application1

3. Чтение AppRole

Читает свойства существующего AppRole.

Метод Путь

Метод	Путь
`GET`	`/auth/approle/role/:role_name`

GET

/auth/approle/role/:role_name

3.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/approle/role/application1

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

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "token_ttl": 1200,
    "token_max_ttl": 1800,
    "secret_id_ttl": 600,
    "secret_id_num_uses": 40,
    "token_policies": ["default"],
    "period": 0,
    "bind_secret_id": true,
    "secret_id_bound_cidrs": []
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

4. Удаление AppRole

Удаляет существующий AppRole из метода.

Метод Путь

Метод	Путь
`DELETE`	`/auth/approle/role/:role_name`

DELETE

/auth/approle/role/:role_name

4.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/auth/approle/role/application1

5. Чтение Role ID AppRole

Читает RoleID существующего AppRole.

Метод Путь

Метод	Путь
`GET`	`/auth/approle/role/:role_name/role-id`

GET

/auth/approle/role/:role_name/role-id

5.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.

Пример запроса:

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

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

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

6. Обновление Role ID AppRole

Обновляет RoleID существующего AppRole на настраиваемое значение.

Метод Путь

Метод	Путь
`POST`	`/auth/approle/role/:role_name/role-id`

POST

/auth/approle/role/:role_name/role-id

6.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.
role_id (string: <required>) - значение, которое следует установить в качестве RoleID.

Пример тела запроса:

{
  "role_id": "custom-role-id"
}

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/role-id

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

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

7. Генерация нового Secret ID

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

Метод Путь

Метод	Путь
`POST`	`/auth/approle/role/:role_name/secret-id`

POST

/auth/approle/role/:role_name/secret-id

7.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.
metadata (string: "") - метаданные, которые будут связаны с SecretID. Это должно быть строкой в формате JSON, содержащей метаданные в виде пар «ключ-значение». Эти метаданные будут установлены на токенах, выданных с этим SecretID, и зарегистрированы в журналах аудита в открытом виде.
cidr_list (array: []) - строка, разделенная запятыми, содержащая список блоков CIDR, заставляющая использовать secret ID из определенного набора IP-адресов. Если secret_id_bound_cidrs установлено на роли, то список блоков CIDR здесь должен быть подмножеством блоков CIDR, перечисленных на роли.
token_bound_cidrs (array: []) - строка, разделенная запятыми, или список блоков CIDR; если установлено, указывает блоки IP-адресов, которые могут использовать токены аутентификации, сгенерированные этим SecretID. Переопределяет любое установленное значение роли, но должно быть подмножеством.
num_uses (integer: 0) - количество раз, которое этот SecretID может быть использован, после чего SecretID истечет. Значение 0 позволит неограниченное использование. Переопределяет опцию secret_id_num_uses роли, когда указано. Не может быть выше, чем secret_id_num_uses роли.
ttl (string: "") - длительность в секундах (3600) или целой единице времени (60m), после чего этот SecretID истечет. Значение 0 позволит SecretID не истекать. Переопределяет опцию secret_id_ttl роли, когда указано. Не может быть длиннее, чем secret_id_ttl роли.

Пример тела запроса:

{
  "metadata": "{ \"tag1\": \"production\" }",
  "ttl": 600,
  "num_uses": 50
}

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id

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

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
    "secret_id": "841771dc-11c9-bbc7-bcac-6a3945a69cd9",
    "secret_id_ttl": 600,
    "secret_id_num_uses": 50
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

8. Список accessor-ов Secret ID

Перечисляет accessor-ы всех SecretID, выданных против AppRole. Это включает и accessor-ы "настраиваемых" SecretID.

Метод Путь

Метод	Путь
`LIST`	`/auth/approle/role/:role_name/secret-id`

LIST

/auth/approle/role/:role_name/secret-id

8.1. Параметры

after (string: "") - необязательная запись, с которой следует начинать перечисление для постраничной навигации; может не существовать.
limit (int: 0) - необязательное количество записей для возврата; по умолчанию возвращаются все записи.

8.2. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id

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

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": [
      "ce102d2a-8253-c437-bf9a-aceed4241491",
      "a1c8dee4-b869-e68d-3520-2040c1a0849a",
      "be83b7e2-044c-7244-07e1-47560ca1c787",
      "84896a0c-1347-aa90-a4f6-aca8b7558780",
      "239b1328-6523-15e7-403a-a48038cdc45a"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

9. Чтение Secret ID AppRole

Читает свойства SecretID.

Метод Путь

Метод	Путь
`POST`	`/auth/approle/role/:role_name/secret-id/lookup`

POST

/auth/approle/role/:role_name/secret-id/lookup

9.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.
secret_id (string: <required>) - Secret ID, связанный с ролью.

Пример тела запроса:

{
  "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id/lookup

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

{
  "request_id": "74752925-f309-6859-3d2d-0fcded95150e",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "cidr_list": [],
    "creation_time": "2023-02-10T18:17:27.089757383Z",
    "expiration_time": "0001-01-01T00:00:00Z",
    "last_updated_time": "2023-02-10T18:17:27.089757383Z",
    "metadata": {
      "tag1": "production"
    },
    "secret_id_accessor": "2be760a4-86bb-2fa9-1637-1b7fa9ba2896",
    "secret_id_num_uses": 0,
    "secret_id_ttl": 0,
    "token_bound_cidrs": []
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

10. Удаление Secret ID AppRole

Удаление Secret ID AppRole.

Метод Путь

Метод	Путь
`POST`	`/auth/approle/role/:role_name/secret-id/destroy`

POST

/auth/approle/role/:role_name/secret-id/destroy

10.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.
secret_id (string: <required>) - Secret ID, связанный с ролью.

Пример тела запроса:

{
  "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id/destroy

11. Чтение accessor-а Secret ID AppRole

Читает свойства SecretID.

Метод Путь

Метод	Путь
`POST`	`/auth/approle/role/:role_name/secret-id-accessor/lookup`

POST

/auth/approle/role/:role_name/secret-id-accessor/lookup

11.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.
secret_id_accessor (string: <required>) - accessor Secret ID, связанный с ролью.

Пример тела запроса:

{
  "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id-accessor/lookup

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

{
  "request_id": "72836cd1-139c-fe66-1402-8bb5ca4044b8",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "cidr_list": [],
    "creation_time": "2023-02-10T18:17:27.089757383Z",
    "expiration_time": "0001-01-01T00:00:00Z",
    "last_updated_time": "2023-02-10T18:17:27.089757383Z",
    "metadata": {
      "tag1": "production"
    },
    "secret_id_accessor": "2be760a4-86bb-2fa9-1637-1b7fa9ba2896",
    "secret_id_num_uses": 0,
    "secret_id_ttl": 0,
    "token_bound_cidrs": []
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

12. Удаление accessor-а Secret ID AppRole

Удаление Secret ID AppRole по его accessor.

Метод Путь

Метод	Путь
`POST`	`/auth/approle/role/:role_name/secret-id-accessor/destroy`

POST

/auth/approle/role/:role_name/secret-id-accessor/destroy

12.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.
secret_id_accessor (string: <required>) - accessor Secret ID, связанный с ролью.

Пример тела запроса:

{
  "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id-accessor/destroy

13. Создание настраиваемого Secret ID AppRole

Назначает "настраиваемый" SecretID для существующего AppRole. Это используется в модели "Push".

Метод Путь

Метод	Путь
`POST`	`/auth/approle/role/:role_name/custom-secret-id`

POST

/auth/approle/role/:role_name/custom-secret-id

13.1. Параметры

role_name (string: <required>) - имя AppRole. Должно содержать менее 4096 байт.
secret_id (string: <required>) - SecretID, который должен быть связан с ролью.
metadata (string: "") - метаданные, которые будут связаны с SecretID. Это должно быть строкой в формате JSON, содержащей метаданные в виде пар «ключ-значение». Эти метаданные будут установлены на токенах, выданных с этим SecretID, и зарегистрированы в журналах аудита в открытом виде.
cidr_list (array: []) - строка, разделенная запятыми, содержащая список блоков CIDR, заставляющая использовать secret ID из определенного набора IP-адресов. Если secret_id_bound_cidrs установлено на роли, то список блоков CIDR здесь должен быть подмножеством блоков CIDR, перечисленных на роли.
token_bound_cidrs (array: []) - строка, разделенная запятыми, или список блоков CIDR; если установлено, указывает блоки IP-адресов, которые могут использовать токены аутентификации, сгенерированные этим SecretID. Переопределяет любое установленное значение роли, но должно быть подмножеством.
num_uses (integer: 0) - количество раз, которое этот SecretID может быть использован, после чего SecretID истечет. Значение ноль позволит неограниченное использование. Переопределяет опцию secret_id_num_uses роли, когда указано. Не может быть выше, чем secret_id_num_uses роли.
ttl (string: "") - длительность в секундах (3600) или целой единице времени (60m), после которого этот SecretID истечет. Значение ноль позволит SecretID не истекать. Переопределяет опцию secret_id_ttl роли, когда указано. Не может быть длиннее, чем secret_id_ttl роли.

Пример тела запроса:

{
  "secret_id": "testsecretid",
  "ttl": 600,
  "num_uses": 50
}

Пример запроса:

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/custom-secret-id

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

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "secret_id": "testsecretid",
    "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
    "secret_id_ttl": 600,
    "secret_id_num_uses": 50
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

14. Вход с помощью AppRole

Выдает токен StarVault на основе представленных учетных данных. role_id всегда требуется; если bind_secret_id включен (по умолчанию) в AppRole, также требуется secret_id. Любые другие связанные значения аутентификации на AppRole (такие как CIDR клиентского IP) также учитываются.

Метод Путь

Метод	Путь
`POST`	`/auth/approle/login`

POST

/auth/approle/login

14.1. Параметры

role_id (string: <required>) - RoleID AppRole.
secret_id (string: <required>) - SecretID, принадлежащий AppRole.

Пример тела запроса:

{
  "role_id": "59d6d1ca-47bb-4e7e-a40b-8be3bc5a0ba8",
  "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Пример запроса:

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/login

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

{
  "auth": {
    "renewable": true,
    "lease_duration": 1200,
    "metadata": null,
    "token_policies": ["default"],
    "accessor": "fd6c9a00-d2dc-3b11-0be5-af7ae0e1d374",
    "client_token": "5b1a0318-679c-9c45-e5c6-d1b9a9035d49"
  },
  "warnings": null,
  "wrap_info": null,
  "data": null,
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

15. Чтение, обновление или удаление свойств AppRole

Обновляет соответствующее свойство в существующем AppRole. Все эти параметры AppRole могут быть обновлены с помощью конечной точки /auth/approle/role/:role_name напрямую. Конечные точки для каждого поля предоставляются отдельно, чтобы иметь возможность делегировать конкретные конечные точки с помощью системы ACL StarVault.

Метод Путь Код ответа

Метод	Путь	Код ответа
`GET/POST/DELETE`	`/auth/approle/role/:role_name/policies`	`200/204`
`GET/POST/DELETE`	`/auth/approle/role/:role_name/secret-id-num-uses`	`200/204`
`GET/POST/DELETE`	`/auth/approle/role/:role_name/secret-id-ttl`	`200/204`
`GET/POST/DELETE`	`/auth/approle/role/:role_name/token-ttl`	`200/204`
`GET/POST/DELETE`	`/auth/approle/role/:role_name/token-max-ttl`	`200/204`
`GET/POST/DELETE`	`/auth/approle/role/:role_name/bind-secret-id`	`200/204`
`GET/POST/DELETE`	`/auth/approle/role/:role_name/secret-id-bound-cidrs`	`200/204`
`GET/POST/DELETE`	`/auth/approle/role/:role_name/token-bound-cidrs`	`200/204`
`GET/POST/DELETE`	`/auth/approle/role/:role_name/period`	`200/204`

GET/POST/DELETE

/auth/approle/role/:role_name/policies

200/204

GET/POST/DELETE

/auth/approle/role/:role_name/secret-id-num-uses

200/204

GET/POST/DELETE

/auth/approle/role/:role_name/secret-id-ttl

200/204

GET/POST/DELETE

/auth/approle/role/:role_name/token-ttl

200/204

GET/POST/DELETE

/auth/approle/role/:role_name/token-max-ttl

200/204

GET/POST/DELETE

/auth/approle/role/:role_name/bind-secret-id

200/204

GET/POST/DELETE

/auth/approle/role/:role_name/secret-id-bound-cidrs

200/204

GET/POST/DELETE

/auth/approle/role/:role_name/token-bound-cidrs

200/204

GET/POST/DELETE

/auth/approle/role/:role_name/period

200/204

Смотрите конечную точку /auth/approle/role/:role_name.

16. Очистка токенов

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

Метод Путь

Метод	Путь
`POST`	`/auth/approle/tidy/secret-id`

POST

/auth/approle/tidy/secret-id

Пример запроса:

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

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

{
  "request_id": "b20b56e3-4699-5b19-cc6b-e74f7b787bbf",
  "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 StarVault's server logs"
  ],
  "auth": null
}