Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Aplica-se a:
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-Originpara essa origem exata permitida, não*. - Permite o método ou
PUTo método necessárioPOSTda 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.
Relações de vínculo
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 umcontinuationTokenpara a seleção pendente. - Uma
_embedded.usermatriz com informações sobre cada conta oferecida e links com suporte. Uma conta ativa tem uma URL específica_links.resumeda conta. - Uma URL no nível
_links.discoverde 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. |
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.