Compartilhar via

Visão geral dos tokens no Azure Active Directory B2C

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.

O Azure AD B2C (Azure Active Directory B2C) emite diferentes tipos de tokens de segurança à medida que processa cada fluxo de autenticação. Este artigo descreve o formato, as características de segurança e o conteúdo de cada tipo de token.

Tipos de token

O Azure AD B2C dá suporte aos protocolos OAuth 2.0 e OpenID Connect, que usa tokens para autenticação e acesso seguro aos recursos. Todos os tokens usados no Azure AD B2C são JWTs (tokens Web JSON) que contêm declarações de informações sobre o portador e o assunto do token.

Os tokens a seguir são usados na comunicação com o Azure AD B2C:

  • Token de ID – um JWT que contém declarações que você pode usar para identificar usuários em seu aplicativo. Esse token é enviado com segurança em solicitações HTTP para comunicação entre dois componentes do mesmo aplicativo ou serviço. Você pode usar as reivindicações em um token de ID conforme achar adequado. Eles geralmente são usados para exibir informações da conta ou para tomar decisões de controle de acesso em um aplicativo. Os tokens de ID emitidos pelo Azure AD B2C são assinados, mas não são criptografados. Quando seu aplicativo ou API recebe um token de ID, ele deve validar a assinatura para provar que o token é autêntico. Seu aplicativo ou API também deve validar algumas declarações no token para provar que ele é válido. Dependendo dos requisitos de cenário, as declarações validadas por um aplicativo podem variar, mas seu aplicativo deve executar algumas validações comuns de declaração em todos os cenários.

  • Token de acesso – um JWT que contém declarações que você pode usar para identificar as permissões concedidas às suas APIs. Os tokens de acesso são assinados, mas não são criptografados. Os tokens de acesso são usados para fornecer acesso a APIs e servidores de recursos. Quando sua API recebe um token de acesso, ela deve validar a assinatura para provar que o token é autêntico. Sua API também deve validar algumas declarações no token para provar que ela é válida. Dependendo dos requisitos de cenário, as declarações validadas por um aplicativo podem variar, mas seu aplicativo deve executar algumas validações comuns de declaração em todos os cenários.

  • Token de atualização – os tokens de atualização são usados para adquirir novos tokens de ID e tokens de acesso em um fluxo OAuth 2.0. Eles fornecem ao aplicativo acesso de longo prazo a recursos em nome dos usuários sem a necessidade de interação com esses usuários. Os tokens de atualização são opacos para seu aplicativo. Eles são emitidos pelo Azure AD B2C e podem ser inspecionados e interpretados apenas pelo Azure AD B2C. Eles são de longa duração, mas seu aplicativo não deve ser escrito com a expectativa de que um token de atualização dure por um período específico de tempo. Os tokens de atualização podem ser invalidados a qualquer momento por vários motivos. A única maneira de seu aplicativo saber se um token de atualização é válido é tentar resgatá-lo fazendo uma solicitação de token para o Azure AD B2C. Ao trocar um token de atualização por um novo, você recebe um novo token de atualização na resposta. Salve o novo token de atualização. Ele substitui o token de atualização que você usou anteriormente na solicitação. Essa ação ajuda a garantir que seus tokens de atualização permaneçam válidos pelo maior tempo possível. Aplicativos de página única que usam o fluxo de código de autorização com PKCE sempre têm a duração do token de atualização de 24 horas. Saiba mais sobre as implicações de segurança de tokens de atualização no navegador.

Pontos de extremidade

Um aplicativo registrado recebe tokens e se comunica com o Azure AD B2C enviando solicitações para esses pontos de extremidade:

  • https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy-name>/oauth2/v2.0/authorize
  • https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy-name>/oauth2/v2.0/token

Os tokens de segurança que seu aplicativo recebe do Azure AD B2C podem vir dos pontos de extremidade /authorize ou /token. Quando os tokens de ID são adquiridos do:

  • Ponto de extremidade /authorize, isso é feito usando o fluxo implícito, que é geralmente usado para os usuários entrarem em aplicativos Web baseados em JavaScript. No entanto, se o aplicativo usar MSAL.js 2.0 ou posterior, não habilite a concessão de fluxo implícita no registro do aplicativo, pois o MSAL.js 2.0+ dá suporte ao fluxo de código de autorização com PKCE.
  • /tokenponto de extremidade, isso é feito usando o fluxo de código de autorização, que mantém o token oculto do navegador.

Declarações

Ao usar o Azure AD B2C, você tem um controle refinado sobre o conteúdo de seus tokens. Você pode configurar fluxos de usuário e políticas personalizadas para enviar determinados conjuntos de dados de usuário em declarações necessárias para seu aplicativo. Essas declarações podem incluir propriedades padrão, como displayName e emailAddress. Seus aplicativos podem usar essas declarações para autenticar com segurança usuários e solicitações.

As declarações em tokens de ID não são retornadas em uma ordem específica. Novas declarações podem ser introduzidas em tokens de ID a qualquer momento. Seu aplicativo não deve ser interrompido à medida que novas declarações são introduzidas. Você também pode incluir atributos de usuário personalizados em suas declarações.

A tabela a seguir lista as declarações que você pode esperar em tokens de ID e tokens de acesso emitidos pelo Azure AD B2C.

Nome Reclamação Valor de exemplo Descrição
Público aud 00001111-aaaa-2222-bbbb-3333cccc4444 Identifica o destinatário pretendido do token. Para o Azure AD B2C, o público-alvo é a ID do aplicativo. Seu aplicativo deve validar esse valor e rejeitar o token se ele não corresponder. Público-alvo é sinônimo de recurso.
Emissor iss https://<tenant-name>.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/ Identifica o STS (serviço de token de segurança) que constrói e retorna o token. Ele também identifica o diretório no qual o usuário foi autenticado. O aplicativo deve validar a declaração do emissor para garantir que o token venha do ponto de extremidade apropriado.
Emitido em iat 1438535543 A hora em que o token foi emitido, representada na época.
Hora de expiração exp 1438539443 A hora em que o token se torna inválido, representada na época. Seu aplicativo deve usar essa declaração para verificar a validade do tempo de vida do token.
Não antes de nbf 1438535543 O horário em que o token se torna inválido, representado no horário da época. Essa hora geralmente é a mesma da hora em que o token foi emitido. Seu aplicativo deve usar essa declaração para verificar a validade do tempo de vida do token.
Versão ver 1.0 A versão do token de ID, conforme definido pelo Azure AD B2C.
Hash de código c_hash SGCPtt01wxwfgnYZy2VJtQ Um hash de código incluído em um token de ID apenas quando o token é emitido junto com um código de autorização OAuth 2.0. Um hash de código pode ser usado para validar a autenticidade de um código de autorização. Para obter mais informações sobre como executar essa validação, consulte a especificação do OpenID Connect.
Hash do token de acesso at_hash SGCPtt01wxwfgnYZy2VJtQ Um hash de token de acesso incluído em um token de ID apenas quando o token é emitido junto com um token de acesso OAuth 2.0. Um hash de token de acesso pode ser usado para validar a autenticidade de um token de acesso. Para obter mais informações sobre como executar essa validação, consulte a especificação do OpenID Connect
Nonce nonce 12345 Um nonce é uma estratégia usada para reduzir ataques de reprodução de token. O aplicativo pode especificar um nonce em uma solicitação de autorização usando o parâmetro de consulta nonce. O valor fornecido na solicitação é emitido sem modificação apenas na declaração nonce de um token de ID. Essa declaração permite que seu aplicativo verifique o valor em relação ao valor especificado na solicitação. Seu aplicativo deve executar essa validação durante o processo de validação de token de ID.
Assunto sub aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb O item mais importante sobre o qual o token declara informações, como o usuário de um aplicativo. Esse valor é imutável e não pode ser reatribuído nem reutilizado. Ele pode ser usado para executar verificações de autorização com segurança, por exemplo, quando o token é usado para acessar um recurso. Por padrão, a declaração de entidade é preenchida com a ID de objeto do usuário no diretório.
Referência de classe de contexto de autenticação acr Não aplicável Usado somente com políticas mais antigas.
Política de arquitetura de confiança tfp b2c_1_signupsignin1 O nome da política que foi usada para adquirir o token de ID.
Tempo de autenticação auth_time 1438535543 A hora em que um usuário inseriu credenciais pela última vez, representada na época. Não há discriminação entre essa autenticação ser uma nova entrada, uma sessão de logon único (SSO) ou outro tipo de entrada. A auth_time é a última vez em que o aplicativo (ou usuário) iniciou uma tentativa de autenticação em relação ao Azure AD B2C. O método usado para autenticar não é diferenciado.
Escopo scp Read As permissões concedidas ao recurso para um token de acesso. Várias permissões concedidas são separadas por um espaço.
Parte Autorizada azp 975251ed-e4f5-4efd-abcb-5f1a8f566ab7 A ID do aplicativo cliente que iniciou a solicitação.

Configuração

As propriedades a seguir são usadas para gerenciar tempos de vida de tokens de segurança emitidos pelo Azure AD B2C:

  • Tempo de vida do token do Access &ID (minutos) – o tempo de vida do token de portador OAuth 2.0 usado para obter acesso a um recurso protegido. O padrão é de 60 minutos. O mínimo (inclusive) é de 5 minutos. O máximo (inclusivo) é de 1.440 minutos.

  • Tempo de vida do token de atualização (dias) – o período máximo antes do qual um token de atualização pode ser usado para adquirir um novo token de acesso ou ID. O período de tempo também abrange a aquisição de um novo token de atualização se o seu aplicativo tiver recebido o escopo de offline_access. O padrão é 14 dias. O mínimo (inclusive) é de um dia. O máximo (inclusivo) é de 90 dias.

  • Tempo de vida da janela deslizante do token de atualização (dias) – após esse período de tempo decorrido, o usuário é forçado a se autenticar novamente, independentemente do período de validade do token de atualização mais recente adquirido pelo aplicativo. Ele só poderá ser fornecido se o interruptor estiver definido como Limitado. Ele precisa ser maior ou igual ao tempo de vida do token de atualização (dias). Se a opção estiver definida como Sem expiração, você não poderá fornecer um valor específico. O padrão é 90 dias. O mínimo (inclusive) é de um dia. O máximo (inclusivo) é de 365 dias.

Os seguintes casos de uso são habilitados usando estas propriedades:

  • Permitir que um usuário permaneça conectado a um aplicativo móvel indefinidamente, desde que o usuário esteja continuamente ativo no aplicativo. Você pode definir Atualizar duração da janela deslizante do token (dias) para Nenhum vencimento em seu fluxo de usuário de inscrição.
  • Atenda aos requisitos de segurança e conformidade do setor definindo os tempos de vida apropriados do token de acesso.

Essas configurações não estão disponíveis para fluxos de usuário de redefinição de senha.

Compatibilidade

As seguintes propriedades são usadas para gerenciar a compatibilidade de token:

  • Declaração do emissor (iss) – essa propriedade identifica o locatário do Azure AD B2C que emitiu o token. O valor padrão é https://<domain>/{B2C tenant GUID}/v2.0/. O valor de https://<domain>/tfp/{B2C tenant GUID}/{Policy ID}/v2.0/ inclui IDs do locatário do Azure AD B2C e do fluxo de usuário usado na solicitação de token. Se seu aplicativo ou biblioteca precisar que o Azure AD B2C esteja em conformidade com a especificação do OpenID Connect Discovery 1.0, use esse valor.

  • Subject (sub) declaração - Esta propriedade identifica a entidade para a qual o token afirma informações. O valor padrão é ObjectID, que preenche a sub declaração no token com a ID do objeto do usuário. O valor de Não suportado é fornecido apenas para compatibilidade com versões anteriores. É recomendável que você alterne para ObjectID assim que puder.

  • Declaração que representa a ID da política – essa propriedade identifica o tipo de declaração no qual o nome da política usado na solicitação de token é preenchido. O valor padrão é tfp. O valor de acr é fornecido apenas para compatibilidade retroativa.

Passagem

Quando um percurso do usuário é iniciado, o Azure AD B2C recebe um token de acesso de um provedor de identidade. O Azure AD B2C usa esse token para recuperar informações sobre o usuário. Habilitar uma declaração no seu fluxo de usuário para passar o token por meio para os aplicativos que você se registrar no Azure AD B2C. Seu aplicativo deve usar um fluxo de usuário recomendado para aproveitar a passagem do token como uma declaração.

Atualmente, o Azure AD B2C dá suporte apenas à passagem do token de acesso de provedores de identidade OAuth 2.0, que incluem Facebook e Google. Para todos os outros provedores de identidade, a declaração é retornada em branco.

Validação

Para validar um token, seu aplicativo deve verificar a assinatura e as declarações do token. Muitas bibliotecas de software livre estão disponíveis para validar JWTs, dependendo do idioma preferido. É recomendável que você explore essas opções em vez de implementar sua própria lógica de validação.

Validar assinatura

Um JWT contém três segmentos, um cabeçalho, um corpo e uma assinatura. O segmento de assinatura pode ser usado para validar a autenticidade do token para que ele possa ser confiável pelo seu aplicativo. Os tokens B2C do Azure AD são assinados usando algoritmos de criptografia assimétrica padrão do setor, como o RSA 256.

O cabeçalho do token contém informações sobre o método de chave e criptografia usado para assinar o token:

{
        "typ": "JWT",
        "alg": "RS256",
        "kid": "GvnPApfWMdLRi8PDmisFn7bprKg"
}

O valor da declaração alg é o algoritmo usado para assinar o token. O valor da declaração kid é a chave pública que foi usada para assinar o token. A qualquer momento, o Azure AD B2C pode assinar um token usando qualquer um de um conjunto de pares de chave pública-privada. O Azure AD B2C rotaciona periodicamente o possível conjunto de chaves. Seu aplicativo deve estar preparado para lidar com essas mudanças importantes automaticamente. Uma frequência razoável para verificar se há atualizações nas chaves públicas usadas pelo Azure AD B2C é a cada 24 horas. Para lidar com alterações inesperadas de chave, seu aplicativo deve ser projetado para recuperar automaticamente as chaves públicas caso receba um valor kid inesperado.

O Azure AD B2C possui um endpoint de metadados do OpenID Connect. Usando este endpoint, os aplicativos podem solicitar informações sobre o Azure AD B2C em tempo de execução. Essas informações incluem terminais, dados do token e chaves de assinatura de token. Seu locatário do Azure AD B2C contém um documento de metadados JSON para cada política. O documento de metadados é um objeto JSON que contém várias informações úteis. Os metadados contêm jwks_uri, que fornece o local do conjunto de chaves públicas que são usadas para assinar tokens. Esse local é fornecido aqui, mas é melhor buscar o local dinamicamente usando o documento de metadados e analisando jwks_uri:

https://contoso.b2clogin.com/contoso.onmicrosoft.com/b2c_1_signupsignin1/discovery/v2.0/keys

O documento JSON localizado nessa URL contém todas as informações de chave pública em uso em um momento específico. Seu aplicativo pode usar a kid declaração no cabeçalho JWT para selecionar a chave pública no documento JSON usado para assinar um token específico. Em seguida, ele pode executar a validação de assinatura usando a chave pública correta e o algoritmo indicado.

O documento de metadados para a política B2C_1_signupsignin1 no locatário contoso.onmicrosoft.com está localizado em:

https://contoso.b2clogin.com/contoso.onmicrosoft.com/b2c_1_signupsignin1/v2.0/.well-known/openid-configuration

Para determinar qual política foi usada para assinar um token (e para onde ir para solicitar os metadados), você tem duas opções. Primeiro, o nome da política é incluído na declaração tfp (padrão) ou acr (conforme configurado) no token. Você pode analisar as declarações fora do corpo do JWT decodificando em base 64 o corpo e desserializando a cadeia de caracteres JSON resultante. A declaração tfp ou acr é o nome da política que foi usada para emitir o token. A outra opção é codificar a política no valor do state parâmetro quando você emitir a solicitação e decodificá-la para determinar qual política foi usada. Qualquer um dos métodos é válido.

O Azure AD B2C usa o algoritmo RS256, que se baseia na especificação RFC 3447 . A chave pública consiste em dois componentes: o módulo RSA (n) e o expoente público RSA (e). Você pode converter n e e valores programaticamente em um formato de certificado para validação de token.

Uma descrição de como executar a validação de assinatura está fora do escopo deste documento. Muitas bibliotecas de software livre estão disponíveis para ajudá-lo a validar um token.

Validar declarações

Quando seus aplicativos ou API recebem um token de ID, ele também deve executar várias verificações em relação às declarações no token de ID. As seguintes declarações devem ser verificadas:

  • audience - verifica se o token de ID foi destinado ao seu aplicativo.
  • não antes e hora de expiração – verifica se o token de ID não expirou.
  • emissor – Verifica se o token foi emitido para seu aplicativo pelo Azure AD B2C.
  • nonce - uma estratégia para redução de ataque de reprodução de token.

Para obter uma lista completa de validações que seu aplicativo deve executar, consulte a especificação do OpenID Connect.

Conteúdo relacionado

Saiba mais sobre como usar tokens de acesso.