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

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

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

Данный механизм может использовать внешние сертификаты X.509 в качестве части TLS или проверки подписи. Проверка подписей на сертификаты X.509 с использованием SHA-1 устарела и больше не может использоваться без обходного решения.

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

1. Создание роли CA сертификата

Устанавливает сертификат CA и связанные параметры в именованной роли.

Метод Путь

POST

/auth/cert/certs/:name

1.1. Параметры

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

  • certificate (string: <required>) - CA сертификат в формате PEM.

  • allowed_names (string: "") - УСТАРЕЛО: пожалуйста, используйте индивидуальные параметры allowed_X_sans вместо. Ограничьте Общие и Альтернативные Имена в клиентском сертификате шаблоном glob. Значение является списком шаблонов, разделенных запятыми. Аутентификация требует, чтобы хотя бы одно Имя соответствовало хотя бы одному шаблону. Если не указано, по умолчанию разрешены все имена.

  • allowed_common_names (string: "" or array: []) - ограничьте Общие Имена в клиентском сертификате шаблоном glob. Значение является списком шаблонов, разделенных запятыми. Аутентификация требует, чтобы хотя бы одно Имя соответствовало хотя бы одному шаблону. Если не указано, по умолчанию разрешено все имена.

  • allowed_dns_sans (string: "" or array: []) - ограничьте Альтернативные Имена в клиентском сертификате шаблоном glob. Значение является списком шаблонов, разделенных запятыми. Аутентификация требует, чтобы хотя бы один DNS соответствовал хотя бы одному шаблону. Если не указано, по умолчанию разрешено все DNS.

  • allowed_email_sans (string: "" or array: []) - ограничьте Альтернативные Имена в клиентском сертификате шаблоном glob. Значение является списком шаблонов, разделенных запятыми. Аутентификация требует, чтобы хотя бы один Email соответствовал хотя бы одному шаблону. Если не указано, по умолчанию разрешены все Email.

  • allowed_uri_sans (string: "" or array: []) - ограничьте Альтернативные Имена в клиентском сертификате шаблоном glob. Значение является списком шаблонов URI, разделенных запятыми. Аутентификация требует, чтобы хотя бы один URI соответствовал хотя бы одному шаблону. Если не указано, по умолчанию разрешены все URI.

  • allowed_organizational_units (string: "" or array: []) - ограничьте Организационные Подразделения (OU) в клиентском сертификате шаблоном glob. Значение является списком OU шаблонов, разделенных запятыми. Аутентификация требует, чтобы хотя бы одно OU соответствовало хотя бы одному шаблону. Если не указано, по умолчанию разрешены все OU.

  • required_extensions (string: "" or array: []) - требует, чтобы конкретные пользовательские OID для расширений существовали и соответствовали шаблону. Значение является строкой, разделенной запятыми, или массивом строк вида oid:value. Ожидает, что значение расширения будет какого-либо типа ASN1 закодированной строки. Все условия должны быть выполнены. Поддерживает globbing на value.

  • allowed_metadata_extensions (array: []) - строка или JSON массив разрешенных расширений oid. При успешной аутентификации эти расширения будут добавлены как метаданные, если они присутствуют в сертификате. Ключ метаданных будет строкой, состоящей из номеров oid, разделённых дефисом (-), вместо точки (.), чтобы разрешить использование в шаблонах ACL.

  • ocsp_enabled (bool: false) - если включено, проверяет статус отмены сертификатов с помощью OCSP.

  • ocsp_ca_certificates (string: "") Любые дополнительные CA сертификаты, необходимые для проверки OCSP ответов. Предоставляется в виде закодированных в base64 данных PEM.

  • ocsp_servers_override (array: []) - строка, разделенная запятыми, адресов серверов OCSP. Если не установлено, сервер OCSP определяется из расширения AuthorityInformationAccess на проверяемом сертификате.

  • ocsp_fail_open (bool: false) - если true и ответ OCSP не может быть получен или имеет неизвестный статус, вход будет продолжен так, как будто сертификат не был отозван.

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

  • display_name (string: "") - отображаемое имя для токенов, выданных при аутентификации с помощью этого сертификата CA. Если не указано, по умолчанию соответствует имени роли.

Пример тела запроса:
{
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
  "display_name": "test",
  "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"]
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --cacert StarVault-ca.pem \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/cert/certs/test-ca

2. Чтение роли CA сертификата

Получает информацию, связанную с именованной ролью.

Метод Путь

GET

/auth/cert/certs/:name

2.1. Параметры

  • name (string: <required>) - Имя роли сертификата.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --cacert StarVault-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/certs/test-ca
Пример ответа:
{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
    "display_name": "test",
    "policies": "",
    "allowed_names": "",
    "required_extensions": "",
    "ttl": 2764800,
    "max_ttl": 2764800,
    "period": 0
  },
  "warnings": null,
  "auth": null
}

3. Список ролей сертификатов

Перечисляет настроенные имена сертификатов.

Метод Путь

LIST

/auth/cert/certs

3.1. Параметры

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

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

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    --cacert StarVault-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/certs
Пример ответа:
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": ["cert1", "cert2"]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

4. Удаление роли сертификата

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

Метод Путь

DELETE

/auth/cert/certs/:name

4.1. Параметры

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

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    --cacert StarVault-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/certs/cert1

5. Список CRL

Перечисляет настройки списков отзыва сертификатов (CRL).

Метод Путь

LIST

/auth/cert/crls

5.1. Параметры

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

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

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    --cacert StarVault-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/crls
Пример ответа:
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": ["crl1", "crl2"]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

6. Создание CRL

Устанавливает именованный CRL.

Метод Путь

POST

/auth/cert/crls/:name

6.1. Параметры

  • name (string: <required>) - имя CRL.

  • crl (string: "") - CRL в формате PEM.

  • url (string: "") - URL точки распространения CRL.

Должен быть предоставлен либо параметр 'crl', либо 'url'. Если указаны оба, используется 'crl'.
Пример тела запроса:
{
  "crl": "-----BEGIN X509 CRL-----\n...\n-----END X509 CRL-----"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --cacert StarVault-ca.pem \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/cert/crls/custom-crl

7. Чтение CRL

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

Метод Путь

GET

/auth/cert/crls/:name

7.1. Параметры

  • name (string: <required>) - Имя CRL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --cacert StarVault-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/crls/custom-crl
Пример ответа:
{
  "auth": null,
  "data": {
    "serials": {
      "13": {}
    }
  },
  "lease_duration": 0,
  "lease_id": "",
  "renewable": false,
  "warnings": null
}

8. Удаление CRL

Удаляет именованный CRL из точки монтирования метода аутентификации.

Метод Путь

DELETE

/auth/cert/crls/:name

8.1. Параметры

  • name (string: <required>) - Имя CRL.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    --cacert StarVault-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/crls/cert1

9. Настроить метод аутентификации по сертификатам TLS

Параметры конфигурации для метода.

Метод Путь

POST

/auth/cert/config

9.1. Параметры

  • disable_binding (boolean: false) - если установлено, при продлении пропускает совпадение представленной клиентской идентичности с идентичностью клиента, используемой во время входа.

  • enable_identity_alias_metadata (boolean: false) - если установлено, метаданные сертификата, включая соответствующие метаданные allowed_metadata_extensions, будут храниться в алиасе.

  • ocsp_cache_size (int: 100) - размер кэша LRU ответа OCSP. Обратите внимание, что этот кэш используется для всех настроенных сертификатов.

Пример тела запроса:
{
  "disable_binding": true
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --cacert StarVault-ca.pem \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/cert/config

10. Вход с помощью метода аутентификации по сертификатам TLS

Вход и получение токена. Если существует действительная цепочка к CA, настроенному в методе, и все ограничения ролей совпадают, будет выдан токен. Если в сертификате есть DNS SAN, каждая из них будет проверяться. Если требуется проверка общего имени, то оно должно быть полным доменным именем DNS и должно дублироваться как DNS SAN (см. https://tools.ietf.org/html/rfc6125#section-2.3).

Метод Путь

POST

/auth/cert/login

10.1. Параметры

  • name (string: "") - аутентификация только против названной роли сертификата, возвращая ее список политик, если это удачно. Если не указано, по умолчанию пробует все роли сертификатов и возвращает любую, которая соответствует.

Пример тела запроса:
{
  "name": "cert1"
}

10.2. Пример запроса

Значение --cacert, используемое здесь - это сертификат CA TLS слушателя StarVault, а не CA, который выдал сертификат клиентской аутентификации. Это может быть опущено, если CA, использованный для выдачи сертификата сервера StarVault, доверен локальной системе, выполняющей эту команду.

 
$ curl \
    --request POST \
    --cacert StarVault-ca.pem \
    --cert cert.pem \
    --key key.pem \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/cert/login
Пример ответа:
{
  "auth": {
    "client_token": "cf95f87d-f95b-47ff-b1f5-ba7bff850425",
    "policies": ["web", "stage"],
    "lease_duration": 3600,
    "renewable": true
  }
}