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

/identity/oidc

В данном разделе представлена документация API для настройки и управления провайдерами OIDC в StarVault.

1. Создание или обновление провайдера

Эта конечная точка создает или обновляет провайдера.

Метод Путь

POST

identity/oidc/provider/:name

1.1. Параметры

  • name (string: <обязательно>) - имя провайдера. Этот параметр указывается как часть URL.

  • issuer (string: <необязательно>) - указывает, что будет использоваться в компоненте scheme://host:port для утверждения iss ID токенов. По умолчанию используется URL с api_addr StarVault в качестве компонента scheme://host:port и /v1/identity/oidc/provider/:name в качестве компонента пути. Если предоставлено явно, оно должно указывать на экземпляр StarVault, который доступен по сети клиентам для валидации ID токена.

  • allowed_client_ids ([]string: <необязательно>) - идентификаторы клиентов, которым разрешено использовать провайдер. Если пусто, клиенты не допускаются. Если указано "*", разрешены все клиенты.

  • scopes_supported ([]string: <необязательно>) - области, доступные для запроса у провайдера.

Пример тела запроса:
{
  "allowed_client_ids": ["*"],
  "scopes_supported": ["test-scope"]
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider

2. Чтение провайдера по имени

Эта конечная точка запрашивает OIDC провайдера по его имени.

Метод Путь

GET

/identity/oidc/provider/:name

2.1. Параметры

  • name (string: <обязательно>) - имя провайдера.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider
Пример ответа:
{
  "data": {
      "allowed_client_ids": ["*"],
      "issuer": "https://127.0.0.1:8200/v1/identity/oidc/provider/test-provider",
      "scopes_supported": ["test-scope"]
  }
}

3. Список провайдеров

Эта конечная точка возвращает список всех OIDC провайдеров.

Метод Путь

LIST

/identity/oidc/provider

3.1. Параметры запроса

  • allowed_client_id (string: <необязательно>) - фильтрует список OIDC провайдеров относительно тех, которые разрешают данный идентификатор клиента в своем наборе allowed_client_ids.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/oidc/provider
Пример ответа:
{
  "data": {
    "key_info": {
      "default": {
        "allowed_client_ids": ["*"],
        "issuer": "https://127.0.0.1:8200/v1/identity/oidc/provider/default",
        "scopes_supported": []
      }
    },
    "keys": [
      "default"
    ]
  }
}

4. Удаление провайдера по имени

Эта конечная точка удаляет OIDC провайдера.

Метод Путь

DELETE

/identity/oidc/provider/:name

4.1. Параметры

  • name (string: <обязательно>) - Имя провайдера.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider

5. Создание или обновление области

Эта конечная точка создает или обновляет область.

Метод Путь

POST

identity/oidc/scope/:name

5.1. Параметры

  • name (string: <обязательно>) - имя области. Этот параметр указывается как часть URL. Имя области openid зарезервировано.

  • template (string: <необязательно>) - строка шаблона JSON для области. Это может быть предоставлено как закодированный JSON или JSON в формате base64.

  • description (string: <необязательно>) - описание области.

Пример тела запроса:
{
   "template": "{ \"groups\": {{identity.entity.groups.names}} }",
   "description": "A simple scope example."
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope

6. Чтение области по имени

Эта конечная точка запрашивает область по ее имени.

Метод Путь

GET

/identity/oidc/scope/:name

6.1. Параметры

  • name (string: <обязательно>) - имя области.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope
Пример ответа:
{
  "data": {
      "description": "A simple scope example.",
      "template": "{ \"groups\": {{identity.entity.groups.names}} }"
   }
}

7. Список областей

Эта конечная точка возвращает список всех настроенных областей.

Метод Путь

LIST

/identity/oidc/scope
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/oidc/scope
Пример ответа:
{
  "data": {
      "keys": [
         "test-scope"
      ]
   }
}

8. Удаление области по имени

Эта конечная точка удаляет область.

Метод Путь

DELETE

/identity/oidc/scope/:name

8.1. Параметры

  • name (string: <обязательно>) - имя области.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope

9. Создание или обновление клиента

Эта конечная точка создает или обновляет клиента.

Метод Путь

POST

identity/oidc/client/:name

9.1. Параметры

  • name (string: <обязательно>) - имя клиента. Этот параметр указывается как часть URL.

  • key (string: "default") - ссылка на ресурс именованного ключа. Этот ключ будет использоваться для подписи ID токенов для клиента. Это нельзя изменить после создания. Если не указано, по умолчанию используется встроенный ключ по умолчанию.

  • redirect_uris ([]string: <необязательно>) - значения URI редиректа, используемые клиентом. Один из этих значений должен точно совпадать с параметром redirect_uri, использованным в каждом запросе аутентификации.

  • assignments ([]string: <необязательно>) - список ресурсов назначений, связанных с клиентом. Назначения клиента ограничивают StarVault сущности и группы, которым разрешено аутентифицироваться через клиента. По умолчанию ни одной сущности StarVault не разрешено. Чтобы разрешить всем сущностям StarVault аутентифицироваться через клиента, предоставьте встроенное назначение allow_all.

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

    • confidential

      • Способен поддерживать конфиденциальность своих учетных данных

      • Имеет секрет клиента

      • Использует метод аутентификации клиента client_secret_basic или client_secret_post

      • Может использовать Proof Key for Code Exchange (PKCE) для потока кода аутентификации

    • public

      • Неспособен поддерживать конфиденциальность своих учетных данных

      • Не имеет секрета клиента

      • Использует метод аутентификации клиента none

      • Должен использовать Proof Key for Code Exchange (PKCE) для потока кода аутентификации

  • id_token_ttl (int or duration: "24h") - время жизни для ID токенов, получаемых клиентом. Принимает строки формата длительности. Значение должно быть меньше verification_ttl на ключе.

  • access_token_ttl (int or duration: "24h") - время жизни для токенов доступа, получаемых клиентом. Принимает строки формата длительности.

Пример тела запроса:
{
   "key": "test-key",
   "access_token_ttl": "30m",
   "id_token_ttl": "1h"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/oidc/client/test-client

10. Чтение клиента по имени

Эта конечная точка запрашивает клиента по его имени.

Метод Путь

GET

/identity/oidc/client/:name

10.1. Параметры

  • name (string: <обязательно>) - имя клиента.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/oidc/client/test-client
Пример ответа:
{
  "data": {
      "access_token_ttl": 1800,
      "assignments": [],
      "client_id": "014zXvcvbvIZWwD5NfD1Uzmv7c5JBRMb",
      "client_secret": "hvo_secret_bZtgQPBZaJXK7F5vOI7JlvEuLOfOUS7DmwynFjE3xKcsen7TyowqPFfYFXG2tbWM",
      "client_type": "confidential",
      "id_token_ttl": 3600,
      "key": "test-key",
      "redirect_uris": []
  }
}

11. Список клиентов

Эта конечная точка возвращает список всех настроенных клиентов.

Метод Путь

LIST

/identity/oidc/client
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/oidc/client
Пример ответа:
{
  "data": {
    "key_info": {
      "my-app": {
        "access_token_ttl": 86400,
        "assignments": [
          "allow_all"
        ],
        "client_id": "wGr981oYLJbcr4zrUriYxjxSc80JL7HW",
        "client_type": "confidential",
        "id_token_ttl": 86400,
        "key": "default",
        "redirect_uris": [
          "http://localhost:5555/callback"
        ]
      }
    },
    "keys": [
      "my-app"
    ]
  }
}

12. Удаление клиента по имени

Эта конечная точка удаляет клиента.

Метод Путь

DELETE

/identity/oidc/client/:name

12.1. Параметры

  • name (string: <обязательно>) - имя клиента.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/oidc/client/test-client

13. Создание или обновление назначения

Эта конечная точка создает или обновляет назначение.

Метод Путь

POST

identity/oidc/assignment/:name

13.1. Параметры

  • name (string: <обязательно>) - имя назначения. Этот параметр указывается как часть URL.

  • entity_ids ([]string: <необязательно>) - список ID сущностей StarVault сущностей.

  • group_ids ([]string: <необязательно>) - cписок ID групп StarVault групп.

Пример тела запроса:
{
   "group_ids": ["262ca5b9-7b69-0a84-446a-303dc7d778af"],
   "entity_ids": ["b6094ac6-baf4-6520-b05a-2bd9f07c66da"]
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment

14. Чтение назначения по имени

Эта конечная точка запрашивает назначение по его имени.

Метод Путь

GET

/identity/oidc/assignment/:name

14.1. Параметры

  • name (string: <обязательно>) - имя назначения.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment
Пример ответа:
{
  "data": {
      "entity_ids": [
         "b6094ac6-baf4-6520-b05a-2bd9f07c66da"
      ],
      "group_ids": [
         "262ca5b9-7b69-0a84-446a-303dc7d778af"
      ]
   }
}

15. Список назначений

Эта конечная точка возвращает список всех настроенных назначений.

Метод Путь

LIST

/identity/oidc/assignment
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/oidc/assignment
Пример ответа:
{
  "data": {
      "keys": [
         "test-assignment"
      ]
   }
}

16. Удаление назначения по имени

Эта конечная точка удаляет назначение.

Метод Путь

DELETE

/identity/oidc/assignment/:name

16.1. Параметры

  • name (string: <обязательно>) - имя назначения.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment

17. Чтение конфигурации OpenID провайдера

Возвращает метаданные OpenID Connect для именованного OIDC провайдера. Ответ является соответствующим Response конфигурации OpenID провайдера.

Метод Путь

GET

/identity/oidc/provider/:name/.well-known/openid-configuration

17.1. Параметры

  • name (string: <обязательно>) - имя провайдера. Этот параметр указывается как часть URL.

Пример запроса:
$ curl \
    --request GET \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/openid-configuration
Пример ответа:
{
  "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider",
  "jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys",
  "authorization_endpoint": "http://127.0.0.1:8200/ui/identity/oidc/provider/test-provider/authorize",
  "token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token",
  "userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo",
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "id_token_signing_alg_values_supported": [
    "RS256",
    "RS384",
    "RS512",
    "ES256",
    "ES384",
    "ES512",
    "EdDSA"
  ],
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "openid"
  ],
  "subject_types_supported": [
    "public"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ]
}

18. Чтение открытых ключей провайдера

Запросите этот путь, чтобы получить открытую часть ключей для OIDC провайдера. Клиенты могут использовать их для проверки подлинности токена идентификации.

Метод Путь

GET

/identity/oidc/provider/:name/.well-known/keys

18.1. Параметры

  • name (string: <обязательно>) - имя провайдера. Этот параметр указывается как часть URL.

Пример запроса:
$ curl \
    --request GET \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys
Пример ответа:
{
  "keys": [
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "ee7c0920-fdb9-5c1a-9c69-6dab710d1a09",
      "alg": "RS256",
      "n": "zdFjUV9lBw5nQPvTtwH-gzKgRG7iepvYbFoc2hNB0-inJL25oh-mvNW3GS8jPY5XHLsiWa_1TKKE99JrKQgane2C96soFeOvR7SozbCeH8_FpZelH1Pym1NV038j05Vp87uB9FeKPsy1PNOLPTs_Fp42JIAenly7ojYwPp1s61p9V0U9rOhtldY7GkXHLN9s8v3aJjxqrTS3Puhs9MFS7EgRrEDAc69uiLXCoYXKygjXddvJi6j446XxnO2eTRMGl1f2t04s_vDgVnFQgjQSKYWPbOMhf2slkeR47fqE3qqUDzINxauqMbkW-PlLP9IN0crR2uC07cG2os4RxN4YHw",
      "e": "AQAB"
    },
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "6e468221-b7c2-9d2d-744d-33b7ae0357cb",
      "alg": "RS256",
      "n": "rMaucILJKiFg_lkCE8ZEV_8jiYdaVDjKkc-8XPBW8S34wIRl1EbsgCYfMHtJnIJ_3eUgOVorW5KVeN9C8W16LR3lhqRWS9y4qlt0AcWpOvsmxr5q5dS_QqgCjeftCKwJzUsMi5bMW8wKjRZdd-qLz6X1rVSZWX82G0So8nRBg9d3MNJbKcdIJrRbrxWkm8U9xMqRouzbyQ2Hsp2rRVgGh7yjEA6daI5Ao8UsPdBmlCM9oKZ1_Kje5JTfZKeHlT-58vn_ylCjMVlapLuUsDN6He2kPVyOzGbie297VOfjmB7QX0ah1f7Ni1UJFJYHrVK9wMfCLTltSFZBcQ9--FlVdQ",
      "e": "AQAB"
    }
  ]
}

19. Конечная точка авторизации

Предоставляет конечную точку авторизации для OIDC провайдера. Это позволяет OIDC клиентам запрашивать код авторизации, который будет использоваться для потока кода авторизации.

Метод Путь

GET/POST

/identity/oidc/provider/:name/authorize

19.1. Параметры

  • name (string: <обязательно>) - имя провайдера. Этот параметр указывается как часть URL.

  • scope (string: <обязательно>) - пробел-разделенный список областей, которые должны быть запрошены. Область openid требуется.

  • response_type (string: <обязательно>) - процесс аутентификации OIDC, который будет использован.Поддерживаемые следующие типы ответов: code.

  • client_id (string: <обязательно>) - ID запрашивающего клиента.

  • redirect_uri (string: <обязательно>) - URI редиректа, на который будет отправлен ответ.

  • state (string: <необязательно>) - значение, используемое для поддержания состояния между запросом аутентификации и клиентом.

  • nonce (string: <необязательно>) - значение, которое возвращается в токене ID в утверждении nonce. Оно используется для снижения атак повторного воспроизведения, поэтому мы настельно рекомендуем предоставлять этот необязательный параметр.

  • max_age (integer: <необязательно>) - допустимое время, прошедшее в секундах с последнего активного аутентифицированного пользователя.

  • code_challenge (string: <необязательно>) - PKCE кодовое испытание, полученное от проверяющего кода клиента. Необязательно для confidential клиентов. Обязательно для public клиентов.

  • code_challenge_method (string: "plain") - метод, который использовался для получения PKCE кодового испытания. Поддерживаются следующие методы: S256, plain.

Пример запроса:
$ curl \
    --request GET \
    --header "X-Vault-Token: ..." \
    -G \
    -d "response_type=code" \
    -d "client_id=$CLIENT_ID" \
    -d "state=af0ifjsldkj" \
    -d "nonce=abcdefghijk" \
    --data-urlencode "scope=openid" \
    --data-urlencode "redirect_uri=http://127.0.0.1:8251/callback" \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/authorize
Пример ответа:
{
  "code": "BDSc9kVYljxND93YpveBuJtSvguM3AWe",
  "state": "af0ifjsldkj"
}

20. Конечная точка токена

Предоставляет конечную точку токена для OIDC провайдера.

Метод Путь

POST

/identity/oidc/provider/:name/token

20.1. Параметры

  • name (string: <обязательно>) - имя провайдера. Этот параметр указывается как часть URL.

  • code (string: <обязательно>) - код авторизации, полученный из конечного пункта авторизации провайдера.

  • grant_type (string: <обязательно>) - тип авторизационного гранта. Поддерживаются следующие типы грантов: authorization_code.

  • redirect_uri (string: <обязательно>) - место обратного вызова, куда был отправлен запрос на авторизацию. Это должно совпадать с redirect_uri, использованным при генерации первоначального кода авторизации.

  • client_id (string: <необязательно>) - ID запрашивающего клиента. Этот параметр требуется для public клиентов, не имеющих секрета клиента, или для confidential клиентов, использующих метод аутентификации клиента client_secret_post.

  • client_secret (string: <необязательно>) - секрет запрашивающего клиента. Этот параметр требуется для confidential клиентов, использующих метод аутентификации клиента client_secret_post.

  • code_verifier (string: <необязательно>) - проверяющий код, связанный с данным code. Обязательно для авторизационных кодов, выданных с использованием PKCE. Обязательно для public клиентов.

20.2. Заголовки

  • Authorization: Basic (string: <необязательно>) - заголовок схемы аутентификации HTTP Basic, включающий client_id и client_secret, как описано в методе аутентификации https://openid.net/specs openid-connect-core-1_0.html#ClientAuthentication[client_secret_basic]. Этот заголовок требуется только для confidential клиентов, использующих метод аутентификации client_secret_basic.

Пример запроса:
$ BASIC_AUTH_CREDS=$(printf "%s:%s" "$CLIENT_ID" "$CLIENT_SECRET" | base64)
$ curl \
    --request POST \
    --header "Authorization: Basic $BASIC_AUTH_CREDS" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d "code=4RL50r78p8HsNJY0GVUNGfjLHnpkRf3N" \
    -d "grant_type=authorization_code" \
    -d "redirect_uri=http://127.0.0.1:8251/callback" \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token
Пример ответа:
{
  "access_token": "b.AAAAAQJEH5VXjfjUESCwySTKk2MS1MGVNc9oU-N2EyoLKVo9SYa-NnOWAXloYfrlO45UWC3R1PC5ZShl3JdmRJ0264julNnlBduSNXJkYjgCQsFQwXTKHcjhqdNsmJNMWiPaHPn5NLSpNQVtzAxfHADt4r9rmX-UEG5seOWbmK_Z5WwS_4a8-wcVPB7FpOGzfBydP7yMxHu-3H1TWyQvYVr28XUfYxcBbdlzxhJn0yqkWItgmZ25xEOp7SW7Pg4tYB7AXfk",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImEzMjk5ZWVmLTllNDEtOGNiYS1kNWExLTZmZWM2NjIyODRjYyJ9.eyJhdF9oYXNoIjoiMUdlQlEzUFdtUjJ2ajZVU2swSW42USIsImF1ZCI6InpTSktMVmk0R1BYS1o3TTZzUUEwY3FNc05VaHNPYkVTIiwiY19oYXNoIjoiN09SOUszNmhNdllENzJkUkFLcHhNdyIsImNvbnRhY3QiOnsiZW1haWwiOiJ2YXVsdEBoYXNoaWNvcnAuY29tIiwicGhvbmVfbnVtYmVyIjoiMTIzLTQ1Ni03ODkwIn0sImV4cCI6MTYzMzEwNjI5NCwiZ3JvdXBzIjpbImVuZ2luZWVyaW5nIl0sImlhdCI6MTYzMzEwNDQ5NCwiaXNzIjoiaHR0cDovLzEyNy4wLjAuMC4xOjgyMDAvdjEvaWRlbnRpdHkvb2lkYyIsIm5hbWVzcGFjZSI6InJvb3QiLCJub25jZSI6ImFiY2RlZmdoaWprIn0.ehdLj6jnrJvltar1kkVSyNK48w2M5vkh5DTFJFZDqatnDWhQbbKGLZnVgd3wD6KPboXRaUwhGe4jDiTIiSoJaovOhsia77NKukym_ROLvGZw-LG7xaYkzJLnmEfeQhelLxWe0DHPROB7VXcFqBx8vX5hkuoVyqrB87vwiobK42pDPZ9MRsmbM2yzBC3wrnT7RQFtT4q2Bbyt9YIAHUaq9rU0PwJRoNISw6of1uQHo3_UzLdpwth7PEOEcI47OBGFA5vR_Gw3ocREfSrUWfCWOInAKCT43cImvg4Bts6qiZYfv9n-iNBq4AihGqq_VEF-hB1Hrprn7VgnEZ1VjUHaQQ",
  "token_type": "Bearer"
}

21. Конечная точка UserInfo

Предоставляет конечную точку UserInfo для OIDC провайдера. Конечная точка UserInfo является защищенным ресурсом OAuth 2.0, который возвращает утверждения о аутентифицированном конечном пользователе.

Метод Путь

POST

/identity/oidc/provider/:name/userinfo

21.1. Параметры

  • name (string: <обязательно>) - имя провайдера. Этот параметр указывается как часть URL.

21.2. Заголовки

  • Access Token (string: <обязательно>) - токен доступа, предоставленный заголовком HTTP Authorization: Bearer <access_token>, полученным с конечного пункта авторизации.

Пример запроса:
$ curl \
    -X GET \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo
Пример ответа:
{
  "contact": {
    "email": "starvault@orionsoft.ru",
    "phone_number": "123-456-7890"
  },
  "groups": [
    "engineering"
  ],
  "sub": "5000796e-36df-0d8c-6460-81853d9b2667",
  "username": "end-user"
}