Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Importante
A partir de 1º de maio de 2025, o Azure AD B2C não estará mais disponível para compra para novos clientes. Saiba mais em nossas perguntas frequentes.
Você pode usar a concessão de código de autorização do 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 inscrição, entrada e outras tarefas de gerenciamento de identidade aos aplicativos de página única, móveis e desktop. Neste artigo, descrevemos como enviar e receber mensagens HTTP sem usar bibliotecas de software livre. Este artigo é independente de idioma. Quando possível, recomendamos que você use as MSAL (Bibliotecas de Autenticação da Microsoft) com suporte. 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. Você pode usá-lo para autenticação e autorização na maioria dos tipos de aplicativos, incluindo aplicativos Web, aplicativos de página única e aplicativos instalados nativamente. Você pode usar o fluxo de código de autorização do OAuth 2.0 para adquirir com segurança tokens de acesso e atualizar tokens para seus aplicativos, que podem ser usados para acessar recursos protegidos por um servidor de autorização. O token de atualização permite que o cliente adquira novos tokens de acesso (e atualize) depois que o token de acesso expirar, normalmente após uma hora.
Este artigo se concentra 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 pode ser confiável para manter com segurança a integridade de uma senha secreta. Isso inclui aplicativos de página única, aplicativos móveis, aplicativos da área de trabalho e, essencialmente, qualquer aplicativo que não seja executado em um servidor.
Observação
Para adicionar o gerenciamento de identidade a 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 OAuth 2.0 padrão para fazer mais do que autenticação e autorização simples. Ele apresenta o fluxo do usuário. Com os fluxos de usuário, você pode usar o OAuth 2.0 para adicionar experiências de 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 ID, 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
00001111-aaaa-2222-bbbb-3333cccc4444pela ID do aplicativo de um aplicativo que você registrou anteriormente em seu locatário do Azure AD B2C. - Substitua
{policy}pelo nome de uma política que você criou em seu locatário, por exemplob2c_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 alguma configuração adicional. 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 ativar o CORS, clique no prompt de migração na seção “Web” da guia Autenticação do registro do aplicativo. Como alternativa, você pode abrir o editor do manifesto de Registros de aplicativo e definir o campo type para o URI de redirecionamento como spa na seção replyUrlsWithType.
O tipo de redirecionamento spa é retrocompatível 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 endpoint /authorize. Essa é a parte interativa do fluxo, em que o usuário toma medidas. Nesta solicitação, o cliente indica no scope parâmetro as permissões que ele precisa adquirir do usuário. Os exemplos a seguir (com quebras de linha para legibilidade) mostram como adquirir um código de autorização. Se você estiver testando essa solicitação HTTP GET, use seu navegador.
GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&response_mode=query
&scope=00001111-aaaa-2222-bbbb-3333cccc4444%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 | Obrigatório? | Descrição |
|---|---|---|
| {inquilino} | Obrigatório | Nome do inquilino do Azure AD B2C |
| {política} | 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. |
| ID do cliente | Obrigatório | A ID do aplicativo atribuída ao seu aplicativo no portal do Azure. |
| tipo_de_resposta | 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. |
| URI de redirecionamento | 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. |
| âmbito | 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. Indica que seu aplicativo precisa de um token de atualização para acesso estendido aos recursos. A client-id indica que o token emitido é destinado para uso pelo cliente registrado do 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, consulte Solicitar um token de acesso. |
| modo_de_resposta | Recomendado | 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. |
| estado | Recomendado | 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. |
| solicitação | Opcional | O tipo de interação do usuário que é necessário. Atualmente, o único valor válido é login, o que força o usuário a inserir suas credenciais nessa solicitação. O logon único não terá efeito. |
| desafio de código | recomendado/obrigatório | Usado para proteger concessões de código de autorização por meio da Chave de Prova para o Code Exchange (PKCE). Necessário se code_challenge_method estiver incluído. Você precisa adicionar lógica em seu aplicativo para gerar o code_verifier e code_challenge. O code_challenge é um hash SHA256 codificado na URL Base64 do code_verifier. Você armazena o code_verifier na sua aplicação 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 permite o uso de plain se, por algum motivo, o cliente não pode dar suporte a SHA256. Se você excluir o code_challenge_method, mas ainda incluir o code_challenge, então o code_challenge será considerado texto sem formatação. A plataforma de identidade da Microsoft dá suporte a ambos plain e S256. Para mais informações, consulte PKCE RFC. Isso é necessário para aplicativos de página única usando o fluxo de código de autorização. |
| login_hint | Não | Pode ser usado para pré-preencher o campo de nome de usuário na página de login. Para obter mais informações, consulte Pré-preencher o nome de entrada. |
| domain_hint | Não | Fornece uma dica ao Azure AD B2C sobre o provedor de identidade social que deve ser usado para entrar. Se um valor válido for incluído, o usuário irá diretamente para a página de entrada do provedor de identidade. Para obter mais informações, consulte Redirecionar o login 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 personalizado dinâmico ou resolvedores de declaração de chave-valor. |
Nesse ponto, o usuário é solicitado a concluir o fluxo de trabalho do fluxo de usuário. Isso pode envolver o usuário inserindo seu nome de usuário e senha, entrando com uma identidade social, inscrevendo-se para o diretório ou qualquer outro número de 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, o Microsoft Entra ID retornará uma resposta ao seu aplicativo no valor usado para redirect_uri. Ele usa o método especificado no response_mode parâmetro. A resposta é exatamente a mesma para cada um dos cenários de ação do usuário, independentemente do fluxo de usuário que 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 |
|---|---|
| código | 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 são de curta duração. Normalmente, eles expiram depois de cerca de 10 minutos. |
| estado | Confira 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 state valores na solicitação e resposta são idênticos. |
As respostas de erro também podem ser enviadas para o URI de redirecionamento para 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. |
| descrição_do_erro | Uma mensagem de erro específica que pode ajudar você a identificar a causa raiz de um erro de autenticação. |
| estado | Confira 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 state valores na solicitação e resposta são idênticos. |
2. Obter um token de acesso
Agora que você adquiriu um código de autorização, você pode resgatar o code por um token para o recurso pretendido enviando uma solicitação POST para o endpoint /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=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=00001111-aaaa-2222-bbbb-3333cccc4444 offline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
| Parâmetro | Obrigatório? | Descrição |
|---|---|---|
| {inquilino} | Obrigatório | Nome do inquilino do Azure AD B2C |
| {política} | Obrigatório | O fluxo de usuário usado para adquirir o código de autorização. Você não pode usar um fluxo de usuário diferente nesta solicitação. |
| ID do cliente | Obrigatório | A ID do aplicativo atribuída ao seu aplicativo no portal do Azure. |
| segredo_do_cliente | Sim, em Aplicativos Web | O segredo do aplicativo foi gerado no portal do Azure. Os segredos do cliente são usados nesse fluxo para cenários de Aplicativo Web, em que o cliente pode armazenar com segurança um segredo do cliente. Para cenários de Aplicativo Nativo (cliente público), os segredos do cliente não podem ser armazenados com segurança e, portanto, não são usados nessa chamada. Se você usar um segredo do cliente, altere-o periodicamente. |
| tipo_de_concessão | 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. |
| âmbito | Recomendado | Uma lista de escopos separados por espaços. Um único valor de escopo indica ao Azure AD B2C ambas as permissões que estão sendo solicitadas. Usar a ID do cliente como escopo indica que seu aplicativo precisa de um token de acesso que possa ser usado em seu próprio serviço ou API Web, representado pela mesma ID do 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 openid escopo para solicitar um token de ID do Azure AD B2C. |
| código | Obrigatório | O código de autorização que você adquiriu do ponto de extremidade /authorize. |
| URI de redirecionamento | Obrigatório | O URI de redirecionamento do aplicativo em que você recebeu o código de autorização. |
| verificador_de_codigo | recomendado | 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 você estiver testando essa solicitação HTTP POST, poderá usar qualquer cliente HTTP, como o Microsoft PowerShell.
Uma resposta de token bem-sucedida é parecida com esta:
{
"not_before": "1442340812",
"token_type": "Bearer",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"scope": "00001111-aaaa-2222-bbbb-3333cccc4444 offline_access",
"expires_in": "3600",
"refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}
| Parâmetro | Descrição |
|---|---|
| não antes | A hora em que o token é considerado válido, nos valores de hora da época. |
| tipo_de_token | O valor do tipo de token. O único tipo que a ID do Microsoft Entra dá suporte é Portador. |
| token_de_acesso | O JWT (Token Web JSON) assinado que você solicitou. |
| âmbito | Os escopos para os quais o token é válido. Você também pode usar os escopos para armazenar tokens em cache para uso posterior. |
| expira_em | O período de tempo em que o token é válido (em segundos). |
| token de atualização | Um token de atualização do OAuth 2.0. O aplicativo pode usar esse token para adquirir tokens adicionais após a expiração do token atual. 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 são semelhantes a esta:
{
"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. |
| descrição_do_erro | 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 você adquiriu com êxito um token de acesso, pode usar o token em solicitações para suas APIs web de back-end, incluindo-o no cabeçalho Authorization.
GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
4. Atualizar o token
Tokens de acesso e tokens de ID são de curta duração. Depois que eles expirarem, você deve 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 são os mesmos que o token de acesso emitido originalmente.
Para atualizar o token, envie outra solicitação POST para o /token endpoint. Desta 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=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=00001111-aaaa-2222-bbbb-3333cccc4444 offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
| Parâmetro | Obrigatório? | Descrição |
|---|---|---|
| {inquilino} | Obrigatório | Nome do inquilino do Azure AD B2C |
| {política} | Obrigatório | O fluxo de usuário usado para adquirir o token de atualização original. Você não pode usar um fluxo de usuário diferente nesta solicitação. |
| ID do cliente | Obrigatório | A ID do aplicativo atribuída ao seu aplicativo no portal do Azure. |
| segredo_do_cliente | Sim, em Aplicativos Web | O segredo do aplicativo foi gerado no portal do Azure. Os segredos do cliente são usados nesse fluxo para cenários de Aplicativo Web, em que o cliente pode armazenar com segurança um segredo do cliente. Para cenários de Aplicativo Nativo (cliente público), os segredos do cliente não podem ser armazenados com segurança e, portanto, não são usados nessa chamada. Se você usar um segredo do cliente, altere-o periodicamente. |
| tipo_de_concessão | Obrigatório | O tipo de concessão. Para esta etapa do fluxo de código de autorização, o tipo de concessão deve ser refresh_token. |
| âmbito | Recomendado | Uma lista de escopos separados por espaços. Um único valor de escopo indica à ID do Microsoft Entra ambas as permissões que estão sendo solicitadas. Usar a ID do cliente como escopo indica que seu aplicativo precisa de um token de acesso que possa ser usado em seu próprio serviço ou API Web, representado pela mesma ID do 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 openid escopo para solicitar um token de ID do Azure AD B2C. |
| URI de redirecionamento | Opcional | O URI de redirecionamento do aplicativo em que você recebeu o código de autorização. |
| token de atualização | Obrigatório | O token de atualização original que você adquiriu na segunda ramificação do fluxo. |
Uma resposta de token bem-sucedida é parecida com esta:
{
"not_before": "1442340812",
"token_type": "Bearer",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"scope": "00001111-aaaa-2222-bbbb-3333cccc4444 offline_access",
"expires_in": "3600",
"refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}
| Parâmetro | Descrição |
|---|---|
| não antes | A hora em que o token é considerado válido, nos valores de hora da época. |
| tipo_de_token | O valor do tipo de token. O único tipo que a ID do Microsoft Entra dá suporte é Portador. |
| token_de_acesso | O JWT assinado que você solicitou. |
| âmbito | Os escopos para os quais o token é válido. Você também pode usar os escopos para armazenar tokens em cache para uso posterior. |
| expira_em | O período de tempo em que o token é válido (em segundos). |
| token de atualização | Um token de atualização do OAuth 2.0. O aplicativo pode usar esse 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 usados 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 são semelhantes a esta:
{
"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 tipos de erros que ocorrem. Você também pode usar a cadeia de caracteres para reagir a erros. |
| descrição_do_erro | Uma mensagem de erro específica que pode ajudar você a identificar a causa raiz de um erro de autenticação. |
Utilize seu próprio diretório do Azure AD B2C
Para experimentar essas solicitações por conta própria, conclua as etapas a seguir. Substitua os valores de exemplo que usamos neste artigo por seus próprios valores.
- Crie um diretório do Azure AD B2C. Use o nome do diretório nas solicitações.
- Crie um aplicativo para obter uma ID do aplicativo e um URI de redirecionamento. Inclua um cliente nativo em seu aplicativo.
- Crie seus fluxos de usuário para obter os nomes de fluxo do usuário.