Определение технического профиля OAuth2 в настраиваемой политике в Azure Active Directory B2C

Мақала
01/11/2024

Примечание

В Azure Active Directory B2C пользовательские политики преимущественно предназначены для выполнения сложных сценариев. В большинстве случаев рекомендуется использовать встроенные пользовательские потоки. Ознакомьтесь со статьей Начало работы с настраиваемыми политиками в Azure Active Directory B2C, чтобы узнать о базовом пакете настраиваемых политик, если еще не сделали этого.

Azure Active Directory B2C (Azure AD B2C) поддерживает протокол OAuth2 для поставщиков удостоверений. OAuth2 — это основной протокол для авторизации и делегированной проверки подлинности. Дополнительные сведения см. в документе RFC 6749 о системе авторизации OAuth 2.0. С помощью технического профиля OAuth2 можно создать федерацию с поставщиком удостоверений на основе OAuth2, например Facebook. Федерация с поставщиком удостоверений позволяет пользователям входить в систему, используя имеющиеся удостоверения социальных сетей или компаний.

Протокол

Атрибуту Name элемента Protocol необходимо присвоить значение OAuth2. Например, OAuth2 — это протокол для технического профиля Facebook-OAUTH.

<TechnicalProfile Id="Facebook-OAUTH">
  <DisplayName>Facebook</DisplayName>
  <Protocol Name="OAuth2" />
  ...

Входящие утверждения

Элементы InputClaims и InputClaimsTransformations не являются обязательными. Но при необходимости можно отправлять дополнительные параметры поставщику удостоверений. В следующем примере к запросу авторизации добавляется параметр строки запроса domain_hint со значением contoso.com.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="domain_hint" DefaultValue="contoso.com" />
</InputClaims>

Исходящие утверждения

Элемент OutputClaims содержит список утверждений, возвращаемых поставщиком удостоверений OAuth2. Возможно, потребуется сопоставить имя утверждения, определенное в вашей политике, с именем, определенным у поставщика удостоверений. Вы также можете добавить утверждения, которые не возвращаются поставщиком удостоверений, установив атрибут DefaultValue.

Элемент OutputClaimsTransformations может содержать коллекцию элементов OutputClaimsTransformation, которые используются для изменения исходящих утверждений или создания новых.

В этом примере показаны утверждения, возвращаемые поставщиком удостоверений Facebook:

Утверждение first_name сопоставляется с утверждением givenName.
Утверждение last_name сопоставляется с утверждением surname.
Утверждение displayName не сопоставляется с именем.
Утверждение email не сопоставляется с именем.

Технический профиль также возвращает утверждения, которые не возвращаются поставщиком удостоверений:

Утверждение IdentityProvider, содержащее имя поставщика удостоверений.
утверждение AuthenticationSource со значением по умолчанию socialIdpAuthentication.

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="id" />
  <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="first_name" />
  <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="last_name" />
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="email" />
  <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="facebook.com" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" />
</OutputClaims>

Метаданные конечной точки авторизации

Поток авторизации начинается, когда Azure AD B2C направляет пользователя в конечную точку /authorize поставщика удостоверений OAuth2. Вызов конечной точки авторизации — это интерактивная часть потока, где пользователь выполняет действие. На этом этапе пользователю предлагается завершить вход с помощью поставщика удостоверений OAuth2, например ввести имя пользователя и пароль.

Azure AD B2C создает запрос авторизации, предоставляя идентификатор клиента, области, универсальный код ресурса (URI) перенаправления и другие параметры, необходимые для получения маркера доступа от поставщика удостоверений. В этом разделе описаны метаданные конечной точки авторизации, позволяющие настроить запрос к конечной точке /authorize поставщика удостоверений.

Запрос к конечной точке авторизации — это всегда HTTP GET. В приведенном ниже примере демонстрируется вызов конечной точки авторизации.

GET https://login.contoso.com/oauth/v2/authorization?
client_id=12345
&response_type=code
&response_mode=query
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&scope=profile%20offline_access
&redirect_uri=https%3a%2f%2fabrikam.b2clogin.com%2fabrikam.onmicrosoft.com%2foauth2%2fauthresp
&state=...

В таблице перечислены метаданные конечной точки авторизации.

Атрибут	Обязательно	Описание
`authorization_endpoint`	Да	URL-адрес конечной точки авторизации, согласно RFC 6749.
`client_id`	Да	Идентификатор приложения поставщика удостоверений.
`AdditionalRequestQueryParameters`	Нет	Дополнительные параметры запроса. Например, можно отправлять дополнительные параметры поставщику удостоверений. Можно добавлять несколько параметров, используя запятую в качестве разделителя.
`response_mode`	Нет	Метод, который использует поставщик удостоверений, чтобы отправить результат обратно в Azure AD B2C. Возможные значения: `query`, `form_post` (по умолчанию) или `fragment`.
`scope`	Нет	Область запроса, определенная в соответствии со спецификацией поставщика удостоверений OAuth2. Возможные значения: `openid`, `profile` и `email`.
`UsePolicyInRedirectUri`	Нет	Указывает, следует ли использовать политику при создании универсального кода ресурса (URI) перенаправления. При настройке приложения в поставщике удостоверений необходимо указать URI перенаправления. URI перенаправления указывает на Azure AD B2C, `https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/oauth2/authresp`. Если вы указываете `true`, необходимо добавить URI перенаправления для каждой используемой политики. Например: `https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/{policy-name}/oauth2/authresp`.

Метаданные конечной точки маркера

После того как пользователь завершает проверку подлинности в конечной точке авторизации поставщика удостоверений, ответ, содержащий code авторизации, возвращается в Azure AD B2C. Azure AD B2C активирует код авторизации для маркера доступа, отправляя запрос POST в конечную точку /token поставщика удостоверений. В этом разделе описаны метаданные конечной точки маркера, позволяющие настроить запрос к конечной точке /token поставщика удостоверений.

Приведенный ниже HTTP-запрос демонстрирует вызов конечной точки токена поставщика удостоверений из Azure AD B2C.

POST https://contoso/oauth2/token 
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=12345&scope=profile offline_access&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...

В таблице перечислены метаданные конечной точки маркера.

Атрибут	Обязательно	Описание
`AccessTokenEndpoint`	Да	URL-адрес конечной точки маркера. Например, `https://www.linkedin.com/oauth/v2/accessToken`.
`HttpBinding`	Нет	Ожидаемая привязка HTTP к конечной точке маркера. Возможные значения: `GET` или `POST`.
`AccessTokenResponseFormat`	Нет	Формат вызова конечной точки маркера доступа. Например, для Facebook требуется метод HTTP GET, но маркер доступа возвращается в формате JSON. Возможные значения: `Default`, `Json` и `JsonP`.
`ExtraParamsInAccessTokenEndpointResponse`	Нет	Содержит дополнительные параметры, которые могут возвращать в ответе от AccessTokenEndpoint некоторые поставщики удостоверений. Например, ответ от AccessTokenEndpoint содержит дополнительный параметр, такой как `openid`, который является обязательным параметром, помимо access_token, в строке запроса ClaimsEndpoint. При указании нескольких имен параметров их следует экранировать, разделяя запятой (,).
`token_endpoint_auth_method`	Нет	Указывает, как Azure AD B2C отправляет заголовок проверки подлинности в конечную точку маркера. Возможные значения: `client_secret_post` (по умолчанию) и `client_secret_basic`, `private_key_jwt`. Дополнительные сведения см. в документе о проверке подлинности клиента OpenID Connect.
`token_signing_algorithm`	Нет	Указывает алгоритм подписания для использования, когда для параметра `token_endpoint_auth_method` задано значение `private_key_jwt`. Возможные значения: `RS256` (по умолчанию) или `RS512`.

Настройка метода привязки HTTP

По умолчанию запрос к конечной точке маркера использует HTTP POST.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">POST</Item>

Следующий вызов HTTP демонстрирует вызов конечной точки маркера с помощью запроса HTTP POST:

POST /oauth2/token

client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Для поставщиков удостоверений, которым требуется использовать метод HTTP GET в конечной точке /token, задайте для метаданных HttpBinding значение GET. Обратите внимание, что в следующем примере параметр AccessTokenResponseFormat имеет значение json, так как конечная точка маркера возвращает ответ в формате JSON.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">GET</Item>
<Item Key="AccessTokenResponseFormat">json</Item>

GET /oauth2/token?client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Настройка формата ответа для маркера доступа

Для поставщиков удостоверений, поддерживающих метод HTTP POST, AccessTokenResponseFormat по умолчанию имеет значение json. Если поставщик удостоверений поддерживает запрос HTTP GET, необходимо явно задать формат ответа json для маркера доступа.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">GET</Item>
<Item Key="AccessTokenResponseFormat">json</Item>

В следующем примере показан ответ конечной точки маркера в формате JSON:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...",
    "token_type": "Bearer",
    "not_before": 1637924390,
    "expires_in": 960000,
}

Настройка способа проверки подлинности

Запросы к конечной точке маркера всегда требуют проверки подлинности. По умолчанию Azure AD B2C предоставляет поставщику удостоверений учетные данные клиента. По умолчанию используется способ проверки подлинности client_secret_post, включая учетные данные клиента (client_id и client_secret) в тексте запроса.

Приведенный ниже HTTP-запрос к конечной точке маркера содержит client_id и client_secret в данных POST. Для запросов GET client_id и client_secret включаются в параметры строки запроса.

POST /oauth2/token

client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Для поставщиков удостоверений, которым требуется использовать обычную проверку подлинности HTTP в конечной точке /token, задайте для метаданных token_endpoint_auth_method значение client_secret_basic. При таком типе проверки подлинности учетные данные клиента передаются поставщику удостоверений с использованием схемы обычной проверки подлинности HTTP.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="token_endpoint_auth_method">client_secret_basic</Item>

Приведенный ниже HTTP-запрос демонстрирует вызов конечной точки маркера с обычной проверкой подлинности HTTP. Заголовок авторизации содержит идентификатор клиента и секрет клиента в формате client_ID:client_secret, закодированном в Base64.

POST /oauth2/token

Authorization: Basic YWJjZDoxMjM0

redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Для поставщиков удостоверений, поддерживающих проверку подлинности JWT с закрытым ключом, задайте для метаданных token_endpoint_auth_method значение private_key_jwt. При таком методе проверки подлинности сертификат, предоставленный Azure AD B2C, используется для создания подписанного утверждения, которое передается поставщику удостоверений в параметре client_assertion. Задайте для client_assertion_type значение urn:ietf:params:oauth:client-assertion-type:jwt-bearer. Метаданные token_signing_algorithm определяют алгоритм подписи токена JWT.

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="token_endpoint_auth_method">private_key_jwt</Item>
<Item Key="token_signing_algorithm">RS256</Item>

Приведенный ниже HTTP-запрос демонстрирует вызов конечной точки маркера с проверкой подлинности JWT с закрытым ключом.

POST /oauth2/token

client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjJFRFg0dWRYeDIxbXNoaXdJVzczMUY3OUZSbFJiUDZXVXJyZmktR1RFeVkifQ.eyJpc3MiOiJhYmNkIiwiZXhwIjoxNjM3OTI5ODY0LCJuYmYiOjE2Mzc5Mjk1NjQsImF1ZCI6Imh0dHBzOi8vNWRlNC0xMDktNjQtMTI0LTUzLm5ncm9rLmlvL2FjY2Vzc190b2tlbiIsImp0aSI6IjVxQWlGV2lEODNDbU1KWWNrejBRdGc9PSIsInN1YiI6ImFiY2QiLCJpYXQiOjE2Mzc5Mjk1NjR9.C4OtRnrLaQatpT5LP45O5Nb418S4v8yZi_C42ld440w&client_id=abcd&client_assertion_type=urn%3aietf%3aparams%3aoauth%3aclient-assertion-type%3ajwt-bearer&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

Метаданные конечной точки сведений о пользователе

После того как служба Azure AD B2C получает маркер доступа от поставщика удостоверений OAuth2, она вызывает конечную точку сведений о пользователе. Конечная точка сведений о пользователе, также известная как конечная точка утверждений, предназначена для получения утверждений о пользователе, прошедшем проверку подлинности. Azure AD B2C использует проверку подлинности на основе токена носителя для проверки подлинности в конечной точке сведений о пользователе поставщиков удостоверений. Токен носителя — это маркер доступа, который Azure AD B2C получает от конечной точки /token поставщиков удостоверений.

Запрос к конечной точке сведений о пользователе — это всегда HTTP GET. Маркер доступа отправляется в параметре строки запроса access_token. Приведенный ниже HTTP-запрос демонстрирует вызов конечной точки сведений о пользователе с маркером доступа в параметре строки запроса.

GET /oauth2/claims?access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

В таблице перечислены метаданные конечной точки сведений о пользователе.

Атрибут	Обязательно	Описание
`ClaimsEndpoint`	Да	URL-адрес конечной точки информации о пользователе. Например, `https://api.linkedin.com/v2/me`.
`ClaimsEndpointAccessTokenName`	Нет	Имя, присваиваемое параметру строки запроса на маркера доступа. Значение по умолчанию: `access_token`.
`ClaimsEndpointFormatName`	Нет	Имя, присваиваемое параметру строки запроса на формат. Например, можно задать имя `format` для этой конечной точки утверждений LinkedIn: `https://api.linkedin.com/v1/people/~?format=json`.
`ClaimsEndpointFormat`	Нет	Значение для параметра строки запроса на формат. Например, можно задать значение `json` для этой конечной точки утверждений LinkedIn: `https://api.linkedin.com/v1/people/~?format=json`.
`BearerTokenTransmissionMethod`	Нет	Указывает способ отправки токена. По умолчанию используется строка запроса. Чтобы отправлять токен в виде заголовка запроса, задайте значение `AuthorizationHeader`.
`ExtraParamsInClaimsEndpointRequest`	Нет	Содержит дополнительные параметры, которые могут возвращать в запросе ClaimsEndpoint некоторые поставщики удостоверений. При указании нескольких имен параметров их следует экранировать, разделяя запятой (,).

Настройка параметра строки запроса с маркером доступа

Для конечной точки сведений о пользователе может требоваться отправка маркера доступа в определенном параметре строки запроса. Чтобы изменить имя параметра строки запроса, содержащего маркер доступа, используйте метаданные ClaimsEndpointAccessTokenName. В следующем примере параметр строки запроса с маркером доступа имеет значение token.

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="ClaimsEndpointAccessTokenName">token</Item>

Следующий вызов HTTP демонстрирует вызов конечной точки сведений о пользователе со значением token параметра ClaimsEndpointAccessTokenName:

GET /oauth2/claims?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Настройка формата утверждений

ClaimsEndpointFormatName и ClaimsEndpointFormat позволяют отправлять параметр строки запроса в виде пары "ключ-значение" в конечную точку сведений о пользователе. В приведенном ниже примере настраивается параметр строки запроса с именем format и значением json.

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="ClaimsEndpointFormatName">format</Item>
<Item Key="ClaimsEndpointFormat">json</Item>

Следующий HTTP-запрос демонстрирует вызов конечной точки сведений о пользователе с заданными значениями ClaimsEndpointFormatName и ClaimsEndpointFormat.

GET /oauth2/claims?format=json&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Настройка метода передачи токена носителя

По умолчанию маркер доступа отправляется в конечную точку сведений о пользователе поставщика удостоверений через параметр строки запроса. Чтобы отправить маркер в заголовке HTTP Authorization, задайте для метаданных BearerTokenTransmissionMethod значение AuthorizationHeader.

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="BearerTokenTransmissionMethod">AuthorizationHeader</Item>

Приведенный ниже HTTP-запрос демонстрирует, как передается маркер доступа, если параметр BearerTokenTransmissionMethod имеет значение AuthorizationHeader.

GET /oauth2/claims

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Передача параметров, возвращаемых конечной точкой маркера

Некоторые поставщики удостоверений требуют передачи дополнительных параметров, возвращаемых конечной точкой маркера в конечную точку сведений о пользователе. Например, ответ от конечной точки маркера содержит параметр с именем resource, который является обязательным для конечной точки сведений о пользователе (помимо маркера доступа). Используйте метаданные ExtraParamsInClaimsEndpointRequest, чтобы указать дополнительные параметры для передачи. При указании нескольких имен параметров их следует экранировать, разделяя запятой (,).

Приведенный ниже код JSON демонстрирует полезные данные JSON, возвращаемые конечной точкой маркера в параметре с именем resource.

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...",
    "token_type": "Bearer",
    "not_before": 1549647431,
    "expires_in": 960000,
    "resource": "f2a76e08-93f2-4350-833c-965c02483b11"
}

Чтобы передать параметр resource в конечную точку сведений о пользователе, добавьте следующие метаданные:

<Item Key="ExtraParamsInClaimsEndpointRequest">resource</Item>

Приведенный ниже HTTP-запрос демонстрирует, как параметр resource передается в конечную точку сведений о пользователе.

GET /oauth2/claims?resource=f2a76e08-93f2-4350-833c-965c02483b11&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Конечная точка конца сеанса

Чтобы пользователь вышел из приложения, перенаправьте его в конечную точку выхода Azure AD B2C (для OAuth2 и OpenID Connect) или отправьте LogoutRequest (для SAML). Azure AD B2C очистит сеанс пользователя из браузера. При получении запроса на выход Azure AD B2C пытается выполнить выход из всех федеративных поставщиков удостоверений, через которые мог выполнить вход пользователь. Универсальный код ресурса (URI) выхода поставщика удостоверений OAuth2 настраивается в метаданных end_session_endpoint. Когда пользователь выходит из приложения с помощью Azure AD B2C, создается скрытый кадр iframe, который вызывает end_session_endpoint на странице выхода Azure AD B2C.

В таблице перечислены метаданные конечной точки сведений о пользователе.

Атрибут	Обязательно	Описание
`end_session_endpoint`	Да	URL-адрес конечной точки завершения сеанса, согласно RFC 6749.
`SingleLogoutEnabled`	Нет	Указывает, будет ли технический профиль при входе пытаться выйти из федеративных поставщиков удостоверений. Дополнительные сведения см. в разделе Выход из сеанса Azure AD B2C. Возможные значения: `true` (по умолчанию) и `false`.

Универсальные метаданные OAuth2

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

Атрибут	Обязательно	Описание
`IdTokenAudience`	Нет	Аудитория id_token. Если этот параметр задан, Azure AD B2C проверяет, содержится ли маркер в утверждении, которое возвращает поставщик удостоверений, и соответствует ли маркер заданному параметру.
`ProviderName`	Нет	Имя поставщика удостоверений.
`ResponseErrorCodeParamName`	Нет	Имя параметра, который содержит сообщение об ошибке, возвращаемое по HTTP 200 (ОК).
`IncludeClaimResolvingInClaimsHandling`	Нет	Для входящих и исходящих утверждений указывает, включено ли разрешение утверждений в технический профиль. Возможные значения: `true` или `false` (по умолчанию). Если вы хотите использовать сопоставитель утверждений в техническом профиле, задайте для этого параметра значение `true`.
`ResolveJsonPathsInJsonTokens`	Нет	Указывает, сопоставляет ли технический профиль пути JSON. Возможные значения: `true` или `false` (по умолчанию). Используйте эти метаданные для чтения данных из вложенного элемента JSON. В разделе OutputClaim установите параметр `PartnerClaimType` на значение элемента пути JSON, который хотите вывести. Например `firstName.localized` или `data[0].to[0].email`.

Криптографические ключи

Элемент CryptographicKeys содержит следующий атрибут:

attribute	Обязательно	Описание
`client_secret`	Да	Секрет клиента приложения поставщика удостоверений. Ключ шифрования является обязательным, только если для метаданных response_types задано значение `code`. В этом случае Azure AD B2C выполняет другой вызов для обмена кода авторизации на маркер доступа. Если для метаданных задано значение `id_token`, криптографический ключ можно не указывать.
`assertion_signing_key`	Нет	Если метаданные `token_endpoint_auth_method` имеют значение `private_key_jwt`, предоставьте сертификат X509, который будет использоваться для подписи ключа JWT. Этот ключ должен предоставляться поставщиком удостоверений OAuth2.

URI перенаправления

При настройке URI перенаправления поставщика удостоверений введите https://{tenant-name}.b2clogin.com/{tenant-name}.onmicrosoft.com/oauth2/authresp. Обязательно замените {tenant-name} именем своего клиента (например, contosob2c). URI перенаправления должен содержать только строчные символы.

Дальнейшие действия

Узнайте, как добавить поставщик удостоверений в клиент Azure Active Directory B2C.

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