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

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

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

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

Управлять OIDC-приложениями может пользователь, которому назначена роль organization-manager.oauthApplications.admin или выше.

Необходимым компонентом OIDC-приложения является OAuth-клиент, который создается в указанном пользователем каталоге и неразрывно связан с OIDC-приложением. OAuth-клиент создается и удаляется автоматически — соответственно при создании и удалении OIDC-приложения.

Схема взаимодействия сторон по стандарту OIDCСхема взаимодействия сторон по стандарту OIDC

Обмен данными между сторонами по стандарту OIDC происходит в формате JSON.

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

1. На странице аутентификации внешнего приложения (поставщика услуг) пользователь Yandex Cloud выбирает аутентификацию с помощью единого входа.
2. Поставщик услуг направляет запрос аутентификации в Yandex Identity Hub (поставщик удостоверений) и перенаправляет пользователя на URL входа Yandex Identity Hub, указанный в поле Authorization endpoint.
3. Пользователь аутентифицируется в Yandex Identity Hub, используя свои учетные данные.
4. Если в Yandex Identity Hub существует OIDC-приложение, соответствующее данному внешнему приложению, аутентифицировавшийся пользователь добавлен в это OIDC-приложение, а полученный запрос аутентификации корректен, то Yandex Identity Hub направляет поставщику услуг код авторизации и перенаправляет пользователя обратно во внешнее приложение.
5. По адресу, заданному в поле Token endpoint, поставщик услуг запрашивает в Yandex Identity Hub ID-токен и токен доступа. В запросе указывается секрет приложения, по которому Yandex Identity Hub проверяет подлинность запроса.
6. Если переданный поставщиком услуг секрет действителен, Yandex Identity Hub направляет поставщику услуг ID-токен и токен доступа.
7. Поставщик услуг проверяет переданный ID-токен с помощью публичного ключа, получив его в Yandex Cloud по идентификатору, указанному в поле kid заголовка ID-токена. В случае успеха поставщик услуг предоставляет пользователю доступ к внешнему приложению.

Типы OIDC-приложений в Yandex Identity HubТипы OIDC-приложений в Yandex Identity Hub

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

• Web Application;
• Single-Page Application;
• Native Application.

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

Приложения Web ApplicationПриложения Web Application

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

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

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

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

Приложения Single-Page ApplicationПриложения Single-Page Application

OIDC-приложения типа Single-Page Application оптимально подходят для аутентификации пользователей во внешних приложениях, построенных по технологии SPA. Как правило, SPA-приложения — это приложения, построенные на JavaScript- или TypeScript-фреймворках (React, Vue, Angular и т.п.) и работающие в браузере.

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

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

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

Приложения Native ApplicationПриложения Native Application

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

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

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

В Redirect URI приложений Native Application допускаются любые корректные схемы URI.

Секрет OIDC-приложенияСекрет OIDC-приложения

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

Секрет может использоваться только в приложениях типа Web Application. В приложениях типов Single-Page Application и Native Application секрет приложения не используется.

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

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

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

Способы передачи секрета приложенияСпособы передачи секрета приложения

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

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

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

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

PKCEPKCE

PKCE (Proof Key for Code Exchange) — это расширение безопасности, применяемое в стандарте OAuth 2.0 с целью минимизировать риски перехвата аутентификационных данных.

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

Настройка на стороне поставщика удостоверений (Yandex Identity Hub)Настройка на стороне поставщика удостоверений (Yandex Identity Hub)

Для корректной работы интеграции на стороне Yandex Identity Hub в OIDC-приложении необходимо указать адрес (адреса) Redirect URI, выбрать набор атрибутов пользователя, которые будут передаваться поставщику услуг, а также сгенерировать секрет приложения. Прежде чем настраивать OIDC-приложение на стороне Yandex Identity Hub, получите адрес (адреса) Redirect URI у вашего поставщика услуг.

Redirect URIRedirect URI

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

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

Для работы с приложениями типа Native Application в Redirect URI допускаются любые корректные схемы URI.

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

Атрибуты пользователяАтрибуты пользователя

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

• openid (идентификатор пользователя) — идентификатор пользователя. Обязательный параметр.

• email (адрес электронной почты) — адрес электронной почты пользователя.

• profile (полное имя, имя, фамилия, аватар и др.) — дополнительная информация о пользователе.

• groups (группы пользователя в организации) — группы пользователей организации, участником которых является аутентифицирующийся пользователь. Возможные значения:

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

    Максимальное количество передаваемых групп — 1 000. Если количество групп, в которые входит пользователь, превышает это число, на сторону поставщика услуг будет передана только первая тысяча групп.

  • Только назначенные группы — из всех групп, в которые входит пользователь, поставщику услуг будут переданы только те группы, которые явно заданы на вкладке Пользователи и группы OIDC-приложения.

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

Настройка на стороне поставщика услуг (внешнее приложение)Настройка на стороне поставщика услуг (внешнее приложение)

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

URL с конфигурацией предоставляет поставщику услуг значения всех необходимых для настройки интеграции параметров и доступен в поле OpenID Configuration в блоке Конфигурация поставщика услуг (SP) на странице с информацией об OIDC-приложении в интерфейсе Cloud Center. На этой же странице доступны значения параметров интеграции для настройки вручную:

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

В дополнение к указанным выше параметрам при настройке интеграции с приложениями типа Web Application на стороне поставщика услуг также необходимо указать секрет приложения.

Полезные ссылкиПолезные ссылки

• Создать OIDC-приложение в Yandex Identity Hub
• Изменить OIDC-приложение в Yandex Identity Hub
• Деактивировать и удалить OIDC-приложение в Yandex Identity Hub
• Чеклист безопасности аутентификации и авторизации
• SAML-приложения