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

O Azure Active Directory B2C (Azure AD B2C) fornece suporte para o provedor de identidade do protocolo OAuth2. OAuth2 é o protocolo principal para autorização e autenticação delegada. Para obter mais informações, consulte o RFC 6749 The OAuth 2.0 Authorization Framework. Com um perfil técnico OAuth2, você pode federar com um provedor de identidade baseado em OAuth2, como o Facebook. A Federação com um provedor de identidade permite que os usuários entrem com identidades sociais ou empresariais existentes.

Protocolo

O atributo Name do elemento Protocol precisa ser definido como OAuth2. Por exemplo, o protocolo para o perfil técnico do Facebook-OAUTH é OAuth2:

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

Declarações de entrada

Os elementos InputClaims e InputClaimsTransformations não são necessários. Mas talvez você queira enviar mais parâmetros para seu provedor de identidade. O exemplo a seguir adiciona o parâmetro de cadeia de caracteres de consulta domain_hint com o valor de contoso.com à solicitação de autorização.

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

Declarações de saída

O elemento OutputClaims contém uma lista de declarações retornadas pelo provedor de identidade OAuth2. Talvez seja necessário mapear o nome da declaração definida em sua política para o nome definido no provedor de identidade. Você também pode incluir declarações que não são retornadas pelo provedor de identidade, desde que você defina o atributo DefaultValue.

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

O exemplo a seguir mostra as declarações retornadas pelo provedor de identidade do Facebook:

• A declaração first_name é mapeada para a declaração givenName.
• A declaração last_name é mapeada para a declaração surname.
• A declaração displayName sem mapeamento de nome.
• A declaração email sem mapeamento de nome.

O perfil técnico também retorna declarações que não são retornadas pelo provedor de identidade:

• A declaração identityProvider que contém o nome do provedor de identidade.
• A declaração authenticationSource com um valor padrão 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 de extremidade de autorização

O fluxo de autorização começa quando o Azure AD B2C direciona o usuário para o ponto de extremidade dos provedores /authorize de identidade OAuth2. A chamada para o endpoint de autorização é a parte interativa do fluxo, onde o usuário executa uma ação. Neste ponto, o usuário é solicitado a concluir a entrada no provedor de identidade OAuth2. Por exemplo, digitando seu nome de usuário e senha.

O Azure AD B2C cria uma solicitação de autorização fornecendo a ID do cliente, os escopos, o URI de redirecionamento e outros parâmetros necessários para adquirir um token de acesso do provedor de identidade. Esta seção descreve os metadados do endpoint de autorização, que permitem configurar a solicitação para o /authorize endpoint do provedor de identidade.

A solicitação para o ponto de extremidade de autorização é sempre HTTP GET. O exemplo a seguir demonstra uma chamada para o ponto de extremidade 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 a seguir lista os metadados do ponto de extremidade de autorização.

Metadados do ponto de extremidade do token

Depois que o usuário conclui a autenticação no ponto de extremidade de autorização do provedor de identidade, uma resposta contendo a autorização code é retornada ao Azure AD B2C. O Azure AD B2C resgata o código de autorização para um token de acesso enviando uma solicitação POST para o /token ponto de extremidade do provedor de identidade. Esta seção descreve os metadados do endpoint do token, que permitem configurar a solicitação para o /token endpoint do provedor de identidade.

A solicitação HTTP a seguir mostra uma chamada do Azure AD B2C para o ponto de extremidade de token do provedor 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 a seguir lista os metadados do ponto de extremidade do token.

Configurar o método de associação HTTP

Por padrão, a solicitação para o ponto de extremidade do token usa HTTP POST.

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

A chamada HTTP a seguir demonstra uma chamada para o ponto de extremidade do token usando a solicitação 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 provedores de identidade que exigem o uso do método HTTP GET no /token endpoint, defina os HttpBinding metadados como GET. Observe que, no exemplo a seguir, o AccessTokenResponseFormat é definido como json, pois o ponto de extremidade do token retorna 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 provedores de identidade que oferecem suporte ao método HTTP POST, o AccessTokenResponseFormat é definido por padrão como json. Se o provedor de identidade der suporte à solicitação HTTP GET, você precisará definir o formato de resposta do token de acesso como json explicitamente.

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

O exemplo a seguir demonstra uma resposta de ponto de extremidade de token no formato JSON:

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

Configurar o método de autenticação

As solicitações para o ponto de extremidade do token sempre exigem autenticação. Por padrão, o Azure AD B2C fornece ao provedor de identidade credenciais de cliente. Por padrão, o método de autenticação é client_secret_post, incluindo as credenciais do cliente (client_id e client_secret) no corpo da solicitação.

A solicitação HTTP a seguir para o ponto de extremidade do token contém o client_id e o client_secret nos dados POST. Para solicitações client_id GET e estão client_secret incluídas nos parâmetros da cadeia de caracteres 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 provedores de identidade que exigem o uso de autenticação básica HTTP em seu /token endpoint, configure os token_endpoint_auth_method metadados como client_secret_basic. Com esse tipo de método de autenticação, as credenciais do cliente são passadas para o provedor de identidade usando o 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>

A solicitação HTTP a seguir demonstra uma chamada para o ponto de extremidade do token com autenticação básica HTTP. O cabeçalho de autorização contém o ID do cliente e o segredo do cliente, no formato client_ID:client_secretcodificado 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 provedores de identidade que oferecem suporte à autenticação JWT de chave privada, configure os token_endpoint_auth_method metadados como private_key_jwt. Com esse tipo de método de autenticação, o certificado fornecido ao Azure AD B2C é usado para gerar uma declaração assinada, que é passada para o provedor de identidade por meio do client_assertion parâmetro. O client_assertion_type conjunto para urn:ietf:params:oauth:client-assertion-type:jwt-bearer. Os token_signing_algorithm metadados especificam o algoritmo de assinatura do 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>

A solicitação HTTP a seguir demonstra uma chamada para o ponto de extremidade do token usando 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 de extremidade de informações do usuário

Depois que o Azure AD B2C obtém o token de acesso do provedor de identidade OAuth2, ele faz uma chamada para o ponto de extremidade de informações do usuário. O ponto de extremidade de informações do usuário, também conhecido como ponto de extremidade de declarações, foi projetado para recuperar declarações sobre o usuário autenticado. O Azure AD B2C usa a autenticação de token de portador para autenticar no ponto de extremidade de informações do usuário dos provedores de identidade. O token de portador é o token de acesso que o Azure AD B2C obtém do ponto de extremidade dos provedores /token de identidade.

A solicitação para o ponto de extremidade de informações do usuário é sempre HTTP GET. O token de acesso é enviado em um parâmetro de cadeia de caracteres de consulta chamado access_token. A solicitação HTTP a seguir mostra uma chamada para o ponto de extremidade de informações do usuário com o token de acesso no parâmetro de cadeia de caracteres de consulta.

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

A tabela a seguir lista os metadados do ponto de extremidade de informações do usuário.

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

O ponto de extremidade de informações do usuário pode exigir que o token de acesso seja enviado em um parâmetro de cadeia de caracteres de consulta específico. Para alterar o nome do parâmetro de cadeia de caracteres de consulta, que contém o token de acesso, use os ClaimsEndpointAccessTokenName metadados. No exemplo a seguir, o parâmetro de cadeia de caracteres de consulta do token de acesso é definido como token.

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

A chamada HTTP a seguir demonstra uma chamada para o ponto de extremidade de informações do usuário com ClaimsEndpointAccessTokenName set to token:

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

Configurar o formato de declarações

O ClaimsEndpointFormatName e ClaimsEndpointFormat permitem que você envie um parâmetro de cadeia de caracteres de consulta de par de valores-chave para o ponto de extremidade de informações do usuário. O exemplo a seguir configura um parâmetro de cadeia de caracteres de consulta chamado 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>

A solicitação HTTP a seguir demonstra uma chamada para o ponto de extremidade de informações do usuário com ClaimsEndpointFormatName e ClaimsEndpointFormat configurado.

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

Configurar o método de transmissão do token de portador

Por padrão, o token de acesso é enviado ao ponto de extremidade de informações do usuário dos provedores de identidade por meio de um parâmetro de cadeia de caracteres de consulta. Para enviar o token dentro do cabeçalho HTTP Authorization , defina BearerTokenTransmissionMethod metadados como AuthorizationHeader.

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

A solicitação HTTP a seguir demonstra como o token de acesso é passado quando BearerTokenTransmissionMethod é definido como AuthorizationHeader.

GET /oauth2/claims

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

Passar parâmetros retornados pelo ponto de extremidade do token

Alguns provedores de identidade exigem a passagem de parâmetros extras que são retornados do ponto de extremidade do token para o ponto de extremidade de informações do usuário. Por exemplo, a resposta do endpoint do token contém um parâmetro chamado resource, que é um parâmetro obrigatório do endpoint de informações do usuário (além do token de acesso). Use os ExtraParamsInClaimsEndpointRequest metadados para especificar quaisquer parâmetros extras a serem passados. Vários nomes de parâmetros devem ser escapados e separados pelo delimitador vírgula ''.

O JSON a seguir demonstra um retorno de carga JSON pelo ponto de extremidade do token com um parâmetro chamado resource.

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

Para passar o resource parâmetro para o ponto de extremidade de informações do usuário, adicione os seguintes metadados:

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

A solicitação HTTP a seguir demonstra como o resource parâmetro é passado para o ponto de extremidade de informações do usuário.

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

Encerrar ponto de extremidade da sessão

Para desconectar o usuário do aplicativo, redirecione-o para o ponto de extremidade de saída do Azure AD B2C (para OAuth2 e OpenID Connect) ou envie um LogoutRequest (para SAML). O Azure AD B2C limpará a sessão do usuário do navegador. Após uma solicitação de saída, o Azure AD B2C tenta sair de todos os provedores de identidade federados pelos quais o usuário possa ter entrado. O URI de saída do provedor de identidade OAuth2 é configurado nos end_session_endpoint metadados. Quando o usuário fizer logoff do aplicativo por meio do Azure AD B2C, um iframe oculto será criado para chamar a página de saída do end_session_endpoint Azure AD B2C.

A tabela a seguir lista os metadados do ponto de extremidade de informações do usuário.

Metadados genéricos do OAuth2

A tabela a seguir lista os metadados genéricos do provedor de identidade OAuth2. Os metadados descrevem como o perfil técnico OAuth2 lida com a validação de token, obtém as declarações e reage a mensagens de erro.

Chaves criptográficas

O elemento CryptographicKeys contém o seguinte atributo:

URI de redirecionamento

Ao configurar o URI de redirecionamento do seu provedor de identidade, insira https://{tenant-name}.b2clogin.com/{tenant-name}.onmicrosoft.com/oauth2/authresp. Certifique-se de substituir {tenant-name} pelo nome do locatário (por exemplo, contosob2c). O URI de redirecionamento deve ser todo em letras minúsculas.

Conteúdo relacionado

• Saiba como adicionar um provedor de identidade ao seu locatário do Azure Active Directory B2C