Поток кода авторизации OAuth 2.0 в Azure Active Directory B2C

Мақала
11/06/2023

Код авторизации 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 в запросе и ответе.

Параметр	Описание
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 перенаправления. Включите собственный клиент в приложение.
Создайте собственные потоки пользователя и получите их имена.

Бөлісу құралы: