Провайдер OIDC

В документе представлена концептуальная информация о функции поставщика идентификационных данных StarVault OpenID Connect (OIDC). Эта функция позволяет клиентским приложениям, использующим протокол OIDC, использовать источник идентификации StarVault и широкий спектр методов аутентификации при проверке подлинности конечных пользователей.

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

В следующих разделах документа приводятся подробности реализации каждого ресурса, позволяющего конфигурировать StarVault в качестве поставщика идентификационных данных OIDC.

1.1. Провайдеры OIDC

Каждое пространство имен StarVault будет содержать встроенный ресурс провайдера с именем default. Провайдер по умолчанию позволит всем клиентским приложениям в пространстве имен использовать его для потоков OIDC. Провайдер по умолчанию можно изменять, но нельзя удалять.

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

Провайдер имеет следующие параметры конфигурации:

URL-адрес эмитента: используется в утверждении идентификационных токенов iss.
Разрешенные идентификаторы клиентов: ограничивает, какие клиенты могут получить доступ к провайдеру.
Поддерживаемые области видимости: ограничивает, какая идентификационная информация доступна в виде утверждений.

Параметр URL эмитента необходим для проверки ID-токенов клиентами. Если параметр URL не указан явно, по умолчанию будет использоваться URL с api_addr StarVault в качестве компонента scheme://host:port и /v1/identity/oidc/provider/:name в качестве компонента path. Это означает, что токены, выпущенные провайдером в указанном кластере StarVault, должны быть проверены в этом же кластере. Если URL-адрес эмитента указан явно, он должен указывать на экземпляр StarVault, доступный клиентам по сети для проверки ID-токенов.

Параметр "Разрешенные идентификаторы клиентов" использует список идентификаторов клиентов, которые были сгенерированы StarVault в процессе регистрации клиентов. По умолчанию все клиенты будут запрещены. Указание * в качестве значения параметра позволит всем клиентам использовать провайдера.

Параметр scopes использует список ссылок на именованные области видимости ресурсов. Предоставленные значения можно обнаружить по ключу scopes_supported в документе обнаружения OIDC провайдера. По умолчанию провайдеру доступен диапазон openid. Более подробную информацию о диапазоне openid см. в разделе диапазонов ниже.

1.2. Области видимости

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

У диапазона будут следующие параметры конфигурации:

Описание: информация об идентификации, захваченная областью действия
Шаблон: сопоставляет отдельные утверждения с информацией об идентификации StarVault

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

Пример шаблона JSON для области видимости:

{
    "username": {{identity.entity.aliases.$MOUNT_ACCESSOR.name}},
    "contact": {
        "email": {{identity.entity.metadata.email}},
        "phone_number": {{identity.entity.metadata.phone_number}}
    },
    "groups": {{identity.entity.groups.names}}
}

Полный список параметров шаблона приведен в следующей таблице:

Имя параметра Описание

Имя параметра	Описание
`identity.entity.id`	Идентификатор сущности
`identity.entity.name`	Имя сущности
`identity.entity.groups.ids`	Идентификаторы групп, членом которых является сущность
`identity.entity.groups.names`	Имена групп, членом которых является сущность
`identity.entity.metadata`	Метаданные, связанные с сущностью
`identity.entity.metadata.<metadata key>`	Метаданные, связанные с сущностью для указанного ключа
`identity.entity.aliases.<mount accessor>.id`	Идентификатор псевдонима сущности для указанного монтирования
`identity.entity.aliases.<mount accessor>.name`	Имя псевдонима сущности для указанного монтирования
`identity.entity.aliases.<mount accessor>.metadata`	Метаданные, связанные с псевдонимом для указанного монтирования
`identity.entity.aliases.<mount accessor>.metadata.<metadata key>`	Метаданные, связанные с псевдонимом для указанного монтирования и ключом метаданных
`identity.entity.aliases.<mount accessor>.custom_metadata`	Пользовательские метаданные, связанные с псевдонимом для указанного монтирования
`identity.entity.aliases.<mount accessor>.custom_metadata.<custom_metadata key>`	Пользовательские метаданные, связанные с псевдонимом для указанного монтирования и пользовательским ключом метаданных
`time.now`	Текущее время в виде интегральных секунд с начала Эпохи
`time.now.plus.<duration>`	Текущее время плюс строка формата длительности
`time.now.minus.<duration>`	Текущее время минус строка формата длительности

identity.entity.id

Идентификатор сущности

identity.entity.name

Имя сущности

identity.entity.groups.ids

Идентификаторы групп, членом которых является сущность

identity.entity.groups.names

Имена групп, членом которых является сущность

identity.entity.metadata

Метаданные, связанные с сущностью

identity.entity.metadata.<metadata key>

Метаданные, связанные с сущностью для указанного ключа

identity.entity.aliases.<mount accessor>.id

Идентификатор псевдонима сущности для указанного монтирования

identity.entity.aliases.<mount accessor>.name

Имя псевдонима сущности для указанного монтирования

identity.entity.aliases.<mount accessor>.metadata

Метаданные, связанные с псевдонимом для указанного монтирования

identity.entity.aliases.<mount accessor>.metadata.<metadata key>

Метаданные, связанные с псевдонимом для указанного монтирования и ключом метаданных

identity.entity.aliases.<mount accessor>.custom_metadata

Пользовательские метаданные, связанные с псевдонимом для указанного монтирования

identity.entity.aliases.<mount accessor>.custom_metadata.<custom_metadata key>

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

time.now

Текущее время в виде интегральных секунд с начала Эпохи

time.now.plus.<duration>

Текущее время плюс строка формата длительности

time.now.minus.<duration>

Текущее время минус строка формата длительности

Для отдельного провайдера может быть доступно несколько именованных диапазонов. Обратите внимание, что ключи верхнего уровня в шаблоне JSON могут конфликтовать с ключами другого диапазона. Когда диапазоны становятся доступными для провайдера, их шаблоны проверяются на наличие конфликтов верхнего уровня. При обнаружении конфликтов оператору StarVault будет выдано предупреждение. Это может привести к ошибке, если диапазоны запрашиваются в запросе аутентификации OIDC.

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

Ниже определено сопоставление ключей и значений формул для области openid:

iss — сконфигурированный эмитент провайдера
sub — уникальный идентификатор сущности пользователя хранилища
aud — идентификатор клиента
iat — время выпуска токена
exp — время выпуска токена + ID-токен TTL

1.3. Клиентские приложения

Ресурс клиента представляет приложение, которое делегирует аутентификацию конечного пользователя на StarVault с помощью протокола OIDC. Информация, предоставленная клиентским ресурсом, может быть использована для настройки доверенной стороны OIDC.

Клиент имеет следующие параметры конфигурации:

Перенаправление URIs: ограничивает допустимые URI перенаправления в запросе аутентификации
Задания: определяет, кто может аутентифицироваться на клиенте
Ключ: используется для подписи ID-токенов
ID токен TTL: определяет время жизни ID-токенов
Токен доступа TTL: определяет время жизни токенов доступа
Тип клиента: определяет способность клиента поддерживать конфиденциальность учетных данных

Параметр key опционален. Ключ будет использоваться для подписи ID-токенов клиента. Параметр не может быть изменен после создания. Если параметр не указан, по умолчанию используется встроенный ключ по умолчанию.

Параметр client_id генерируется и возвращается после успешной регистрации клиента. client_id уникально идентифицирует клиента. Значение client_id — строка с 32 случайными символами из набора символов base62.

Один из URI перенаправления клиента должен точно соответствовать параметру redirect_uri, используемому в запросе аутентификации, инициированном клиентом.

[[client-types] ==== Типы клиентов

Ресурс клиента имеет параметр client_type, который определяет тип клиента OAuth 2.0 в зависимости от способности сохранять конфиденциальность учетных данных. В следующих разделах подробно описаны различия между конфиденциальными и публичными клиентами в StarVault.

[[conf-clients] ==== Конфиденциальные клиенты

Конфиденциальные клиенты способны сохранять конфиденциальность своих учетных данных. У конфиденциальных клиентов есть секрет клиента (client_secret). client_secret имеет префикс hvo_secret, за которым следуют 64 случайных символа из набора символов base62.

Конфиденциальные клиенты могут использовать ключ доказательства для обмена кодами (PKCE) во время потока кода авторизации.

Конфиденциальные клиенты должны аутентифицироваться на конечной точке токена с помощью метода аутентификации client_secret_basic или client_secret_post.

[[pub-clients] ==== Публичные клиенты

Публичные клиенты не способны сохранять конфиденциальность своих учетных данных. Поэтому у публичных клиентов нет client_secret.

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

Публичные клиенты используют метод аутентификации none.

[[designations] === Назначения

Клиенты ссылаются на ресурсы назначений с помощью параметра assignments. Этот параметр ограничивает набор пользователей StarVault, которым разрешена аутентификация. Назначения связанного клиента проверяются во время запроса на аутентификацию, гарантируя, что идентификатор StarVault, связанный с запросом, является членом сущностей или групп назначения.

Каждое пространство имен StarVault содержит встроенный ресурс назначения с именем allow_all. Назначение allow_all позволяет всем сущностям StarVault проходить аутентификацию через клиента. Назначение allow_all не может быть изменено или удалено.

1.4. Ключи

Клиенты обращаются к ключевым ресурсам через параметр key. Этот параметр задает ключ, который будет использоваться для подписи ID-токенов клиента. В настоящее время ключ, на который ссылается клиент, не может быть изменен.

Каждое пространство имен StarVault будет содержать встроенный ключевой ресурс с именем default. Ключ по умолчанию может быть изменен, но не удален. Клиенты, не указавшие параметр ключа во время создания, будут использовать ключ по умолчанию.

Ключ по умолчанию (default) будет иметь следующую конфигурацию:

algorithm — RS256
allowed_client_ids — *
rotation_period — 24h
verification_ttl — 24h

2. Поток OIDC

В настоящее время функция StarVault OIDC Provider поддерживает только поток кодов авторизации.

В следующих разделах приведены подробности реализации OIDC-совместимых API, предоставляемых поставщиками StarVault OIDC.

Провайдеры StarVault OIDC позволяют зарегистрированным клиентам аутентифицировать и получать идентификационную информацию (или "утверждения") для своих конечных пользователей. Для этого провайдеры предоставляют API и поведение, необходимые для удовлетворения спецификации OIDC для потока кода авторизации. Все клиенты рассматриваются как первые лица. Это означает, что конечные пользователи не должны предоставлять провайдеру согласие, как указано в разделе 3.1.2.4 спецификации OIDC. Провайдер будет предоставлять информацию клиентам до тех пор, пока конечный пользователь имеет ACL-доступ к провайдеру и его личность была авторизована с помощью назначения.

Провайдеры StarVault OIDC внедряют ключ доказательства для обмена кодами (PKCE) для защиты от атак перехвата кода авторизации. PKCE требуется для публичных типов клиентов (public) и необязателен для конфиденциальных типов клиентов (confidential).

2.1. Конфигурация OpenID

Каждый провайдер предлагает неаутентифицированную конечную точку, которая облегчает обнаружение OIDC. Все необходимые метаданные, перечисленные в OpenID Provider Metadata, включены в документ обнаружения. Кроме того, включены рекомендуемые метаданные userinfo_endpoint и scopes_supported.

2.2. Ключи

Каждый провайдер предлагает неаутентифицированную конечную точку, которая предоставляет публичную часть ключей, используемых для подписания ID-токенов. Ключи публикуются в формате JSON Web Key Set (JWKS). Набор ключей для отдельного провайдера содержит ключи, на которые ссылаются все клиенты через параметр конфигурации allowed_client_ids. Заголовок Cache-Control устанавливается на основе ответов, позволяя клиентам обновлять свои ключи при ротации. Максимальный срок действия заголовка (max-age) устанавливается на основе самого раннего времени ротации любого из ключей в наборе ключей.

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

Каждый провайдер предлагает аутентифицированную конечную точку авторизации. Конечная точка авторизации для каждого провайдера добавляется в политику StarVault по умолчанию с помощью пути identity/oidc/provider/+/authorize. Конечная точка включает в себя все необходимые параметры запроса аутентификации в качестве входных данных.

Конечная точка проверяет клиентские запросы и убеждается, что все необходимые параметры присутствуют и действительны. redirect_uri запроса сверяется с redirect_uris клиента. Запрашивающая сущность StarVault проверяется на соответствие назначениям клиента (assignments). Для недействительных запросов возвращается соответствующий код ошибки.

При успешной проверке запроса генерируется код авторизации. Код авторизации — одноразовый и кэшируется со временем жизни около 5 минут, что снижает риск утечки. Ответ, содержащий исходное состояние state, представленное клиентом, и code, будет возвращен в пользовательский интерфейс StarVault, инициировавший запрос. StarVault выдаст HTTP 302 редирект на redirect_uri запроса, который включает code и state в качестве параметров запроса.

2.4. Конечная точка токенов

Каждый провайдер предлагает конечную точку токена. Конечная точка может быть неаутентифицированной в StarVault, но аутентифицируется с помощью запроса client_secret, как описано в разделе "Аутентификация клиента". Конечная точка получает все необходимые параметры запроса токена в качестве входных данных. Конечная точка проверяет клиентские запросы и обменивается кодом авторизации на ID-токен и токен доступа. Кэш кодов авторизации будет сверен с кодом, представленным в процессе обмена. Для всех недействительных запросов возвращаются соответствующие коды ошибок.

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

Также генерируется маркер доступа, который возвращается после успешной аутентификации клиента и проверки запроса. Токен доступа представляет собой пакетный токен StarVault с политикой, предоставляющей только доступ на чтение к конечной точке userinfo выдающего провайдера. Токен доступа также имеет TTL, определяемый access_token_ttl запрашивающего клиента.

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

Каждый провайдер предоставляет аутентифицированную конечную точку userinfo. Конечная точка принимает токен доступа, полученный от конечной точки token, в качестве маркера предъявителя. Ответ userinfo представляет собой объект JSON с типом содержимого application/json. Объект JSON содержит утверждения для сущности StarVault, связанной с маркером доступа. Возвращаемые утверждения определяются диапазонами, запрошенными в запросе аутентификации, в результате которого был получен маркер доступа. sub всегда возвращается как идентификатор сущности в ответе userinfo.