Definir um perfil técnico OAuth2 numa política personalizada do Azure Active Directory B2C

  • Artigo

Nota

No Azure Active Directory B2C, as políticas personalizadas são concebidas principalmente para abordar cenários complexos. Para a maioria dos cenários, recomendamos que utilize fluxos de utilizador incorporados. Se ainda não o fez, saiba mais sobre o pacote de introdução de políticas personalizadas em Introdução às políticas personalizadas no Active Directory B2C.

O Azure Active Directory B2C (Azure AD B2C) fornece suporte para o fornecedor de identidade do protocolo OAuth2. O OAuth2 é o protocolo principal para autorização e autenticação delegada. Para obter mais informações, veja RFC 6749 The OAuth 2.0 Authorization Framework (OAuth 2.0 Authorization Framework). Com um perfil técnico do OAuth2, pode federar com um fornecedor de identidade baseado em OAuth2, como o Facebook. A federação com um fornecedor de identidade permite que os utilizadores iniciem sessão com as identidades sociais ou empresariais existentes.

Protocolo

O atributo Nome do elemento Protocolo tem de ser definido como OAuth2. Por exemplo, o protocolo para o perfil técnico Facebook-OAUTH é OAuth2:

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

Afirmações de entrada

Os elementos InputClaims e InputClaimsTransformations não são necessários . Contudo, poderá querer enviar mais parâmetros para o seu fornecedor de identidade. O exemplo seguinte adiciona o parâmetro domain_hint cadeia de consulta com o valor de ao pedido de contoso.com autorização.

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

Afirmações de saída

O elemento OutputClaims contém uma lista de afirmações devolvidas pelo fornecedor de identidade OAuth2. Poderá ter de mapear o nome da afirmação definida na política para o nome definido no fornecedor de identidade. Também pode incluir afirmações que não são devolvidas pelo fornecedor de identidade, desde que defina o DefaultValue atributo.

O elemento OutputClaimsTransformations pode conter uma coleção de elementos OutputClaimsTransformation que são utilizados para modificar as afirmações de saída ou gerar novas.

O exemplo seguinte mostra as afirmações devolvidas pelo fornecedor de identidade do Facebook:

  • A afirmação first_name está mapeada para a afirmação givenName .
  • A reivindicação last_name está mapeada para a reivindicação do sobrenome .
  • A afirmação displayName sem mapeamento de nomes.
  • A afirmação de e-mail sem mapeamento de nomes.

O perfil técnico também devolve afirmações que não são devolvidas pelo fornecedor de identidade:

  • A afirmação identityProvider que contém o nome do fornecedor de identidade.
  • A afirmação authenticationSource com um valor predefinido de 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>

Metadados do ponto final de autorização

O fluxo de autorização começa quando Azure AD B2C direciona o utilizador para o ponto final de fornecedores /authorize de identidade OAuth2. A chamada para o ponto final de autorização é a parte interativa do fluxo, onde o utilizador toma medidas. Neste momento, é pedido ao utilizador para concluir o início de sessão no fornecedor de identidade do OAuth2. Por exemplo, ao introduzir o respetivo nome de utilizador e palavra-passe.

Azure AD B2C cria um pedido de autorização ao fornecer o ID de cliente, âmbitos, URI de redirecionamento e outros parâmetros de que precisa para adquirir um token de acesso do fornecedor de identidade. Esta secção descreve os metadados do ponto final de autorização, que permitem configurar o pedido para o /authorize ponto final do fornecedor de identidade.

O pedido para o ponto final de autorização é sempre HTTP GET. O exemplo seguinte demonstra uma chamada para o ponto final de autorização.

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=...

A tabela seguinte lista os metadados do ponto final de autorização.

Atributo Necessário Descrição
authorization_endpoint Sim O URL do ponto final de autorização de acordo com RFC 6749.
client_id Yes O identificador da aplicação do fornecedor de identidade.
AdditionalRequestQueryParameters No Parâmetros de consulta de pedidos adicionais. Por exemplo, poderá querer enviar parâmetros adicionais para o seu fornecedor de identidade. Pode incluir vários parâmetros através do delimitador de vírgulas.
response_mode No O método que o fornecedor de identidade utiliza para enviar o resultado de volta para Azure AD B2C. Valores possíveis: query, form_post (predefinição) ou fragment.
scope No O âmbito do pedido definido de acordo com a especificação do fornecedor de identidade OAuth2. openidComo , profilee email.
UsePolicyInRedirectUri No Indica se deve utilizar uma política ao construir o URI de redirecionamento. Quando configurar a aplicação no fornecedor de identidade, tem de especificar o URI de redirecionamento. O URI de redirecionamento aponta para Azure AD B2C, https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/oauth2/authresp. Se especificar true, terá de adicionar um URI de redirecionamento para cada política que utilizar. Por exemplo: https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/{policy-name}/oauth2/authresp.

Metadados de ponto final de token

Depois de o utilizador concluir a autenticação no ponto final de autorização do fornecedor de identidade, é devolvida uma resposta que contém a autorização code ao Azure AD B2C. Azure AD B2C resgata o código de autorização de um token de acesso ao enviar um pedido POST para o /token ponto final do fornecedor de identidade. Esta secção descreve os metadados do ponto final do token, que permitem configurar o pedido para o /token ponto final do fornecedor de identidade.

O seguinte pedido HTTP mostra uma Azure AD chamada B2C para o ponto final do token do fornecedor de identidade.

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...

A tabela seguinte lista os metadados do ponto final do token.

Atributo Necessário Descrição
AccessTokenEndpoint Sim O URL do ponto final do token. Por exemplo, https://www.linkedin.com/oauth/v2/accessToken.
HttpBinding No O enlace HTTP esperado para o ponto final do token. Valores possíveis: GET ou POST.
AccessTokenResponseFormat No O formato da chamada de ponto final do token de acesso. Por exemplo, o Facebook requer um método HTTP GET, mas a resposta do token de acesso está no formato JSON. Valores possíveis: Default, Jsone JsonP.
ExtraParamsInAccessTokenEndpointResponse No Contém os parâmetros adicionais que podem ser devolvidos na resposta do AccessTokenEndpoint por alguns fornecedores de identidade. Por exemplo, a resposta de AccessTokenEndpoint contém um parâmetro adicional, como openid, que é um parâmetro obrigatório para além do access_token numa cadeia de consulta de pedido ClaimsEndpoint . Vários nomes de parâmetros devem ser escapados e separados pela vírgula "", delimitador.
token_endpoint_auth_method No Especifica como Azure AD B2C envia o cabeçalho de autenticação para o ponto final do token. Valores possíveis: client_secret_post (predefinição) e client_secret_basic, private_key_jwt. Para obter mais informações, veja a secção Autenticação de cliente do OpenID Connect.
token_signing_algorithm No Especifica o algoritmo de assinatura a utilizar quando token_endpoint_auth_method estiver definido como private_key_jwt. Valores possíveis: RS256 (predefinição) ou RS512.

Configurar o método de enlace HTTP

Por predefinição, o pedido para o ponto final do token utiliza HTTP POST.

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

A seguinte chamada HTTP demonstra uma chamada para o ponto final do token com o pedido 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

Para os fornecedores de identidade que requerem a utilização do método HTTP GET no /token ponto final, defina os HttpBinding metadados como GET. Tenha em atenção que, no exemplo seguinte, o AccessTokenResponseFormat está definido como json, uma vez que o ponto final do token devolve a resposta no formato 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

Configurar o formato de resposta do token de acesso

Para fornecedores de identidade que suportam o método HTTP POST, o AccessTokenResponseFormat está predefinido como json. Se o fornecedor de identidade suportar o pedido HTTP GET, tem de definir explicitamente o formato json de resposta do token de acesso.

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

O exemplo seguinte demonstra uma resposta de ponto final de token no formato JSON:

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

Configurar o método de autenticação

Os pedidos para o ponto final do token requerem sempre autenticação. Por predefinição, Azure AD B2C fornece ao fornecedor de identidade credenciais de cliente. Por predefinição, o método de autenticação é client_secret_post, incluindo as credenciais do cliente (client_id e client_secret) no corpo do pedido.

O seguinte pedido HTTP para o ponto final do token contém o client_id e o client_secret nos dados POST. Para pedidos client_id GET e os client_secret estão incluídos nos parâmetros da cadeia de consulta.

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

Para os fornecedores de identidade que requerem a utilização da autenticação básica HTTP no ponto /token final, configure os token_endpoint_auth_method metadados para client_secret_basic. Com este tipo de método de autenticação, as credenciais de cliente são transmitidas ao fornecedor de identidade através do esquema de autenticação HTTP Basic.

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

O seguinte pedido HTTP demonstra uma chamada para o ponto final do token com autenticação básica HTTP. O cabeçalho de autorização contém o ID de cliente e o segredo do cliente, no formato client_ID:client_secret, codificado em 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

Para fornecedores de identidade que suportam a autenticação JWT de chave privada, configure os token_endpoint_auth_method metadados para private_key_jwt. Com este tipo de método de autenticação, o certificado fornecido ao Azure AD B2C é utilizado para gerar uma asserção assinada, que é transmitida ao fornecedor de identidade através do client_assertion parâmetro . O client_assertion_type conjunto como urn:ietf:params:oauth:client-assertion-type:jwt-bearer. Os token_signing_algorithm metadados especificam o algoritmo de assinatura do token 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>

O seguinte pedido HTTP demonstra uma chamada para o ponto final do token com a autenticação JWT de chave privada.

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

Metadados do ponto final de informações do utilizador

Depois de Azure AD B2C obter o token de acesso do fornecedor de identidade OAuth2, faz uma chamada para o ponto final de informações do utilizador. O ponto final de informações do utilizador, também conhecido como ponto final de afirmações, foi concebido para obter afirmações sobre o utilizador autenticado. Azure AD B2C utiliza a autenticação de token de portador para autenticar no ponto final de informações de utilizador dos fornecedores de identidade. O token de portador é o token de acesso que Azure AD B2C obtém do ponto final dos fornecedores /token de identidade.

O pedido para o ponto final de informações do utilizador é sempre HTTP GET. O token de acesso é enviado num parâmetro de cadeia de consulta com o nome access_token. O seguinte pedido HTTP mostra uma chamada para o ponto final de informações do utilizador com o token de acesso no parâmetro da cadeia de consulta.

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

A tabela seguinte lista os metadados do ponto final de informações do utilizador.

Atributo Necessário Descrição
ClaimsEndpoint Sim O URL do ponto final de informações do utilizador. Por exemplo, https://api.linkedin.com/v2/me.
ClaimsEndpointAccessTokenName No O nome do parâmetro da cadeia de consulta do token de acesso. Valor predefinido: access_token.
ClaimsEndpointFormatName No O nome do parâmetro da cadeia de consulta de formato. Por exemplo, pode definir o nome como format neste ponto https://api.linkedin.com/v1/people/~?format=jsonfinal de afirmações do LinkedIn .
ClaimsEndpointFormat No O valor do parâmetro da cadeia de consulta de formato. Por exemplo, pode definir o valor como json neste ponto https://api.linkedin.com/v1/people/~?format=jsonfinal de afirmações do LinkedIn.
BearerTokenTransmissionMethod No Especifica como o token é enviado. O método predefinido é uma cadeia de consulta. Para enviar o token como cabeçalho de pedido, defina como AuthorizationHeader.
ExtraParamsInClaimsEndpointRequest No Contém os parâmetros adicionais que podem ser devolvidos no pedido ClaimsEndpoint por alguns fornecedores de identidade. Vários nomes de parâmetros devem ser escapados e separados pela vírgula "", delimitador.

Configurar o parâmetro da cadeia de consulta do token de acesso

O ponto final de informações do utilizador pode exigir que o token de acesso seja enviado num parâmetro de cadeia de consulta específico. Para alterar o nome do parâmetro da cadeia de consulta, que contém o token de acesso, utilize os ClaimsEndpointAccessTokenName metadados. No exemplo seguinte, o parâmetro da cadeia de consulta do token de acesso está definido como token.

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

A seguinte chamada HTTP demonstra uma chamada para o ponto final de informações do utilizador com ClaimsEndpointAccessTokenName definido como token:

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

Configurar o formato de afirmações

O ClaimsEndpointFormatName e ClaimsEndpointFormat permitem-lhe enviar um parâmetro de cadeia de consulta de par chave-valor para o ponto final de informações do utilizador. O exemplo seguinte configura um parâmetro de cadeia de consulta com o nome format, com o valor de json.

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

O seguinte pedido HTTP demonstra uma chamada para o ponto final de informações do utilizador com ClaimsEndpointFormatName e ClaimsEndpointFormat configurado.

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

Configurar o método de transmissão de tokens de portador

Por predefinição, o token de acesso é enviado para o ponto final de informações do utilizador dos fornecedores de identidade através de um parâmetro de cadeia de consulta. Para enviar o token no cabeçalho HTTP Authorization , defina BearerTokenTransmissionMethod os metadados como AuthorizationHeader.

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

O seguinte pedido HTTP demonstra como o token de acesso é transmitido quando BearerTokenTransmissionMethod está definido como AuthorizationHeader.

GET /oauth2/claims

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Transmitir parâmetros devolvidos pelo ponto final do token

Alguns fornecedores de identidade necessitam de transmitir parâmetros adicionais que são devolvidos do ponto final do token para o ponto final de informações do utilizador. Por exemplo, a resposta do ponto final do token contém um parâmetro chamado resource, que é um parâmetro obrigatório do ponto final de informações do utilizador (além do token de acesso). Utilize os ExtraParamsInClaimsEndpointRequest metadados para especificar quaisquer parâmetros adicionais a transmitir. Vários nomes de parâmetros devem ser escapados e separados pela vírgula "", delimitador.

O JSON seguinte demonstra uma devolução de payload JSON pelo ponto final do token com um parâmetro com o nome resource.

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

Para transmitir o resource parâmetro para o ponto final de informações do utilizador, adicione os seguintes metadados:

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

O seguinte pedido HTTP demonstra como o resource parâmetro é transmitido para o ponto final de informações do utilizador.

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

Ponto final da sessão final

Para terminar sessão do utilizador na aplicação, redirecione o utilizador para o ponto final de fim de sessão do Azure AD B2C (para OAuth2 e OpenID Connect) ou envie um LogoutRequest (para SAML). Azure AD B2C limpará a sessão do utilizador a partir do browser. Após um pedido de fim de sessão, Azure AD B2C tenta terminar sessão a partir de quaisquer fornecedores de identidade federados através dos quais o utilizador possa ter iniciado sessão. O URI de início de sessão do fornecedor de identidade OAuth2 está configurado nos end_session_endpoint metadados. Quando o utilizador terminar sessão na sua aplicação através do Azure AD B2C, será criado um iframe oculto que chamará o end_session_endpoint na respetiva página de fim de sessão do Azure AD B2C.

A tabela seguinte lista os metadados do ponto final de informações do utilizador.

Atributo Necessário Descrição
end_session_endpoint Sim O URL do ponto final da sessão final de acordo com RFC 6749.
SingleLogoutEnabled No Indica se durante o início de sessão o perfil técnico tenta terminar sessão a partir de fornecedores de identidade federados. Para obter mais informações, veja Azure AD início de sessão B2C. Valores possíveis: true (predefinição) ou false.

Metadados genéricos do OAuth2

A tabela seguinte lista os metadados genéricos do fornecedor de identidade OAuth2. Os metadados descrevem como o perfil técnico OAuth2 processa a validação de tokens, obtém as afirmações e reagem às mensagens de erro.

Atributo Necessário Descrição
IdTokenAudience Não O público do id_token. Se especificado, Azure AD B2C verifica se o token está numa afirmação devolvida pelo fornecedor de identidade e é igual ao especificado.
ProviderName No O nome do fornecedor de identidade.
ResponseErrorCodeParamName No O nome do parâmetro que contém a mensagem de erro devolvida através de HTTP 200 (OK).
IncludeClaimResolvingInClaimsHandling   No Para afirmações de entrada e saída, especifica se a resolução de afirmações está incluída no perfil técnico. Valores possíveis: true, ou false (predefinição). Se quiser utilizar uma resolução de afirmações no perfil técnico, defina esta opção como true.
ResolveJsonPathsInJsonTokens No Indica se o perfil técnico resolve os caminhos JSON. Valores possíveis: true, ou false (predefinição). Utilize estes metadados para ler dados de um elemento JSON aninhado. Num OutputClaim, defina o PartnerClaimType como o elemento de caminho JSON que pretende exportar. Por exemplo: firstName.localized, ou data[0].to[0].email.

Chaves criptográficas

O elemento CryptographicKeys contém o seguinte atributo:

Atributo Necessário Descrição
client_secret Sim O segredo do cliente da aplicação do fornecedor de identidade. A chave criptográfica só é necessária se o response_types metadados estiver definido como code. Neste caso, Azure AD B2C faz outra chamada para trocar o código de autorização por um token de acesso. Se os metadados estiverem definidos como id_token, pode omitir a chave criptográfica.
assertion_signing_key No Quando os token_endpoint_auth_method metadados estiverem definidos como private_key_jwt, forneça um certificado X509 a utilizar para assinar a chave JWT. Esta chave deve ser-lhe fornecida pelo fornecedor de identidade OAuth2.

URI de Redirecionamento

Quando configurar o URI de redirecionamento do seu fornecedor de identidade, introduza https://{tenant-name}.b2clogin.com/{tenant-name}.onmicrosoft.com/oauth2/authresp. Certifique-se de que substitui {tenant-name} pelo nome do inquilino (por exemplo, contosob2c). O URI de redirecionamento tem de estar em minúsculas.

Passos seguintes