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 incorporada.
O fluxo de autenticação nativa é uma transação controlada por resposta. ID externa do Microsoft Entra retorna o estado atual, a ação necessária e as operações permitidas. Seu aplicativo apresenta a interface e seleciona uma operação permitida por meio da escolha do usuário ou da lógica de fluxo do aplicativo.
A autorização envolve o percurso
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.
A solicitação de desafio de autorização inicial contém a ID do aplicativo, os escopos solicitados e as declarações opcionais. Se a autenticação for necessária, sua 401 InsufficientAuthorization resposta conterá um token de continuação e links de percurso. Essa resposta é um convite para interagir, não uma verificação de senha com falha.
Use o guid de locatário e o domínio personalizado verificado pelo locatário configurado para cada chamada à API de serviço. Essa autoridade se aplica à autorização, interações nativas e troca de tokens. Consulte Operações e autoridade.
Login, cadastro e redefinição de senha retornam à autorização quando o serviço retorna state: continue. Seu aplicativo posta o token de continuação mais recente no link continue retornado. Em seguida, ele troca o código de autorização resultante por um token no endpoint de token.
Após a verificação de senha, a criação da conta ou uma atualização de senha, o aplicativo manipula todos os requisitos de política restantes e retoma a autorização antes de solicitar tokens.
Esses limites de autorização descrevem a autenticação nativa incorporada. O UX BYO usa as operações de interação nativa compartilhadas entre sua transferência para o navegador e o link de término retornado. Sua página auto-hospedada não inicia nem retoma /authorize-challenge; o aplicativo cliente conclui o fluxo de autorização original do navegador. Consulte Escolher uma abordagem de autenticação.
| Limite | Solicitação ou resposta |
|---|---|
| Iniciar autorização | Codificado no formato de formulário: client_id, scope, response_type=code e claims opcional. |
| Insira uma jornada | URL de nível superior sign_in, sign_up ou reset_password e continuation_token da resposta OAuth. |
| Interagir | Solicitações JSON e respostas HAL com continuationToken, estado, ações e links. |
| Retomar autorização | Codificado em formulário continuation_token, enviado somente quando a resposta atual permite a continuação. |
| Solicitação de tokens | Troca de código de autorização com codificação de formulário. |
A sequência a seguir ilustra a fronteira de autorização e o loop de interação controlado por resposta. Baseie-se na resposta atual em vez de fixar a ordem do diagrama no código.
A resposta atual é o modelo de controle
Cada resposta de autenticação nativa bem-sucedida substitui o modelo de interação anterior. As políticas de tenant, o fluxo de usuário do aplicativo e o estado da transação podem adicionar, repetir ou reordenar ações. O aplicativo seleciona as operações da resposta mais recente e organiza suas telas em torno dos requisitos retornados.
| Estado ou ação | Significado para o cliente |
|---|---|
interactionRequired |
Processe action por meio de uma operação permitida, coletando a entrada do usuário quando necessário. |
continue |
Siga _links.continue para retomar a autorização. |
redirect |
Interrompa a transação nativa. Essa resposta pode conter apenas state, sem um token de continuação ou URL do navegador. Um login no navegador configurado inicia uma nova tentativa. |
discover |
Colete o identificador de login do usuário. |
disambiguate |
Identifica a seleção da conta em state: interactionRequired. |
collectAttributes |
Colete os atributos de inscrição solicitados. |
challenge |
Inicie o desafio do método selecionado. |
verify |
Envie a senha solicitada ou o código de uso único. |
enroll |
Selecione um método oferecido e envie seus dados de registro. |
activate |
Envie um código de uso único para ativar o método registrado. |
update |
Envie uma senha de substituição. |
poll |
Verifique uma atualização de senha assíncrona. |
Por exemplo, o login pode retornar um método de senha e, em seguida, uma ação de verificação e, em seguida, métodos de email ou SMS para autenticação multifator (MFA). O aplicativo processa o fator adicional antes de retomar a autorização.
Durante a inscrição, enviar um email pode enviar um código de acesso imediatamente e retornar verify. O aplicativo coleta esse código de acesso e usa o link de verificação retornado.
Concluir uma operação individual não significa que o aplicativo tenha tokens. Nos percursos nativos descritos aqui, continue permite que a autorização seja retomada; a troca de código subsequente adquire tokens. O estado completed indica a conclusão dessa operação; ela não indica necessariamente um resultado com sessão iniciada nem inclui outro link.
Tokens de continuação associam a próxima operação
Um token de continuação representa a transação em um estágio específico. Ele está associado ao tenant, ao cliente, ao cenário e à ação atual. Mensagens OAuth o chamam de continuation_token; mensagens de autenticação nativa o chamam de continuationToken.
Mantenha apenas o token mais recente para a transação ativa. Emparelhe-o com os links da mesma resposta. Não analise, altere, registre-o ou persista-o além da transação e não o use para um usuário ou jornada diferente. Reinicie a autorização após a expiração em vez de reutilizar um token mais antigo.
A validade padrão documentada é de 10 minutos para um token de continuação individual. Um token mais recente não é uma garantia de estender todo o percurso. Um token de continuação e uma senha única têm tempos de vida separados; lide com a expiração de acordo com a resposta do serviço.
IDs de método e URLs retornadas são opacas. Os exemplos da API de Autenticação Nativa usam /api/v2.0. Siga o link retornado; não substitua uma versão nem construa uma URL a partir do tipo de método. Resolva links relativos em relação à origem da autoridade configurada e valide o destino antes de enviar credenciais.
Descoberta de método não é registro de método
Um recurso de método descreve um método de autenticação disponível.
type, hint mascarado, isPreferred opcional e links permitem que seu aplicativo apresente uma opção e conclua um desafio.
codeLength descreve a entrada de senha quando for retornada.
Os links verify e challenge operam em métodos disponíveis. Registrar um método é uma interação separada orientada por políticas com sua própria ação e contrato de solicitação. A coleção de atributos de perfil também tem um contrato separado.
O registro de método embutido usa as ações enroll e activate. O registro telefônico é anunciado type: phone com channels: ["sms"]; o registro de email usa type: email. A ativação envia o código no campo raiz otp para o link activate, não para o link verify de uma credencial. O cadastro pode atender a um requisito de MFA, portanto, outro desafio não é garantido. Consulte o registro do método de autenticação.
Interações de política e atributo
O fluxo do usuário determina o método de inscrição de email e os atributos solicitados. O cadastro por e-mail com senha coleta um atributo de senha. A inscrição com código de uso único por email cria uma conta sem senha e não coleta uma senha.
Os descritores de atributo podem conter rótulos, tipos de entrada, validation.validationRegEx e valores iniciais. Use cada attributeId exato como uma chave de envio. Os metadados de agrupamento de páginas não são necessários para renderizar o formulário. A validação do servidor continua sendo a referência definitiva. Consulte os atributos de usuário de autenticação nativa.
Há suporte para MFA por meio de políticas do sistema. Após a inscrição ou redefinição de senha, a MFA e o Acesso Condicional podem exigir mais interações antes da conclusão da autorização. Seu aplicativo continua tratando respostas em vez de manter um caminho separado de "já autenticado" que ignora esses requisitos.
Erros e interações sem suporte
Os erros de autenticação OAuth e nativa têm envelopes diferentes. Use códigos estáveis para tratamento, não mensagens localizadas. Manter protegidos os identificadores de solicitação e as marcas de tempo para diagnóstico; não registre tokens ou corpos de credencial.
Ignorar propriedades opcionais desconhecidas e relações de vínculo. Por outro lado, uma ação necessária desconhecida, campo necessário ausente ou resposta malformada impedem a continuação segura. Interrompa a operação nativa quando uma interação necessária não puder ser processada.
Um erro OAuth com invalid_grant e web_redirect_required, ou uma resposta nativa com state: redirect, sinaliza que a transação nativa não pode continuar. Nenhuma resposta estabelece uma transferência para o navegador que possa ser retomada. Ofereça um login no navegador configurado separadamente ou uma falha clara. Mantenha o token de continuação nativo dentro da transação nativa.
Não há suporte para federação, TOTP, passkeys, autenticação de primeiro fator por telefone, step-up de operação posterior e interoperabilidade de perfil ou de gerenciamento de credenciais por meio deste contrato nativo. Consulte as matrizes de suporte.