Share via

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

  • Artigo

Pode utilizar a concessão de código de autorização OAuth 2.0 em aplicações instaladas num dispositivo para obter acesso a recursos protegidos, como APIs Web. Ao utilizar a implementação do Azure Active Directory B2C (Azure AD B2C) do OAuth 2.0, pode adicionar tarefas de inscrição, início de sessão e outras tarefas de gestão de identidades às suas aplicações de página única, móveis e de ambiente de trabalho. Este artigo é independente de linguagem. No artigo, descrevemos como enviar e receber mensagens HTTP sem utilizar bibliotecas open source. Sempre que possível, recomendamos que utilize as Bibliotecas de Autenticação da Microsoft (MSAL) suportadas. Veja o exemplo de aplicações que utilizam o MSAL.

O fluxo de código de autorização OAuth 2.0 está descrito na secção 4.1 da especificação OAuth 2.0. Pode utilizá-la para autenticação e autorização na maioria dos tipos de aplicações, incluindo aplicações Web, aplicações de página única e aplicações instaladas nativamente. Pode utilizar o fluxo de código de autorização OAuth 2.0 para adquirir de forma segura tokens de acesso e atualizar tokens para as suas aplicações, que podem ser utilizados para aceder a recursos protegidos por um servidor de autorização. O token de atualização permite que o cliente adquira novos tokens de acesso (e atualização) assim que o token de acesso expirar, normalmente após uma hora.

Este artigo centra-se no fluxo de código de autorização OAuth 2.0 dos clientes públicos . Um cliente público é qualquer aplicação cliente que não pode ser considerada fidedigna para manter em segurança a integridade de uma palavra-passe secreta. Isto inclui aplicações de página única, aplicações móveis, aplicações de ambiente de trabalho e, essencialmente, qualquer aplicação que não seja executada num servidor.

Nota

Para adicionar a gestão de identidades a uma aplicação Web com Azure AD B2C, utilize o OpenID Connect em vez do OAuth 2.0.

Azure AD B2C expande os fluxos OAuth 2.0 padrão para fazer mais do que a autenticação e autorização simples. Apresenta o fluxo de utilizador. Com os fluxos de utilizador, pode utilizar o OAuth 2.0 para adicionar experiências de utilizador à sua aplicação, como inscrição, início de sessão e gestão de perfis. Os fornecedores de identidade que utilizam o protocolo OAuth 2.0 incluem a Amazon, Microsoft Entra ID, Facebook, GitHub, Google e LinkedIn.

Para experimentar os pedidos HTTP neste artigo:

  1. Substitua {tenant} pelo nome do seu Azure AD inquilino B2C.
  2. Substitua 90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 pelo ID da aplicação que registou anteriormente no inquilino do Azure AD B2C.
  3. Substitua {policy} pelo nome de uma política que criou no seu inquilino, por exemplo b2c_1_sign_in.

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

O fluxo de código de autorização para aplicações de página única requer alguma configuração adicional. Siga as instruções para criar a aplicação de página única para marcar corretamente o URI de redirecionamento como ativado para CORS. Para atualizar um URI de redirecionamento existente para ativar o CORS, pode clicar no pedido de migração na secção "Web" do separador Autenticação do Registo de aplicações. Em alternativa, pode abrir a Registos de aplicações editor de manifestos e definir o type campo do URI de redirecionamento como spa na replyUrlsWithType secção .

O spa tipo de redirecionamento é retrocompatível com o fluxo implícito. As aplicações que utilizam atualmente o fluxo implícito para obter tokens podem mover-se para o spa tipo de URI de redirecionamento sem problemas e continuar a utilizar o fluxo implícito.

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

O fluxo de código de autorização começa com o cliente a direcionar o utilizador para o /authorize ponto final. Esta é a parte interativa do fluxo, onde o utilizador toma medidas. Neste pedido, o cliente indica no parâmetro as scope permissões que tem de adquirir ao utilizador. Os exemplos seguintes (com quebras de linha para legibilidade) mostram como adquirir um código de autorização. Se estiver a testar este pedido GET HTTP, utilize o browser.

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? Description
{tenant} Necessário Nome do inquilino do Azure AD B2C
{policy} Necessário O fluxo de utilizador a ser executado. Especifique o nome de um fluxo de utilizador que criou no seu inquilino Azure AD B2C. Por exemplo: b2c_1_sign_in, b2c_1_sign_upou b2c_1_edit_profile.
client_id Necessário O ID da aplicação atribuído à sua aplicação no portal do Azure.
response_type Necessário O tipo de resposta, que tem de incluir code para o fluxo de código de autorização. Pode receber um token de ID se o incluir no tipo de resposta, como code+id_token, e, neste caso, o âmbito tem de incluir openid.
redirect_uri Necessário O URI de redirecionamento da sua aplicação, para onde as respostas de autenticação são enviadas e recebidas pela sua aplicação. Tem de corresponder exatamente a um dos URIs de redirecionamento que registou no portal, exceto que tem de estar codificado com URL.
scope Necessário Uma lista de âmbitos separada por espaços. O openid âmbito indica uma permissão para iniciar sessão no utilizador e obter dados sobre o utilizador sob a forma de tokens de ID. O offline_access âmbito é opcional para aplicações Web. Indica que a sua aplicação precisará de um token de atualização para um acesso alargado aos recursos. O client-id indica que o token emitido se destina a ser utilizado pelo cliente registado Azure AD B2C. Indica https://{tenant-name}/{app-id-uri}/{scope} uma permissão para recursos protegidos, como uma API Web. Para obter mais informações, veja Pedir um token de acesso.
response_mode Recomendado O método que utiliza para enviar o código de autorização resultante de volta para a sua aplicação. Pode ser query, form_postou fragment.
state Recomendado Um valor incluído no pedido que pode ser uma cadeia de qualquer conteúdo que pretenda utilizar. Normalmente, é utilizado um valor exclusivo gerado aleatoriamente para impedir ataques de falsificação de pedidos entre sites. O estado também é utilizado para codificar informações sobre o estado do utilizador na aplicação antes do pedido de autenticação ter ocorrido. Por exemplo, a página em que o utilizador estava ou o fluxo de utilizador que estava a ser executado.
pedido de aviso Opcional O tipo de interação do utilizador que é necessário. Atualmente, o único valor válido é login, o que força o utilizador a introduzir as respetivas credenciais nesse pedido. O início de sessão único não entrará em vigor.
code_challenge recomendado/necessário Utilizado para proteger as concessões de código de autorização através da Chave de Prova para o Code Exchange (PKCE). Necessário se code_challenge_method estiver incluído. Tem de adicionar lógica na sua aplicação para gerar o code_verifier e code_challenge. code_challenge é um hash SHA256 com codificação URL Base64 de code_verifier. Armazene o na sua aplicação code_verifier para utilização posterior e envie-o code_challenge juntamente com o pedido de autorização. Para obter mais informações, veja o RFC do PKCE. Isto é agora recomendado para todos os tipos de aplicações – aplicações nativas, SPAs e clientes confidenciais, como aplicações Web.
code_challenge_method recomendado/necessário O método utilizado para codificar o code_verifier para o code_challenge parâmetro . Deve serS256, mas a especificação permite a utilização de plain se, por algum motivo, o cliente não conseguir suportar SHA256.

Se excluir o code_challenge_method, mas ainda incluir o code_challenge, assume-se que é code_challenge texto simples. plataforma de identidades da Microsoft suporta e plainS256. Para obter mais informações, veja o RFC do PKCE. Isto é necessário para aplicações de página única com o fluxo de código de autorização.
login_hint No Pode ser utilizado para pré-preencher o campo de nome de início de sessão da página de início de sessão. Para obter mais informações, veja Prepopular o nome do início de sessão.
domain_hint No Fornece uma sugestão para Azure AD B2C sobre o fornecedor de identidade social que deve ser utilizado para o início de sessão. Se estiver incluído um valor válido, o utilizador acede diretamente à página de início de sessão do fornecedor de identidade. Para obter mais informações, veja Redirecionar o início de sessão para um fornecedor de redes sociais.
Parâmetros personalizados No Parâmetros personalizados que podem ser utilizados com políticas personalizadas. Por exemplo, URI de conteúdo de página personalizada dinâmica ou resoluções de afirmações chave-valor.

Neste momento, é pedido ao utilizador que conclua o fluxo de trabalho do fluxo de utilizador. Isto pode envolver o utilizador a introduzir o nome de utilizador e a palavra-passe, iniciar sessão com uma identidade social, inscrever-se no diretório ou qualquer outro número de passos. As ações do utilizador dependem da forma como o fluxo de utilizador é definido.

Depois de o utilizador concluir o fluxo de utilizador, Microsoft Entra ID devolve uma resposta à sua aplicação pelo valor que utilizou para redirect_uri. Utiliza o método especificado no response_mode parâmetro . A resposta é exatamente a mesma para cada um dos cenários de ação do utilizador, independentemente do fluxo de utilizador que foi executado.

Uma resposta bem-sucedida que utiliza response_mode=query tem o seguinte aspeto:

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 a aplicação pediu. A aplicação pode utilizar o código de autorização para pedir um token de acesso para um recurso de destino. Os códigos de autorização são de curta duração. Normalmente, expiram após cerca de 10 minutos.
state Veja a descrição completa na tabela na secção anterior. Se um state parâmetro estiver incluído no pedido, o mesmo valor deverá aparecer na resposta. A aplicação deve verificar se os state valores no pedido e na resposta são idênticos.

As respostas de erro também podem ser enviadas para o URI de redirecionamento para que a aplicação possa processá-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 código de erro que pode utilizar para classificar os tipos de erros que ocorrem. Também pode utilizar a cadeia para reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa raiz de um erro de autenticação.
state Veja a descrição completa na tabela anterior. Se um state parâmetro estiver incluído no pedido, o mesmo valor deverá aparecer na resposta. A aplicação deve verificar se os state valores no pedido e na resposta são idênticos.

2. Obter um token de acesso

Agora que adquiriu um código de autorização, pode resgatar o code de um token para o recurso pretendido ao enviar um pedido POST para o /token ponto final. No Azure AD B2C, pode pedir tokens de acesso para outras API como habitualmente, especificando os respetivos âmbitos no pedido.

Também pode pedir um token de acesso para a própria API Web de back-end da sua aplicação por convenção de utilização do ID de cliente da aplicação como âmbito pedido (o que resultará num token de acesso com esse ID de cliente como "audiência"):

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? Description
{tenant} Necessário Nome do seu inquilino Azure AD B2C
{policy} Necessário O fluxo de utilizador utilizado para adquirir o código de autorização. Não pode utilizar um fluxo de utilizador diferente neste pedido.
client_id Necessário O ID da aplicação atribuído à sua aplicação no portal do Azure.
client_secret Sim, no Aplicações Web O segredo da aplicação que foi gerado no portal do Azure. Os segredos do cliente são utilizados neste fluxo para cenários de Aplicações Web, onde o cliente pode armazenar em segurança um segredo do cliente. Para cenários de Aplicação Nativa (cliente público), os segredos do cliente não podem ser armazenados de forma segura e, por conseguinte, não são utilizados nesta chamada. Se utilizar um segredo do cliente, altere-o periodicamente.
grant_type Necessário O tipo de concessão. Para o fluxo de código de autorização, o tipo de concessão tem de ser authorization_code.
scope Recomendado Uma lista de âmbitos separados por espaço. Um valor de âmbito único indica para Microsoft Entra ID de ambas as permissões que estão a ser pedidas. Utilizar o ID de cliente como âmbito indica que a sua aplicação precisa de um token de acesso que possa ser utilizado no seu próprio serviço ou API Web, representado pelo mesmo ID de cliente. O offline_access âmbito indica que a sua aplicação precisa de um token de atualização para acesso de longa duração aos recursos. Também pode utilizar o openid âmbito para pedir um token de ID ao Azure AD B2C.
code Necessário O código de autorização que adquiriu a /authorize partir do ponto final.
redirect_uri Necessário O URI de redirecionamento da aplicação onde recebeu o código de autorização.
code_verifier recomendado O mesmo code_verifier utilizado para obter o código de autorização. Necessário se o PKCE tiver sido utilizado no pedido de concessão de código de autorização. Para obter mais informações, veja o RFC do PKCE.

Se estiver a testar este pedido POST HTTP, pode utilizar qualquer cliente HTTP, como o Microsoft PowerShell ou o Postman.

Uma resposta de token com êxito tem o seguinte aspeto:

{
    "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 O momento em que o token é considerado válido, no tempo de época.
token_type O valor do tipo de token. O único tipo que Microsoft Entra ID suporta é o Portador.
access_token O JSON Web Token (JWT) assinado que pediu.
scope Os âmbitos para os quais o token é válido. Também pode utilizar âmbitos para colocar tokens em cache para utilização posterior.
expires_in O período de tempo durante o qual o token é válido (em segundos).
refresh_token Um token de atualização OAuth 2.0. A aplicação pode utilizar este token para adquirir tokens adicionais após a expiração do token atual. Os tokens de atualização são de longa duração. Pode utilizá-los para manter o acesso aos recursos por longos períodos de tempo. Para obter mais informações, veja o Azure AD referência do token B2C.

As respostas de erro têm o seguinte aspeto:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}
Parâmetro Descrição
erro Uma cadeia de código de erro que pode utilizar para classificar os tipos de erros que ocorrem. Também pode utilizar a cadeia para reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa raiz de um erro de autenticação.

3. Utilize o token

Agora que adquiriu com êxito um token de acesso, pode utilizar o token em pedidos para as SUAS APIs Web de back-end ao incluí-lo no Authorization cabeçalho:

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

4. Atualizar o token

Os tokens de acesso e os tokens de ID são de curta duração. Depois de expirarem, tem de atualizá-los para continuar a aceder aos recursos. Quando atualiza o token de acesso, Azure AD B2C devolve um novo token. O token de acesso atualizado terá atualizado nbf (não antes), iat (emitido em) e exp (expiração) valores de afirmação. Todos os outros valores de afirmação serão os mesmos que o token de acesso originalmente emitido.

Para atualizar o token, submeta outro pedido POST para o /token ponto final. Desta vez, indique 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? Description
{tenant} Necessário Nome do seu inquilino Azure AD B2C
{policy} Necessário O fluxo de utilizador utilizado para adquirir o token de atualização original. Não pode utilizar um fluxo de utilizador diferente neste pedido.
client_id Necessário O ID da aplicação atribuído à sua aplicação no portal do Azure.
client_secret Sim, no Aplicações Web O segredo da aplicação que foi gerado no portal do Azure. Os segredos do cliente são utilizados neste fluxo para cenários de Aplicações Web, onde o cliente pode armazenar em segurança um segredo do cliente. Para cenários de Aplicação Nativa (cliente público), os segredos do cliente não podem ser armazenados de forma segura e, por conseguinte, não são utilizados nesta chamada. Se utilizar um segredo do cliente, altere-o periodicamente.
grant_type Necessário O tipo de concessão. Para esta etapa do fluxo de código de autorização, o tipo de concessão tem de ser refresh_token.
scope Recomendado Uma lista de âmbitos separados por espaço. Um valor de âmbito único indica para Microsoft Entra ID de ambas as permissões que estão a ser pedidas. Utilizar o ID de cliente como âmbito indica que a sua aplicação precisa de um token de acesso que possa ser utilizado no seu próprio serviço ou API Web, representado pelo mesmo ID de cliente. O offline_access âmbito indica que a sua aplicação precisará de um token de atualização para o acesso de longa duração aos recursos. Também pode utilizar o openid âmbito para pedir um token de ID ao Azure AD B2C.
redirect_uri Opcional O URI de redirecionamento da aplicação onde recebeu o código de autorização.
refresh_token Necessário O token de atualização original que adquiriu na segunda parte do fluxo.

Uma resposta de token com êxito tem o seguinte aspeto:

{
    "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 O momento em que o token é considerado válido, no tempo de época.
token_type O valor do tipo de token. O único tipo que Microsoft Entra ID suporta é o Portador.
access_token O JWT assinado que pediu.
scope Os âmbitos para os quais o token é válido. Também pode utilizar os âmbitos para colocar tokens em cache para utilização posterior.
expires_in O período de tempo durante o qual o token é válido (em segundos).
refresh_token Um token de atualização OAuth 2.0. A aplicação pode utilizar este token para adquirir tokens adicionais após a expiração do token atual. Os tokens de atualização são de longa duração e podem ser utilizados para manter o acesso aos recursos por longos períodos de tempo. Para obter mais informações, veja o Azure AD referência do token B2C.

As respostas de erro têm o seguinte aspeto:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}
Parâmetro Descrição
erro Uma cadeia de código de erro que pode utilizar para classificar tipos de erros que ocorrem. Também pode utilizar a cadeia para reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa raiz de um erro de autenticação.

Utilizar o seu próprio diretório Azure AD B2C

Para experimentar estes pedidos, conclua os seguintes passos. Substitua os valores de exemplo que utilizámos neste artigo pelos seus próprios valores.

  1. Crie um diretório B2C Azure AD. Utilize o nome do diretório nos pedidos.
  2. Crie uma aplicação para obter um ID de aplicação e um URI de redirecionamento. Inclua um cliente nativo na sua aplicação.
  3. Crie os fluxos de utilizador para obter os nomes dos fluxos de utilizador.