Fluxo de código de autorização do OAuth 2.0 no Azure Active Directory B2C

Artigo
11/06/2023

Você pode usar a concessão de código de autorização OAuth 2.0 em aplicativos instalados em um dispositivo para obter acesso a recursos protegidos, como APIs Web. Usando a implementação do Azure AD B2C (Azure Active Directory B2C) do OAuth 2.0, você pode adicionar tarefas de inscrição, entrada e outras de gerenciamento de identidade aos seus aplicativos móveis e da área de trabalho. Este artigo é independente de linguagem. No artigo, descreveremos como enviar e receber mensagens HTTP sem usar nenhuma biblioteca de software livre. Quando possível, recomendamos que você use as bibliotecas de autenticação da Microsoft (MSAL) compatíveis. Dê uma olhada nos aplicativos de exemplo que usam MSAL.

O fluxo do código de autorização do OAuth 2.0 é descrito na seção 4.1 da especificação do OAuth 2.0. É possível usá-lo para autenticação e autorização na maioria dos tipos de aplicativos, incluindo aplicativos Web, de página única e aplicativos instalados nativamente. Você pode usar o fluxo do código de autorização OAuth 2.0 para adquirir com segurança tokens de acesso e atualizar tokens para os aplicativos, que podem ser usados para acessar recursos protegidos por um servidor de autorização. O token de atualização permite que o cliente adquirir novo acesso (e atualizar) tokens depois que o token de acesso expira, normalmente após uma hora.

Este artigo concentra-se no fluxo de código de autorização do OAuth 2.0 de clientes públicos. Um cliente público é qualquer aplicativo cliente que não é confiável para manter a integridade de uma senha secreta com segurança. Isso inclui aplicativos de página única, aplicativos móveis, aplicativos de área de trabalho e, essencialmente, qualquer aplicativo que não seja executado em um servidor.

Observação

Para adicionar o gerenciamento de identidade em um aplicativo Web usando o Azure AD B2C, use o OpenID Connect em vez do OAuth 2.0.

O Azure AD B2C estende os fluxos padrão do OAuth 2.0 para fazer mais do que simples ações de autenticação e autorização. Ele apresenta o fluxo do usuário. Com os fluxos do usuário, você pode usar o OAuth 2.0 para adicionar experiências do usuário ao seu aplicativo, como inscrição, entrada e gerenciamento de perfil. Os provedores de identidade que usam o protocolo OAuth 2.0 incluem Amazon, Microsoft Entra, Facebook, GitHub, Google e LinkedIn.

Para experimentar as solicitações HTTP neste artigo:

Substitua {tenant} pelo nome de seu locatário do Azure AD B2C.
Substitua 90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 pela ID do aplicativo que você registrou anteriormente em seu locatário Azure AD B2C.
Substitua {policy} pelo nome de uma política que você criou em seu locatário, por exemplo b2c_1_sign_in.

Configuração do URI de redirecionamento necessária para aplicativos de página única

O fluxo de código de autorização para aplicativos de página única requer umas configurações adicionais. Siga as instruções para criar seu aplicativo de página única para marcar corretamente o URI de redirecionamento como habilitado para CORS. Para atualizar um URI de redirecionamento existente para habilitar o CORS, você pode clicar no prompt migrar na seção "Web" do Registros de aplicativo do autenticação. Como alternativa, você pode abrir o Editor de manifesto Registros de aplicativo e definir o type campo para o URI de redirecionamento para spa na replyUrlsWithType seção.

O tipo de redirecionamento spa é compatível com versões anteriores com o fluxo implícito. Os aplicativos que atualmente usam o fluxo implícito para obter tokens podem mudar para o tipo de URI de redirecionamento spa sem problemas e continuar usando o fluxo implícito.

1. Obter um código de autorização

O fluxo do código de autorização começa com o cliente direcionando o usuário para o ponto de extremidade /authorize . Essa é a parte interativa do fluxo, na qual o usuário entra em ação. Nessa solicitação, o cliente indica no parâmetro scope as permissões que ele precisa adquirir do usuário. Os exemplos a seguir (com quebras de linha para facilitar a leitura) mostram como adquirir um código de autorização. Se você estiver testando essa solicitação HTTP GET, use o navegador.

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

Parâmetro	Necessário?	Descrição
{tenant}	Obrigatório	O nome de seu locatário do Azure AD B2C
{policy}	Obrigatório	O fluxo do usuário a ser executado. Especifique o nome de um fluxo de usuário que você criou em seu locatário do Azure AD B2C. Por exemplo: `b2c_1_sign_in`, `b2c_1_sign_up` ou `b2c_1_edit_profile`
client_id	Obrigatório	A ID do aplicativo atribuída ao seu aplicativo no portal do Azure.
response_type	Obrigatório	O tipo de resposta, que deve incluir `code` para o fluxo do código de autorização. Você pode receber um token de ID se o incluir no tipo de resposta, como `code+id_token`, e nesse caso, o escopo precisa incluir `openid`.
redirect_uri	Obrigatório	O URI de redirecionamento do seu aplicativo, no qual as respostas de autenticação são enviadas e recebidas pelo seu aplicativo. Ele deve corresponder exatamente a um dos URIs de redirecionamento registrados no portal, exceto que ele deve ser codificado como URL.
scope	Obrigatório	Uma lista de escopos separados por espaços. O escopo `openid` indica uma permissão para entrar no usuário e obter dados sobre ele na forma de tokens de ID. O escopo `offline_access` é opcional para aplicativos Web. Isso indica que seu aplicativo precisará de um token de atualização para acesso estendido aos recursos. A ID do cliente indica que o token emitido destina-se a ser usado pelo cliente registrado no Azure AD B2C. O `https://{tenant-name}/{app-id-uri}/{scope}` indica uma permissão para os recursos protegidos, como uma API Web. Para obter mais informações, veja Solicitar um token de acesso.
response_mode	Recomendadas	O método que você usa para enviar o código de autorização resultante para seu aplicativo. Pode ser `query`, `form_post` ou `fragment`.
state	Recomendadas	Um valor incluído na solicitação que pode ser uma cadeia de caracteres de qualquer conteúdo que você deseja usar. Geralmente, um valor exclusivo gerado aleatoriamente é usado para evitar ataques de solicitação intersite forjada. O estado também é usado para codificar informações sobre o estado do usuário no aplicativo, antes que a solicitação de autenticação tenha ocorrido. Por exemplo, a página em que o usuário estava ou fluxo de usuário que estava sendo executado.
prompt	Opcional	O tipo de interação do usuário que é necessário. Atualmente, o único valor válido é `login`, que força o usuário a inserir suas credenciais nessa solicitação. O logon único não terá efeito.
code_challenge	recomendado/obrigatório	Usado para proteger as concessões de código de autorização por meio da Chave de Prova para Troca de Código (PKCE). Necessário se `code_challenge_method` estiver incluído. Você precisa adicionar lógica no aplicativo para gerar `code_verifier` e `code_challenge`. O `code_challenge` é um hash SHA256 codificado de URL Base64 de `code_verifier`. Você armazena o `code_verifier` no aplicativo para uso posterior e envia o `code_challenge` junto com a solicitação de autorização. Para mais informações, consulte PKCE RFC. Isso agora é recomendado para todos os tipos de aplicativos: aplicativos nativos, SPAs e clientes confidenciais, como aplicativos Web.
`code_challenge_method`	recomendado/obrigatório	O método utilizado para codificar o `code_verifier` para o parâmetro `code_challenge`. Isso DEVE ser `S256`, mas a especificação permitirá o uso de `plain` se, por algum motivo, o cliente não der suporte a SHA256. Se você excluir o `code_challenge_method`, mas ainda incluir o `code_challenge`, o `code_challenge` será considerado texto não criptografado. A plataforma de identidade da Microsoft tem suporte para `plain` e `S256`. Para mais informações, consulte PKCE RFC. Isso é necessário para aplicativos de página única que usam o fluxo de código de autorização.
login_hint	Não	Pode ser usado para preencher previamente o campo nome de credenciais da página de entrada. Para obter mais informações, consulte prepopular o nome de credenciais.
domain_hint	Não	Fornece uma dica para o Azure AD B2C sobre o provedor de identidade social que deve ser usado para as credenciais. Se um valor válido for incluído, o usuário vai diretamente para a página de entrada do provedor de identidade. Para obter mais informações, consulte redirecionar entrada para um provedor social.
Parâmetros personalizados	Não	Parâmetros personalizados que podem ser usados com políticas personalizadas. Por exemplo, URI de conteúdo de página personalizada dinâmicaou resolvedores de declaração de valor chave.

Nesse ponto, o usuário é solicitado a concluir o fluxo de trabalho do fluxo de usuário. Isso pode exigir que o usuário insira seu nome de usuário e senha, entre com uma identidade social, inscreva-se no diretório ou realize outras etapas. As ações do usuário dependem de como o fluxo de usuário é definido.

Depois que o usuário completar o fluxo de usuário, a ID do Microsoft Entra retornará uma resposta ao seu aplicativo no valor usado para redirect_uri. Ele usa o método especificado no parâmetro response_mode. A resposta é exatamente a mesma para cada um dos cenários de ação do usuário, independentemente de qual fluxo de usuário foi executado.

Uma resposta bem-sucedida que usa response_mode=query tem esta aparência:

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

Parâmetro	Descrição
code	O código de autorização que o aplicativo solicitou. O aplicativo pode usar o código de autorização para solicitar um token de acesso para um recurso de destino. Os códigos de autorização têm uma duração muito curta. Normalmente, eles expiram depois de cerca de 10 minutos.
state	Consulte a descrição completa na tabela na seção anterior. Se um parâmetro `state` for incluído na solicitação, o mesmo valor deverá aparecer na resposta. O aplicativo deve verificar se os valores `state` na solicitação e na resposta são idênticos.

As respostas de erro também podem ser enviadas ao URI de redirecionamento, de modo que o aplicativo possa tratá-las adequadamente:

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

Parâmetro	Descrição
erro	Uma cadeia de caracteres de código de erro que você pode usar para classificar os tipos de erros que ocorrem. Você também pode usar a cadeia de caracteres para reagir a erros.
error_description	Uma mensagem de erro específica que pode ajudar você a identificar a causa raiz de um erro de autenticação.
state	Consulte a descrição completa na tabela anterior. Se um parâmetro `state` for incluído na solicitação, o mesmo valor deverá aparecer na resposta. O aplicativo deve verificar se os valores `state` na solicitação e na resposta são idênticos.

2. Obter um token de acesso

Agora que você adquiriu um código de autorização, será possível resgatar o code de um token para o recurso desejado enviando uma solicitação POST para o ponto de extremidade /token. No Azure AD B2C, você pode solicitar tokens de acesso para outras APIs como de costume, especificando seus escopos na solicitação.

Você também pode solicitar um token de acesso para a própria API Web de back-end do seu aplicativo por convenção de uso da ID do cliente do aplicativo como o escopo solicitado (o que resultará em um token de acesso com essa ID de cliente como o "público-alvo"):

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

Parâmetro	Necessário?	Descrição
{tenant}	Obrigatório	O nome de seu locatário do Azure AD B2C
{policy}	Obrigatório	O fluxo de usuário que foi usado para adquirir o código de autorização. Você não poderá usar um fluxo de usuário diferente nessa solicitação.
client_id	Obrigatório	A ID do aplicativo atribuída ao seu aplicativo no portal do Azure.
client_secret	Sim, em aplicativos da Web	O segredo do aplicativo que foi gerado no portal do Azure. Os segredos de cliente são usados nesse fluxo para cenários de aplicativos Web, em que o cliente pode armazenar com segurança um segredo de cliente. Para cenários de Aplicativo Nativo (cliente público), os segredos de cliente não podem ser armazenados com segurança e, portanto, não são usados nesta recorrência. Se você usar um segredo de cliente, altere-o periodicamente.
grant_type	Obrigatório	O tipo de concessão. Para o fluxo de código de autorização, o tipo de concessão deve ser `authorization_code`.
scope	Recomendadas	Uma lista de escopos separados por espaços. Um valor de escopo único indica à ID do Microsoft Entra que ambas as permissões estão sendo solicitadas. O uso da ID do cliente como o escopo indica que seu aplicativo precisa de um token de acesso que possa ser usado em relação a seu próprio serviço ou API Web, representado pela mesma ID de cliente. O escopo `offline_access` indica que seu aplicativo precisa de um token de atualização para acesso de longa duração a recursos. Você também pode usar o escopo `openid` para solicitar um token de ID do Azure AD B2C.
code	Obrigatório	O código de autorização que você adquiriu do ponto de extremidade `/authorize`.
redirect_uri	Obrigatório	O URI de redirecionamento do aplicativo em que você recebeu o código de autorização.
code_verifier	recomendável	O mesmo `code_verifier` usado para obter o código de autorização. Obrigatório se o PKCE foi usado na solicitação de concessão de código de autorização. Para mais informações, consulte PKCE RFC.

Se estiver testando essa solicitação HTTP POST, use qualquer cliente HTTP, como o Microsoft PowerShell ou o Postman.

Uma resposta de token bem-sucedido tem esta aparência:

{
    "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...",
}

Parâmetro	Descrição
not_before	A hora em que o token é considerado válido, nos valores de hora da época.
token_type	O valor do tipo de token. O único tipo que a ID do Microsoft Entra dá suporte é Portador.
access_token	O JWT (Token Web JSON) assinado que você solicitou.
scope	Os escopos para os quais o token é válido. Você também pode usar os escopos para armazenar tokens em cache para uso posterior.
expires_in	O período de tempo pelo qual o token é válido (em segundos).
refresh_token	Um token de atualização do OAuth 2.0. O aplicativo pode usar esse token para adquirir tokens de acesso adicionais depois que o atual expirar. Os tokens de atualização têm uma vida longa. Você pode usá-los para manter o acesso aos recursos por longos períodos de tempo. Para obter mais informações, consulte a Referência de token do Azure AD B2C.

As respostas de erro tem esta aparência:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

Parâmetro	Descrição
erro	Uma cadeia de caracteres de código de erro que você pode usar para classificar os tipos de erros que ocorrem. Você também pode usar a cadeia de caracteres para reagir a erros.
error_description	Uma mensagem de erro específica que pode ajudar você a identificar a causa raiz de um erro de autenticação.

3. Usar o token

Agora que adquiriu um token de acesso com êxito, você poderá usá-lo em solicitações às suas APIs Web de back-end incluindo-o no cabeçalho Authorization:

GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

4. Atualizar o token

Os tokens de acesso e os tokens de ID tem curta duração. Depois que eles expirarem, você deverá atualizá-los para continuar a acessar recursos. Quando você atualiza o token de acesso, o Azure AD B2C retorna um novo token. O token de acesso atualizado terá os valores de declaração atualizados nbf (não antes), iat (emitido em) e exp (expiração). Todos os outros valores de declaração serão iguais ao token de acesso originalmente emitido.

Para atualizar o token, envie outra solicitação POST ao ponto de extremidade /token. Dessa vez, forneça o refresh_token em vez do 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

Parâmetro	Necessário?	Descrição
{tenant}	Obrigatório	O nome de seu locatário do Azure AD B2C
{policy}	Obrigatório	O fluxo de usuário que foi usado para adquirir o token de atualização original. Você não poderá usar um fluxo de usuário diferente nessa solicitação.
client_id	Obrigatório	A ID do aplicativo atribuída ao seu aplicativo no portal do Azure.
client_secret	Sim, em aplicativos da Web	O segredo do aplicativo que foi gerado no portal do Azure. Os segredos de cliente são usados nesse fluxo para cenários de aplicativos Web, em que o cliente pode armazenar com segurança um segredo de cliente. Para cenários de Aplicativo Nativo (cliente público), os segredos de cliente não podem ser armazenados com segurança e, portanto, não são usados nesta recorrência. Se você usar um segredo de cliente, altere-o periodicamente.
grant_type	Obrigatório	O tipo de concessão. Para este segmento do fluxo de código de autorização, o tipo de concessão deve ser `refresh_token`.
scope	Recomendadas	Uma lista de escopos separados por espaços. Um valor de escopo único indica à ID do Microsoft Entra que ambas as permissões estão sendo solicitadas. O uso da ID do cliente como o escopo indica que seu aplicativo precisa de um token de acesso que possa ser usado em relação a seu próprio serviço ou API Web, representado pela mesma ID de cliente. O escopo `offline_access` indica que o aplicativo precisará de um token de atualização para acessar os recursos de longa duração. Você também pode usar o escopo `openid` para solicitar um token de ID do Azure AD B2C.
redirect_uri	Opcional	O URI de redirecionamento do aplicativo em que você recebeu o código de autorização.
refresh_token	Obrigatório	O token de atualização original que você adquiriu na segunda ramificação do fluxo.