Referência da API de autenticação nativa v2

Aplica-se a: Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica a locatários externos. Locatários externos (saiba mais)

Abordagem de autenticação: Autenticação nativa inserida.

A API de Autenticação Nativa usa um fluxo controlado por resposta em ID externa do Microsoft Entra locatários externos. Inicie a autorização, conclua as interações de autenticação retornadas, retome a autorização e troque o código de autorização por tokens. Essa referência define operações compartilhadas; As referências específicas do percurso definem a descoberta de entrada, os atributos de inscrição e a redefinição de senha.

Para uma integração V1 existente, use a referência da API V1. Consulte Migrar de V1 para V2 para versões de pacote, requisitos de migração e detalhes de integração do SDK.

Prerequisites

Importante

A API de Autenticação Nativa V2 está em versão prévia. A API de Autenticação Nativa V1 permanece disponível em geral. Consulte os Termos de Uso Complementares para visualizações de Microsoft Azure para termos legais que se aplicam aos recursos de visualização.

  • Um locatário externo e um aplicativo configurados para fluxos de autenticação nativa e cliente público. Consulte Configurar um aplicativo.
  • Um fluxo de usuário associado ao aplicativo.
  • Um domínio de URL personalizado verificado pelo locatário configurado para todas as chamadas à API de serviço.
  • As permissões delegadas e o consentimento exigidos pelo recurso de destino, se você solicitar acesso a uma API.
  • Para SPAs com autenticação nativa inserida e sites de UX BYO, uma política de proxy ou borda que implementa os requisitos de proxy do navegador.

Operações e autoridade

Os exemplos usam https://{custom_domain}/{tenant}, onde custom_domain é um domínio de autenticação verificado pelo locatário, como login.contoso.com, e tenant é sua ID de Diretório (locatário), um GUID. client_id é a ID do aplicativo (cliente). Todas as URLs de chamada de API de serviço usam esse domínio personalizado, incluindo desafios de autorização e troca de tokens. Consulte Configurar a autoridade de API.

Com exceção da solicitação de autorização inicial e da troca de tokens, use a URL anunciada pela resposta atual. As IDs do método são opacas. Resolva links relativos na origem da autoridade configurada, valide o destino e mantenha o caminho e a consulta retornados inalterados.

O início, o currículo e a troca de código de autorização abaixo descrevem a autenticação nativa inserida. Em vez disso, uma página de UX BYO usa a entrega do navegador e o link de término retornado em torno das operações de interação nativa compartilhadas. Não inicie ou retome /authorize-challenge dentro dessa transação de UX BYO.

Operation Método Caminho ou link
Iniciar autorização POST /{tenant}/oauth2/v2.0/authorize-challenge
Retomar autorização POST Link retornado continue .
Iniciar entrada POST Link retornado sign_in ; exemplos usam /{tenant}/api/v2.0/signin/start.
Iniciar inscrição POST Link retornado sign_up ; exemplos usam /{tenant}/api/v2.0/signup/start.
Enviar atributos de inscrição POST Link retornado submitAttributes .
Iniciar redefinição de senha POST Link de redefinição-senha retornado; exemplos de uso /{tenant}/api/v2.0/resetpassword/start.
Iniciar a redefinição de senha embutida POST Link retornado recover do método password.
Registrar um método de autenticação POST Link retornado enroll do método selecionado.
Ativar um método de autenticação POST Link retornado activate .
Desafiar ou reenviar POST Retornado challenge ou resend link.
Verificar uma credencial POST Link retornado verify .
Atualizar uma senha PUT Link retornado update .
Atualização de senha de votação POST Link retornado poll .
Exchange um código de autorização POST /{tenant}/oauth2/v2.0/token

Exemplos nativos usam /api/v2.0; As operações OAuth usam /oauth2/v2.0. Use o GUID do locatário nesses exemplos de autoridade. Siga os links retornados sem reescrever seus caminhos, versões ou parâmetros de consulta.

Headers

OAuth e as operações de autenticação nativa usam codificações de corpo diferentes.

Header Usar
Content-Type: application/x-www-form-urlencoded Necessário para o desafio de autorização e solicitações de token.
Content-Type: application/json Necessário para corpos de solicitação de autenticação nativa.
Accept: application/hal+json Recomendado para solicitações de autenticação nativas.
client-request-id: {guid} Recomendado. Gere um novo valor para cada fluxo e mantenha-o para diagnóstico.

Requisitos de proxy do navegador

Esses requisitos se aplicam a chamadas à API do navegador de SPAs com autenticação nativa inserida e sites de UX BYO. Aplicativos Android e iOS usando transportes HTTP nativos não precisam de configuração cors ou um proxy CORS.

Identificador de rotas OPTIONSde autenticação nativa, mas não conceda acesso à origem do navegador por meio Access-Control-Allow-Originde . As integrações entre origens do navegador, portanto, precisam de uma configuração de proxy ou de borda que:

  • Encaminha a resposta de pré-vôo bem-sucedida do serviço e aplica a política de origem do navegador configurada.
  • Retorna Access-Control-Allow-Origin para essa origem exata permitida, não *.
  • Permite o método ou PUT o método necessário POST da operação e os cabeçalhos de solicitação usados pela integração.
  • Preserva corpos de solicitação, códigos de status de resposta, tipos de conteúdo e links de transação sem armazenar em cache respostas de autenticação.
  • Manipula a origem e o roteamento consistentemente entre autorização, operações nativas e troca de tokens.
  • Preserva as diretrizes de repetição, incluindo Retry-Aftere expõe-as ao código do navegador quando necessário.

Consulte os conceitos de CORS de autenticação nativa para o limite do navegador e a configuração de proxy local para desenvolvimento.

Tokens de continuação

Um token de continuação representa a transação de autenticação em seu estágio atual. Ele está associado ao locatário, ao cliente, ao cenário e à ação.

Formato da mensagem Field
OAuth continuation_token
API de autenticação nativa continuationToken

Use apenas o token atual com a operação identificada pela mesma resposta. Não analise, modifique, registre ou mantenha-o além da transação ativa. Quando uma resposta fornece uma substituição, pare de usar o token anterior. Não mova um token para outro usuário ou percurso. Reinicie a autorização após a expiração.

A validade padrão documentada é de 10 minutos para um token de continuação individual. Manipular a expiração de acordo com a resposta do serviço; um token mais recente não é uma garantia de estender todo o percurso. O token e uma senha única têm tempos de vida separados. Os códigos de autorização são de curta duração e de uso único; não interprete uma resposta de expires_in token como o tempo de vida de código de autorização.

Modelo de resposta

Operações de interação nativa bem-sucedidas retornam HAL JSON. A próxima ação pode ser diferente até mesmo para chamadas sucessivas para o mesmo ponto de extremidade. Os campos são específicos para a resposta: por exemplo, um redirecionamento pode conter apenas state.

Membro Purpose
continuationToken Token para a próxima solicitação permitida, quando incluído.
state Estado da transação atual.
action Interação necessária para uma interactionRequired resposta.
_links URLs para operações permitidas.
_embedded Recursos relacionados, incluindo métodos disponíveis.

O conceito de fluxo explica os estados e as ações. Para interactionRequired, manipule a ação retornada usando uma operação permitida. Para continue, retome a autorização por meio do link retornado. O estado de completed uma operação individual não confirma se os tokens foram emitidos.

Uma transação nativa que não pode continuar pode retornar:

{
  "state": "redirect"
}

Essa resposta não fornece um token de continuação, links ou uma URL de entrega do navegador. Interrompa solicitações nativas e ofereça uma entrada de navegador configurada separadamente ou uma falha clara. A entrada do navegador reinicia a autenticação; não retoma o progresso nativo.

Ação de seleção de conta

Note

A seleção de conta não é relevante na autenticação nativa inserida e ainda não tem suporte para páginas auto-hospedadas do BYO UX.

disambiguate identifica a seleção da conta em state: interactionRequired.

Use links da resposta mais recente e valide sua autoridade antes de encaminhar segredos.

Relação Purpose
self Recurso ou operação atual.
discover Envie um identificador de entrada.
challenge Inicie o desafio do método selecionado.
verify Verifique uma senha ou senha única.
resend Solicite outra senha única.
submitAttributes Envie valores de inscrição solicitados.
recover Inicie a recuperação de senha na transação de entrada ativa.
enroll Inicie o registro de um método de autenticação anunciado.
activate Verifique o código de um método registrado.
update Envie uma senha de substituição.
poll Verifique uma atualização assíncrona.
continue Retomar a autorização do OAuth.

Essa ação é relevante para a seleção da conta byo (UX do Bring Your Own UX). No momento, não há suporte para integrações de autenticação nativa inseridas e não há suporte para a seleção de conta na página de UX BYO auto-hospedada.

Se sua integração de UX BYO seguir a solução alternativa recomendada enviando login_hint ou prompt=login na solicitação de autorização, a introdução à seleção de conta não interromperá ou interromperá sua experiência de usuário existente.

O conteúdo da ação faz parte da entrega existente do initialResponse navegador BYO UX e inclui:

  • state: interactionRequired, action: disambiguatee um continuationToken para a seleção pendente.
  • Uma _embedded.user matriz com informações sobre cada conta oferecida e links com suporte. Uma conta ativa tem uma URL específica _links.resume da conta.
  • Uma URL no nível _links.discover de resposta para uma conta inativa ou use outra conta.

Recursos do método de autenticação

A seleção do método de credencial existente usa _embedded.methods. O serviço também pode selecionar um único método. Uma credencial existente tem uma credencial opaca id, type como password, emailou sms, e links para operações permitidas. Um mascarado hint identifica um destino sem divulgá-lo na íntegra; isPreferred são metadados de preferência opcionais. As opções de registro têm uma representação separada e não precisam de uma ID de credencial existente.

{
  "_embedded": {
    "methods": [
      {
        "id": "{id}",
        "type": "email",
        "hint": "u***@contoso.com",
        "isPreferred": true,
        "_links": {
          "challenge": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{id}/challenge"
          },
          "verify": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{id}/verify"
          }
        }
      }
    ]
  }
}

Este fragmento ilustra os metadados do método. A disponibilidade do método é determinada para cada transação. Seu aplicativo pode apresentar métodos disponíveis ou selecionar um por meio da lógica de fluxo do aplicativo. O desafio e a verificação operam no método selecionado; O registro do método tem um contrato separado.

Não exija metadados de apresentação opcionais, como pages ou scenario. Os exemplos descrevem as interações básicas de senha e email/SMS, não todos os requisitos adicionais específicos do método.

Iniciar autorização

Envie o aplicativo, os escopos e as declarações opcionais na solicitação inicial. Valores de codificação de formulário; as quebras de linha abaixo são para legibilidade.

POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
scope=openid%20profile%20offline_access&
response_type=code
Parameter Usar
client_id ID do aplicativo obrigatório (cliente).
scope Escopos de suas solicitações de aplicativo. Inclua o OIDC (OpenID Connect) e os escopos de recurso necessários para os tokens resultantes.
response_type code neste exemplo. O ponto de extremidade retorna um código de autorização após a autenticação.
claims Solicitação de declarações do OpenID Connect codificada em JSON opcional.

Quando a autenticação é necessária, a resposta é 401 Unauthorized, com Content-Type: application/json:

{
  "error": "InsufficientAuthorization",
  "error_description": "AADSTS500127: No authenticated credentials found in request.",
  "error_codes": [
    500127
  ],
  "timestamp": "2026-08-28T17:30:00Z",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
  "continuation_token": "******",
  "reset_password": "/{tenant}/api/v2.0/resetpassword/start",
  "sign_in": "/{tenant}/api/v2.0/signin/start",
  "sign_up": "/{tenant}/api/v2.0/signup/start"
}

As URLs de entrada e de inscrição são condicionais. Os links de jornada são propriedades de resposta OAuth de nível superior, não _links entradas. Selecione um percurso anunciado e envie seu token como continuationToken na solicitação JSON. Lidar com qualquer política ou rejeição específica da conta.

Retomar autorização

Quando a resposta atual retornar state: continue, poste o token mais recente em _links.continue.href. Não reenviar a inicial client_id, scopeou claims nesta solicitação.

POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
continuation_token={continuation_token}

A resposta bem-sucedida é 200 OK json:

{
  "code": "{authorization_code}"
}

Os códigos de autorização são de curta duração e uso único. Exchange o código em vez de tratá-lo como um token de acesso.

Exchange o código de autorização

Poste o código com a mesma ID do aplicativo:

POST https://{custom_domain}/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
grant_type=authorization_code&
code={authorization_code}

Todos os três parâmetros são necessários. grant_type é authorization_code. Essa solicitação de cliente público não contém um segredo do cliente.

A resposta bem-sucedida é 200 OK json:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "******",
  "id_token": "******",
  "refresh_token": "******"
}

Os campos de token dependem dos escopos e declarações estabelecidos inicialmente. Um token de atualização é retornado somente quando a solicitação inicial inclui offline_access. O valor de expiração de exemplo não é uma garantia de tempo de vida fixa. Não solicite offline_access se seu aplicativo não precisa de um token de atualização.

Desafiar ou reenviar

Siga o link do challenge método selecionado ou um link atual resend quando o cliente solicitar outra senha:

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/{methodType}/{id}/challenge
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

Um desafio por email pode retornar:

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "verify",
  "id": "{email_method_id}",
  "type": "email",
  "hint": "u***@contoso.com",
  "codeLength": 8,
  "_links": {
    "verify": {
      "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
    },
    "resend": {
      "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
    }
  }
}

O SMS usa a mesma forma de desafio de credencial com type: sms, uma dica de telefone mascarada e seus links de método retornados. Os desafios de senha não enviam senha e retornam uma ação de senha verify . Use o comprimento retornado codeLength, não o tamanho do exemplo. Siga os limites de tentativa e reenviamento controlados pelo serviço.

Verificar uma credencial

Poste no link atual verify . Para um método de senha:

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{id}/verify
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "password": "******"
}

Para um email ou método SMS:

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/{methodType}/{id}/verify
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "otp": "{one_time_passcode}"
}

A verificação pode retornar outro desafio, coleção de atributos, uma atualização de senha ou continuação. Manipule a ação retornada. A verificação não é idempotente; não tente novamente automaticamente após uma falha de rede ambígua.

Registro do método de autenticação

A inscrição ou entrada pode exigir o registro embutido por meio action: enrollde , seguido por action: activate. O registro é separado da coleta de atributos de perfil ou da verificação de uma credencial existente.

Importante

O registro é separado da autenticação com um método registrado. Use apenas os métodos de registro anunciados para a transação atual; não inferir uma operação de registro de um desafio de credencial.

Selecionar e registrar um método

Selecione um método _embedded.methods com suporte e siga sua _links.enroll URL.

Método Anúncio Campos JSON necessários
SMS de telefone type: phone, com sms em channels. continuationToken, phoneNumber incluindo o código do país e channel: sms.
Email type: email. continuationToken e email. Não envie um channel.

O registro telefônico usa, não o sms tipo usado pelos métodos type: phonede desafio de SMS existentes. O exemplo de URL de registro de telefone é /{tenant}/api/v2.0/auth/methods/phone; a URL de email é /{tenant}/api/v2.0/auth/methods/email. Use POST com JSON e siga a URL anunciada em vez de construir uma.

Para registro de SMS por telefone, o corpo é:

{
  "continuationToken": "******",
  "phoneNumber": "+1 2025550123",
  "channel": "sms"
}

Para o registro de email, o corpo é:

{
  "continuationToken": "******",
  "email": "user@contoso.com"
}

O serviço envia uma senha e retorna action: activate, um novo token de continuação e um activate link. Exiba a máscara retornada hint e codeLength quando presente. Email e SMS podem usar diferentes comprimentos de código.

Uma resposta de ativação de telefone pode ser:

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "activate",
  "id": "{phone_method_id}",
  "type": "phone",
  "channel": "sms",
  "hint": "***0123",
  "codeLength": 6,
  "_links": {
    "activate": {
      "href": "/{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activate"
    },
    "resend": {
      "href": "/{tenant}/api/v2.0/auth/methods/phone"
    }
  }
}

Use os campos e links da resposta real; O email usa seu próprio tipo de método, comprimento de código e links.

Ativar ou reenviar

Envie um JSON POST para o link atual activate com o código mais recente continuationToken e o código do usuário em otp. Exemplos de telefone usam /{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activate; o email usa seu próprio link anunciado. Não envie códigos de ativação para o link de verify uma credencial.

{
  "continuationToken": "******",
  "otp": "{one_time_passcode}"
}

Se a resposta de ativação for anunciada resend, envie um JSON POST contendo apenas o mais recente continuationToken para esse link. O link pode apontar de volta para o registro. Não retenha ou reenvia os detalhes do contato; o token carrega o contexto de registro.

{
  "continuationToken": "******"
}

Substitua o token ativo, os links, a dica e o comprimento do código após cada resposta. Continue tratando ações retornadas após a ativação; só state: continue permite a retomada da autorização. O registro por si só pode satisfazer a MFA, portanto, um desafio de credencial separado nem sempre é necessário.

Para invalidGrant com innerError.code: invalidOneTimeCode, mantenha o token de ativação atual e os links anunciados. Permitir que o usuário corrija o código ou solicite uma reenviação. Não reproduza automaticamente o registro ou a ativação após uma falha de conexão ambígua.

Erros

Os erros de OAuth usam campos como error, error_descriptione trace_idcorrelation_id. Falhas de autenticação nativas usam um envelope aninhado. Por exemplo, um código de verificação de email incorreto pode retornar HTTP 400 com:

{
  "error": {
    "code": "invalidGrant",
    "message": "AADSTS50181: Unable to validate the otp.",
    "timestamp": "2026-08-28T17:30:00Z",
    "traceId": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "innerError": {
      "code": "invalidOneTimeCode"
    }
  }
}

Use códigos estáveis para lidar em vez de mensagens localizadas. A validação de atributo pode retornar error.innerError.code: attributeValidationError com details entradas que contêm code, messagee attributeIds, além de opcional suggestions ou recovery. Verificar o status HTTP e o tipo de conteúdo antes da análise; não renderize um corpo de erro HTML inesperado no aplicativo.

Condition Status ou erro Processamento
Parâmetro OAuth inválido 400 invalid_request Corrija a solicitação; não tente novamente inalterado.
Código inválido ou expirado 400 invalid_grant Reinicie a autorização.
Aplicativo inválido 400 invalid_client Configuração correta do aplicativo.
Escopo inválido ou inválido 400 invalid_scope Verifique os escopos e o consentimento solicitados.
Autenticação necessária 401 InsufficientAuthorization Siga um link de percurso habilitado.
Token/estado de continuação inválido 400 invalidRequest Reinicie o fluxo aplicável.
Token de atualização de senha expirado 400 expiredToken com innerError.code: expiredContinuationToken Reinicie a autorização.
Código de verificação ausente 400 invalidRequest Corrija a entrada ausente.
Código de verificação de SMS ou email incorreto 400 invalidGrant com innerError.code: invalidOneTimeCode Permitir que o usuário corrija o código usando o estado de verificação atual utilizável ou siga um link de reenviamento anunciado. Não reenvie automaticamente.
Código de ativação incorreto 400 invalidGrant com innerError.code: invalidOneTimeCode Mantenha o token de ativação atual e os links anunciados. Permitir que o usuário corrija o código ou use uma ação de reenviamento anunciada. Não reenvie automaticamente.
Interação do navegador necessária invalid_grant com web_redirect_required Pare solicitações nativas e use o caminho de recuperação interativo configurado. Não encaminhe o token de continuação para uma URL arbitrária.
A transação nativa não pode continuar Corpo nativo {"state":"redirect"} Pare solicitações nativas. Uma entrada separada do navegador não preserva o progresso nativo.
Limitação 429 Diretrizes de honra Retry-After e servidor.

Falhas de rede e serviço podem usar outros formatos de resposta. Trate um tipo de conteúdo inesperado como uma falha explícita. A tabela descreve casos comuns específicos, não um catálogo de erros exaustivo para cada operação.

Segurança e diagnóstico

Use HTTPS para cada solicitação upstream. Mantenha senhas, senhas, tokens de continuação, códigos e tokens emitidos fora de URLs, logs, telemetria, exceções, capturas de tela e anexos de suporte. Não armazene em cache respostas de autenticação ou compartilhe o estado da transação entre usuários.

Rejeite autoridades e redirecionamentos inesperados em vez de encaminhar segredos. Não tente automaticamente a verificação de credenciais, envios de criação de conta ou atualizações de senha após uma falha ambígua.

Exiba apenas as dicas mascaradas fornecidas pelo serviço. Use falhas de descoberta genéricas para que as mensagens e a apresentação do método não divulguem desnecessariamente a existência da conta.

Mantenha o diagnóstico seguro: status HTTP, categoria da operação, client-request-idIDs de rastreamento/correlação de serviço e carimbo de data/hora. Os nomes OAuth usam sublinhados; Os nomes de erro de autenticação nativa usam maiúsculas e minúsculas. Extraia esses campos de diagnóstico sem reter a solicitação completa ou os corpos de resposta.

Extensões de autenticação personalizadas

A configuração de eventos e os contratos são específicos para cada extensão e jornada. Seu aplicativo continua selecionando operações permitidas de respostas de serviço quando uma extensão participa do fluxo.

A cobertura de eventos nativos inclui OnOtpSend email e OnTokenIssuanceStart. OnAttributeCollectionStart e OnAttributeCollectionSubmit não há suporte para autenticação nativa inserida ou traga sua própria experiência. Consulte extensões de autenticação personalizadas para obter um comportamento específico do evento. Esse conjunto de eventos não estabelece ganchos de migração de senha, sincronização de atualização de senha ou propagação de contexto arbitrária.