plataforma de identidades da Microsoft tokens de acesso

Os tokens de acesso permitem que os clientes chamem as APIs Web protegidas de forma segura. Os tokens de acesso são utilizados pelas APIs Web para efetuar autenticação e autorização.

De acordo com a especificação OAuth, os tokens de acesso são cadeias opacas sem um formato definido. Alguns fornecedores de identidade (IDPs) utilizam GUIDs e outros utilizam blobs encriptados. O formato do token de acesso pode depender da forma como a API que aceita o token está configurada.

As APIs personalizadas registadas pelos programadores no plataforma de identidades da Microsoft podem escolher entre dois formatos diferentes de JSON Web Tokens (JWTs) chamados v1.0 e v2.0. As APIs desenvolvidas pela Microsoft, como o Microsoft Graph ou as APIs no Azure, têm outros formatos de token proprietário. Estes formatos proprietários podem ser tokens encriptados, JWTs ou tokens especiais semelhantes a JWT que não serão validados.

Os clientes têm de tratar os tokens de acesso como cadeias opacas porque os conteúdos do token destinam-se apenas à API. Apenas para fins de validação e depuração, os programadores podem descodificar JWTs com um site como jwt.ms. Os tokens recebidos para uma API da Microsoft podem nem sempre ser um JWT e nem sempre podem ser descodificados.

Para obter detalhes sobre o que está dentro do token de acesso, os clientes devem utilizar os dados de resposta do token devolvidos com o token de acesso ao cliente. Quando o cliente pede um token de acesso, o plataforma de identidades da Microsoft também devolve alguns metadados sobre o token de acesso para o consumo da aplicação. Estas informações incluem o tempo de expiração do token de acesso e os âmbitos para os quais é válido. Estes dados permitem que a aplicação faça uma colocação em cache inteligente de tokens de acesso sem ter de analisar o próprio token de acesso.

Veja as secções seguintes para saber como uma API pode validar e utilizar as afirmações dentro de um token de acesso.

Nota

Toda a documentação nesta página, exceto quando indicado, aplica-se apenas a tokens emitidos para APIs registadas. Não se aplica a tokens emitidos para APIs pertencentes à Microsoft, nem esses tokens podem ser utilizados para validar a forma como o plataforma de identidades da Microsoft emite tokens para uma API registada.

Formatos de token

Existem duas versões de tokens de acesso disponíveis no plataforma de identidades da Microsoft: v1.0 e v2.0. Estas versões determinam as afirmações que estão no token e garantem que uma API Web pode controlar o conteúdo do token.

As APIs Web têm uma das seguintes versões selecionadas como predefinição durante o registo:

  • v1.0 para aplicações apenas Azure AD. O exemplo seguinte mostra um token v1.0 (este exemplo de token não valida porque as chaves rodaram antes da publicação e as informações pessoais foram removidas):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd
    
  • v2.0 para aplicações que suportam contas de consumidor. O exemplo seguinte mostra um token v1.0 (este exemplo de token não valida porque as chaves rodaram antes da publicação e as informações pessoais foram removidas):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
    

A versão pode ser definida para aplicações ao fornecer o valor adequado à accessTokenAcceptedVersion definição no manifesto da aplicação. Os valores de null e 1 resultam em tokens v1.0 e o valor dos 2 resultados em tokens v2.0.

Propriedade do token

Duas partes estão envolvidas num pedido de token de acesso: o cliente, que pede o token e o recurso (API Web) que aceita o token. A aud afirmação num token indica o recurso para o qual o token se destina (a respetiva audiência). Os clientes utilizam o token, mas não devem compreender ou tentar analisá-lo. Os recursos aceitam o token.

O plataforma de identidades da Microsoft suporta a emissão de qualquer versão de token a partir de qualquer ponto final de versão - não estão relacionadas. Quando accessTokenAcceptedVersion está definido como 2, um cliente que chama o ponto final v1.0 para obter um token para esse recurso recebe um token de acesso v2.0.

Os recursos possuem sempre os respetivos tokens através da aud afirmação e são as únicas aplicações que podem alterar os detalhes do token.

Afirmações em tokens de acesso

Os JWTs são divididos em três partes:

  • Cabeçalho – fornece informações sobre como validar o token, incluindo informações sobre o tipo de token e como foi assinado.
  • Payload - Contém todos os dados importantes sobre o utilizador ou a aplicação que está a tentar chamar o serviço.
  • Assinatura – é a matéria-prima utilizada para validar o token.

Cada peça é separada por um ponto final (.) e codificada separadamente por Base64.

As afirmações só estão presentes se existir um valor para o preencher. Uma aplicação não deve assumir uma dependência de uma afirmação presente. Os exemplos incluem pwd_exp (nem todos os inquilinos necessitam que as palavras-passe expirem) e family_name (os fluxos de credenciais do cliente estão em nome de aplicações que não têm nomes). As afirmações utilizadas para validação de tokens de acesso estão sempre presentes.

Algumas afirmações são utilizadas para ajudar a plataforma de identidades da Microsoft tokens seguros para reutilização. Estas afirmações estão marcadas como não sendo para consumo público na descrição como Opaque. Estas afirmações podem ou não aparecer num token e as novas podem ser adicionadas sem aviso prévio.

Afirmações de cabeçalho

Afirmação Formato Descrição
typ Cadeia - sempre JWT Indica que o token é um JWT.
alg String Indica o algoritmo que foi utilizado para assinar o token, por exemplo, RS256.
kid String Especifica o thumbprint para a chave pública que pode ser utilizada para validar esta assinatura do token. Emitidos em tokens de acesso v1.0 e v2.0.
x5t String Funciona da mesma forma (em utilização e valor) que kid. x5t e é uma afirmação legada emitida apenas em tokens de acesso v1.0 para fins de compatibilidade.

Pedidos de payload

Afirmação Formato Descrição
aud Cadeia, um URI ou GUID do ID da Aplicação Identifica a audiência pretendida do token. A API tem de validar este valor e rejeitar o token se o valor não corresponder. Nos tokens v2.0, este valor é sempre o ID de cliente da API. Nos tokens v1.0, pode ser o ID de cliente ou o URI de recurso utilizado no pedido. O valor pode depender da forma como o cliente pediu o token.
iss Cadeia, um URI do serviço de tokens de segurança (STS) Identifica o STS que constrói e devolve o token e o inquilino Azure AD no qual o utilizador foi autenticado. Se o token emitido for um token v2.0 (veja a ver afirmação), o URI termina em /v2.0. O GUID que indica que o utilizador é um utilizador consumidor de uma conta Microsoft é 9188040d-6c67-4c5b-b112-36a304b66dad. A aplicação pode utilizar a parte GUID da afirmação para restringir o conjunto de inquilinos que podem iniciar sessão na aplicação, se aplicável.
idp Cadeia, normalmente um URI de STS Regista o fornecedor de identidade que autenticou o requerente do token. Este valor é idêntico ao valor da afirmação emissor, a menos que a conta de utilizador não esteja no mesmo inquilino que o emissor, como os convidados. Se a afirmação não estiver presente, o valor de iss pode ser utilizado. Para contas pessoais que estão a ser utilizadas num contexto organizacional (por exemplo, uma conta pessoal convidada para um inquilino Azure AD), a idp afirmação pode ser "live.com" ou um URI de STS que contenha o inquilino 9188040d-6c67-4c5b-b112-36a304b66dadda conta Microsoft.
iat int, um carimbo de data/hora Unix Especifica quando ocorreu a autenticação deste token.
nbf int, um carimbo de data/hora Unix Especifica a hora anterior à qual o JWT não pode ser aceite para processamento.
exp int, um carimbo de data/hora Unix Especifica o tempo de expiração em ou após o qual o JWT não pode ser aceite para processamento. Um recurso também pode rejeitar o token antes desta altura. A rejeição pode ocorrer quando é necessária uma alteração na autenticação ou foi detetada uma revogação de tokens.
aio Cadeia Opaca Uma afirmação interna utilizada pelo Azure AD para registar dados para reutilização de tokens. Os recursos não devem utilizar esta afirmação.
acr Cadeia, a 0 ou 1, só presentes em tokens v1.0 Um valor da afirmação "Classe de 0 contexto de autenticação" indica que a autenticação do utilizador final não cumpriu os requisitos de ISO/IEC 29115.
amr Matriz JSON de cadeias, apenas presentes em tokens v1.0 Identifica como o assunto do token foi autenticado.
appid Cadeia, um GUID, apenas presente em tokens v1.0 O ID da aplicação do cliente com o token. A aplicação pode agir como ela própria ou em nome de um utilizador. Normalmente, o ID da aplicação representa um objeto de aplicação, mas também pode representar um objeto do principal de serviço no Azure AD.
azp Cadeia, um GUID, apenas presente em tokens v2.0 Um substituto para appid. O ID da aplicação do cliente com o token. A aplicação pode agir como ela própria ou em nome de um utilizador. Normalmente, o ID da aplicação representa um objeto de aplicação, mas também pode representar um objeto do principal de serviço no Azure AD.
appidacr Cadeia, um 0, 1ou 2, apenas presentes em tokens v1.0 Indica como o cliente foi autenticado. Para um cliente público, o valor é 0. Se for utilizado o ID do cliente e o segredo do cliente, o valor é 1. Se um certificado de cliente tiver sido utilizado para autenticação, o valor é 2.
azpacr Cadeia, , 01ou 2, só presentes em tokens v2.0 Um substituto para appidacr. Indica como o cliente foi autenticado. Para um cliente público, o valor é 0. Se for utilizado o ID do cliente e o segredo do cliente, o valor é 1. Se um certificado de cliente tiver sido utilizado para autenticação, o valor é 2.
preferred_username Cadeia, presente apenas em tokens v2.0. O nome de utilizador principal que representa o utilizador. O valor pode ser um endereço de e-mail, um número de telefone ou um nome de utilizador genérico sem um formato especificado. O valor é mutável e pode mudar ao longo do tempo. Uma vez que o valor é mutável, não pode ser utilizado para tomar decisões de autorização. No entanto, o valor pode ser utilizado para sugestões de nome de utilizador e na IU legível por humanos como um nome de utilizador. O profile âmbito é necessário para receber esta afirmação.
name String Fornece um valor legível por humanos que identifica o assunto do token. O valor não é garantido para ser exclusivo, é mutável e é utilizado apenas para fins de apresentação. O profile âmbito é necessário para receber esta afirmação.
scp Cadeia, uma lista de âmbitos separada por espaço O conjunto de âmbitos expostos pela aplicação para a qual a aplicação cliente pediu (e recebeu) consentimento. A aplicação deve verificar se estes âmbitos são válidos expostos pela aplicação e tomar decisões de autorização com base no valor destes âmbitos. Apenas incluído para tokens de utilizador.
roles Matriz de cadeias, uma lista de permissões O conjunto de permissões expostas pela aplicação que o utilizador ou a aplicação que pede foi dada permissão para ligar. Para tokens de aplicação, este conjunto de permissões é utilizado durante o fluxo de credenciais do cliente em vez de âmbitos de utilizador. Para tokens de utilizador, este conjunto de valores é preenchido com as funções a que o utilizador foi atribuído na aplicação de destino.
wids Matriz de GUIDs RoleTemplateID Indica as funções de todo o inquilino atribuídas a este utilizador, a partir da secção de funções presentes no Azure AD funções incorporadas. Esta afirmação é configurada numa base por aplicação, através da groupMembershipClaims propriedade do manifesto da aplicação. A definição para All ou DirectoryRole é necessária. Pode não estar presente em tokens obtidos através do fluxo implícito devido a problemas de comprimento do token.
groups Matriz JSON de GUIDs Fornece IDs de objeto que representam as associações de grupo do assunto. Estes valores são exclusivos e podem ser utilizados com segurança para gerir o acesso, como a imposição de autorização para aceder a um recurso. Os grupos incluídos na afirmação de grupos são configurados numa base por aplicação, através da groupMembershipClaims propriedade do manifesto da aplicação. Um valor de null exclui todos os grupos, um valor de SecurityGroup inclui apenas associações do Grupo de Segurança do Active Directory e um valor de inclui Grupos de All Segurança e Listas de Distribuição do Microsoft 365.

Veja a hasgroups afirmação para obter detalhes sobre como utilizar a groups afirmação com a concessão implícita. Para outros fluxos, se o número de grupos em que o utilizador se encontra for superior a 150 para SAML e 200 para JWT, Azure AD adiciona uma afirmação de utilização excedida às origens de afirmação. As origens de afirmação apontam para o ponto final do Microsoft Graph que contém a lista de grupos para o utilizador.
hasgroups Booleano Se estiver presente, sempre true, indica se o utilizador está em, pelo menos, um grupo. Utilizado em vez da afirmação para JWTs em fluxos de concessão implícitos se a afirmação de grupos completos expandir o fragmento de URI para além dos groups limites de comprimento do URL (atualmente, seis ou mais grupos). Indica que o cliente deve utilizar o microsoft Graph API para determinar os grupos (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) do utilizador.
groups:src1 Objeto JSON Para pedidos de tokens que não têm comprimento limitado (veja hasgroups) mas que ainda são demasiado grandes para o token, está incluída uma ligação para a lista de grupos completos do utilizador. Para JWTs como uma afirmação distribuída, para SAML como uma nova afirmação em vez da groups afirmação.

Valor JWT de exemplo:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub String O principal sobre o qual o token afirma informações, como o utilizador de uma aplicação. Este valor é imutável e não pode ser reatribuído ou reutilizado. Pode ser utilizado para efetuar verificações de autorização de forma segura, como quando o token é utilizado para aceder a um recurso e pode ser utilizado como chave em tabelas de bases de dados. Uma vez que o assunto está sempre presente nos tokens que Azure AD problemas, utilize este valor num sistema de autorização para fins gerais. O assunto é, no entanto, um identificador em modo de par que é exclusivo de um ID de aplicação específico. Se um único utilizador iniciar sessão em duas aplicações diferentes com dois IDs de cliente diferentes, essas aplicações receberão dois valores diferentes para a afirmação do requerente. Podem ou não ser desejados dois valores diferentes, consoante os requisitos de arquitetura e privacidade. Veja também a oid afirmação (que permanece a mesma em todas as aplicações dentro de um inquilino).
oid Cadeia, um GUID O identificador imutável do requerente, que é o utilizador ou principal de serviço cuja identidade foi verificada. Também pode ser utilizado para efetuar verificações de autorização de forma segura e como chave em tabelas de bases de dados. Este ID identifica exclusivamente o requerente em todas as aplicações. Duas aplicações diferentes que iniciam sessão no mesmo utilizador recebem o mesmo valor na oid afirmação. Pode oid ser utilizado ao efetuar consultas no Microsoft serviços online, como o Microsoft Graph. O Microsoft Graph devolve este ID como a id propriedade de uma determinada conta de utilizador. Uma vez que permite oid que várias aplicações correlacionem principais, o profile âmbito é necessário para receber esta afirmação para os utilizadores. Se existir um único utilizador em vários inquilinos, o utilizador contém um ID de objeto diferente em cada inquilino. As contas são consideradas diferentes, embora o utilizador inicie sessão em cada conta com as mesmas credenciais.
tid Cadeia, um GUID Representa o inquilino no qual o utilizador está a iniciar sessão. Para contas escolares e profissionais, o GUID é o ID de inquilino imutável da organização na qual o utilizador está a iniciar sessão. Para inícios de sessão no inquilino pessoal da conta Microsoft (serviços como Xbox, Teams for Life ou Outlook), o valor é 9188040d-6c67-4c5b-b112-36a304b66dad. Para receber esta afirmação, a aplicação tem de pedir o profile âmbito.
unique_name Cadeia, presente apenas em tokens v1.0 Fornece um valor legível por humanos que identifica o requerente do token. Este valor não é garantido para ser exclusivo dentro de um inquilino e deve ser utilizado apenas para fins de apresentação.
uti String Afirmação do identificador de token, equivalente a jti na especificação JWT. Identificador exclusivo por token sensível a maiúsculas e minúsculas.
rh Cadeia Opaca Uma afirmação interna utilizada pelo Azure para revalidar tokens. Os recursos não devem utilizar esta afirmação.
ver Cadeia, ou 1.02.0 Indica a versão do token de acesso.

Afirmação de utilização excedida de grupos

Azure AD limita o número de IDs de objeto incluídos nos grupos que afirmam permanecer dentro do limite de tamanho do cabeçalho HTTP. Se um utilizador for membro de mais grupos do que o limite de utilização excedida (150 para tokens SAML, 200 para tokens JWT e apenas 6 se emitido através do fluxo implícito), Azure AD não emite a afirmação de grupos no token. Em vez disso, inclui uma afirmação de utilização excedida no token que indica à aplicação para consultar o microsoft Graph API para obter a associação ao grupo do utilizador.

{
    ...
    "_claim_names": {
        "groups": "src1"
    },
    "_claim_sources": {
        "src1": {
            "endpoint": "[Url to get this user's group membership from]"
        }   
    }
    ...
}

Utilize o BulkCreateGroups.ps1 fornecido na pasta Scripts de Criação de Aplicações para ajudar a testar cenários de utilização excedida.

afirmações básicas v1.0

As afirmações seguintes estão incluídas em tokens v1.0, se aplicável, mas não são incluídas em tokens v2.0 por predefinição. Para utilizar estas afirmações para v2.0, a aplicação pede-lhes que utilizem afirmações opcionais.

Afirmação Formato Description
ipaddr String O endereço IP a partir do qual o utilizador se autenticou.
onprem_sid Cadeia, no formato SID Nos casos em que o utilizador tem uma autenticação no local, esta afirmação fornece o SID. Utilize esta afirmação para autorização em aplicações legadas.
pwd_exp int, um carimbo de data/hora Unix Indica quando a palavra-passe do utilizador expira.
pwd_url String Um URL para o qual os utilizadores podem ser enviados para repor a palavra-passe.
in_corp boolean Indica se o cliente está a iniciar sessão a partir da rede empresarial. Se não estiverem, a afirmação não está incluída.
nickname String Outro nome para o utilizador, separado do nome próprio ou apelido.
family_name String Fornece o apelido, apelido ou nome da família do utilizador, conforme definido no objeto de utilizador.
given_name String Fornece o primeiro ou dado nome do utilizador, conforme definido no objeto de utilizador.
upn String O nome de utilizador do utilizador. Pode ser um número de telefone, um endereço de e-mail ou uma cadeia não formatado. Só deve ser utilizado para fins de apresentação e fornecer sugestões de nome de utilizador em cenários de reautenção.

afirmação amr

As identidades podem autenticar-se de diferentes formas, o que pode ser relevante para a aplicação. A amr afirmação é uma matriz que pode conter vários itens, como ["mfa", "rsa", "pwd"], para uma autenticação que utilizou uma palavra-passe e a aplicação Authenticator.

Valor Descrição
pwd Autenticação por palavra-passe, palavra-passe microsoft de um utilizador ou segredo de cliente de uma aplicação.
rsa A autenticação baseou-se na prova de uma chave RSA, por exemplo, com a aplicação Microsoft Authenticator. Este valor também indica se a autenticação foi efetuada por um JWT autoassinado com um certificado X509 pertencente ao serviço.
otp Código de acesso único com um e-mail ou uma mensagem de texto.
fed Foi utilizada uma asserção de autenticação federada (como JWT ou SAML).
wia Autenticação Integrada do Windows
mfa Foi utilizada a autenticação multifator. Quando esta afirmação está presente, os outros métodos de autenticação são incluídos.
ngcmfa Equivalente a mfa, utilizado para o aprovisionamento de determinados tipos de credenciais avançados.
wiaormfa O utilizador utilizou o Windows ou uma credencial de MFA para autenticar.
none Não foi feita nenhuma autenticação.

Duração do token de acesso

A duração predefinida de um token de acesso é variável. Quando emitido, a duração predefinida de um token de acesso é atribuída a um valor aleatório que varia entre 60 a 90 minutos (75 minutos, em média). A variação melhora a resiliência do serviço ao distribuir a procura de tokens de acesso ao longo de um tempo, o que impede picos de tráfego por hora para Azure AD.

Os inquilinos que não utilizam o Acesso Condicional têm uma duração de token de acesso predefinida de duas horas para clientes como o Microsoft Teams e o Microsoft 365.

A duração de um token de acesso pode ser ajustada para controlar a frequência com que a aplicação cliente expira a sessão da aplicação e a frequência com que exige que o utilizador reautilize (de forma silenciosa ou interativa). Para substituir a variação de duração do token de acesso predefinida, defina uma duração de token de acesso predefinida estática com a duração configurada do token (CTL).

A variação de duração do token predefinida é aplicada às organizações que têm a Avaliação de Acesso Contínuo (CAE) ativada. A variação de duração do token predefinida é aplicada mesmo que as organizações utilizem políticas CTL. A duração do token predefinida para uma duração de token de longa duração varia entre 20 e 28 horas. Quando o token de acesso expirar, o cliente tem de utilizar o token de atualização para adquirir automaticamente um novo token de atualização e token de acesso.

As organizações que utilizam a frequência de início de sessão de Acesso Condicional (SIF) para impor a frequência com que ocorrem inícios de sessão não podem substituir a variação de duração do token de acesso predefinida. Quando as organizações utilizam o SIF, o tempo entre pedidos de credenciais para um cliente é a duração do token que varia entre 60 e 90 minutos mais o intervalo de frequência de início de sessão.

Eis um exemplo de como a variação de duração do token predefinida funciona com a frequência de início de sessão. Digamos que uma organização define a frequência de início de sessão a ocorrer a cada hora. O intervalo de início de sessão real ocorre entre 1 hora e 2,5 horas porque o token é emitido com duração que varia entre 60 e 90 minutos (devido à variação de duração do token).

Se um utilizador com um token com uma duração de uma hora executar um início de sessão interativo aos 59 minutos (pouco antes de a frequência de início de sessão ser excedida), não existe nenhum pedido de credenciais porque o início de sessão está abaixo do limiar SIF. Se for emitido um novo token com uma duração de 90 minutos, o utilizador não verá um pedido de credenciais durante mais uma hora e meia. Quando é feita uma renovação silenciosa da duração do token de 90 minutos, Azure AD requer um pedido de credenciais porque o comprimento total da sessão excedeu a definição de frequência de início de sessão de 1 hora. Neste exemplo, a diferença de tempo entre os pedidos de credenciais devido ao intervalo SIF e à variação de duração do token seria de 2,5 horas.

Validar tokens

Nem todas as aplicações devem validar tokens. Apenas em cenários específicos é que as aplicações validem um token:

  • As APIs Web têm de validar os tokens de acesso que lhes são enviados por um cliente. Só têm de aceitar tokens que contenham a respetiva aud afirmação.
  • As aplicações Web confidenciais, como ASP.NET Core, têm de validar os tokens de ID que lhes são enviados através do browser do utilizador no fluxo híbrido, antes de permitir o acesso aos dados de um utilizador ou estabelecer uma sessão.

Se nenhum dos cenários acima se aplicar, a aplicação não beneficiará da validação do token e poderá apresentar um risco de segurança e fiabilidade se as decisões forem tomadas com base na validade do token. Os clientes públicos, como aplicações nativas ou de página única, não beneficiam da validação de tokens porque a aplicação comunica diretamente com o IDP, onde a proteção SSL garante que os tokens são válidos.

As APIs e as aplicações Web só têm de validar tokens que tenham uma afirmação aud que corresponda à aplicação. Outros recursos podem ter regras de validação de tokens personalizadas. Por exemplo, os tokens para o Microsoft Graph não serão validados de acordo com estas regras devido ao formato proprietário. Validar e aceitar tokens destinados a outro recurso é um exemplo do problema de adjunto confuso .

Se a aplicação precisar de validar um token de ID ou um token de acesso, deve primeiro validar a assinatura do token e do emissor relativamente aos valores no documento de deteção openID. Por exemplo, a versão independente do inquilino do documento está localizada em https://login.microsoftonline.com/common/.well-known/openid-configuration.

O middleware Azure AD tem capacidades incorporadas para validar tokens de acesso, veja exemplos para encontrar um no idioma adequado. Existem também várias bibliotecas open source de terceiros disponíveis para validação JWT. Para obter mais informações sobre Azure AD bibliotecas de autenticação e exemplos de código, veja as bibliotecas de autenticação.

Validar a assinatura

Um JWT contém três segmentos, que são separados pelo . caráter. O primeiro segmento é conhecido como o cabeçalho, o segundo como o corpo e o terceiro como a assinatura. O segmento de assinatura pode ser utilizado para validar a autenticidade do token para que possa ser considerado fidedigno pela aplicação.

Os tokens emitidos por Azure AD são assinados com algoritmos de encriptação assimétrica padrão da indústria, como RS256. O cabeçalho do JWT contém informações sobre a chave e o método de encriptação utilizado para assinar o token:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

A alg afirmação indica o algoritmo que foi utilizado para assinar o token, enquanto a kid afirmação indica a chave pública específica que foi utilizada para validar o token.

Em qualquer momento, Azure AD pode assinar um token de ID com qualquer um de um determinado conjunto de pares de chaves público-privado. Azure AD roda o possível conjunto de chaves numa base periódica, pelo que a aplicação deve ser escrita para processar essas alterações de chave automaticamente. Uma frequência razoável para verificar se existem atualizações às chaves públicas utilizadas pelo Azure AD é de 24 em 24 horas.

Adquira os dados da chave de assinatura necessários para validar a assinatura com o documento de metadados do OpenID Connect localizado em:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Dica

Experimente isto num browser: URL

As seguintes informações descrevem o documento de metadados:

  • É um objeto JSON que contém várias informações úteis, como a localização dos vários pontos finais necessários para a autenticação do OpenID Connect.
  • Inclui um jwks_uri, que fornece a localização do conjunto de chaves públicas que correspondem às chaves privadas utilizadas para assinar tokens. A Chave Web JSON (JWK) localizada no jwks_uri contém todas as informações de chave pública em utilização nesse momento específico. O formato JWK é descrito em RFC 7517. A aplicação pode utilizar a kid afirmação no cabeçalho JWT para selecionar a chave pública, neste documento, que corresponde à chave privada que foi utilizada para assinar um token específico. Em seguida, pode efetuar a validação de assinatura com a chave pública correta e o algoritmo indicado.

Nota

Utilize a kid afirmação para validar o token. Embora os tokens v1.0 contenham as x5t afirmações e kid , os tokens v2.0 contêm apenas a kid afirmação.

A validação da assinatura está fora do âmbito deste documento. Existem muitas bibliotecas open source disponíveis para ajudar na validação de assinaturas, se necessário. No entanto, o plataforma de identidades da Microsoft tem uma extensão de assinatura de tokens para as normas, que são chaves de assinatura personalizadas.

Se a aplicação tiver chaves de assinatura personalizadas como resultado da utilização da funcionalidade de mapeamento de afirmações , acrescente um appid parâmetro de consulta que contenha o ID da aplicação para obter um jwks_uri que aponte para as informações da chave de assinatura da aplicação, que devem ser utilizadas para validação. Por exemplo: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contém um jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Autorização baseada em afirmações

A lógica de negócio da aplicação dita a autorização baseada em afirmações. Alguns métodos de autorização comuns estão listados abaixo.

Validar o token

Utilize a aud afirmação para garantir que o utilizador pretendia chamar a aplicação. Se o identificador do recurso não estiver na afirmação, rejeite-o aud .

Validar a permissão do utilizador

Utilize as roles afirmações e wids para validar que o utilizador tem autorização para chamar a API. Por exemplo, um administrador pode ter permissão para escrever na API, mas não um utilizador normal. Verifique se o tid interior do token corresponde ao ID de inquilino utilizado para armazenar os dados na API.

Quando um utilizador armazena dados na API a partir de um inquilino, tem de iniciar sessão novamente nesse inquilino para aceder a esses dados. Nunca permita que os dados num inquilino sejam acedidos a partir de outro inquilino.

Utilize a amr afirmação para verificar se o utilizador efetuou a MFA. A imposição da MFA é efetuada com o Acesso Condicional. Se roles forem pedidas afirmações ou groups no token de acesso, verifique se o utilizador está no grupo autorizado a efetuar esta ação.

Para tokens obtidos com o fluxo implícito, consulte o Microsoft Graph relativamente a estes dados, uma vez que é muitas vezes demasiado grande para caber no token.

Não utilize email nem upn reclame valores para determinar se o utilizador num token de acesso deve ter acesso aos dados. Valores de afirmação mutáveis como estes podem mudar ao longo do tempo, tornando-os inseguros e pouco fiáveis para autorização.

Utilize valores tid de afirmação imutáveis e sub ou oid como uma chave combinada para identificar exclusivamente os dados da API e determinar se um utilizador deve ter acesso a esses dados.

  • Bom: tid + sub
  • Melhor: tid + oid – o oid é consistente entre aplicações, pelo que um ecossistema de aplicações pode auditar o acesso dos utilizadores aos dados.

Não utilize identificadores mutáveis e legíveis por humanos, como email ou upn para identificar dados de forma exclusiva.

Validar o início de sessão da aplicação

  • Utilize a scp afirmação para validar que o utilizador concedeu a permissão da aplicação de chamada para chamar a sua API.
  • Confirme que o cliente de chamada tem permissão para chamar a API com a appid afirmação (para tokens v1.0) ou a azp afirmação (para tokens v2.0).
    • Só precisa de validar estas afirmações (appid, azp) se quiser restringir a sua API Web para ser chamada apenas por aplicações pré-determinadas (por exemplo, aplicações de linha de negócio ou APIs Web chamadas por front-ends conhecidos). As APIs destinadas a permitir o acesso a partir de qualquer aplicação de chamada não precisam de validar estas afirmações.

Tokens de utilizador e de aplicação

Uma aplicação pode receber tokens para um utilizador ou diretamente de uma aplicação através do fluxo de credenciais do cliente. Estes tokens apenas de aplicação indicam que esta chamada vem de uma aplicação e não tem um utilizador a apoiá-la. Estes tokens são processados em grande parte da mesma forma:

  • Utilize roles para ver as permissões que foram concedidas ao assunto do token.
  • Utilize oid ou sub para validar que o principal de serviço de chamada é o esperado.

Se a aplicação precisar de distinguir entre tokens de acesso apenas de aplicações e tokens de acesso para os utilizadores, utilize a idtypafirmação opcional. Para detetar tokens de acesso apenas à aplicação, adicione a idtyp afirmação ao accessToken campo e verifique o valor app. Os tokens de ID e os tokens de acesso dos utilizadores não terão a idtyp afirmação incluída.

Revogação de tokens

Os tokens de atualização podem ser invalidados ou revogados em qualquer altura, por diferentes motivos. Os motivos enquadram-se nas categorias de tempos limite e revogações.

Tempos limite de tokens

Quando uma organização utiliza a configuração de duração do token, a duração dos tokens de atualização pode ser alterada. Espera-se que alguns tokens não sejam utilizados. Por exemplo, o utilizador não abre a aplicação durante três meses e, em seguida, o token expira. As aplicações podem encontrar cenários em que o servidor de início de sessão rejeita um token de atualização devido à sua idade.

  • MaxInactiveTime: se o token de atualização não tiver sido utilizado dentro do tempo ditado pelo MaxInactiveTime, o token de atualização já não é válido.
  • MaxSessionAge: se MaxAgeSessionMultiFactor ou MaxAgeSessionSingleFactor tiverem sido definidos para algo diferente da predefinição (Até revogado), a reautenticação é necessária após o tempo definido nos decorridos maxAgeSession*. Exemplos:
    • O inquilino tem um MaxInactiveTime de cinco dias e o utilizador esteve de férias durante uma semana, pelo que Azure AD não vê um novo pedido de token do utilizador há sete dias. Da próxima vez que o utilizador pedir um novo token, verá que o token de atualização foi revogado e terá de introduzir as credenciais novamente.
    • Uma aplicação sensível tem um MaxAgeSessionSingleFactor de um dia. Se um utilizador iniciar sessão na segunda-feira e na terça-feira (após 25 horas decorridos), terá de voltar a autenticar.

Revogações de tokens

Os tokens de atualização podem ser revogados pelo servidor devido a uma alteração nas credenciais ou devido à utilização ou à ação administrativa. Os tokens de atualização estão nas classes de clientes confidenciais e clientes públicos.

Alterar Cookie baseado em palavra-passe Token baseado em palavra-passe Cookie não baseado em palavra-passe Token não baseado em palavra-passe Token de cliente confidencial
A palavra-passe expira Mantém-se vivo Mantém-se vivo Mantém-se vivo Mantém-se vivo Mantém-se vivo
Palavra-passe alterada pelo utilizador Revoked Revoked Mantém-se vivo Mantém-se vivo Mantém-se vivo
O utilizador faz a SSPR Revoked Revoked Mantém-se vivo Mantém-se vivo Mantém-se vivo
Administração repõe a palavra-passe Revoked Revoked Mantém-se vivo Mantém-se vivo Mantém-se vivo
O utilizador revoga os tokens de atualização com o PowerShell Revoked Revoked Revoked Revoked Revoked
Administração revoga todos os tokens de atualização de um utilizador com o PowerShell Revoked Revoked Revoked Revoked Revoked
Terminar sessão único na Web Revoked Mantém-se vivo Revoked Mantém-se vivo Mantém-se vivo

Não baseada em palavra-passe

Um início de sessão não baseado em palavra-passe é aquele em que o utilizador não escreveu uma palavra-passe para o obter. Exemplos de início de sessão não baseado em palavra-passe incluem:

  • Utilizar o rosto com Windows Hello
  • Chave FIDO2
  • SMS
  • Voz
  • PIN

Para obter mais informações, veja Tokens de Atualização Primária.

Passos seguintes