Compartilhar via

Referência de API de autenticação nativa

  • Artigo

Aplica-se a: Círculo branco com um símbolo X cinza. Locatários da força de trabalho Círculo verde com um símbolo de marca de seleção branco. Locatários externos (saiba mais)

A autenticação nativa do Microsoft Entra permite que você hospede a interface do usuário do seu aplicativo no aplicativo cliente, em vez de delegar a autenticação aos navegadores, resultando em uma experiência de autenticação nativamente integrada. Como desenvolvedor, você tem controle total sobre a aparência da interface de entrada.

Este artigo de referência da API descreve os detalhes necessários somente quando você faz manualmente solicitações HTTP brutas para executar o fluxo. No entanto, não recomendamos essa abordagem. Portanto, quando possível, use um SDK de autenticação compatível e desenvolvido pela Microsoft. Para obter mais informações sobre como usar o SDK, consulte Tutorial: Preparar seu aplicativo móvel Android para autenticação nativa e Tutorial: Preparar seu aplicativo móvel iOS/macOS para autenticação nativa.

Quando uma chamada para os pontos de extremidade da API é bem-sucedida, você recebe um token de ID para identificação do usuário e um token de acesso para chamar APIs protegidas. Todas as respostas da API estão em um formato JSON.

A API de autenticação nativa do Microsoft Entra dá suporte à inscrição e entrada para dois métodos de autenticação:

  • Email com senha, que dá suporte à inscrição e entrada com um email e uma senha, e à redefinição de senha por autoatendimento (SSPR).

  • Senha de acesso único por email, que suporta inscrição e login com senha de acesso único por email.

Observação

Atualmente, os pontos de extremidade da API de autenticação nativa não oferecem suporte ao CORS (Cross-Origin Resource Sharing).

Pré-requisitos

  1. Um locatário externo do Microsoft Entra. Se você ainda não tem um, crie um locatário externo.

  2. Se você ainda não tiver feito isso, Registre um aplicativo no Centro de administração do Microsoft Entra. Certifique-se de conceder permissões delegadas e habilitar fluxos de autenticação nativa e de cliente público.

  3. Se você ainda não tiver feito isso, Crie um fluxo de usuário no centro de administração do Microsoft Entra. Ao criar o fluxo dos usuários, anote os atributos do usuário que você configura como necessários, pois esses atributos são aqueles que o Microsoft Entra espera que seu aplicativo envie.

  4. Associe o registro do aplicativo ao fluxo do usuário.

  5. Para fluxo de entrada, registrar um usuário do cliente, que você usa para testar as APIs de entrada. Como alternativa, você pode obter esse usuário de teste depois de executar o fluxo de inscrição.

  6. Para o fluxo de SSPR, habilite a redefinição de senha self-service para usuários clientes no locatário externo. A SSPR está disponível para usuários clientes que usam email com método de autenticação de senha.

Token de continuação

Cada vez que você chama um ponto de extremidade em qualquer um dos fluxos, entrada, inscrição ou SSPR, o ponto de extremidade inclui um token de continuação em sua resposta. O token de continuação é um identificador exclusivo que o Microsoft Entra ID usa para manter o estado entre chamadas para pontos de extremidade diferentes dentro do mesmo fluxo. Você deve incluir esse token nas solicitações subsequentes no mesmo fluxo.

Cada token de continuação é válido por um período específico e só pode ser usado para as solicitações subsequentes dentro do mesmo fluxo.

Referência da API de inscrição

Para concluir um fluxo de inscrição do usuário para qualquer método de autenticação, seu aplicativo interage com quatro pontos de extremidade, /signup/v1.0/start, /signup/v1.0/challenge, /signup/v1.0/continue e /token.

Pontos de extremidade da API de inscrição

Ponto de extremidade Descrição
/signup/v1.0/start Esse ponto de extremidade inicia o fluxo de inscrição. Você passa a ID do aplicativo válida, o novo nome de usuário e tipo de desafio e, em seguida, recebe de volta um novo token de continuação. O ponto de extremidade pode retornar uma resposta para indicar ao aplicativo para usar um fluxo de autenticação da Web se os métodos de autenticação escolhidos pelo aplicativo não forem compatíveis com o Microsoft Entra.
/signup/v1.0/challenge Seu aplicativo chama esse ponto de extremidade com uma lista de tipos de desafio com suporte do Microsoft Entra. Em seguida, o Microsoft Entra seleciona um dos métodos de autenticação com suporte para o usuário se autenticar.
/signup/v1.0/continue Esse ponto de extremidade ajuda a continuar o fluxo para criar a conta de usuário ou interromper o fluxo devido a requisitos ausentes, como requisitos de política de senha ou formatos de atributo incorretos. Esse ponto de extremidade gera um token de continuação e, em seguida, retorna-o ao aplicativo. O ponto de extremidade pode retornar uma resposta para indicar ao aplicativo para usar um fluxo de autenticação baseado na Web se o aplicativo não fizer um método de autenticação escolhido pelo Microsoft Entra.
/token O aplicativo chama esse ponto de extremidade para finalmente solicitar tokens de segurança. O aplicativo precisa incluir o token de continuação adquirido da última chamada bem-sucedida para o ponto de extremidade /signup/v1.0/continue.

Tipos de desafio de inscrição

A API permite que o aplicativo do cliente anuncie os métodos de autenticação compatíveis, quando faz uma chamada ao Microsoft Entra. Para fazer isso, o aplicativo usa o parâmetro challenge_type na solicitação do aplicativo. Esse parâmetro contém valores predefinidos, que representam diferentes métodos de autenticação.

Saiba mais sobre os tipos de desafio nos tipos de desafio de autenticação nativa. Este artigo explica os valores de tipo de desafio que você deve usar para um método de autenticação.

Detalhes do protocolo de fluxo de inscrição

O diagrama de sequência demonstra o fluxo do processo de inscrição.

Diagrama do fluxo de inscrição de autenticação nativa.

Este diagrama indica que o aplicativo coleta nome de usuário (email), senha (para email com métodos de autenticação de senha) e atributos do usuário em momentos diferentes (e possivelmente em telas separadas). No entanto, você pode projetar seu aplicativo para coletar o nome de usuário (email), a senha e todos os valores de atributo necessários e opcionais na mesma tela e, em seguida, enviar todos eles por meio do ponto de extremidade /signup/v1.0/start. Nesse caso, o aplicativo não precisa fazer chamadas e manipular respostas para etapas opcionais.

Etapa 1: Solicitar para iniciar o fluxo de inscrição

O fluxo de inscrição começa com o aplicativo fazendo uma solicitação POST para o ponto de extremidade /signup/v1.0/start para iniciar o fluxo de inscrição.

Aqui estão exemplos da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

Exemplo 1:

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com

Exemplo 2 (incluir atributos de usuário e senha na solicitação):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
username Sim Email do usuário do cliente com o qual ele deseja se inscrever, como contoso-consumer@contoso.com.
challenge_type Sim Uma lista separada por espaço de cadeias de caracteres de tipo de desafio de autorização que o aplicativo dá suporte, como oob password redirect. A lista deve sempre incluir o tipo de desafio redirect. O valor é esperado para oob redirect ou oob password redirect para email com método de autenticação de senha.
password Não O valor da senha que o aplicativo coleta do usuário cliente. Você pode enviar a senha de um usuário por meio do /signup/v1.0/start ou posterior no ponto de extremidade /signup/v1.0/continue. Substitua {secure_password} pelo valor de senha que o aplicativo coleta do usuário cliente. É sua responsabilidade confirmar que o usuário está ciente da senha que deseja usar fornecendo o campo de confirmação de senha na interface do usuário do aplicativo. Você também deve garantir que o usuário esteja ciente do que constitui uma senha forte de acordo com a política da sua organização. Saiba mais sobre as políticas de senha do Microsoft Entra.
Esse parâmetro só é aplicável para email com método de autenticação de senha.
attributes Não O usuário atribui valores que o aplicativo coleta do usuário cliente. O valor é uma cadeia de caracteres, mas formatada como um objeto JSON cujos valores de chave são nomes programáveis ou atributos de usuário. Esses atributos podem ser internos ou personalizados e obrigatórios ou opcionais. Os nomes de chave do objeto dependem dos atributos que o administrador configurou no Centro de administração do Microsoft Entra. Você pode enviar alguns ou todos os atributos de usuário por meio do ponto de extremidade /signup/v1.0/start ou posteriormente no ponto de extremidade /signup/v1.0/continue. Se você enviar todos os atributos necessários por meio do ponto de extremidade /signup/v1.0/start, não precisará enviar nenhum atributo no ponto de extremidade /signup/v1.0/continue. No entanto, se você enviar alguns atributos necessários por meio do ponto de extremidade /signup/v1.0/start, poderá enviar os atributos necessários restantes posteriormente no ponto de extremidade /signup/v1.0/continue. Substitua {given_name}, {user_age} e {postal_code} pelos valores de nome, idade e CEP, respectivamente, que o aplicativo coleta do usuário do cliente. O Microsoft Entra ignora todos os atributos que você envia, que não existem.

Resposta bem-sucedida

Aqui está um exemplo de uma resposta bem-sucedida:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "AQABAAEAAA…",
}
Parâmetro Descrição
continuation_token Token de continuação que o Microsoft Entra retorna.

Se um aplicativo não puder oferecer suporte a um método de autenticação necessário pelo Microsoft Entra, será necessário um fallback para o fluxo de autenticação baseado na Web. Nesse cenário, o Microsoft Entra informa o aplicativo retornando um tipo de desafio redirecionamento em sua resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parâmetro Descrição
challenge_type O Microsoft Entra retorna uma resposta que tem um tipo de desafio. O valor desse tipo de desafio é o redirecionamento, que permite que o aplicativo use o fluxo de autenticação baseado na Web.

Essa resposta é considerada bem-sucedida, mas o aplicativo é necessário para alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação com suporte e criada pela Microsoft.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "user_already_exists", 
    "error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [ 
        1003037 
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.
invalid_attributes Uma lista (matriz de objetos) de atributos que falharam na validação. Essa resposta é possível se o aplicativo enviar atributos de usuário e o valor do parâmetro suberror for attribute_validation_failed.
suberror Uma cadeia de caracteres de código de erro que pode ser usada para classificar ainda mais os tipos de erros.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação, como quando o valor do parâmetro challenge_type contém um método de autenticação sem suporte ou a solicitação não incluiu o parâmetro de tipoclient_id, o valor da ID do cliente está vazio ou inválido. Use o parâmetro error_description para saber a causa exata do erro.
invalid_client A ID do cliente que o aplicativo inclui na solicitação é para um aplicativo que não possui configuração de autenticação nativa, como não é um cliente público ou não está habilitado para autenticação nativa. Use o parâmetro suberror para saber a causa exata do erro.
unauthorized_client O ID do cliente usado na solicitação tem um formato de ID do cliente válido, mas não existe no locatário externo ou está incorreto.
unsupported_challenge_type O valor do parâmetro challenge_type não inclui o tipo de desafio redirect.
user_already_exists O usuário já existe.
invalid_grant A senha enviada pelo aplicativo não atende a todos os requisitos de complexidade, como a senha, é muito curta. Use o parâmetro suberror para saber a causa exata do erro.
Esse parâmetro só é aplicável para email com método de autenticação de senha.

Se o parâmetro error tiver um valor de invalid_grant, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror para um erro de invalid_grant:

Valor do suberror Descrição
password_too_weak A senha é muito fraca, pois não atende aos requisitos de complexidade. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta será possível se o aplicativo enviar uma senha de usuário.
password_too_short A nova senha tem menos de 8 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta será possível se o aplicativo enviar uma senha de usuário.
password_too_long A nova senha tem mais de 256 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta será possível se o aplicativo enviar uma senha de usuário.
password_recently_used A nova senha não deve ser a mesma usada recentemente. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta será possível se o aplicativo enviar uma senha de usuário.
password_banned A nova senha contém uma palavra, frase ou padrão que é proibido. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta será possível se o aplicativo enviar uma senha de usuário.
password_is_invalid A senha é inválida, por exemplo, porque usa caracteres não permitidos. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta será possível se o aplicativo enviar uma senha de usuário.

Se o parâmetro error tiver um valor de invalid_client, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror para um erro de invalid_client:

Valor do suberror Descrição
nativeauthapi_disabled A ID do cliente de um aplicativo que não está habilitado para autenticação nativa.

Observação

Se você enviar todos os atributos necessários por meio do ponto de extremidade /signup/v1.0/start, mas não todos os atributos opcionais, não poderá enviar nenhum atributo opcional adicional posteriormente por meio do ponto de extremidade /signup/v1.0/continue. O Microsoft Entra não solicita explicitamente atributos opcionais, pois eles não são obrigatórios para que o fluxo de inscrição seja concluído. Veja a tabela na seção Enviando atributos de usuário para o ponto de extremidade para saber quais atributos de usuário você pode enviar para o ponto de extremidade /signup/v1.0/start e /signup/v1.0/continue.

Etapa 2: selecionar um método de autenticação

O aplicativo solicita que o Microsoft Entra selecione um dos tipos de desafio com suporte para o usuário se autenticar. Para fazer isso, o aplicativo faz uma solicitação para o ponto de extremidade /signup/v1.0/challenge. O aplicativo precisa incluir o token de continuação que ele adquire do ponto de extremidade /signup/v1.0/start na solicitação.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade).

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
challenge_type Não Uma lista separada por espaço de autorização tipo de desafio cadeias de caracteres que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de desafio redirect. Espera-se que o valor seja oob redirect para email com senha de uso único e oob password redirect para método de autenticação com senha.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.

Resposta bem-sucedida

O Microsoft Entra envia uma senha única para o email do usuário e, em seguida, responde com o tipo de desafio com o valor oob e informações adicionais sobre a senha única:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "interval": 300,
    "continuation_token": "AQABAAEAAAYn...",
    "challenge_type": "oob",
    "binding_method": "prompt",
    "challenge_channel": "email",
    "challenge_target_label": "c***r@co**o**o.com",
    "code_length": 8
}
Parâmetro Descrição
interval O tempo em segundos que o aplicativo precisa aguardar antes de tentar reenviar o OTP.
continuation_token Token de continuação que o Microsoft Entra retorna.
challenge_type Tipo de desafio selecionado para o usuário se autenticar.
binding_method O único valor válido é prompt. Esse parâmetro pode ser usado no futuro para oferecer mais maneiras ao usuário de inserir a senha única. Emitido se challenge_type for oob
challenge_channel O tipo de canal através do qual a senha única foi enviada. No momento, há suporte apenas para o canal de email.
challenge_target_label Um email ofuscado para onde a senha única foi enviada.
code_length O comprimento da senha única gerada pelo Microsoft Entra.

Se um aplicativo não puder oferecer suporte a um método de autenticação necessário pelo Microsoft Entra, será necessário um fallback para o fluxo de autenticação baseado na Web. Nesse cenário, o Microsoft Entra informa o aplicativo retornando um tipo de desafio redirecionamento em sua resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "challenge_type": "redirect"
}
Parâmetro Descrição
challenge_type O Microsoft Entra retorna uma resposta que tem um tipo de desafio. O valor desse tipo de desafio é o redirecionamento, que permite que o aplicativo use o fluxo de autenticação baseado na Web.

Essa resposta é considerada bem-sucedida, mas o aplicativo é necessário para alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação com suporte e criada pela Microsoft.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação, como a ID do cliente, está vazia ou inválida.
expired_token O token de continuação expirou.
unsupported_challenge_type O valor do parâmetro challenge_type não inclui o tipo de desafio redirect.
invalid_grant O token de continuação é inválido.

Etapa 3: envie a senha única

O aplicativo envia a senha única enviada para o email do usuário. Como estamos enviando uma senha única, um parâmetro oob é obrigatório, e o parâmetro grant_type deve ter um valor oob.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
grant_type Yes Uma solicitação para o ponto de extremidade /signup/v1.0/continue pode ser usada para enviar código de acesso único, senha ou atributos de usuário. Nesse caso, o valor grant_type é usado para diferenciar esses três casos de uso. Os valores possíveis para o grant_type são oob, senha, atributos. Nessa chamada, como estamos enviando uma senha única, espera-se que o valor seja oob.
oob Yes A senha única que o usuário cliente recebeu em seu email. Substitua {otp_code} pelos valores de senha de uso único que o usuário cliente recebeu em seu email. Para reenviar uma senha única, o aplicativo precisa fazer uma solicitação ao ponto de extremidade /signup/v1.0/challenge novamente.

Depois que o aplicativo enviar a senha única com êxito, o fluxo de inscrição dependerá dos cenários, conforme mostrado na tabela:

Cenário Como proceder
O aplicativo envia com sucesso a senha do usuário (para o email com método de autenticação de senha) por meio do ponto de extremidade /signup/v1.0/start e nenhum atributo é configurado no Centro de administração do Microsoft Entra ou todos os atributos de usuário necessários são enviados por meio do ponto de extremidade /signup/v1.0/start. O Microsoft Entra emite um token de continuação. O aplicativo pode usar o token de continuação para solicitar tokens de segurança, conforme mostrado no etapa 5.
O aplicativo envia com êxito a senha do usuário (para email com método de autenticação de senha) por meio do /signup/v1.0/start, mas nem todos os atributos de usuário necessários, o Microsoft Entra indica os atributos que o aplicativo precisa enviar conforme mostrado em atributos de usuário necessários. O aplicativo precisa enviar os atributos de usuário necessários por meio do ponto de extremidade /signup/v1.0/continue. A resposta é semelhante àquela em Atributos de usuário necessários. Envie os atributos de usuário mostrados em enviar atributos de usuário.
O aplicativo não envia a senha do usuário (para email com método de autenticação de senha) por meio do ponto de extremidade /signup/v1.0/start. A resposta do Microsoft Entra indica que a credencial é necessária. Veja a resposta.
Essa resposta é possível para email com método de autenticação de senha.

Resposta

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.
continuation_token Token de continuação que o Microsoft Entra retorna.
suberror Uma cadeia de caracteres de código de erro que pode ser usada para classificar ainda mais os tipos de erros.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
credential_required A autenticação é necessária para a criação da conta, portanto, você precisa fazer uma chamada para o ponto de extremidade /signup/v1.0/challenge para determinar a credencial que o usuário precisa fornecer.
invalid_request A validação do parâmetro de solicitação falhou, como uma validação do token de continuação falhou ou a solicitação não incluiu o parâmetroclient_id o valor do ID do cliente está vazio ou inválido ou o administrador do locatário externo não habilitou o OTP de email para todos os usuários do locatário.
invalid_grant O tipo de concessão incluído na solicitação não é válido ou tem suporte ou o valor OTP está incorreto.
expired_token O token de continuação incluído na solicitação expirou.

Se o parâmetro error tiver um valor de invalid_grant, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror para um erro de invalid_grant:

Valor do suberror Descrição
invalid_oob_value O valor da senha única é inválido.

Para que a credencial de senha seja coletada do usuário, o aplicativo precisa fazer uma chamada para o ponto de extremidade /signup/v1.0/challenge para determinar a credencial que o usuário precisa fornecer.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
challenge_type Não Uma lista separada por espaço de autorização tipo de desafio cadeias de caracteres que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de desafio redirect. Para o fluxo de inscrição de email com senha, espera-se que o valor contenha password redirect.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.

Resposta bem-sucedida

Se a senha for o método de autenticação configurado para o usuário no Centro de administração do Microsoft Entra, uma resposta de êxito com o token de continuação será retornada ao aplicativo.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}
Parâmetro Descrição
challenge_type a senha é retornada na resposta para a credencial necessária.
continuation_token Token de continuação que o Microsoft Entra retorna.

Se um aplicativo não puder oferecer suporte a um método de autenticação necessário pelo Microsoft Entra, será necessário um fallback para o fluxo de autenticação baseado na Web. Nesse cenário, o Microsoft Entra informa o aplicativo retornando um tipo de desafio redirecionamento em sua resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
    "challenge_type": "redirect" 
}
Parâmetro Descrição
challenge_type O Microsoft Entra retorna uma resposta que tem um tipo de desafio. O valor desse tipo de desafio é o redirecionamento, que permite que o aplicativo use o fluxo de autenticação baseado na Web.

Essa resposta é considerada bem-sucedida, mas o aplicativo é necessário para alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação com suporte e criada pela Microsoft.

Etapa 4: Autenticar e obter token para entrar

O aplicativo precisa enviar a credencial do usuário, nesse caso, a senha solicitada pelo Microsoft Entra na etapa anterior. O aplicativo precisará enviar uma credencial de senha se não tiver feito isso por meio do ponto de extremidade /signup/v1.0/start. O aplicativo faz uma solicitação ao ponto de extremidade /signup/v1.0/continue para enviar a senha. Como estamos enviando uma senha, um parâmetro password é necessário e o parâmetro grant_type deve ter um valor senha.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
continuation_token Sim Token de continuação retornado pelo Microsoft Entra na etapa anterior.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
grant_type Yes Uma solicitação para o ponto de extremidade /signup/v1.0/continue pode ser usada para enviar código de acesso único, senha ou atributos de usuário. Nesse caso, o valor grant_type é usado para diferenciar esses três casos de uso. Os valores possíveis para o grant_type são oob, senha, atributos. Nesta chamada, como estamos enviando a senha do usuário, espera-se que o valor seja senha.
password Sim O valor da senha que o aplicativo coleta do usuário cliente. Substitua {secure_password} pelo valor de senha que o aplicativo coleta do usuário cliente. É sua responsabilidade confirmar que o usuário está ciente da senha que deseja usar fornecendo o campo de confirmação de senha na interface do usuário do aplicativo. Você também deve garantir que o usuário esteja ciente do que constitui uma senha forte de acordo com a política da sua organização. Saiba mais sobre as políticas de senha do Microsoft Entra.

Resposta bem-sucedida

Se a solicitação for bem-sucedida, mas nenhum atributo tiver sido configurado no Centro de administração do Microsoft Entra ou todos os atributos necessários forem enviados por meio do ponto de extremidade /signup/v1.0/start, o aplicativo receberá um token de continuação sem enviar nenhum atributo. O aplicativo pode usar o token de continuação para solicitar tokens de segurança, conforme mostrado no etapa 5. Caso contrário, a resposta do Microsoft Entra indica que o aplicativo precisa enviar os atributos necessários. Esses atributos, internos ou personalizados, foram configurados no Centro de administração do Microsoft Entra pelo administrador do locatário.

Atributos de usuário necessários

Essa resposta solicita que o aplicativo envie valores para atributos de nome, *idade e telefone.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "attributes_required",
    "error_description": "User attributes required",
    "error_codes": [
            55106
        ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABAAEAAAAtn...",
    "required_attributes": [
        {
            "name": "displayName",
            "type": "string",
            "required": true,
            "options": {
              "regex": ".*@.**$"
            }
        },
        {
            "name": "extension_2588abcdwhtfeehjjeeqwertc_age",
            "type": "string",
            "required": true
        },
        {
            "name": "postalCode",
            "type": "string",
            "required": true,
            "options": {
              "regex":"^[1-9][0-9]*$"
            }
        }
    ],
}

Observação

Os atributos personalizados (também conhecidos como extensões de diretório) são nomeados usando o extension_{appId-without-hyphens}_{attribute-name} de convenção, onde {appId-without-hyphens} é a versão despojada da ID do cliente para o aplicativo extensões. Por exemplo, se a ID do cliente do aplicativo extensões estiver 2588a-bcdwh-tfeehj-jeeqw-ertc e o nome do atributo for hobbies, o atributo personalizado será nomeado comoextension_2588abcdwhtfeehjjeeqwertc_hobbies. Saiba mais sobre atributos personalizados e aplicativo de extensão.

Parâmetro Descrição
error Esse atributo será definido se o Microsoft Entra não puder criar a conta de usuário porque um atributo precisa ser verificado ou enviado.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa do erro.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.
continuation_token Token de continuação que o Microsoft Entra retorna.
required_attributes Uma lista (matriz de objetos) de atributos que o aplicativo precisa para enviar a próxima chamada para continuar. Esses atributos são os atributos extras que o aplicativo precisa enviar além do nome de usuário. Microsoft Entra inclui esse parâmetro é a resposta se o valor de error parâmetro é attributes_required.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação, como uma validação de token de continuação falha ou a solicitação não incluiu o parâmetro client_id em que o valor da ID do cliente está vazio ou inválido.
invalid_grant O tipo de concessão incluído na solicitação não é válido ou tem suporte. Os valores possíveis para o grant_type são oob, password, attributes
expired_token O token de continuação incluído na solicitação expirou.
attributes_required Um ou mais atributos de usuário são necessários.

Se um aplicativo não puder oferecer suporte a um método de autenticação necessário pelo Microsoft Entra, será necessário um fallback para o fluxo de autenticação baseado na Web. Nesse cenário, o Microsoft Entra informa o aplicativo retornando um tipo de desafio redirecionamento em sua resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parâmetro Descrição
challenge_type O Microsoft Entra retorna uma resposta que tem um tipo de desafio. O valor desse tipo de desafio é o redirecionamento, que permite que o aplicativo use o fluxo de autenticação baseado na Web.

Essa resposta é considerada bem-sucedida, mas o aplicativo é necessário para alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação com suporte e criada pela Microsoft.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "invalid_grant",
    "error_description": "New password is too weak",
    "error_codes": [
        399246
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "suberror": "password_too_weak"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.
suberror Uma cadeia de caracteres de código de erro que pode ser usada para classificar ainda mais os tipos de erros.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação, como quando o challenge_type parâmetro inclui um tipo de desafio inválido.
invalid_grant A concessão enviada é inválida, como a senha enviada é muito curta. Use o parâmetro suberror para saber a causa exata do erro.
expired_token O token de continuação expirou.
attributes_required Um ou mais atributos de usuário são necessários.

Se o parâmetro error tiver um valor de invalid_grant, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror:

Valor do suberror Descrição
password_too_weak A senha é muito fraca, pois não atende aos requisitos de complexidade. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_too_short A nova senha tem menos de 8 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_too_long A nova senha tem mais de 256 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_recently_used A nova senha não deve ser a mesma usada recentemente. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_banned A nova senha contém uma palavra, frase ou padrão que é proibido. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_is_invalid A senha é inválida, por exemplo, porque usa caracteres não permitidos. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta será possível se o aplicativo enviar uma senha de usuário.

Enviar atributos de usuário

Para continuar com o fluxo, o aplicativo precisa fazer uma chamada para o ponto de extremidade /signup/v1.0/continue para enviar os atributos de usuário necessários. Como estamos enviando atributos, um parâmetro attributes é necessário e o parâmetro grant_type deve ter um valor igual a atributos.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
grant_type Yes Uma solicitação para o ponto de extremidade /signup/v1.0/continue pode ser usada para enviar código de acesso único, senha ou atributos de usuário. Nesse caso, o valor grant_type é usado para diferenciar esses três casos de uso. Os valores possíveis para o grant_type são oob, senha, atributos. Nesta chamada, como estamos enviando atributos de usuário, espera-se que o valor seja atributos.
attributes Sim Os valores de atributo do usuário que o aplicativo coleta do usuário cliente. O valor é uma cadeia de caracteres, mas formatada como um objeto JSON cujos valores de chave são nomes de atributos de usuário, internos ou personalizados. Os nomes de chave do objeto dependem dos atributos que o administrador configurou no Centro de administração do Microsoft Entra. Substitua {given_name}, {user_age} e {postal_code} pelos valores de nome, idade e CEP, respectivamente, que o aplicativo coleta do usuário do cliente. O Microsoft Entra ignora todos os atributos que você envia, que não existem.

Resposta bem-sucedida

Se a solicitação for bem-sucedida, o Microsoft Entra emitirá um token de continuação, que o aplicativo pode usar para solicitar tokens de segurança.

HTTP/1.1 200 OK
Content-Type: application/json

{  
    "continuation_token": "AQABAAEAAAYn..."
}
Parâmetro Descrição
continuation_token Token de continuação que o Microsoft Entra retorna.

Se um aplicativo não puder oferecer suporte a um método de autenticação necessário pelo Microsoft Entra, será necessário um fallback para o fluxo de autenticação baseado na Web. Nesse cenário, o Microsoft Entra informa o aplicativo retornando um tipo de desafio redirecionamento em sua resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parâmetro Descrição
challenge_type O Microsoft Entra retorna uma resposta que tem um tipo de desafio. O valor desse tipo de desafio é o redirecionamento, que permite que o aplicativo use o fluxo de autenticação baseado na Web.

Essa resposta é considerada bem-sucedida, mas o aplicativo é necessário para alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação com suporte e criada pela Microsoft.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.  .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [
        552003
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd" 
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.
continuation_token Token de continuação que o Microsoft Entra retorna.
unverified_attributes Uma lista (matriz de objetos) de nomes de chave de atributo que devem ser verificados. Esse parâmetro é incluído na resposta quando o valor do parâmetro error é verification_required.
required_attributes Uma lista (matriz de objetos) de atributos que o aplicativo precisa enviar. O Microsoft Entra inclui esse parâmetro em sua resposta quando o valor do parâmetro error é attributes_required.
invalid_attributes Uma lista (matriz de objetos) de atributos que falharam na validação. Esse parâmetro é incluído na resposta quando o valor do parâmetro suberror é attribute_validation_failed.
suberror Uma cadeia de caracteres de código de erro que pode ser usada para classificar ainda mais os tipos de erros.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação, como uma validação de token de continuação falha ou a solicitação não incluiu o parâmetro client_id em que o valor da ID do cliente está vazio ou inválido.
invalid_grant O tipo de concessão fornecido não é válido ou tem suporte ou falha na validação, como falha na validação de atributos. Use o parâmetro suberror para saber a causa exata do erro.
expired_token O token de continuação incluído na solicitação expirou.
attributes_required Um ou mais atributos de usuário são necessários.

Se o parâmetro error tiver um valor de invalid_grant, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror para um erro de invalid_grant:

Valor do suberror Descrição
attribute_validation_failed Falha na validação do atributo de usuário. O parâmetro invalid_attributes contém a lista (matriz de objetos) de atributos que falharam na validação.

Etapa 5: Solicitação de tokens de segurança

O aplicativo faz uma solicitação POST para o ponto de extremidade /token e fornece o token de continuação obtido da etapa anterior para adquirir tokens de segurança.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
grant_type Sim O valor do parâmetro deve ser token de continuação.
continuation_token Sim Token de continuação retornado pelo Microsoft Entra na etapa anterior.
scope Sim Uma lista separada por espaço de escopos para os quais o token de acesso é válido. Substitua {scopes} pelos escopos válidos para os quais o token de acesso retornado pelo Microsoft Entra é válido.
username Sim Email do usuário do cliente com o qual ele deseja se inscrever, como contoso-consumer@contoso.com.

Resposta bem-sucedida

Aqui está um exemplo de uma resposta bem-sucedida:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}
Parâmetro Descrição
access_token O token de acesso que o aplicativo solicitou do ponto de extremidade /token. O aplicativo pode usar esse token de acesso para solicitar acesso a recursos protegidos, como APIs da Web.
token_type Indica o valor do tipo de token. O único tipo que o Microsoft Entra suporta é Bearer.
expires_in O período de tempo em segundos em que o token de acesso permanece válido.
scopes Uma lista separada por espaço de escopos para os quais o token de acesso é válido.
refresh_token Um token de atualização do OAuth 2.0. O aplicativo pode usar esse token para adquirir outros tokens de acesso depois que o token de acesso atual expirar. Os tokens de atualização têm uma vida longa. Eles podem manter o acesso aos recursos por períodos prolongados. Para obter mais detalhes sobre como atualizar um token de acesso, consulte o artigo Atualizar o token de acesso.
Nota: Somente emitido se offline_access escopo foi solicitado.
id_token Um JSON Web Token (Jwt) usado para identificar o usuário do cliente. O aplicativo pode decodificar o token para ler informações sobre o usuário que entrou. O aplicativo pode armazenar os valores em cache e exibi-los. Os clientes confidenciais podem usar esse token para autorização. Para obter mais informações sobre tokens de ID, consulte Tokens de ID.
Nota: Somente emitido se o escopo openid for solicitado.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request A validação do parâmetro de solicitação falhou, pois o cliente/aplicativo não tem consentimento para os escopos solicitados.
invalid_grant O token de continuação incluído na solicitação é inválido.
unauthorized_client O ID do cliente incluído na solicitação é inválido ou não existe.
unsupported_grant_type O tipo de concessão incluído na solicitação não é suportado ou está incorreto.

Enviando atributos de usuário para ponto de extremidade

No centro de administração do Microsoft Entra, você pode configurar atributos de usuário conforme necessário ou opcional. Essa configuração determina como o Microsoft Entra responde quando você faz uma chamada para seus pontos de extremidade. Atributos opcionais não são obrigatórios para a conclusão do fluxo de inscrição. Portanto, quando todos os atributos são opcionais, eles devem ser enviados antes da verificação do nome de usuário. Caso contrário, a inscrição será concluída sem os atributos opcionais.

A tabela a seguir resume quando é possível enviar atributos de usuário para pontos de extremidade do Microsoft Entra.

Ponto de extremidade Atributos necessários Atributos opcionais Atributos obrigatórios e opcionais
/signup/v1.0/start ponto de extremidade Sim Sim Yes
/signup/v1.0/continue ponto de extremidade antes da verificação do nome de usuário Sim Sim Yes
/signup/v1.0/continue ponto de extremidade após verificação de nome de usuário Sim Não Sim

Formato dos valores de atributos do usuário

Você especifica as informações que deseja coletar do usuário definindo as configurações de fluxo de usuário no centro de administração do Microsoft Entra. Use o artigo Coletar atributos de usuário personalizados durante a inscrição para saber como coletar valores para atributos internos e personalizados.

Você também pode especificar o Tipo de Entrada do Usuário para os atributos configurados. A tabela a seguir resume os tipos de entrada de usuário com suporte e como enviar valores coletados pelos controles de interface do usuário para o Microsoft Entra.

Tipo de entrada do usuário Formato dos valores enviados
TextBox  Um único valor, como cargo, Engenheiro de Software.
SingleRadioSelect Um único valor, como Language, norueguês. 
CheckboxMultiSelect Um ou vários valores, como um hobby ou hobbies, Dança ou Dança, Natação, Viajar.

Aqui está um exemplo de solicitação que mostra como você envia os valores dos atributos:

POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtfyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...

Saiba mais sobre os tipos de entrada de atributos de usuário no artigo Tipos de entrada de atributos de usuário personalizados.

Como referenciar atributos de usuário

Ao criar um fluxo de usuário de inscrição, você configura os atributos de usuário que deseja coletar do usuário durante a inscrição. Os nomes dos atributos de usuário no centro de administração do Microsoft Entra são diferentes de como você os referencia na API de autenticação nativa.

Por exemplo, Nome para exibição no centro de administração do Microsoft Entra é referenciado como displayName na API.

Use o artigo Atributos de perfil de usuário para saber como fazer referência a atributos de usuário internos e personalizados na API de autenticação nativa.

Referência da API de entrada

Os usuários precisam entrar com o método de autenticação que usam para se inscrever. Por exemplo, os usuários que se inscreverem usando email com o método de autenticação de senha devem entrar por email e senha.

Para solicitar tokens de segurança, seu aplicativo interage com três pontos de extremidade, /initiate, /challenge e /token.

Pontos de extremidade da API de entrada

Ponto de extremidade Descrição
/initiate Esse ponto de extremidade inicia o fluxo de entrada. Se seu aplicativo o chamar com um nome de usuário de uma conta de usuário que já existe, ele retornará uma resposta de sucesso com um token de continuação. Se o aplicativo solicitar o uso de métodos de autenticação que não são compatíveis com o Microsoft Entra, essa resposta de ponto de extremidade poderá indicar ao seu aplicativo que ele precisa usar um fluxo de autenticação baseado em navegador.
/challenge seu aplicativo chama esse ponto de extremidade com uma lista de tipos de desafio suportados pelo serviço de identidade. Nosso serviço de identidade gera e envia uma senha única para o canal de desafio escolhido, como email. Se seu aplicativo chamar esse ponto de extremidade repetidamente, um novo OTP será enviado sempre que uma chamada for feita.
/token Esse ponto de extremidade verifica a senha única que recebe do seu aplicativo e, em seguida, emite tokens de segurança para o seu aplicativo.

Tipos de desafio de entrada

A API permite que o aplicativo anuncie os métodos de autenticação compatíveis, quando faz uma chamada ao Microsoft Entra. Para fazer isso, o aplicativo usa o parâmetro challenge_type em suas solicitações. Esse parâmetro contém valores predefinidos, que representam diferentes métodos de autenticação.

Para um determinado método de autenticação, os valores de tipo de desafio que um aplicativo envia ao Microsoft Entra durante o fluxo de inscrição são os mesmos para quando o aplicativo entra. Por exemplo, o email com o método de autenticação de senha usa valores de tipo de desafio oob, senha e redirecionamento para fluxos de inscrição e entrada.

Saiba mais sobre os tipos de desafio no artigo tipos de desafio de autenticação nativa.

Detalhes do protocolo de fluxo de entrada

O diagrama de sequência demonstra o fluxo do processo de entrada.

Diagrama de login de autenticação nativa com senha única de email.

Depois que o aplicativo verifica o email do usuário com a OTP, ele recebe tokens de segurança. Se a entrega da senha única atrasar ou nunca for entregue no email do usuário, o usuário poderá solicitar o envio de outra senha única. O Microsoft Entra reenvia outra senha única se a anterior não tiver sido verificada. Quando o Microsoft Entra reenvia uma senha única, ele invalida o código enviado anteriormente.

Nas seções a seguir, resumimos o fluxo de diagrama de sequência em três etapas básicas.

Etapa 1: Solicitar para iniciar o fluxo de entrada

O fluxo de autenticação começa com o aplicativo fazendo uma solicitação POST para o ponto de extremidade /initiate para iniciar o fluxo de entrada.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
username Sim Email do usuário cliente, como contoso-consumer@contoso.com.
challenge_type Sim Uma lista separada por espaço de autorização tipo de desafio cadeias de caracteres que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de desafio redirect. Espera-se que o valor seja oob redirect para email com senha de uso único e password redirect para email com senha.

Resposta bem-sucedida

Aqui está um exemplo de uma resposta bem-sucedida:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Parâmetro Descrição
continuation_token Token de continuação que o Microsoft Entra retorna.

Se um aplicativo não puder oferecer suporte a um método de autenticação necessário pelo Microsoft Entra, será necessário um fallback para o fluxo de autenticação baseado na Web. Nesse cenário, o Microsoft Entra informa o aplicativo retornando um tipo de desafio redirecionamento em sua resposta:

HTTP/1.1 200 OK
Content-Type: application/json


{     
   "challenge_type": "redirect" 
}
Parâmetro Descrição
challenge_type O Microsoft Entra retorna uma resposta que tem um tipo de desafio. O valor desse tipo de desafio é o redirecionamento, que permite que o aplicativo use o fluxo de autenticação baseado na Web.

Essa resposta é considerada bem-sucedida, mas o aplicativo é necessário para alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação com suporte e criada pela Microsoft.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação, como quando o challenge_type parâmetro inclui um tipo de desafio inválido. ou a solicitação não incluiu o parâmetro client_id em que o valor da ID do cliente está vazio ou inválido. Use o parâmetro error_description para saber a causa exata do erro.
unauthorized_client O ID do cliente usado na solicitação tem um formato de ID do cliente válido, mas não existe no locatário externo ou está incorreto.
invalid_client A ID do cliente que o aplicativo inclui na solicitação é para um aplicativo que não possui configuração de autenticação nativa, como não é um cliente público ou não está habilitado para autenticação nativa. Use o parâmetro suberror para saber a causa exata do erro.
user_not_found O nome de usuário não existe.
unsupported_challenge_type O valor do parâmetro challenge_type não inclui o tipo de desafio redirect.

Se o parâmetro error tiver um valor de invalid_client, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror para um erro de invalid_client:

Valor do suberror Descrição
nativeauthapi_disabled A ID do cliente de um aplicativo que não está habilitado para autenticação nativa.

Etapa 2: selecionar um método de autenticação

Para continuar com o fluxo, o aplicativo usa o token de continuação adquirido da etapa anterior para solicitar que o Microsoft Entra selecione um dos tipos de desafio com suporte para o usuário se autenticar. O aplicativo faz uma solicitação POST para o ponto de extremidade /challenge.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect 
&continuation_token=uY29tL2F1dGhlbnRpY...
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.
challenge_type Não Uma lista separada por espaço de autorização tipo de desafio cadeias de caracteres que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de desafio redirect. Espera-se que o valor seja oob redirect para email com senha de uso único e password redirect para email com senha.

Resposta bem-sucedida

Se o administrador do locatário configurou a senha única de email no centro de administração do Microsoft Entra como o método de autenticação do usuário, o Microsoft Entra envia uma senha única para o email do usuário e, em seguida, responde com um tipo de desafio oob e fornece mais informações sobre a senha. senha de tempo.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}
Parâmetro Descrição
continuation_token Token de continuação que o Microsoft Entra retorna.
challenge_type Tipo de desafio selecionado para o usuário se autenticar.
binding_method O único valor válido é prompt. Esse parâmetro pode ser usado no futuro para oferecer mais maneiras para o usuário inserir a senha única. Emitido se challenge_type for oob
challenge_channel O tipo de canal através do qual a senha única foi enviada. No momento, apoiamos por email.
challenge_target_label Um email ofuscado para onde a senha única foi enviada.
code_length O comprimento da senha única gerada pelo Microsoft Entra.

Se um aplicativo não puder oferecer suporte a um método de autenticação necessário pelo Microsoft Entra, será necessário um fallback para o fluxo de autenticação baseado na Web. Nesse cenário, o Microsoft Entra informa o aplicativo retornando um tipo de desafio redirecionamento em sua resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parâmetro Descrição
challenge_type O Microsoft Entra retorna uma resposta que tem um tipo de desafio. O valor desse tipo de desafio é o redirecionamento, que permite que o aplicativo use o fluxo de autenticação baseado na Web.

Essa resposta é considerada bem-sucedida, mas o aplicativo é necessário para alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação com suporte e criada pela Microsoft.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação, como quando o challenge_type parâmetro inclui um tipo de desafio inválido.
invalid_grant O token de continuação incluído na solicitação não é válido.
expired_token O token de continuação incluído na solicitação expirou.
unsupported_challenge_type O valor do parâmetro challenge_type não inclui o tipo de desafio redirect.

Etapa 3: Solicitação de tokens de segurança

O aplicativo faz uma solicitação POST para o ponto de extremidade /token e fornece as credenciais do usuário escolhidas na etapa anterior, nesse caso, senha, para adquirir tokens de segurança.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.
grant_type Sim O valor deve ser senha para email com método de autenticação de senha e oob para o método de autenticação de senha única de email.
scope Sim Uma lista de escopos separados por espaços. Todos os escopos devem ser de um único recurso, juntamente com escopos OpenID Connect (OIDC), como profile, *openid e email. O aplicativo precisa incluir openid escopo para que o Microsoft Entra emita um token de ID. O aplicativo precisa incluir offline_access escopo para que o Microsoft Entra emita um token de atualização. Saiba mais sobre Permissões e consentimento na plataforma de identidade da Microsoft.
password Sim
(para email com senha)		 O valor da senha que o aplicativo coleta do usuário cliente. Substitua {secure_password} pelo valor de senha que o aplicativo coleta do usuário cliente.
oob Sim
(para email com senha de uso único)		 A senha única que o usuário cliente recebeu em seu email. Substitua {otp_code} pela senha única que o usuário cliente recebeu em seu email. Para reenviar uma senha única, o aplicativo precisa fazer uma solicitação ao ponto de extremidade /challenge novamente.

Resposta bem-sucedida

Aqui está um exemplo de uma resposta bem-sucedida:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}
Parâmetro Descrição
token_type Indica o valor do tipo de token. O único tipo que o Microsoft Entra suporta é Bearer.
scopes Uma lista separada por espaço de escopos para os quais o token de acesso é válido.
expires_in O período de tempo em segundos em que o token de acesso permanece válido.
access_token O token de acesso que o aplicativo solicitou do ponto de extremidade /token. O aplicativo pode usar esse token de acesso para solicitar acesso a recursos protegidos, como APIs da Web.
refresh_token Um token de atualização do OAuth 2.0. O aplicativo pode usar esse token para adquirir outros tokens de acesso depois que o token de acesso atual expirar. Os tokens de atualização têm uma vida longa. Eles podem manter o acesso aos recursos por períodos prolongados. Para obter mais detalhes sobre como atualizar um token de acesso, consulte o artigo Atualizar o token de acesso.
Observação: emitido somente se você solicitar o escopo offline_access.
id_token Um JSON Web Token (Jwt) usado para identificar o usuário do cliente. O aplicativo pode decodificar o token para solicitar informações sobre o usuário que entrou. O aplicativo pode armazenar os valores em cache e exibi-los. Os clientes confidenciais podem usar esse token para autorização. Para obter mais informações sobre tokens de ID, consulte Tokens de ID.
Observação: emitido somente se você solicitar escopo openid.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_grant", 
    "error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação. Para entender o que aconteceu, use a mensagem na descrição do erro.
invalid_grant O token de continuação incluído na solicitação não é válido ou as credenciais de entrada do usuário do cliente incluídas na solicitação são inválidas ou o tipo de concessão incluído na solicitação é desconhecido.
invalid_client O ID do cliente incluído na solicitação não é para um cliente público.
expired_token O token de continuação incluído na solicitação expirou.
invalid_scope Um ou mais dos escopos incluídos na solicitação são inválidos.

Se o parâmetro error tiver um valor de invalid_grant, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror para um erro de invalid_grant:

Valor do suberror Descrição
invalid_oob_value O valor da senha única é inválido. Esse sub-erro aplica apenas o email de senha de uso único

SSPR (redefinição de senha por autoatendimento)

Se você usar email e senha como método de autenticação em seu aplicativo, use a API de autoatendimento de redefinição de senha (SSPR) para permitir que os usuários do cliente redefinam suas senhas. Use essa API para cenários de esquecimento de senha ou alteração de senha.

Pontos de extremidade da API de redefinição de senha de autoatendimento

Para usar essa API, o aplicativo interage com o ponto de extremidade mostrado na tabela a seguir:

Ponto de extremidade Descrição
/start Seu aplicativo chama esse ponto de extremidade quando o usuário do cliente seleciona Senha esquecida ou Alterar senha link ou botão no aplicativo. Esse ponto de extremidade valida o nome de usuário (email) do usuário e retorna um token de continuação para uso no fluxo de redefinição de senha. Se o aplicativo solicitar o uso de métodos de autenticação que não são compatíveis com o Microsoft Entra, essa resposta de ponto de extremidade poderá indicar ao seu aplicativo que ele precisa usar um fluxo de autenticação baseado em navegador.
/challenge Aceita uma lista de tipos de desafio compatíveis com o cliente e o token de continuação. Um desafio é emitido para uma das credenciais de recuperação preferenciais. Por exemplo, oob desafio emite uma senha única fora de banda para o email associado à conta de usuário do cliente. Se o aplicativo solicitar o uso de métodos de autenticação que não são compatíveis com o Microsoft Entra, essa resposta de ponto de extremidade poderá indicar ao seu aplicativo que ele precisa usar um fluxo de autenticação baseado em navegador.
/continue Valida o desafio emitido pelo ponto de extremidade /challenge e, em seguida, retorna um token de continuação para o ponto de extremidade /submit ou emite outro desafio para o usuário.
/submit Aceita uma nova entrada de senha pelo usuário junto com o token de continuação para concluir o fluxo de redefinição de senha. Esse ponto de extremidade emite outro token de continuação.
/poll_completion Por fim, o aplicativo pode usar o token de continuação emitido pelo ponto de extremidade /submit para verificar o status da solicitação de redefinição de senha.

Tipos de desafio de redefinição de senha de autoatendimento

A API permite que o aplicativo anuncie os métodos de autenticação compatíveis, quando faz uma chamada ao Microsoft Entra. Para fazer isso, o aplicativo usa o parâmetro challenge_type em suas solicitações. Esse parâmetro contém valores predefinidos, que representam diferentes métodos de autenticação.

Para o fluxo de SSPR, os valores de tipo de desafio são oobe redirecionamento.

Saiba mais sobre os tipos de desafio nos tipos de desafio de autenticação nativa.

Detalhes do protocolo de fluxo de redefinição de senha de autoatendimento

O diagrama de sequência demonstra o fluxo para o processo de redefinição de senha.

Diagrama do fluxo de redefinição de senha de autoatendimento de autenticação nativa.

Este diagrama indica que o aplicativo coleta o nome de usuário (email) e a senha do usuário em momentos diferentes (e possivelmente em telas separadas). No entanto, você pode projetar seu aplicativo para coletar o nome de usuário (email) e a nova senha na mesma tela. Nesse caso, o aplicativo contém a senha e a envia por meio do ponto de extremidade /submit em que ela é necessária.

Etapa 1: Solicitar para iniciar o fluxo de redefinição de senha de autoatendimento

O fluxo de redefinição de senha começa com o aplicativo fazendo uma solicitação POST para o ponto de extremidade /start para iniciar o fluxo de redefinição de senha de autoatendimento.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&challenge_type=oob redirect 
&username=contoso-consumer@contoso.com
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
username Sim Email do usuário cliente, como contoso-consumer@contoso.com.
challenge_type Sim Uma lista separada por espaço de autorização tipo de desafio cadeias de caracteres que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de desafio redirect. Para essa solicitação, espera-se que o valor contenha oob redirect.

Resposta bem-sucedida

Exemplo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Parâmetro Descrição
continuation_token Token de continuação que o Microsoft Entra retorna.

Se um aplicativo não puder oferecer suporte a um método de autenticação necessário pelo Microsoft Entra, será necessário um fallback para o fluxo de autenticação baseado na Web. Nesse cenário, o Microsoft Entra informa o aplicativo retornando um tipo de desafio redirecionamento em sua resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parâmetro Descrição
challenge_type O Microsoft Entra retorna uma resposta que tem um tipo de desafio. O valor desse tipo de desafio é o redirecionamento, que permite que o aplicativo use o fluxo de autenticação baseado na Web.

Essa resposta é considerada bem-sucedida, mas o aplicativo é necessário para alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação com suporte e criada pela Microsoft.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request A validação do parâmetro de solicitação falhou, como quando o parâmetro challenge_type inclui um tipo de desafio inválido ou a solicitação não inclui client_id parâmetro o valor de ID do cliente está vazio ou inválido. Use o parâmetro error_description para saber a causa exata do erro.
user_not_found O nome de usuário não existe.
unsupported_challenge_type O valor do parâmetro challenge_type não inclui o tipo de desafio redirect.
invalid_client A ID do cliente que o aplicativo inclui na solicitação é para um aplicativo que não possui configuração de autenticação nativa, como não é um cliente público ou não está habilitado para autenticação nativa. Use o parâmetro suberror para saber a causa exata do erro.
unauthorized_client O ID do cliente usado na solicitação tem um formato de ID do cliente válido, mas não existe no locatário externo ou está incorreto.

Se o parâmetro error tiver um valor de invalid_client, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror para um erro de invalid_client:

Valor do suberror Descrição
nativeauthapi_disabled A ID do cliente de um aplicativo que não está habilitado para autenticação nativa.

Etapa 2: selecionar um método de autenticação

Para continuar com o fluxo, o aplicativo usa o token de continuação adquirido da etapa anterior para solicitar que o Microsoft Entra selecione um dos tipos de desafio com suporte para o usuário se autenticar. O aplicativo faz uma solicitação POST para o ponto de extremidade /challenge. Se essa solicitação for bem-sucedida, o Microsoft Entra enviará uma senha única para o email da conta do usuário. No momento, só damos suporte ao OTP de email.

Aqui está um exemplo (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.
challenge_type Não Uma lista separada por espaço de autorização tipo de desafio cadeias de caracteres que o aplicativo suporta, como oob redirect. A lista deve sempre incluir o tipo de desafio redirect. Para essa solicitação, espera-se que o valor contenha oob redirect.

Resposta bem-sucedida

Exemplo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}
Parâmetro Descrição
continuation_token Token de continuação que o Microsoft Entra retorna.
challenge_type Tipo de desafio selecionado para o usuário se autenticar.
binding_method O único valor válido é prompt. Esse parâmetro pode ser usado no futuro para oferecer mais maneiras ao usuário de inserir a senha única. Emitido se challenge_type for oob
challenge_channel O tipo de canal através do qual a senha única foi enviada. No momento, apoiamos por email.
challenge_target_label Um email ofuscado para onde a senha única foi enviada.
code_length O comprimento da senha única gerada pelo Microsoft Entra.

Se um aplicativo não puder oferecer suporte a um método de autenticação necessário pelo Microsoft Entra, será necessário um fallback para o fluxo de autenticação baseado na Web. Nesse cenário, o Microsoft Entra informa o aplicativo retornando um tipo de desafio redirecionamento em sua resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parâmetro Descrição
challenge_type O Microsoft Entra retorna uma resposta que tem um tipo de desafio. O valor desse tipo de desafio é o redirecionamento, que permite que o aplicativo use o fluxo de autenticação baseado na Web.

Essa resposta é considerada bem-sucedida, mas o aplicativo é necessário para alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação com suporte e criada pela Microsoft.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request A validação do parâmetro de solicitação falhou, como quando o parâmetro challenge_type inclui um tipo de desafio inválido ou token de continuação falha na validação.
expired_token O token de continuação expirou.
unsupported_challenge_type O valor do parâmetro challenge_type não inclui o tipo de desafio redirect.

Etapa 3: envie a senha única

Em seguida, o aplicativo faz uma solicitação POST para o ponto de extremidade /continue. Na solicitação, o aplicativo precisa incluir as credenciais do usuário escolhidas na etapa anterior e o token de continuação emitido do ponto de extremidade /challenge.

Aqui está um exemplo da solicitação (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
grant_type Sim O único valor válido é oob.
oob Yes A senha única que o usuário cliente recebeu em seu email. Substitua {otp_code} pela senha única que o usuário cliente recebeu em seu email. Para reenviar uma senha única, o aplicativo precisa fazer uma solicitação ao /challenge ponto de extremidade novamente.

Resposta bem-sucedida

Exemplo:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
}
Parâmetro Descrição
expires_in Tempo em segundos antes do continuation_token expirar. O valor máximo de expires_in é 600 segundos.
continuation_token Token de continuação que o Microsoft Entra retorna.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.
suberror Uma cadeia de caracteres de código de erro que pode ser usada para classificar ainda mais os tipos de erros.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request A validação do parâmetro de solicitação falhou, como uma validação de token de continuação falhou ou a solicitação não incluiu o parâmetroclient_id o valor do ID do cliente está vazio ou inválido ou o administrador de locatário externo não habilitou SSPR e email OTP para todos os usuários de locatário. Use o parâmetro error_description para saber a causa exata do erro.
invalid_grant O tipo de concessão é desconhecido ou não corresponde ao valor de tipo de concessão esperado. Use o parâmetro suberror para saber a causa exata do erro.
expired_token O token de continuação expirou.

Se o parâmetro error tiver um valor de invalid_grant, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror para um erro de invalid_grant:

Valor do suberror Descrição
invalid_oob_value A senha única fornecida pelo usuário é inválida.

Etapa 4: Enviar uma nova senha

O aplicativo coleta uma nova senha do usuário e, em seguida, usa o token de continuação emitido pelo ponto de extremidade /continue para enviar a senha fazendo uma solicitação POST para o ponto de extremidade /submit.

Aqui está um exemplo (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.
new_password Sim Nova senha do usuário. Substitua {new_password} pela nova senha do usuário. É sua responsabilidade confirmar que o usuário está ciente da senha que deseja usar fornecendo o campo de confirmação de senha na interface do usuário do aplicativo. Você também deve garantir que o usuário esteja ciente do que constitui uma senha forte de acordo com a política da sua organização. Saiba mais sobre as políticas de senha do Microsoft Entra.

Resposta bem-sucedida

Exemplo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}
Parâmetro Descrição
continuation_token Token de continuação que o Microsoft Entra retorna.
poll_interval O tempo mínimo em segundos que o aplicativo deve aguardar entre solicitações de sondagem para verificar o status da solicitação de redefinição de senha por meio do ponto de extremidade /poll_completion, consulte etapa 5

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.
suberror Uma cadeia de caracteres de código de erro que pode ser usada para classificar ainda mais os tipos de erros.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação, como uma validação do token de continuação falha.
expired_token O token de continuação expirou.
invalid_grant A concessão enviada é inválida, como a senha enviada é muito curta. Use o parâmetro suberror para saber a causa exata do erro.

Se o parâmetro error tiver um valor de invalid_grant, o Microsoft Entra incluirá um parâmetro suberror em sua resposta. Aqui estão os valores possíveis do parâmetro suberror:

Valor do suberror Descrição
password_too_weak A senha é muito fraca, pois não atende aos requisitos de complexidade. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_too_short A nova senha tem menos de 8 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_too_long A nova senha tem mais de 256 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_recently_used A nova senha não deve ser a mesma usada recentemente. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_banned A nova senha contém uma palavra, frase ou padrão que é proibido. Saiba mais sobre as políticas de senha do Microsoft Entra.
password_is_invalid A senha é inválida, por exemplo, porque usa caracteres não permitidos. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta será possível se o aplicativo enviar uma senha de usuário.

Etapa 5: Sondar o status de redefinição de senha

Por fim, como a atualização da configuração do usuário com a nova senha gera algum atraso, o aplicativo pode usar o ponto de extremidade /poll_completion para sondar o Microsoft Entra para obter o status de redefinição de senha. O tempo mínimo em segundos que o aplicativo deve aguardar entre solicitações de sondagem é retornado do ponto de extremidade /submit no parâmetro poll_interval.

Aqui está um exemplo (apresentamos a solicitação de exemplo em várias linhas para legibilidade):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0...
Parâmetro Obrigatório Descrição
tenant_subdomain Sim O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Diretório (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o subdomínio do locatário, saiba como ler os detalhes do locatário.
continuation_token Sim Token de continuação que o Microsoft Entra retornou na solicitação anterior.
client_id Sim A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra.

Resposta bem-sucedida

Exemplo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
}
Parâmetro Descrição
status O status da solicitação de redefinição de senha. Se o Microsoft Entra retornar um status de falha, o aplicativo poderá reenviar a nova senha fazendo outra solicitação para o ponto de extremidade /submit e incluir o novo token de continuação.
continuation_token Token de continuação que o Microsoft Entra retorna. Se o status for bem-sucedido, o aplicativo poderá usar o token de continuação que o Microsoft Entra retorna para solicitar tokens de segurança por meio do ponto de extremidade /token, conforme explicado na etapa 5 do fluxo de inscrição. Isso significa que, depois que um usuário redefine a senha com êxito, você pode conectá-la diretamente ao seu aplicativo sem iniciar um novo fluxo de entrada.

Aqui estão os possíveis status que o Microsoft Entra retorna (possíveis valores do parâmetro status):

Valor do erro Descrição
succeeded Redefinição de senha concluída com êxito.
failed Falha na redefinição de senha. O aplicativo pode reenviar a nova senha fazendo outra solicitação para o ponto de extremidade /submit.
not_started A redefinição de senha não foi iniciada. O aplicativo pode verificar o status novamente mais tarde.
in_progress A redefinição de senha está em andamento. O aplicativo pode verificar o status novamente mais tarde.

Resposta de erro

Exemplo:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "expired_token", 
    "error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        552003 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros e reagir a erros.
error_description Uma mensagem de erro específica que pode ajudá-lo a identificar a causa de um erro de autenticação.
error_codes Uma lista de códigos de erro específicos do Microsoft Entra que podem ajudá-lo a diagnosticar erros.
timestamp A hora em que o erro ocorreu.
trace_id Um identificador exclusivo para a solicitação que pode ajudá-lo a diagnosticar erros.
correlation_id Um identificador exclusivo para a solicitação que pode ajudar no diagnóstico entre os componentes.

Aqui estão os possíveis erros que você pode encontrar (valores possíveis do parâmetro error):

Valor do erro Descrição
invalid_request Falha na validação do parâmetro de solicitação, como a validação de token de continuação falha.
expired_token O token de continuação expirou.

Conteúdo relacionado