Руководство администратора Deckhouse Stronghold по API

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

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

AppRole

Этот раздел подразумевает, что метод активирован по пути /auth/approle.

Вывод списка ролей

Этот путь возвращает список существующих AppRoles в методе.

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

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

curl \
  --header "X-Vault-Token: ${VAULT_TOKEN}" \
  --request LIST \
    ${VAULT_ADDR}/v1/auth/approle/role

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

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

Создание или обновление AppRole

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

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

Параметры:

role_name (строка: ) - Имя AppRole. Должно быть короче 4096 байт, допустимые символы включают a-Z, 0-9, пробел, тире, подчеркивания и точки.
bind_secret_id (булевый: true) - Требуется, чтобы secret_id был представлен при входе с использованием этого AppRole
secret_id_bound_cidrs (массив: []) - Строка, разделенная запятыми, или список блоков CIDR; установленное значение указывает блоки IP-адресов, которые могут выполнять операцию входа.
secret_id_num_uses (целое число: 0) - Количество раз, которое любой конкретный SecretID может использоваться для получения токена из этого AppRole, после чего SecretID по умолчанию истекает. Установка значения равного нулю позволяет неограниченное использование. Однако этот параметр может быть переопределен полем ’num_uses’ запроса при создании SecretID.
secret_id_ttl (строка: “”) - Продолжительность в виде целого числа секунд (3600) или целевого временного интервала (60m), после чего любой SecretID по умолчанию истекает. Установка значения равного нулю позволит SecretID не истекать. Однако этот параметр может быть переопределен полем ’ttl’ запроса при создании SecretID.
local_secret_ids (булевый: false) - Если установлено, секретные ID, созданные с использованием этой роли, будут локальными для кластера. Этот параметр можно установить только при создании роли и изменить позднее невозможно.
token_ttl (целое число: 0 или строка: “”) - Инкрементальный срок действия для созданных токенов. Текущее значение этого параметра будет учтено при продлении.
token_max_ttl (целое число: 0 или строка: “”) - Максимальный срок действия для созданных токенов. Текущее значение этого параметра будет учтено при продлении.
token_policies (массив: [] или строка с разделением запятыми: “”) - Список политик токенов, которые будут добавлены в создаваемые токены. В зависимости от метода аутентификации, этот список может быть дополнен значениями пользователя/группы/другими значениями.
token_bound_cidrs (массив: [] или строка с разделением запятыми: “”) - Список блоков CIDR; установленное значение указывает блоки IP-адресов, которые могут успешно аутентифицироваться, и связывает полученный токен с этими блоками.
token_explicit_max_ttl (целое число: 0 или строка: “”) - Если установлено, будет добавлен явный максимальный срок действия токена. Это жесткое ограничение, даже если token_ttl и token_max_ttl позволили бы продление.
token_no_default_policy (булевый: false) - Если установлено, политика по умолчанию не будет установлена на создаваемых токенах; в противном случае она будет добавлена к установленным политикам в token_policies.
token_num_uses (целое число: 0) - Максимальное количество раз, которое может быть использован созданный токен (в пределах его срока действия); 0 означает неограниченное количество раз. Если вам необходимо, чтобы токен имел возможность создавать дочерние токены, установите значение на 0.
token_period (целое число: 0 или строка: “”) - Максимальное допустимое значение периода времени, когда запрашивается периодический токен из этой роли.
token_type (строка: “”) - Тип токена, который должен быть создан. Значение может быть равно service, batch, или default для использования настроенного по умолчанию значения (которое, если не изменено, будет service токенами). Для ролей хранилища токенов есть две дополнительные возможности: default-service и default-batch, которые указывают тип для возврата, если клиент не запросит другой тип при создании. Для случаев аутентификации, основанной на машинном взаимодействии, используйте токены типа batch.

Пример данных:

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

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

curl \
  --header "X-Vault-Token: ${VAULT_TOKEN}" \
  --request POST \
  --data @payload.json \
    ${VAULT_ADDR}/v1/auth/approle/role/application

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

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

Чтение AppRole

Выводит свойства существующего AppRole.

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

Параметры:

role_name (string: <required>) - Имя AppRole. Должно быть короче 4096 байт.

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/auth/approle/role/application1

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

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

Удаление AppRole

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

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

Параметры:

role_name (строка: <required>) - Имя AppRole. Должно быть короче 4096 байт.

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

$ curl \
  --header "X-Vault-Token: ${VAULT_TOKEN}" \
  --request DELETE \
  ${VAULT_ADDR}/v1/auth/approle/role/application1

Чтение RoleID AppRole

Выводит RoleID существующего AppRole.

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

Параметры:

role_name (string: <required>) - Имя AppRole. Должно быть короче 4096 байт.

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/auth/approle/role/application1/role-id

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

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

Обновление RoleID AppRole

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

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

Параметры:

role_name (string: <required>) - Имя AppRole. Должно быть короче 4096 байт.
role_id (string: <required>) - Значение RoleID.

Пример данных:

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

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/auth/approle/role/application1/role-id

Генерация нового SecretID

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

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

Параметры:

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

Пример данных:

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

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/auth/approle/role/application1/secret-id

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

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

Список идентификаторов доступа SecretID

Выводит идентификаторы доступа всех выданных SecretID для AppRole. Это включает идентификаторы доступа для “пользовательских” SecretID.

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

Параметры:

role_name (string: <required>) - Имя AppRole. Должно быть короче 4096 байт.

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request LIST \
    ${VAULT_ADDR}/v1/auth/approle/role/application1/secret-id

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

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": [
      "ce202d2a-8253-c437-bf9a-aceed4241491",
      "a1c0dee4-b869-e68d-3520-2040c1a0849a",
      "be03b7e2-044c-7244-07e1-47560ca1c787",
      "84896a0c-1347-aa80-a3f6-aca8b7558780",
      "439b1328-6523-15e7-403a-a48038cdc45a"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

Чтение SecretID AppRole

Выводит свойства SecretID AppRole.

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

Параметры:

role_name (string: <required>) - Имя AppRole. Должно быть короче 4096 байт.
secret_id (строка: <обязательно>) - SecretID, привязанный к роли.

Пример данных:

{
  "secret_id": "84896a0c-1347-aa80-a3f6-aca8b7558780"
}

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/auth/approle/role/application1/secret-id/lookup

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

{
  "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-87bb-2fa9-1637-1b7fa9ba2896",
    "secret_id_num_uses": 0,
    "secret_id_ttl": 0,
    "token_bound_cidrs": []
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Уничтожение SecretID AppRole

Уничтожает SecretID AppRole.

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

Параметры:

role_name (string: <required>) - Имя AppRole. Должно быть короче 4096 байт.
secret_id (string: <required>) - SecretID, привязанный к роли.

Пример данных:

{
  "secret_id": "84896a0c-1347-aa80-a3f6-aca8b7558780"
}

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/auth/approle/role/application1/secret-id/destroy

Чтение SecretID AppRole

Выводит свойства SecretID AppRole.

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

Параметры:

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

Пример данных:

{
  "secret_id_accessor": "84896a0c-1347-aa80-a3f6-aca8b7558780"
}

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/auth/approle/role/application1/secret-id-accessor/lookup

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

{
  "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-87bb-2fa9-1637-1b7fa9ba2896",
    "secret_id_num_uses": 0,
    "secret_id_ttl": 0,
    "token_bound_cidrs": []
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Уничтожение SecretID AppRole по идентификатору доступа

Уничтожает SecretID AppRole по его идентификатору доступа.

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

Параметры:

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

Пример данных:

{
  "secret_id_accessor": "84896a0c-1347-aa80-a3f6-aca8b7558780"
}

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/auth/approle/role/application1/secret-id-accessor/destroy

Создание пользовательского SecretID AppRole

Назначает “пользовательский” SecretID для существующей роли AppRole. Это используется в модели “Push” операции.

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

Параметры:

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

Пример данных:

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

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/auth/approle/role/application1/custom-secret-id

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

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

Вход с использованием AppRole

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

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

Параметры:

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

Пример данных:

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

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

$ curl \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/auth/approle/login

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

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

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

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

Method	Path
`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.

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

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

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

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

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    ${VAULT_ADDR}/v1/auth/approle/tidy/secret-id

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

{
  "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 Stronghold's server logs."
  ],
  "auth": null
}