Поток кода авторизации OAuth 2.0 в Azure Active Directory B2C
Код авторизации OAuth 2.0 может использоваться в приложениях, установленных на устройстве, для получения доступа к защищенным ресурсам, таким как веб-API. С помощью реализации OAuth 2.0 в Azure Active Directory B2C (Azure AD B2C) можно добавить регистрацию, вход и другие задачи по управлению удостоверениями в одностраничное, мобильное приложение, а также приложение для настольных систем. Эта статья не зависит от языка. В ней описывается, как отправлять и получать сообщения HTTP, не используя ни одну из библиотек с открытым исходным кодом. По возможности рекомендуется использовать поддерживаемые библиотеки проверки подлинности Майкрософт (MSAL). Ознакомьтесь с примерами приложений, которые используют MSAL.
Описание потока кода авторизации OAuth 2.0 см. в разделе 4.1 спецификации OAuth 2.0. Его можно использовать для проверки подлинности и авторизации в большинстве типов приложений, в том числе в веб-приложениях, одностраничных приложениях и изначально установленных приложениях. Вы можете использовать поток кода авторизации OAuth 2.0, чтобы безопасно получать маркеры доступа и маркеры обновления для приложений, с помощью которых можно получить доступ к ресурсам, защищенным сервером авторизации. Маркер обновления позволяет клиенту получать новые маркеры доступа (и обновления) после истечения их срока действия (как правило, через час).
В этой статье мы сосредоточимся на потоке кода авторизации OAuth 2.0 для открытых клиентов. Открытый клиент — это любое клиентское приложение, которому нельзя доверять в безопасном сохранении целостности секретного пароля. К ним относятся одностраничные приложения, мобильные приложения, приложения для настольных систем и практически любое приложения, которое выполняется не на сервере.
Примечание
Чтобы добавить управление идентификацией в веб-приложение с помощью Azure AD B2C, используйте OpenID Connect, а не OAuth 2.0.
В Azure AD B2C стандартные потоки OAuth 2.0 выходят за рамки простой проверки подлинности и авторизации. Теперь в службе появился поток пользователя. Потоки пользователей дают возможность использовать OAuth 2.0 для добавления в приложение различных действий пользователя, таких как регистрация, вход и управление профилями. Поставщики удостоверений, использующие протокол OAuth 2.0, включают Amazon, Microsoft Entra ID, Facebook, GitHub, Google и LinkedIn.
Чтобы попробовать HTTP-запросы, описанные в этой статье:
- Замените
{tenant}именем вашего клиента Azure AD B2C. - Замените
90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6идентификатором приложения, которое вы ранее зарегистрировали в своем клиенте Azure AD B2C. - Замените
{policy}именем политики, созданной в клиенте, напримерb2c_1_sign_in.
Для одностраничных приложений требуется настройка URI перенаправления
Поток кода авторизации для одностраничных приложений требует некоторой дополнительной настройки. Следуйте инструкциям по созданию одностраничного приложения, чтобы правильно пометить URI перенаправления, как включенный для CORS. Чтобы обновить существующий URI перенаправления для включения CORS, можно щелкнуть запрос миграции в разделе "Веб" на вкладке Проверка подлинности регистрацииприложения. Кроме того, можно открыть Редактор манифеста регистрации приложения и настроить поле type для вашего URI перенаправления spa в разделе replyUrlsWithType.
spaТип перенаправления обратно совместим с неявным потоком. Приложения, в настоящее время использующие неявный поток для получения токенов, могут переноситься в spa тип URI перенаправления без проблем и продолжать использовать неявный поток.
1.Получение кода авторизации
Поток кода авторизации начинается с того, что клиент направляет пользователя к конечной точке /authorize . Это интерактивная часть потока, в которой пользователь выполняет действие. В этом запросе клиент указывает в параметре scope разрешения, которые ему требуется получить от пользователя. В следующих примерах (с разрывами строк для удобочитаемости) показано, как получить код авторизации. Если вы тестируете этот HTTP-запрос GET, используйте браузер.
GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&response_type=code
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&response_mode=query
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6%20offline_access%20https://{tenant-name}/{app-id-uri}/{scope}
&state=arbitrary_data_you_can_receive_in_the_response
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Параметр | Необходим? | Описание |
|---|---|---|
| {tenant} | Обязательно | Имя клиента Azure AD B2C |
| {policy} | Обязательно | Пользовательский процесс для выполнения. Укажите имя пользовательского процесса, созданного в клиенте Azure AD B2C. Например, b2c_1_sign_in, b2c_1_sign_upили b2c_1_edit_profile. |
| client_id | Обязательно | Идентификатор приложения, назначенный вашему приложению на портале Azure. |
| response_type | Обязательно | Тип ответа, который должен содержать code для потока кода авторизации. Маркер идентификатора можно получить, если включить его в тип ответа, например code+id_token, и в этом случае область должна включать openid. |
| redirect_uri | Обязательно | URI перенаправления приложения, на который можно отправлять ответы проверки подлинности для их получения приложением. Он должен в точности соответствовать одному из URI перенаправления, зарегистрированных на портале, но иметь форму закодированного URL-адреса. |
| область | Обязательно | Список областей с разделителями-пробелами. Область openid определяет разрешение на вход пользователя и получение данных о пользователе в форме маркеров идентификации. Область offline_access для веб-приложений является необязательной. Это означает, что приложению потребуется маркер обновления для продолжительного доступа к ресурсам. Идентификатор клиента указывает, что выданный маркер предназначен для использования зарегистрированным клиентом Azure AD B2C. Область https://{tenant-name}/{app-id-uri}/{scope} определяет разрешение для защищенных ресурсов, таких как веб-API. Дополнительные сведения см. в статье Запрос маркера доступа. |
| response_mode | Рекомендуемая | Метод, используемый для отправки полученного кода авторизации приложению. Он может иметь значение query, form_post или fragment. |
| Состояние | Рекомендуемая | Значение, включенное в запрос, может содержать строку или любое содержимое на ваше усмотрение. Как правило, с целью предотвращения подделки межсайтовых запросов используется генерируемое случайным образом уникальное значение. Этот параметр также включает информацию о состоянии пользователя в приложении перед созданием запроса на проверку подлинности. Например, об открытой пользователем в тот момент странице или выполняемом потоке пользователя. |
| prompt | Необязательно | Требуемый тип взаимодействия с пользователем. Сейчас единственное допустимое значение — это login, при котором пользователю приходится вводить учетные данные по запросу. Единый вход не сработает. |
| code_challenge | рекомендованный/обязательный | Используется, чтобы защитить разрешения кода авторизации с помощью ключа проверки для обмена кодом (PKCE). Является обязательным, если указан параметр code_challenge_method. Необходимо добавить логику в приложение для создания code_verifier и code_challenge. code_challenge — это хэш SHA256 URL-адреса в кодировке Base64 для code_verifier. code_verifier хранится в приложении для последующего использования, code_challenge отправляется вместе с запросом авторизации. Дополнительные сведения см. в описании PKCE RFC. Теперь это рекомендуется для всех типов приложений — собственных приложений, одностраничных приложений и конфиденциальных клиентов, таких как веб-приложения. |
code_challenge_method |
рекомендованный/обязательный | Метод, используемый для кодирования code_verifier в параметре code_challenge. Это ДОЛЖНО быть S256, но спецификация позволяет использовать plain, если по какой-либо причине клиент не поддерживает SHA256. Если параметр code_challenge_method исключен, но для параметра code_challenge задано значение, предполагается, что для code_challenge принимается формат обычного текста. Платформа удостоверений Майкрософт поддерживает как plain, так и S256. Дополнительные сведения см. в описании PKCE RFC. Это необходимо для одностраничных приложений, использующих поток кода авторизации. |
| login_hint | Нет | Можно использовать для предварительной заливки поля имени входа на странице входа. Дополнительные сведения см. в разделе Предварительное заполнение имени для входа. |
| domain_hint | Нет | Предоставляет подсказку для Azure AD B2C о поставщике удостоверений в социальных сетях, который должен использоваться для входа в систему. Если включено допустимое значение, пользователь переходит непосредственно на страницу входа поставщика удостоверений. Дополнительные сведения см. в статье Перенаправление входа в поставщика социальных сетей. |
| Настраиваемые параметры | Нет | Пользовательские параметры, которые можно использовать с пользовательскими политиками. Например, URL-адрес динамического содержимого пользовательской страницы или сопоставитель утверждений "ключ — значение". |
На этом этапе пользователю предлагается выполнить рабочий процесс потока пользователя. Для этого могут потребоваться ввод имени пользователя и пароля, вход с помощью удостоверения социальной сети, регистрация в каталоге или любые другие шаги. Действия пользователя зависят от того, как определен его поток.
После того как пользователь завершит поток пользователя, идентификатор Microsoft Entra возвращает вашему приложению ответ со значением, которое вы использовали для redirect_uri. Она использует метод, указанный в параметре response_mode. Какие бы действия пользователь ни выполнял и каким бы ни был его поток, ответ всегда будет одинаковым.
Успешный ответ с использованием метода response_mode=query выглядит следующим образом:
GET urn:ietf:wg:oauth:2.0:oob?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq... // the authorization_code, truncated
&state=arbitrary_data_you_can_receive_in_the_response // the value provided in the request
| Параметр | Описание |
|---|---|
| code | Запрашиваемый приложением код авторизации. Приложение может использовать код авторизации для запроса маркера доступа для целевого ресурса. Срок действия кодов авторизации крайне мал. и обычно истекает по прошествии порядка 10 минут. |
| Состояние | Полное описание см. в таблице выше. Если в запрос включен параметр state, идентичное значение должно содержаться и в ответе на этот запрос. Приложение должно проверить, совпадают ли значения параметра state в запросе и ответе. |
Сообщения об ошибках также можно отправлять на универсальный код ресурса (URI) перенаправления, чтобы приложение могло их правильно обработать:
GET urn:ietf:wg:oauth:2.0:oob?
error=access_denied
&error_description=The+user+has+cancelled+entering+self-asserted+information
&state=arbitrary_data_you_can_receive_in_the_response
| Параметр | Описание |
|---|---|
| error | Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на них. |
| error_description | Конкретное сообщение об ошибке, с помощью которого можно определить первопричину возникновения ошибки аутентификации. |
| Состояние | См. полное описание в предыдущей таблице. Если в запрос включен параметр state, идентичное значение должно содержаться и в ответе на этот запрос. Приложение должно проверить, совпадают ли значения параметра state в запросе и ответе. |
2. Получение маркера доступа
После получения кода авторизации можно использовать code, чтобы получить маркер для целевого ресурса путем отправки запроса POST на конечную точку /token. В Azure AD B2C можно запросить маркеры доступа для других API обычным образом, указав их область (-и) в запросе.
Вы также можете запросить маркер доступа для собственного серверного веб-API в соответствии с соглашением об использовании идентификатора клиента приложения в качестве запрошенной области (в результате маркер доступа будет содержать идентификатор клиента в качестве "аудитории"):
POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
| Параметр | Необходим? | Описание |
|---|---|---|
| {tenant} | Обязательно | Имя клиента Azure AD B2C |
| {policy} | Обязательно | Поток пользователя, который использовался для получения кода авторизации. Другой поток пользователя в этом запросе использовать нельзя. |
| client_id | Обязательно | Идентификатор приложения, назначенный вашему приложению на портале Azure. |
| client_secret | Да, в веб-приложениях | Секрет приложения, созданный на портале Azure. Секреты клиента используются в этом потоке для сценариев веб-приложений, где клиент может безопасно хранить секрет клиента. Для сценариев собственного приложения (общедоступного клиента) секреты клиента не могут быть безопасно сохранены, поэтому они не используются в этом вызове. При использовании секрета клиента следует периодически менять его. |
| grant_type | Обязательно | Тип предоставления. Для потока кода авторизации это должен быть тип authorization_code. |
| область | Рекомендуемая | Список областей с разделителями-пробелами. Одно значение область указывает, Microsoft Entra идентификатор обоих запрашиваемых разрешений. Использование идентификатора клиента в качестве области указывает на то, что приложению нужен маркер доступа, который может использоваться в вашей службе или веб-API, представленных таким же идентификатором клиента. Область offline_access означает, что вашему приложению потребуется маркер обновления для продолжительного доступа к ресурсам. Вы также можете использовать область openid для запроса идентификатора маркера из Azure AD B2C. |
| code | Обязательно | Код авторизации, полученный из конечной точки /authorize. |
| redirect_uri | Обязательно | URI перенаправления приложения, в котором вы получили код авторизации. |
| code_verifier | рекомендуется | Это тот же параметр code_verifier, который использовался для получения кода авторизации. Является обязательным, если в запросе на код авторизации использовался PKCE. Дополнительные сведения см. в описании PKCE RFC. |
Если вы тестируете этот HTTP-запрос POST, можно использовать любой клиент HTTP, например Microsoft PowerShell или Postman.
Успешный ответ маркера выглядит следующим образом:
{
"not_before": "1442340812",
"token_type": "Bearer",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
"expires_in": "3600",
"refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}
| Параметр | Описание |
|---|---|
| not_before | Момент времени, в который маркер начинает считаться действительным (с начала эпохи). |
| token_type | Значение типа маркера. Единственным типом, поддерживаемым идентификатором Microsoft Entra, является Bearer. |
| access_token | Подписанный маркер JSON Web Token (JWT), который вы запрашивали. |
| область | Области, для которых действителен маркер. Области также можно использовать, чтобы кэшировать маркеры для последующего использования. |
| expires_in | Срок действия маркера (в секундах). |
| refresh_token | Маркер обновления OAuth 2.0. Приложение может использовать этот маркер для получения дополнительных маркеров по истечении срока действия текущего маркера. Маркеры обновления имеют большой срок действия. Их можно использовать для длительного сохранения доступа к ресурсам. Дополнительные сведения см. в статье Azure AD B2C: справочник по маркерам. |
Сообщения об ошибках выглядят следующим образом:
{
"error": "access_denied",
"error_description": "The user revoked access to the app.",
}
| Параметр | Описание |
|---|---|
| error | Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на них. |
| error_description | Конкретное сообщение об ошибке, с помощью которого можно определить первопричину возникновения ошибки аутентификации. |
3. Использование маркера
После успешного получения маркера доступа маркер можно использовать в запросах к веб-API серверной части приложения путем включения маркера в заголовок Authorization:
GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
4. Обновление маркера
Срок действия маркеров доступа и маркеров идентификации крайне мал. Для сохранения доступа к ресурсам маркеры с истекшим сроком действия необходимо обновлять. При обновлении маркера доступа Azure AD B2C возвращает новый маркер. Обновленный маркер доступа обновит значения утверждений nbf (не раньше), iat (выдан в) и exp (истечение срока действия). Все остальные значения утверждений будут совпадать с изначально выданным маркером доступа.
Для обновления маркера отправьте еще один запрос POST в конечную точку /token, указав refresh_token вместо code:
POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
| Параметр | Необходим? | Описание |
|---|---|---|
| {tenant} | Обязательно | Имя клиента Azure AD B2C |
| {policy} | Обязательно | Поток пользователя, который использовался для получения исходного маркера обновления. Другой поток пользователя в этом запросе использовать нельзя. |
| client_id | Обязательно | Идентификатор приложения, назначенный вашему приложению на портале Azure. |
| client_secret | Да, в веб-приложениях | Секрет приложения, созданный на портале Azure. Секреты клиента используются в этом потоке для сценариев веб-приложений, где клиент может безопасно хранить секрет клиента. Для сценариев собственного приложения (общедоступного клиента) секреты клиента не могут быть безопасно сохранены, поэтому они не используются в этом вызове. При использовании секрета клиента следует периодически менять его. |
| grant_type | Обязательно | Тип предоставления. Для этого участка потока кода авторизации это должен быть тип refresh_token. |
| область | Рекомендуемая | Список областей с разделителями-пробелами. Одно значение область указывает на Microsoft Entra идентификатор обоих запрашиваемых разрешений. Использование идентификатора клиента в качестве области указывает на то, что приложению нужен маркер доступа, который может использоваться в вашей службе или веб-API, представленных таким же идентификатором клиента. Область offline_access означает, что вашему приложению потребуется маркер обновления для продолжительного доступа к ресурсам. Вы также можете использовать область openid для запроса идентификатора маркера из Azure AD B2C. |
| redirect_uri | Необязательно | URI перенаправления приложения, в котором вы получили код авторизации. |
| refresh_token | Обязательно | Исходный маркер обновления, полученный на втором участке потока. |
Успешный ответ маркера выглядит следующим образом:
{
"not_before": "1442340812",
"token_type": "Bearer",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
"expires_in": "3600",
"refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}
| Параметр | Описание |
|---|---|
| not_before | Момент времени, в который маркер начинает считаться действительным (с начала эпохи). |
| token_type | Значение типа маркера. Единственный тип, поддерживаемый идентификатором Microsoft Entra, — Bearer. |
| access_token | Подписанный маркер JWT, который вы запрашивали. |
| область | Области, для которых действителен маркер. Области также можно использовать, чтобы кэшировать маркеры для последующего использования. |
| expires_in | Срок действия маркера (в секундах). |
| refresh_token | Маркер обновления OAuth 2.0. Приложение может использовать этот маркер для получения дополнительных маркеров по истечении срока действия текущего маркера. У маркеров обновления длительный срок действия. Их можно использовать, чтобы надолго сохранять доступ к ресурсам. Дополнительные сведения см. в статье Azure AD B2C: справочник по маркерам. |
Сообщения об ошибках выглядят следующим образом:
{
"error": "access_denied",
"error_description": "The user revoked access to the app.",
}
| Параметр | Описание |
|---|---|
| error | Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на них. |
| error_description | Конкретное сообщение об ошибке, с помощью которого можно определить первопричину возникновения ошибки аутентификации. |
Использование собственного каталога Azure AD B2C
Чтобы отправить эти запросы самостоятельно, выполните следующие действия. Замените значения, приведенные в этой статье в качестве примера, собственными.
- Создайте каталог Azure AD B2C. Используйте имя своего каталога в запросах.
- Создайте приложение для получения идентификатора приложения и URI перенаправления. Включите собственный клиент в приложение.
- Создайте собственные потоки пользователя и получите их имена.