Обзор OIDC

ℹ️ О документе

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

Что такое OpenID Connect

OpenID Connect (OIDC) — это современный протокол аутентификации, построенный на основе OAuth 2.0. Он позволяет приложениям безопасно получать информацию о пользователе от IDENTYX без необходимости хранить пароли пользователей.

OIDC решает две основные задачи:

Аутентификация — подтверждение личности пользователя
Авторизация — предоставление приложению доступа к информации о пользователе

Зачем нужен OIDC

Использование OIDC в IDENTYX обеспечивает следующие преимущества:

🔐 Единый вход (SSO)

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

🛡️ Безопасность

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

🎯 Централизованное управление

Все управление пользователями, группами и правами доступа выполняется в одном месте — в системе IDENTYX.

⚙️ Простота интеграции

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

Как работает OIDC в IDENTYX

Процесс аутентификации через OIDC включает следующие шаги:

Пользователь открывает приложение
Пользователь пытается получить доступ к защищенному приложению, зарегистрированному в IDENTYX.
Перенаправление на IDENTYX
Приложение перенаправляет пользователя на страницу входа IDENTYX с параметрами запроса (client_id, redirect_uri, scope).
Аутентификация пользователя
Пользователь вводит свои учетные данные на странице входа IDENTYX. Если пользователь уже аутентифицирован в другом приложении, этот шаг может быть пропущен (Single Sign-On).
Согласие пользователя (опционально)
Если для приложения настроено требование согласия с офертой, пользователю отображается текст условий использования, которые необходимо принять.
Генерация кода авторизации
IDENTYX создает одноразовый код авторизации и перенаправляет пользователя обратно в приложение с этим кодом в параметрах URL.
Обмен кода на токены
Приложение отправляет код авторизации обратно в IDENTYX вместе с client_secret и получает в ответ набор токенов:
- Access Token — для доступа к защищенным ресурсам
- ID Token — с информацией о пользователе в формате JWT
- Refresh Token — для обновления токенов после истечения срока действия
Доступ к приложению
Приложение получает информацию о пользователе из токенов и предоставляет ему доступ.

ℹ️ Authorization Code Flow

IDENTYX использует поток Authorization Code Flow — наиболее безопасный вариант OIDC, рекомендованный для серверных приложений. В этом потоке чувствительные данные (client_secret, токены) никогда не передаются через браузер пользователя.

Токены в OIDC

IDENTYX выдает приложениям три типа токенов:

Access Token

Access Token — это временный токен, который приложение использует для доступа к защищенным эндпоинтам IDENTYX, таким как получение информации о пользователе (UserInfo endpoint).

Формат: случайная строка длиной 32 символа
Срок действия: настраивается в параметрах системы (по умолчанию 3600 секунд = 1 час)
Использование: передается в заголовке Authorization: Bearer <access_token>

Refresh Token

Refresh Token — это долгосрочный токен, используемый для получения нового Access Token после истечения срока действия старого.

Формат: случайная строка длиной 32 символа
Срок действия: настраивается в параметрах системы (по умолчанию 86400 секунд = 24 часа)
Использование: отправляется в запросе обновления токенов вместе с client_id и client_secret

⚠️ Безопасность

Refresh Token является конфиденциальным и должен храниться в безопасном месте на сервере приложения. Никогда не передавайте его в браузер или клиентские приложения.

ID Token

ID Token — это JWT (JSON Web Token), содержащий информацию о пользователе и параметрах аутентификации.

Формат: JWT (JSON Web Token) с подписью HMAC SHA-512
Алгоритм подписи: HS512
Ключ подписи: client_secret приложения

ID Token содержит следующие стандартные поля (claims):

Поле	Описание
`iss`	Издатель токена (URL IDENTYX)
`sub`	Идентификатор пользователя (subject ID)
`aud`	Аудитория — client_id приложения
`exp`	Время истечения токена (Unix timestamp)
`iat`	Время выдачи токена (Unix timestamp)
`auth_time`	Время аутентификации пользователя
`nonce`	Случайное значение для защиты от replay-атак
`sid`	Идентификатор OIDC сессии

В зависимости от запрошенных scopes, ID Token может также содержать дополнительные поля с данными пользователя.

Scopes (области доступа)

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

IDENTYX поддерживает следующие scopes:

openid

Обязательный scope. Указывает, что используется протокол OpenID Connect (а не просто OAuth 2.0).

При наличии этого scope в ID Token всегда включается:

sub — идентификатор пользователя

profile

Запрашивает доступ к базовой информации профиля пользователя.

При наличии этого scope в ID Token и UserInfo добавляются:

name — отображаемое имя пользователя
phone — номер телефона (если указан)
phone_verified — статус проверки телефона (всегда false)

email

Запрашивает доступ к адресу электронной почты пользователя.

При наличии этого scope в ID Token и UserInfo добавляются:

email — адрес электронной почты пользователя
email_verified — статус проверки email (всегда false)

permissions

Специальный scope IDENTYX. Запрашивает права доступа пользователя в системе RBAC.

При наличии этого scope в ID Token и UserInfo добавляется:

permissions — массив прав доступа пользователя, относящихся к данному приложению, в формате ["объект:действие", ...]

Приложение может использовать эти права для контроля доступа к своим функциям на основе централизованной системы прав IDENTYX.

✅ Пример использования

Если пользователь имеет право /myapp/reports:view, приложение может показать ему раздел с отчетами. Если права нет — скрыть этот раздел или показать сообщение об ограниченном доступе.

UserInfo Endpoint

UserInfo Endpoint — это специальный API эндпоинт, который приложение может вызвать для получения актуальной информации о пользователе.

URL: /api/service/oidc/userinfo

Метод: GET или POST

Аутентификация: Access Token в заголовке Authorization: Bearer <access_token>

Ответ: JSON с теми же полями, что и в ID Token (в зависимости от запрошенных scopes)

Преимущества UserInfo Endpoint:

Позволяет получить обновленные данные пользователя (например, если изменилось отображаемое имя)
Можно использовать вместо парсинга ID Token
Актуальные права доступа на момент запроса (для scope permissions)

Backchannel Logout

Backchannel Logout — это механизм, позволяющий IDENTYX уведомить приложение о завершении сессии пользователя.

Когда пользователь выходит из системы в IDENTYX или его сессия принудительно завершается администратором, IDENTYX отправляет всем активным приложениям специальный logout токен (JWT) с информацией о завершенной сессии.

Приложение получает уведомление на свой эндпоинт /backchannel-logout и должно:

Проверить подпись logout токена
Извлечь идентификатор сессии (sid)
Завершить соответствующую локальную сессию пользователя

ℹ️ Автоматическая реализация

Если вы используете IDENTYX Proxy для интеграции приложения, механизм Backchannel Logout реализуется автоматически, и вам не нужно его программировать.

OIDC Discovery (конфигурация)

IDENTYX предоставляет стандартный эндпоинт OIDC Discovery, содержащий всю необходимую информацию о конфигурации OIDC провайдера.

URL: /.well-known/openid-configuration

Этот эндпоинт возвращает JSON с информацией о:

Издателе (issuer)
Эндпоинтах авторизации, токенов, UserInfo
Поддерживаемых scopes и claims
Поддерживаемых методах аутентификации
Алгоритмах подписи токенов

Многие OIDC библиотеки могут автоматически загрузить эту конфигурацию и настроиться на работу с IDENTYX.

Управление сессиями

Для каждого OIDC приложения можно настроить ограничения на количество одновременных сессий пользователя:

Лимит сессий — максимальное количество активных сессий одного пользователя в приложении
Автоматическое закрытие старых сессий — при превышении лимита самые старые сессии автоматически завершаются

Это полезно для предотвращения передачи учетных данных между пользователями и повышения безопасности.

Безопасность OIDC

IDENTYX обеспечивает высокий уровень безопасности OIDC интеграции:

🔐 Защита client_secret

Client Secret должен храниться только на сервере приложения и никогда не передаваться в браузер пользователя.

🔒 Проверка redirect_uri

IDENTYX проверяет, что URL перенаправления соответствует списку разрешенных URL, настроенных для приложения.

⏱️ Ограниченный срок действия

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

✅ Подпись токенов

ID Token и logout токены подписываются HMAC SHA-512, что позволяет приложению проверить их подлинность.

Сценарии использования

OIDC в IDENTYX подходит для различных сценариев интеграции:

Веб-приложения

Классический вариант — серверное веб-приложение, которое выполняет все операции OIDC на backend и никогда не раскрывает client_secret в браузере.

Single Page Applications (SPA)

Для SPA рекомендуется использовать IDENTYX Proxy, который берет на себя всю работу с OIDC и передает данные пользователя в приложение через заголовки HTTP.

Мобильные приложения

Мобильные приложения могут использовать OIDC с Authorization Code Flow + PKCE (Proof Key for Code Exchange) для дополнительной защиты.

API и микросервисы

API могут проверять Access Token и получать информацию о пользователе через UserInfo Endpoint для авторизации запросов.

✅ Готовы продолжить?

Переходите к разделу Создание OIDC приложения для изучения процесса регистрации и настройки приложений в IDENTYX.