Entrar na Web com OpenID Connect no Azure Active Directory B2C

O OpenID Connect é um protocolo de autenticação criado com base em OAuth 2.0 que pode ser usado para conectar com segurança os usuários em aplicativos Web. Usando a implementação do Azure AD B2C (Azure Active Directory B2C) do OpenID Connect, você pode terceirizar a inscrição, a entrada e outras experiências de gerenciamento de identidade nos seus aplicativos Web para a ID do Microsoft Entra. Este guia mostra como fazer isso de maneira independente da linguagem. Ele descreve como enviar e receber mensagens HTTP sem usar qualquer uma das nossas bibliotecas de software livre.

O OpenID Connect estende o protocolo de autorização do OAuth 2.0 a ser usado como um protocolo de autenticação. Esse protocolo de autenticação permite que você execute o logon único. Ele apresenta o conceito de um token de ID, que permite ao cliente verificar a identidade do usuário e obter informações básicas de perfil sobre o usuário.

O OpenID Connect também permite que os aplicativos adquiram tokens de acesso com segurança. Você pode usar tokens de acesso para acessar recursos que o servidor de autorização protege. Nós recomendamos o OpenID Connect se você estiver criando um aplicativo Web que fica hospedado em um servidor e é acessado por meio de um navegador. Para obter mais informações sobre os tokens, consulte a visão geral dos tokens no Azure Active Directory B2C

O Azure AD B2C estende o protocolo padrão OpenID Connect para fazer mais do que uma simples ação de autenticação e autorização. Ele apresenta o parâmetro de fluxo de usuário, que habilita o uso do OpenID Connect para adicionar experiências do usuário ao seu aplicativo, como inscrever-se, entrar e gerenciar o perfil.

Enviar solicitações de autenticação

Quando o aplicativo Web precisa autenticar o usuário e executar um fluxo de usuário, ele pode direcionar o usuário para o ponto de extremidade /authorize. O usuário executa a ação dependendo do fluxo do usuário.

Nesta solicitação, o cliente indica as permissões que precisa obter do usuário no parâmetro scope, e especifica o fluxo de usuário a ser executado. Para ter uma ideia de como a solicitação funciona, cole a solicitação em seu navegador e execute-a. Substitua:

• {tenant} pelo nome do seu locatário.
• 90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 com a ID do aplicativo de um aplicativo que você registrou no seu locatário.
• {application-id-uri}/{scope-name} pelo URI da ID de Aplicativo e o Escopo de um aplicativo que você registrou anteriormente em seu locatário.
• {policy} pelo nome da política que você tem no locatário, por exemplo b2c_1_sign_in.

GET /{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
Host: {tenant}.b2clogin.com

client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&response_type=code+id_token
&redirect_uri=https%3A%2F%2Fjwt.ms%2F
&response_mode=fragment
&scope=openid%20offline_access%20{application-id-uri}/{scope-name}
&state=arbitrary_data_you_can_receive_in_the_response
&nonce=12345

Neste ponto, o usuário é convidado a completar o fluxo de trabalho. O usuário pode precisar inserir seu nome de usuário e senha, entrar com uma identidade social ou inscrever-se no diretório. Pode haver qualquer outro número de etapas, dependendo de como o fluxo do usuário é definido.

Depois que o usuário conclui o fluxo de usuário, uma resposta é retornada ao seu aplicativo no parâmetro redirect_uri indicado, usando o método especificado no parâmetro response_mode. A resposta é a mesma para cada um dos casos anteriores, independentemente do fluxo de usuário.

Uma resposta bem-sucedida usando response_mode=fragment se parece com esta:

GET https://jwt.ms/#
id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=arbitrary_data_you_can_receive_in_the_response

As respostas de erro também podem ser enviadas ao parâmetro redirect_uri para que o aplicativo possa tratá-las adequadamente:

GET https://jwt.ms/#
error=access_denied
&error_description=AADB2C90091%3a+The+user+has+cancelled+entering+self-asserted+information.%0d%0aCorrelation+ID%3a+xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%0d%0aTimestamp%3a+xxxx-xx-xx+xx%3a23%3a27Z%0d%0a
&state=arbitrary_data_you_can_receive_in_the_response

Validar o token de ID

Apenas o recebimento de um tokend de ID não é suficiente para autenticar o usuário. Valide a assinatura do token de ID e verificar as declarações no token de acordo com os requisitos do seu aplicativo. O Azure AD B2C usa JWTs (Tokens Web JSON) e criptografia de chave pública para assinar tokens e verificar se eles são válidos.

O Azure AD B2C tem um ponto de extremidade de metadados do OpenID Connect, que permite a um aplicativo obtenha informações sobre o Azure AD B2C no runtime. Essas informações incluem pontos de extremidade, conteúdos de token e chaves de assinatura de token. Há um documento de metadados JSON para cada fluxo de usuário em seu locatário B2C. Por exemplo, o documento de metadados para o fluxo de usuário b2c_1_sign_in em fabrikamb2c.onmicrosoft.com está localizado em:

https://fabrikamb2c.b2clogin.com/fabrikamb2c.onmicrosoft.com/b2c_1_sign_in/v2.0/.well-known/openid-configuration

Uma das propriedades desse documento de configuração é a jwks_uri, cujo valor para o mesmo fluxo de usuário seria:

https://fabrikamb2c.b2clogin.com/fabrikamb2c.onmicrosoft.com/b2c_1_sign_in/discovery/v2.0/keys

Para determinar qual fluxo de usuário foi usado para assinar um token de ID, você tem duas opções. Primeiro, o nome do fluxo de usuário é incluído na declaração acr no token de ID, consulte a declaração que representa o fluxo de usuário. A outra opção é codificar o fluxo de usuário no valor do parâmetro state quando você emitir a solicitação e, em seguida, decodificá-lo para determinar qual fluxo de usuário foi usado. Ambos os métodos são válidos.

Após ter adquirido o documento de metadados a partir do ponto de extremidade de metadados do OpenID Connect, você poderá utilizar as chaves públicas RSA 256 para validar a assinatura do token de ID. Poderá haver várias chaves listadas nesse ponto de extremidade, cada uma identificada por uma declaração kid. O cabeçalho do token de ID também contém uma declaração kid, que indica quais dessas chaves foi usada para assinar o token de ID.

Para verificar os tokens do Azure AD B2C, você precisa gerar a chave pública usando o expoente (e) e o módulo (n). Para fazer isso, você precisa aprender a gerar a chave pública em uma linguagem de programação de sua escolha. A documentação oficial sobre a geração de chave pública com o protocolo RSA pode ser encontrada aqui: https://tools.ietf.org/html/rfc3447#section-3.1

Depois de validar a assinatura do token de ID, há várias declarações que você precisa verificar. Por exemplo:

• Valide a declaração nonce para evitar ataques de reprodução de token. Seu valor deve ser o que você especificou na solicitação de conexão.
• Valide a declaração aud para garantir que o token de ID foi emitido para seu aplicativo. Seu valor deve ser a ID da aplicação do seu aplicativo.
• Valide as declarações iat e exp para garantir que o token de ID não tenha expirado.

Também há várias outras validações que devem ser realizadas. As validações estão descritas detalhadamente nas Especificações básicas do OpenID Connect. Talvez você também queira validar mais declarações, dependendo do cenário. Algumas validações comuns incluem:

• Verifique se o usuário/organização se inscreveu no aplicativo.
• Verifique se o usuário tem autorização/privilégios adequados.
• Verifique se ocorreu uma determinada força de autenticação, como a autenticação multifator do Microsoft Entra.

Depois que o token de ID for validado, você poderá iniciar uma sessão com o usuário. Você pode usar as declarações no token de ID para obter informações sobre o usuário em seu aplicativo. Os usos para essas informações incluem exibição, registros e autorização.

Obter um token

Se você precisar de seu aplicativo Web excute apenas fluxos de usuário, você poderá ignorar as próximas seções. Essas seções são aplicáveis apenas a aplicativos Web que precisam fazer chamadas autenticadas para uma API Web, que é protegida pelo próprio Azure AD B2C.

Você pode resgatar o código de autorização adquirido (usando response_type=code+id_token) para um token do recurso desejado enviando uma solicitação POST ao 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 API Web de back-end do seu aplicativo. Nesse caso, você usa a ID do cliente do aplicativo como o escopo solicitado, o que resulta em um token de acesso com essa ID do cliente como o "público-alvo":

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1
Host: {tenant}.b2clogin.com
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

Uma resposta de token bem-sucedida tem a seguinte aparência:

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "expires_on": "1644254945",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

As respostas de erro se parecem com:

{
    "error": "invalid_grant",
    "error_description": "AADB2C90080: The provided grant has expired. Please re-authenticate and try again. Current time: xxxxxxxxxx, Grant issued time: xxxxxxxxxx, Grant expiration time: xxxxxxxxxx\r\nCorrelation ID: xxxxxxxx-xxxx-xxxX-xxxx-xxxxxxxxxxxx\r\nTimestamp: xxxx-xx-16 xx:10:52Z\r\n"
}

Usar o token

Depois de adquirir 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...

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 são semelhantes aos do token de acesso anterior.

Atualize um token enviando outra solicitação POST ao ponto de extremidade /token. Desta vez, forneça o parâmetro refresh_token em vez do parâmetro code:

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1
Host: {tenant}.b2clogin.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=openid offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

Uma resposta de token bem-sucedida tem a seguinte 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...",
    "refresh_token_expires_in": "1209600"
}

As respostas de erro se parecem com:

{
    "error": "invalid_grant",
    "error_description": "AADB2C90129: The provided grant has been revoked. Please reauthenticate and try again.\r\nCorrelation ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\nTimestamp: xxxx-xx-xx xx:xx:xxZ\r\n",
}

Enviar uma solicitação de saída

Quando você deseja desconectar o usuário do aplicativo, não é suficiente limpar os cookies do aplicativo ou encerrar a sessão com o usuário. Redirecione o usuário para Azure AD B2C para sair. Se você não conseguir fazer isso, o usuário poderá se autenticar novamente em seu aplicativo sem inserir suas credenciais novamente. Para saber mais, confira Comportamento da sessão do Azure AD B2C.

Para desconectar o usuário, redirecione o usuário para end_session_endpoint listado no documento de metadados do OpenID Connect descrito anteriormente:

GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/logout?post_logout_redirect_uri=https%3A%2F%2Fjwt.ms%2F

Após uma solicitação de saída, o Azure AD B2C invalida a sessão com base em cookie do Azure AD B2C e tenta sair de provedores de identidade federados. Para saber mais, confira Logon único.

Proteger seu redirecionamento de logout

Após o logout, o usuário é redirecionado para o URI especificado no parâmetro post_logout_redirect_uri, independentemente das URLs de resposta especificadas para o aplicativo. No entanto, se um valor válido id_token_hint for passado e o token de ID necessário em solicitações de logout estiver ativado, o Azure AD B2C verificará se o valor de post_logout_redirect_uri corresponde a um dos URIs de redirecionamento configurados do aplicativo antes de executar o redirecionamento. Se nenhuma URL de resposta correspondente foi configurada para o aplicativo, uma mensagem de erro será exibida e o usuário não será redirecionado.

Para definir o token de ID necessário em solicitações de logout, consulte configurar o comportamento da sessão no Azure Active Directory B2C.

Próximas etapas

• Saiba mais sobre a sessão do Azure AD B2C.