Настройка SSO в Azure AD через OpenID Connect

Логотип Microsoft Azure

О чём эта статья

Краткое объяснение, что такое OpenID Connect и чем он отличается от SAML.
Пошаговая инструкция: как добавить приложение OpenID в Azure AD.
Разбор простого потока аутентификации (authorization code flow), что такое id_token и refresh_token.
Как работает фреймворк согласий (consent) и где настраивать права доступа к API.
Практические рекомендации, чек-листы, варианты отказа и план отката.

Основные термины в одну строку

OIDC: протокол аутентификации поверх OAuth 2.0, возвращает id_token.
OAuth 2.0: фреймворк авторизации, предоставляет токены доступа.
id_token: JWT с утверждениями (claims) о пользователе.
refresh_token: токен для получения новых access/id токенов без повторного входа.

Почему стоит выбрать OpenID Connect

Лучше работает на мобильных устройствах и SPA.
Разработчикам проще интегрировать — много готовых библиотек.
Удобен для внешних подрядчиков и клиентов (B2B/B2C).
Поддерживается основными IdP: Azure AD, Google, Okta, Auth0 и др.
Может сосуществовать с SAML — гибкость архитектуры.

Важно: OIDC фокусируется на аутентификации (кто пользователь), OAuth — на авторизации (к чему доступ).

Когда OIDC не лучший выбор

Если ваша организация полностью ориентирована на устаревшую инфраструктуру, где уже развернуты только SAML-провайдеры.
Если вам нужны очень специфичные SAML-функции (например, SOAP-базированные коннекторы старых решений).
Для чисто однократной серверной интеграции, где уже наработан и отлажен SAML — миграция может быть затратной.

1. Как добавить приложение OpenID в Azure AD

Ниже — расширенная пошаговая инструкция с пояснениями и советами по безопасности.

Войдите в Azure Portal и откройте Azure Active Directory.
В меню слева выберите Enterprise applications или App registrations в зависимости от сценария:
- Enterprise applications — для управления доступом и назначений в каталоге (готовые SaaS-приложения).
- App registrations — для регистрации собственных приложений (web, SPA, native, API).
Для регистрации нового приложения нажмите New application (Enterprise applications) или New registration (App registrations).
- Если кнопка “Add” для готовых OpenID/OAuth-приложений не активна — администратор арендатора должен разрешить установку третьих сторон или выполнить Sign up/Consent.

Экран регистрации нового приложения в Azure

В App registrations задайте имя приложения, выберите Supported account types:
- Single tenant — только пользователи вашей организации.
- Multitenant — пользователи других арендаторов Azure AD могут входить (потребует дополнительного управления согласиями).
- Accounts in any identity provider (e.g., Microsoft accounts) — для смешанных сценариев.
Укажите Redirect URI (URI перенаправления). Для web-приложения это обычно https://yourapp.example.com/signin-oidc. Для SPA — https://yourapp.example.com.
Сохраните регистрацию. После регистрации вы получите Application (client) ID и Directory (tenant) ID.

Ключ безопасности: не храните client secret в публичных репозиториях. Для серверных приложений используйте секреты или сертификаты; для SPA и мобильных приложений — PKCE.

2. Настройка аутентификационного потока (Authorization Code Flow)

Ниже описан стандартный сценарий с обменом кода на токены (recommended flow для серверных приложений).

Основные шаги в терминах протокола:

Клиент перенаправляет пользователя на точку авторизации Azure AD: /oauth2/authorize или /oauth2/v2.0/authorize с параметрами response_type=code, client_id, redirect_uri, scope и state.
Пользователь вводит учётные данные и подтверждает права (consent), если требуется.
Azure AD возвращает authorization_code в параметре запроса к redirect_uri.
Клиент (с сервера) посылает POST на token endpoint (/oauth2/token или /oauth2/v2.0/token) с authorization_code, client_id и client_secret (или с PKCE verifier для публичных клиентов).
Сервер получает в ответ access_token, id_token и, при наличии, refresh_token.
id_token — JWT, содержит claims: sub, aud, iss, exp, iat, name, email и т.д.
Сервер проверяет подпись и валидность id_token, устанавливает сессионную куку или другой механизм сессии.
Для вызова защищённых Web API клиент использует access_token в заголовке Authorization: Bearer .
При истечении access_token клиент может обменять refresh_token на новый набор токенов.

Примечания:

Используйте HTTPS для всех redirect_uri и token endpoint.
Для SPA и мобильных приложений используйте Authorization Code Flow с PKCE (Proof Key for Code Exchange).
В Azure AD есть версии V1 и V2 endpoints; V2 даёт гибкие скопы (например, offline_access для refresh_token, openid для получения id_token).

3. Разрешения API и фреймворк согласий

Фреймворк согласий управляет тем, какие права приложение может получить от имени пользователя или как приложение в целом.

Типы разрешений:

Delegated permissions — приложение действует от имени вошедшего пользователя. Требует, чтобы пользователь был аутентифицирован.
Application permissions — приложение действует автономно (daemon/service), доступ к данным не зависит от конкретного пользователя; требует администраторского согласия.

Как добавить разрешения:

В App registrations откройте приложение и перейдите в API permissions.
Нажмите Add a permission и выберите Microsoft Graph или собственный API.
Выберите Delegated или Application permissions, отметьте нужные скопы, затем Grant admin consent при необходимости.

Путь доступа к разрешениям API в App Registrations

Опыт пользователя при первом входе:

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

Экран согласия с правами доступа

Важно: для мультитенантных приложений администратор каждого арендатора должен дать согласие, если это требуется политикой.

4. Безопасность и рекомендуемые практики

Всегда проверяйте подпись и claims id_token (iss, aud, exp, nonce).
Используйте PKCE для публичных клиентов (SPA, мобильные).
Храните client secrets и сертификаты в безопасном хранилище (Key Vault).
Ограни́чьте redirect_uri по точному совпадению (не используйте wildcard).
Включите мониторинг и логирование входов (Audit logs, Sign-ins в Azure AD).
Минимизируйте необходимые sc ope’ы (принцип наименьших привилегий).

5. Развёртывание: чек-лист для продакшна

Роль: инженер платформы

Зарегистрировано приложение в App registrations.
Redirect URI настроены и проверены.
Client ID и секреты в Key Vault.
PKCE включён для публичных клиентов.
Необходимые API permissions добавлены и подтверждены.
Администраторский consent выполнен для мультитенантных сценариев.
Логи входов и оповещения настроены.

Роль: Dev

Библиотека OIDC корректно настроена (например MSAL).
Валидация токенов реализована.
Обработка ошибок и сценариев отказа реализована.
Тесты на истечение токенов и обновление через refresh_token добавлены.

6. Когда интеграция может провалиться — типичные причины и решения

Неправильный Redirect URI — решение: сверить и задать точное совпадение.
Отсутствует consent для запрошенных sc ope’ов — решение: запросите администраторский consent или уменьшите sc ope’ы.
Неправильно проверяется audience (aud) — решение: убедитесь, что aud совпадает с client_id.
Использование implicit flow для SPA (устаревший) — решение: переход на Authorization Code Flow с PKCE.
Токены не принимаются Web API — решение: проверьте, какой тип токена ожидает API (v1/v2, scope/audience).

7. Альтернативы и комбинации

SAML 2.0 — хорош для традиционных корпоративных приложений; широко используется в больших организациях.
OAuth 2.0 без OIDC — подходит, если нужно только авторизация (доступ к ресурсам), но не требуется информация о пользователе.
Комбинация SAML для сотрудников и OIDC для внешних интеграций — гибридный подход, часто применяемый.

8. Модель принятия решений (простая схема)

Mermaid диаграмма ниже помогает выбрать между SAML и OIDC:

flowchart TD
  A[Начало: нужно SSO?] --> B{Целевая аудитория}
  B -->|Сотрудники в корпоративном каталоге| C[SAML или OIDC]
  B -->|Внешние клиенты/мобильные| D[OIDC]
  C --> E{Наличие старой инфраструктуры}
  E -->|Да| F[SAML]
  E -->|Нет| D
  D --> G[Используйте Authorization Code Flow с PKCE]
  F --> H[Используйте SAML 2.0]

9. План отката и ругулярные проверки (runbook)

Сценарий: после релиза пользователи не могут входить.

Проверить Sign-in logs в Azure AD.
Проверить recent changes: обновление redirect_uri, смена client secret, изменения permission.
Вернуть прежний client secret из резервной копии (Key Vault versioning).
Откатить конфигурацию в App registrations к проверенной версии.
Если проблема в consent — откатить запросы sc ope’ов и вернуть минимальные права.

10. Тестовые случаи и критерии приёмки

Пользователь из каталога успешно проходит SSO и получает id_token (проверка: валидный JWT).
Приложение получает access_token и вызывает защищённый API с кодом возврата 200.
Refresh_token корректно обновляет access_token после истечения.
Попытка входа с неподдерживаемого типа учётной записи отклоняется безопасно.

Критерии приёмки:

Успешный энд-ту-энд сценарий авторизации в тестовой среде.
Автоматические тесты токенов проходят.
Логи входов отображают успешные и неуспешные попытки для аудита.

11. Риски и способы смягчения

Утечка client secrets — хранить в Key Vault и ограничить доступ.
Избыточные права — проводить ревью разрешений и минимизировать sc ope’ы.
Неправильная конфигурация redirect_uri — использовать строгую валидацию и тесты.

12. Короткий SOP для регистрации нового приложения

Зарегистрировать приложение (App registrations).
Настроить redirect_uri и платформу.
Добавить API permissions и запросить admin consent.
Сгенерировать client secret или загрузить сертификат.
Конфигурировать приложение: client_id, tenant_id, endpoints.
Запустить тестовый вход и проверить id_token, access_token, refresh_token.

13. Глоссарий (одной строкой)

Redirect URI: адрес, на который Identity Provider перенаправляет после входа.
Client secret: секрет приложения для аутентификации при обмене кода на токен.
PKCE: защита для публичных клиентов, предотвращающая подмену кода.

14. Советы по локализации и доступности для регионов

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

Заключение

OpenID Connect в Azure AD — практичное решение для реализации SSO, особенно в гибридных и облачных сценариях. OIDC хорошо подходит для современных веб- и мобильных приложений, обеспечивает удобство пользователю и управляемость администратору. При правильной настройке — проверки redirect URI, хранения секретов и контроля разрешений — вы получите безопасную и масштабируемую аутентификационную систему.

Ключевые шаги для старта: зарегистрировать приложение, настроить redirect_uri, добавить права доступа, протестировать authorization code flow и настроить мониторинг. При мультитенантных сценариях заранее подготовьте процесс администраторского consent и план отката.

Важно: чтение официальной документации Azure AD поможет уточнить детали конкретных сценариев и версий endpoint’ов.