[Документация Yandex Cloud](../../../index.md) > [Yandex Identity Hub](../../index.md) > Концепции > [Приложения (SSO)](index.md) > OIDC-приложения

# OIDC-приложения


{% note warning %}

Функциональность доступна только в [регионе Россия](../../../overview/concepts/region.md).

{% endnote %}


В Yandex Identity Hub вы можете [создавать](../../operations/applications/oidc-create.md) OIDC-приложения, которые позволяют настроить единый вход по стандарту OpenID Connect (OIDC) на стороне Yandex Identity Hub, а также предоставляют необходимые значения для настройки интеграции на стороне поставщика услуг.

Доступ к внешнему приложению разрешен только тем пользователям организации Yandex Cloud, которые явно [добавлены](../../operations/applications/oidc-create.md#users-and-groups) в соответствующее OIDC-приложение или входят в [группы пользователей](../groups.md), явно добавленные в это OIDC-приложение.

{% note tip %}

Если вы хотите более тонко настроить аутентификацию пользователей в приложениях, в том числе разрешить аутентификацию только с определенных IP-адресов, используйте [политики аутентификации](*authentication_policies).

{% endnote %}

[*authentication_policies]: Политики аутентификации — это инструмент Yandex Identity Hub, позволяющий гибко настраивать доступ к приложениям, запрещая или разрешая аутентификацию определенным пользователям в определенных приложениях и/или с определенных IP-адресов. Подробнее читайте в разделе [Политики аутентификации в Yandex Identity Hub](../authentication-policy.md).

Управлять OIDC-приложениями может пользователь, которому назначена [роль](../../security/index.md#organization-manager-oauthApplications-admin) `organization-manager.oauthApplications.admin` или выше.

Необходимым компонентом OIDC-приложения является OAuth-клиент, который создается в указанном пользователем [каталоге](../../../resource-manager/concepts/resources-hierarchy.md#folder) и неразрывно связан с OIDC-приложением. OAuth-клиент создается и удаляется автоматически — соответственно при создании и удалении OIDC-приложения.

## Схема взаимодействия сторон по стандарту OIDC {#oidc-scheme}

Обмен данными между сторонами по стандарту OIDC происходит в формате [JSON](https://ru.wikipedia.org/wiki/JSON).

В базовом представлении аутентификация пользователя с использованием механизма единого входа по стандарту OpenID Connect происходит по следующей схеме:

```mermaid
sequenceDiagram
  autonumber
  actor U as Пользователь
  
  participant SP as Поставщик услуг (SP)
  participant IdP as Identity Hub (IdP)

  U ->> SP: Начало аутентификации
  SP ->> IdP: Отправка запроса в IdP и перенаправление пользователя на Authorization endpoint
  IdP ->> U: Запрос учетных данных
  U ->> IdP: Ввод учетных данных
  IdP ->> IdP: Проверка наличия OIDC-приложения,<br/>доступа пользователя и корректности запроса
  IdP ->> SP: Отправка кода авторизации и перенаправление пользователя в SP
  SP ->> IdP: Запрос ID- и access-токенов и передача секрета приложения
  IdP ->> IdP: Валидация секрета 
  IdP ->> SP: Передача ID- и access-токена
  SP ->> SP: Проверка ID-токена с помощью<br/>публичного ключа на стороне Yandex Cloud 
  SP ->> U: Успешная аутентификация
```

1. На странице аутентификации внешнего приложения (поставщика услуг) пользователь Yandex Cloud выбирает аутентификацию с помощью единого входа.
1. Поставщик услуг направляет запрос аутентификации в Yandex Identity Hub (поставщик удостоверений) и перенаправляет пользователя на URL входа Yandex Identity Hub, указанный в поле `Authorization endpoint`.
1. Пользователь аутентифицируется в Yandex Identity Hub, используя свои учетные данные.
1. Если в Yandex Identity Hub существует OIDC-приложение, соответствующее данному внешнему приложению, аутентифицировавшийся пользователь добавлен в это OIDC-приложение, а полученный запрос аутентификации корректен, то Yandex Identity Hub направляет поставщику услуг код авторизации и перенаправляет пользователя обратно во внешнее приложение.
1. По адресу, заданному в поле `Token endpoint`, поставщик услуг запрашивает в Yandex Identity Hub [ID-токен](../../../iam/concepts/authorization/id-token.md) и токен доступа. В запросе указывается [секрет приложения](#oidc-secret), по которому Yandex Identity Hub проверяет подлинность запроса.
1. Если переданный поставщиком услуг секрет действителен, Yandex Identity Hub направляет поставщику услуг ID-токен и токен доступа.
1. Поставщик услуг проверяет переданный ID-токен с помощью публичного ключа, [получив](https://kz.auth.yandex.cloud/oauth/jwks/keys) его в Yandex Cloud по идентификатору, указанному в поле `kid` заголовка ID-токена. В случае успеха поставщик услуг предоставляет пользователю доступ к внешнему приложению.

{% note info %}

На схеме представлено взаимодействие сторон при использовании OIDC-приложения типа [Web Application](#oidc-web). При использовании приложений типов [Single-Page Application](#oidc-single-page) и [Native Application](#oidc-native) из процесса взаимодействия исключаются запрос секрета приложения и его проверка.

{% endnote %}

## Типы OIDC-приложений в Yandex Identity Hub {#oidc-application-types}

OIDC-приложения в Yandex Identity Hub в зависимости от предустановленных настроек могут относиться к одному из следующих типов:

* [Web Application](#oidc-web);
* [Single-Page Application](#oidc-single-page);
* [Native Application](#oidc-native).

Тип приложения выбирается при его создании, изменить выбранный тип после создания приложения нельзя.

{% note info %}

В настоящее время создавать OIDC-приложения [типов](oidc.md#oidc-application-types) `Single-Page Application` и `Native Application`, а также управлять такими приложениями можно только в [интерфейсе Cloud Center](https://kz.center.yandex.cloud/organization).

{% endnote %}

### Приложения Web Application {#oidc-web}

OIDC-приложения типа `Web Application` оптимально подходят для аутентификации пользователей во внешних веб-приложениях, имеющих серверную часть (бэкенд), в которой может безопасно храниться [секрет приложения](#oidc-secret).

Приложения `Web Application` поддерживают использование секрета приложения: в зависимости от заданных настроек секрет может [передаваться](#secret-delivery) в HTTP-заголовке `Authorization: Basic` и/или в теле POST-запроса. По умолчанию в приложениях включена возможность передачи секрета всеми доступными способами.

Приложения `Web Application` по умолчанию требуют от поставщиков услуг применять расширение безопасности [PKCE](#pkce), при этом в настройках приложения можно отключить это требование.

[Redirect URI](#oidc-redirect-uri) приложений `Web Application` должен соответствовать схеме `https`. Использовать протокол без шифрования допускается только в целях тестирования на локальном хосте (значения `http://127.0.0.1` и `http://localhost`).

### Приложения Single-Page Application {#oidc-single-page}

OIDC-приложения типа `Single-Page Application` оптимально подходят для аутентификации пользователей во внешних приложениях, построенных по технологии [SPA](https://ru.wikipedia.org/wiki/Одностраничное_приложение). Как правило, SPA-приложения — это приложения, построенные на [JavaScript](https://ru.wikipedia.org/wiki/JavaScript)- или [TypeScript](https://www.typescriptlang.org/)-фреймворках ([React](https://react.dev/), [Vue](https://vuejs.org/), [Angular](https://angular.dev/) и т.п.) и работающие в браузере.

Приложения `Single-Page Application` не поддерживают использование секрета приложения.

Приложения `Single-Page Application` требуют от поставщиков услуг применять расширение безопасности [PKCE](#pkce), и отключить это требование в настройках приложения нельзя.

[Redirect URI](#oidc-redirect-uri) приложений `Single-Page Application` должен соответствовать схеме `https`. Использовать протокол без шифрования допускается только в целях тестирования на локальном хосте (значения `http://127.0.0.1` и `http://localhost`).

### Приложения Native Application {#oidc-native}

OIDC-приложения типа `Native Application` оптимально подходят для аутентификации пользователей во внешних мобильных или настольных приложениях, установленных на устройствах пользователей.

Приложения `Native Application` не поддерживают использование секрета приложения.

Приложения `Native Application` требуют от поставщиков услуг применять расширение безопасности [PKCE](#pkce), и отключить это требование в настройках приложения нельзя.

В [Redirect URI](#oidc-redirect-uri) приложений `Native Application` допускаются любые корректные схемы URI.

## Секрет OIDC-приложения {#oidc-secret}

_Секрет приложения_ генерируется пользователем на стороне OIDC-приложения в Yandex Identity Hub и представляет собой случайную строку определенной длины, начинающуюся с префикса `yccs__`.

Секрет может использоваться только в приложениях типа [Web Application](#oidc-web). В приложениях типов [Single-Page Application](#oidc-single-page) и [Native Application](#oidc-native) секрет приложения не используется.

Секрет приложения должен быть указан в настройках интеграции на стороне поставщика услуг и будет использоваться для проверки подлинности поступающих от поставщика услуг запросов.

Срок жизни секрета OIDC-приложения не ограничен. При этом вы в любой момент можете [сгенерировать](../../operations/applications/oidc-update.md#update-secret) в приложении любое количество новых секретов, а также удалить их.

{% note warning %}

После удаления секрета в OIDC-приложении не забудьте указать новый секрет в настройках интеграции на стороне поставщика услуг.

{% endnote %}

Секреты OIDC-приложений не сохраняются на стороне Yandex Cloud и отображаются пользователю только в момент создания. После обновления или закрытия страницы браузера, на которой был сгенерирован секрет, содержимое секрета становится недоступно.

### Способы передачи секрета приложения {#secret-delivery}

В процессе аутентификации пользователя передача секрета приложения от поставщика услуг поставщику удостоверений может осуществляться следующими способами:

* `Client secret basic` — секрет приложения передается в HTTP-заголовке `Authorization: Basic`;
* `Client secret post` — секрет приложения передается в теле POST-запроса.

В приложениях типа `Web Application` вы можете выбрать один или одновременно оба способа передачи секрета.

В приложениях `Single-Page Application` и `Native Application` секрет не используется, и настроить способ передачи секрета нельзя.

## PKCE {#pkce}

[PKCE](https://www.rfc-editor.org/info/rfc7636/) (_Proof Key for Code Exchange_) — это расширение безопасности, применяемое в стандарте [OAuth 2.0](https://www.rfc-editor.org/info/rfc6749/) с целью минимизировать риски перехвата аутентификационных данных.

По умолчанию OIDC-приложения всех [типов](#oidc-web) требуют от поставщика услуг использовать расширение PKCE (передавать `code_challenge` при запросе авторизации и `code_verifier` при обмене кода на токены). При этом для приложений [Web Application](#oidc-web) вы можете отключить это требование. Для приложений [Single-Page Application](#oidc-single-page) и [Native Application](#oidc-native) отключить требование использования PKCE нельзя.

## Настройка на стороне поставщика удостоверений (Yandex Identity Hub) {#oidc-idp-setup}

Для корректной работы интеграции на стороне Yandex Identity Hub в OIDC-приложении необходимо [указать](../../operations/applications/oidc-create.md#setup-idp) адрес (адреса) [Redirect URI](#oidc-redirect-uri), выбрать [набор атрибутов](#oidc-user-attributes) пользователя, которые будут передаваться поставщику услуг, а также сгенерировать [секрет приложения](#oidc-secret). Прежде чем настраивать OIDC-приложение на стороне Yandex Identity Hub, получите адрес (адреса) Redirect URI у вашего поставщика услуг.

### Redirect URI {#oidc-redirect-uri}

_Redirect URI_ — адрес на стороне внешнего приложения, куда пользователь будет перенаправляться в результате успешного прохождения аутентификации в Yandex Identity Hub.

Для работы с приложениями типов [Web Application](#oidc-web) и [Single-Page Application](#oidc-single-page) Redirect URI должен соответствовать схеме `https`. Использовать протокол без шифрования в приложениях этих типов допускается только в целях тестирования на локальном хосте (значения `http://127.0.0.1` и `http://localhost`).

Для работы с приложениями типа [Native Application](#oidc-native) в Redirect URI допускаются любые корректные схемы URI.

В OIDC-приложениях вы можете задать одновременно несколько адресов Redirect URI.

### Атрибуты пользователя {#oidc-attributes}

В настройках OIDC-приложения вы можете задать состав атрибутов пользователя, которые определяются выбранными в поле **Scopes** значениями и будут передаваться поставщику услуг в ID-токене:

* `openid (идентификатор пользователя)` — идентификатор пользователя. Обязательный параметр.
* `email (адрес электронной почты)` — адрес электронной почты пользователя.
* `profile (полное имя, имя, фамилия, аватар и др.)` — дополнительная информация о пользователе.
* `groups (группы пользователя в организации)` — [группы пользователей](../groups.md) организации, участником которых является аутентифицирующийся пользователь. Возможные значения:

    * `Все группы` — поставщику услуг будут переданы все группы, в которые входит пользователь.

        Максимальное количество передаваемых групп — 1&nbsp;000. Если количество групп, в которые входит пользователь, превышает это число, на сторону поставщика услуг будет передана только первая тысяча групп. 
    * `Только назначенные группы` — из всех групп, в которые входит пользователь, поставщику услуг будут переданы только те группы, которые явно заданы на вкладке **Пользователи и группы** OIDC-приложения.

В новом OIDC-приложении по умолчанию выбраны все атрибуты, за исключением `groups`.

## Настройка на стороне поставщика услуг (внешнее приложение) {#oidc-sp-setup}

Для корректной работы интеграции на стороне поставщика услуг также необходимо настроить ряд параметров интеграции. В зависимости от возможностей вашего поставщика услуг вы можете [выполнить эти настройки](../../operations/applications/oidc-create.md#setup-sp) как вручную, так и автоматически, указав URL с конфигурацией.

URL с конфигурацией предоставляет поставщику услуг значения всех необходимых для настройки интеграции параметров и доступен в поле **OpenID Configuration** в блоке **Конфигурация поставщика услуг (SP)** на странице с информацией об OIDC-приложении в [интерфейсе Cloud Center](https://kz.center.yandex.cloud/organization/apps). На этой же странице доступны значения параметров интеграции для настройки вручную:

* `ClientID` — уникальный идентификатор приложения.
* `Authorization endpoint` — адрес в Yandex Cloud, на который поставщик услуг будет перенаправлять пользователя для прохождения аутентификации.
* `Token endpoint` — адрес, на который от внешнего приложения поступает запрос на получение ID-токена и токена доступа.
* `Userinfo endpoint` — адрес, по которому внешнее приложение может получить атрибуты пользователя.

В дополнение к указанным выше параметрам при настройке интеграции с приложениями типа [Web Application](#oidc-web) на стороне поставщика услуг также необходимо указать [секрет приложения](#oidc-secret).

#### Полезные ссылки {#see-also}

* [Создать OIDC-приложение в Yandex Identity Hub](../../operations/applications/oidc-create.md)
* [Изменить OIDC-приложение в Yandex Identity Hub](../../operations/applications/oidc-update.md)
* [Деактивировать и удалить OIDC-приложение в Yandex Identity Hub](../../operations/applications/oidc-deactivate-remove.md)
* [Чеклист безопасности аутентификации и авторизации](../../../security/domains/iam-checklist.md)
* [SAML-приложения](saml.md)