Referência da API de autenticação nativa
Aplica-se a:
Locatários da força de
trabalho 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, sempre que possível, use um SDK de autenticação criado e suportado 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 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 suporta inscrição e entrada para dois métodos de autenticação:
E-mail com senha, que suporta inscrição e login com um e-mail e senha, e redefinição de senha de autoatendimento (SSPR).
Senha única por e-mail, que suporta inscrição e login com senha única de e-mail.
Nota
Atualmente, os pontos de extremidade da API de autenticação nativa não oferecem suporte ao CORS (Cross-Origin Resource Sharing).
Pré-requisitos
ID externa do Microsoft Entra para locatário de clientes. Se ainda não tiver uma, inscreva-se para uma avaliação gratuita.
Se ainda não o fez, Registe uma aplicação 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.
Se ainda não o fez, crie um fluxo de utilizadores no centro de administração do Microsoft Entra. Ao criar o fluxo de usuário, anote os atributos de usuário que você configura necessários, pois esses atributos são aqueles que o Microsoft Entra espera que seu aplicativo envie. Em Provedores de identidade, selecione a opção Enviar senha única por e-mail .
Para fluxo de entrada, registre um usuário 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.
Para o fluxo SSPR, habilite a redefinição de senha de autoatendimento para usuários clientes no locatário do cliente. O SSPR está disponível para usuários clientes que usam e-mail com método de autenticação de senha.
Token de continuação
Sempre que você chamar um ponto de extremidade em qualquer um dos fluxos, entrar, inscrever-se ou SSPR, o ponto de extremidade incluirá 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 diferentes pontos de extremidade 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 de 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/continuee /token.
Pontos de extremidade da API de inscrição
| Ponto final | Description |
|---|---|
/signup/v1.0/start |
Este ponto de extremidade inicia o fluxo de inscrição. Você passa ID de aplicativo válido, 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 suportados pelo Microsoft Entra. |
/signup/v1.0/challenge |
Seu aplicativo chama esse ponto de extremidade com uma lista de tipos de desafio suportados pelo Microsoft Entra. Em seguida, o Microsoft Entra seleciona um dos métodos de autenticação suportados 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 atributos errados. Esse ponto de extremidade gera um token de continuação e o retorna 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 for 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 que adquire da última chamada bem-sucedida para o /signup/v1.0/continue ponto de extremidade. |
Tipos de desafio de inscrição
A API permite que o aplicativo cliente anuncie os métodos de autenticação suportados, quando faz uma chamada para o Microsoft Entra. Para fazer isso, o aplicativo usa o challenge_type parâmetro na solicitação do aplicativo. Este 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 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.
Este diagrama indica que o aplicativo coleta nome de usuário (e-mail), senha (para e-mail 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 (e-mail), senha e todos os valores de atributos necessários e opcionais na mesma tela e, em seguida, enviar todos eles por meio do /signup/v1.0/start ponto de extremidade. Nesse caso, o aplicativo não precisa fazer chamadas e lidar com respostas para as 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 ao /signup/v1.0/start ponto de extremidade 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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
client_id |
Sim | A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra. |
username |
Sim | E-mail do usuário cliente com o qual ele deseja se inscrever, como contoso-consumer@contoso.com. |
challenge_type |
Sim | Uma lista separada por espaços de cadeias de caracteres de tipo de desafio de autorização que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de redirect desafio. O valor é esperado para oob redirect ou oob password redirect para e-mail com método de autenticação de senha. |
password |
Não | O valor de 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 ponto de extremidade ou posteriormente /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. Este parâmetro só é aplicável para e-mails 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 formatado como um objeto JSON cujos valores-chave são o nome programável dos atributos do usuário. Esses atributos podem ser incorporados ou personalizados, 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 do usuário por meio do /signup/v1.0/start ponto de extremidade ou posteriormente no ponto de /signup/v1.0/continue extremidade. Se você enviar todos os atributos necessários por meio do /signup/v1.0/start ponto de extremidade, não precisará enviar nenhum atributo no /signup/v1.0/continue ponto de extremidade. No entanto, se você enviar alguns atributos necessários via /signup/v1.0/start endpoint, poderá enviar os atributos necessários restantes posteriormente no /signup/v1.0/continue endpoint. Substitua {given_name}e {user_age}{postal_code} pelos valores de nome, idade e código postal, respectivamente, que o aplicativo coleta do usuário cliente. O Microsoft Entra ignora todos os atributos enviados, que não existem. |
Resposta de sucesso
Aqui está um exemplo de uma resposta bem-sucedida:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAA…",
}
| Parâmetro | Description |
|---|---|
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 de redirecionamento em sua resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parâmetro | Description |
|---|---|
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 precisa alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação criada e suportada 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
1003037
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 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 suberror valor do parâmetro 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 (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
A validação do parâmetro de solicitação falhou, 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 client_id o parâmetro, o valor da ID do cliente está vazio ou é inválido. Use o error_description parâmetro 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 ser um cliente público ou não estar habilitado para autenticação nativa. Use o suberror parâmetro para saber a causa exata do erro. |
unauthorized_client |
A ID do cliente usada na solicitação tem um formato de ID de cliente válido, mas não existe no locatário externo ou está incorreta. |
unsupported_challenge_type |
O challenge_type valor do parâmetro não inclui o redirect tipo de desafio. |
user_already_exists |
Usuário já existe. |
invalid_grant |
A senha que o aplicativo envia não atende a todos os requisitos de complexidade, como a senha ser muito curta. Use o suberror parâmetro para saber a causa exata do erro. Este parâmetro só é aplicável para e-mails com método de autenticação de senha. |
Se o parâmetro de erro tiver um valor de invalid_grant, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do parâmetro para um erro de suberror invalid_grant:
| Valor do suberro | Description |
|---|---|
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 é possível se o aplicativo enviar uma senha de usuário. |
password_too_short |
A nova palavra-passe tem menos de 8 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta é possível se o aplicativo enviar uma senha de usuário. |
password_too_long |
A nova palavra-passe tem mais de 256 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta é 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 é possível se o aplicativo enviar uma senha de usuário. |
password_banned |
A nova palavra-passe contém uma palavra, frase ou padrão que é proibido. Saiba mais sobre as políticas de senha do Microsoft Entra. Essa resposta é 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 é possível se o aplicativo enviar uma senha de usuário. |
Se o parâmetro de erro tiver um valor de invalid_client, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do parâmetro para um erro de suberror invalid_client:
| Valor do suberro | Description |
|---|---|
nativeauthapi_disabled |
A ID do cliente de um aplicativo que não está habilitado para autenticação nativa. |
Nota
Se você enviar todos os atributos necessários via /signup/v1.0/start endpoint, mas não todos os atributos opcionais, não poderá enviar nenhum atributo opcional adicional posteriormente por meio do /signup/v1.0/continue endpoint. 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. Consulte a tabela na seção Enviando atributos de usuário para pontos de extremidade para saber os atributos de usuário que você pode enviar para os /signup/v1.0/start pontos de extremidade e /signup/v1.0/continue .
Etapa 2: Selecione um método de autenticação
O aplicativo solicita que o Microsoft Entra selecione um dos tipos de desafio suportados para o usuário se autenticar. Para fazer isso, o aplicativo faz uma chamada para o /signup/v1.0/challenge ponto de extremidade. O aplicativo precisa incluir o token de continuação que adquire do /signup/v1.0/start ponto de extremidade 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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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ços de cadeias de caracteres de tipo de desafio de autorização que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de redirect desafio. Espera-se que o valor seja para oob redirect senha única de e-mail e oob password redirect para e-mail com método de autenticação de senha. |
continuation_token |
Sim | Token de continuação que o Microsoft Entra retornou na solicitação anterior. |
Resposta de sucesso
O Microsoft Entra envia uma senha única para o e-mail do usuário e, em seguida, responde com o tipo de desafio com o valor de oob e informações adicionais sobre a senha de uso único:
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 | Description |
|---|---|
interval |
O período de tempo, em segundos, que o aplicativo precisa esperar antes de tentar reenviar a OTP. |
continuation_token |
Token de continuação que o Microsoft Entra retorna. |
challenge_type |
Tipo de desafio selecionado para o usuário autenticar. |
binding_method |
O único valor válido é prompt. Este parâmetro pode ser usado no futuro para oferecer mais maneiras ao usuário de inserir a senha única. Emitido se challenge_type é oob |
challenge_channel |
O tipo de canal através do qual a senha única foi enviada. No momento, apenas o canal de e-mail é suportado. |
challenge_target_label |
Um e-mail ofuscado para onde a senha única foi enviada. |
code_length |
O comprimento da senha única que o Microsoft Entra gera. |
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 de redirecionamento em sua resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parâmetro | Description |
|---|---|
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 precisa alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação criada e suportada 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 componentes. |
Aqui estão os possíveis erros que você pode encontrar (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
Falha na validação do parâmetro de solicitação, como ID do cliente vazio ou inválido. |
expired_token |
O token de continuação expirou. |
unsupported_challenge_type |
O challenge_type valor do parâmetro não inclui o redirect tipo de desafio. |
invalid_grant |
O token de continuação é inválido. |
Etapa 3: Envie uma senha única
O aplicativo envia a senha única enviada para o e-mail do usuário. Como estamos enviando uma senha única, um oob parâmetro é necessário, e o grant_type parâmetro 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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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 | Uma solicitação para o /signup/v1.0/continue ponto de extremidade pode ser usada para enviar senha, senha ou atributos de usuário únicos. Neste caso, o grant_type valor é usado para diferenciar entre esses três casos de uso. Os valores possíveis para o grant_type são oob, password, attributes. Nesta chamada, como estamos enviando uma senha única, espera-se que o valor seja oob. |
oob |
Sim | A senha única que o usuário cliente recebeu em seu e-mail. Substitua {otp_code} pelos valores de senha única que o usuário cliente recebeu em seu e-mail. Para reenviar uma senha única, o aplicativo precisa fazer uma solicitação ao /signup/v1.0/challenge ponto de extremidade novamente. |
Depois que o aplicativo envia com êxito a senha única, o fluxo de inscrição depende dos cenários, conforme mostrado na tabela:
| Cenário | Como proceder |
|---|---|
O aplicativo envia com êxito a senha do usuário (para e-mail com método de autenticação de senha) através do /signup/v1.0/start ponto de extremidade, e nenhum atributo é configurado no centro de administração do Microsoft Entra ou todos os atributos de usuário necessários são enviados através do /signup/v1.0/start ponto de extremidade. |
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 na etapa 5. |
O aplicativo envia com êxito a senha do usuário (para e-mail com método de autenticação de senha) através do /signup/v1.0/start, mas não 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 /signup/v1.0/continue ponto de extremidade. A resposta é semelhante à dos atributos de usuário necessários. Envie os atributos de usuário a mostrado em enviar atributos de usuário. |
O aplicativo não envia a senha do usuário (para e-mail com método de autenticação de senha) via /signup/v1.0/start endpoint. |
A resposta do Microsoft Entra indica que a credencial é necessária. Ver resposta. Esta resposta é possível para e-mail com método de autenticação de senha. |
Response
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 | Description |
|---|---|
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 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 (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
credential_required |
A autenticação é necessária para a criação da conta, portanto, você precisa fazer uma chamada para o /signup/v1.0/challenge ponto de extremidade para determinar a credencial que o usuário deve 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 client_id o parâmetro, o valor da ID do cliente está vazio ou inválido ou o administrador de locatário externo não habilitou a OTP de email para todos os usuários locatários. |
invalid_grant |
O tipo de concessão incluído na solicitação não é válido ou suportado, ou o valor da OTP está incorreto. |
expired_token |
O token de continuação incluído na solicitação expirou. |
Se o parâmetro de erro tiver um valor de invalid_grant, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do parâmetro para um erro de suberror invalid_grant:
| Valor do suberro | Description |
|---|---|
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 /signup/v1.0/challenge ponto de extremidade para determinar a credencial que o usuário deve 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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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ços de cadeias de caracteres de tipo de desafio de autorização que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de redirect desafio. Para o fluxo de inscrição de e-mail 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 de sucesso
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 bem-sucedida 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 | Description |
|---|---|
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 de redirecionamento em sua resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parâmetro | Description |
|---|---|
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 precisa alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação criada e suportada pela Microsoft.
Etapa 4: Autenticar e obter token para se inscrever
O aplicativo precisa enviar a credencial do usuário, no caso senha, que o Microsoft Entra solicitou na etapa anterior. O aplicativo precisa enviar uma credencial de senha se não o fez por meio do /signup/v1.0/start ponto de extremidade. O aplicativo faz uma solicitação ao /signup/v1.0/continue ponto de extremidade para enviar a senha. Como estamos enviando uma senha, um password parâmetro é necessário, e o grant_type parâmetro deve ter uma senha de valor.
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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
continuation_token |
Sim | Token de continuação que o Microsoft Entra retornou 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 |
Sim | Uma solicitação para o /signup/v1.0/continue ponto de extremidade pode ser usada para enviar senha, senha ou atributos de usuário únicos. Neste caso, o grant_type valor é usado para diferenciar entre esses três casos de uso. Os valores possíveis para o grant_type são oob, password, attributes. Nesta chamada, como estamos enviando a senha do usuário, espera-se que o valor seja senha. |
password |
Sim | O valor de 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 de sucesso
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 tiverem sido enviados por meio do /signup/v1.0/start ponto de extremidade, 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 na 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]*$"
}
}
],
}
Nota
Os atributos personalizados (também conhecidos como extensões de diretório) são nomeados usando a convenção extension_{appId-without-hyphens}_{attribute-name} onde {appId-without-hyphens} é a versão removida da ID do cliente para o aplicativo de extensões. Por exemplo, se a ID do cliente do aplicativo de extensões for 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 | Description |
|---|---|
error |
Esse atributo é 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 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 enviar na 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 este parâmetro é a resposta se o valor do error parâmetro é attributes_required. |
Aqui estão os possíveis erros que você pode encontrar (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
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 client_id o parâmetro, 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 suportado. Os valores possíveis para o grant_type são oob, senha, atributos |
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 de redirecionamento em sua resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parâmetro | Description |
|---|---|
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 precisa alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação criada e suportada 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": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6",
"suberror": "password_too_weak"
}
| Parâmetro | Description |
|---|---|
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 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 (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
A validação do parâmetro de solicitação falhou, como quando o challenge_type parâmetro inclui um tipo de desafio inválido. |
invalid_grant |
A subvenção enviada é inválida, tal como a palavra-passe submetida é demasiado curta. Use o suberror parâmetro 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 de erro tiver um valor de invalid_grant, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do suberror parâmetro:
| Valor do suberro | Description |
|---|---|
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 palavra-passe tem menos de 8 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra. |
password_too_long |
A nova palavra-passe 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 palavra-passe 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 é 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 /signup/v1.0/continue ponto de extremidade para enviar os atributos de usuário necessários. Como estamos enviando atributos, um attributes parâmetro é necessário, e o grant_type parâmetro 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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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 | Uma solicitação para o /signup/v1.0/continue ponto de extremidade pode ser usada para enviar senha, senha ou atributos de usuário únicos. Neste caso, o grant_type valor é usado para diferenciar entre esses três casos de uso. Os valores possíveis para o grant_type são oob, password, attributes. Nesta chamada, como estamos enviando atributos de usuário, espera-se que o valor seja atributos. |
attributes |
Sim | Os valores de atributo de usuário que o aplicativo coleta do usuário cliente. O valor é uma cadeia de caracteres, mas formatado como um objeto JSON cujos valores-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}e {user_age}{postal_code} pelos valores de nome, idade e código postal, respectivamente, que o aplicativo coleta do usuário cliente. O Microsoft Entra ignora todos os atributos enviados, que não existem. |
Resposta de sucesso
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 | Description |
|---|---|
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 de redirecionamento em sua resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parâmetro | Description |
|---|---|
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 precisa alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação criada e suportada 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 componentes. |
continuation_token |
Token de continuação que o Microsoft Entra retorna. |
unverified_attributes |
Uma lista (matriz de objetos) de nomes de chaves de atributos que devem ser verificados. Este parâmetro é incluído na resposta quando o error valor do parâmetro é 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 error valor do parâmetro é attributes_required. |
invalid_attributes |
Uma lista (matriz de objetos) de atributos que falharam na validação. Este parâmetro é incluído na resposta quando o suberror valor do parâmetro é 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 (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
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 client_id o parâmetro, o valor da ID do cliente está vazio ou é inválido. |
invalid_grant |
O tipo de concessão fornecido não é válido ou não é suportado ou falha na validação, como falha na validação de atributos. Use o suberror parâmetro 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 de erro tiver um valor de invalid_grant, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do parâmetro para um erro de suberror invalid_grant:
| Valor do suberro | Description |
|---|---|
attribute_validation_failed |
Falha na validação do atributo do usuário. 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 /token ponto de extremidade e fornece o token de continuação obtido na 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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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 o token de continuação. |
continuation_token |
Sim | Token de continuação que o Microsoft Entra retornou na etapa anterior. |
scope |
Sim | Uma lista separada por espaços 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 | E-mail do usuário cliente com o qual ele deseja se inscrever, como contoso-consumer@contoso.com. |
Resposta com êxito
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 | Description |
|---|---|
access_token |
O token de acesso que o aplicativo solicitou do /token ponto de extremidade. O aplicativo pode usar esse token de acesso para solicitar acesso a recursos seguros, como APIs da Web. |
token_type |
Indica o valor do tipo de token. O único tipo que o Microsoft Entra suporta é o Portador. |
expires_in |
O período de tempo, em segundos, o token de acesso permanece válido. |
scopes |
Uma lista separada por espaços de escopos para os quais o token de acesso é válido. |
refresh_token |
Um token de atualização 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 são de longa duração. 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: Emitido apenas se offline_access âmbito tiver sido 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, e os clientes confidenciais podem usar esse token para autorização. Para obter mais informações sobre tokens de ID, consulte Tokens de ID. Nota: Emitido apenas 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 componentes. |
Aqui estão os possíveis erros que você pode encontrar (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
Falha na validação do parâmetro de solicitação, como 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 pontos 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. Os atributos opcionais não são obrigatórios para que o fluxo de inscrição seja concluído. Portanto, quando todos os atributos são opcionais, eles devem ser enviados antes que o nome de usuário seja verificado. 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 final | Atributos obrigatórios | Atributos opcionais | Atributos obrigatórios e opcionais |
|---|---|---|---|
/signup/v1.0/start Ponto final |
Sim | Sim | Sim |
/signup/v1.0/continue ponto de extremidade antes da verificação do nome de usuário |
Sim | Sim | Sim |
/signup/v1.0/continue ponto de extremidade após a verificação do nome de usuário |
Sim | No | 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 suportados 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 [en] | Um único valor, como Language, norueguês. |
| Caixa de seleçãoMultiSelect | Um ou vários valores, como um hobby ou hobbies, Dançar ou Dançar, Nadar, 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 fazer referência a atributos de usuário
Ao criar um fluxo de usuário de inscrição, você configura 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, o 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 início de sessão
Os usuários precisam entrar com o método de autenticação que eles usam para se inscrever. Por exemplo, os usuários que se inscreverem usando e-mail com método de autenticação de senha devem entrar em e-mail e senha.
Para solicitar tokens de segurança, seu aplicativo interage com três pontos /initiate/challenge de extremidade e /token.
Pontos de extremidade da API de entrada
| Ponto final | Description |
|---|---|
/initiate |
Este ponto de extremidade inicia o fluxo de entrada. Se seu aplicativo chamá-lo 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 seu aplicativo solicitar o uso de métodos de autenticação que não são suportados pelo Microsoft Entra, essa resposta de ponto de extremidade pode 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, em seguida, envia uma senha única para o canal de desafio escolhido, como e-mail. Se seu aplicativo chamar esse ponto de extremidade repetidamente, uma nova OTP será enviada cada vez que uma chamada for feita. |
/token |
Este 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 suportados, quando faz uma chamada para o Microsoft Entra. Para fazer isso, o aplicativo usa o challenge_type parâmetro em suas solicitações. Este 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 de quando o aplicativo entra. Por exemplo, o método de autenticação de e-mail com 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.
Depois que o aplicativo verifica o e-mail do usuário com OTP, ele recebe tokens de segurança. Se a entrega da senha única atrasar ou nunca for entregue no e-mail do usuário, o usuário pode 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, ela invalida o código enviado anteriormente.
Nas seções a seguir, resumimos o fluxo do 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 ao /initiate ponto de extremidade 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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
client_id |
Sim | A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra. |
username |
Sim | E-mail do usuário do cliente, como contoso-consumer@contoso.com. |
challenge_type |
Sim | Uma lista separada por espaços de cadeias de caracteres de tipo de desafio de autorização que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de redirect desafio. Espera-se que o valor seja para oob redirect senha única de e-mail e password redirect para e-mail com senha. |
Resposta de sucesso
Aqui está um exemplo de uma resposta bem-sucedida:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parâmetro | Description |
|---|---|
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 de redirecionamento em sua resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parâmetro | Description |
|---|---|
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 precisa alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação criada e suportada 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 componentes. |
Aqui estão os possíveis erros que você pode encontrar (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
A validação do parâmetro de solicitação falhou, como quando o challenge_type parâmetro inclui um tipo de desafio inválido. ou a solicitação não incluiu client_id o parâmetro o valor da ID do cliente está vazio ou é inválido. Use o error_description parâmetro para saber a causa exata do erro. |
unauthorized_client |
A ID do cliente usada na solicitação tem um formato de ID de cliente válido, mas não existe no locatário externo ou está incorreta. |
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 ser um cliente público ou não estar habilitado para autenticação nativa. Use o suberror parâmetro para saber a causa exata do erro. |
user_not_found |
O nome de usuário não existe. |
unsupported_challenge_type |
O challenge_type valor do parâmetro não inclui o redirect tipo de desafio. |
Se o parâmetro de erro tiver um valor de invalid_client, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do parâmetro para um erro de suberror invalid_client:
| Valor do suberro | Description |
|---|---|
nativeauthapi_disabled |
A ID do cliente de um aplicativo que não está habilitado para autenticação nativa. |
Etapa 2: Selecione um método de autenticação
Para continuar com o fluxo, o aplicativo usa o token de continuação adquirido na etapa anterior para solicitar que o Microsoft Entra selecione um dos tipos de desafio suportados para o usuário se autenticar. O aplicativo faz uma solicitação POST para o /challenge ponto de extremidade.
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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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ços de cadeias de caracteres de tipo de desafio de autorização que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de redirect desafio. Espera-se que o valor seja para oob redirect senha única de e-mail e password redirect para e-mail com senha. |
Resposta de sucesso
Se o administrador do locatário configurou a senha única de email no centro de administração do Microsoft Entra como 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 de oob e fornece mais informações sobre a senha de uso único.
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 | Description |
|---|---|
continuation_token |
Token de continuação que o Microsoft Entra retorna. |
challenge_type |
Tipo de desafio selecionado para o usuário autenticar. |
binding_method |
O único valor válido é prompt. Este parâmetro pode ser usado no futuro para oferecer mais maneiras para o usuário inserir a senha única. Emitido se challenge_type é oob |
challenge_channel |
O tipo de canal através do qual a senha única foi enviada. No momento, nós suportamos e-mail. |
challenge_target_label |
Um e-mail ofuscado para onde a senha única foi enviada. |
code_length |
O comprimento da senha única que o Microsoft Entra gera. |
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 de redirecionamento em sua resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parâmetro | Description |
|---|---|
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 precisa alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação criada e suportada 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 componentes. |
Aqui estão os possíveis erros que você pode encontrar (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
A validação do parâmetro de solicitação falhou, 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 challenge_type valor do parâmetro não inclui o redirect tipo de desafio. |
Etapa 3: Solicitação de tokens de segurança
O aplicativo faz uma solicitação POST para o /token ponto de extremidade e fornece as credenciais do usuário escolhidas na etapa anterior, neste 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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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 e-mail com método de autenticação de senha e oob para método de autenticação de senha única de e-mail. |
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 perfil, *openid e e-mail. O aplicativo precisa incluir o escopo openid 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 e-mail com senha) |
O valor de 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 senha única de e-mail) |
A senha única que o usuário cliente recebeu em seu e-mail. Substitua {otp_code} pela senha única que o usuário cliente recebeu em seu e-mail. Para reenviar uma senha única, o aplicativo precisa fazer uma solicitação ao /challenge ponto de extremidade novamente. |
Resposta com êxito
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 | Description |
|---|---|
token_type |
Indica o valor do tipo de token. O único tipo que o Microsoft Entra suporta é o Portador. |
scopes |
Uma lista separada por espaços de escopos para os quais o token de acesso é válido. |
expires_in |
O período de tempo, em segundos, o token de acesso permanece válido. |
access_token |
O token de acesso que o aplicativo solicitou do /token ponto de extremidade. O aplicativo pode usar esse token de acesso para solicitar acesso a recursos seguros, como APIs da Web. |
refresh_token |
Um token de atualização 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 são de longa duração. 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: Emitido apenas se você solicitar offline_access escopo. |
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 fez login. O aplicativo pode armazenar os valores em cache e exibi-los, e os clientes confidenciais podem usar esse token para autorização. Para obter mais informações sobre tokens de ID, consulte Tokens de ID. Nota: Emitido apenas se você solicitar o 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 componentes. |
Aqui estão os possíveis erros que você pode encontrar (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
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 login 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 escopo incluídos na solicitação são inválidos. |
Se o parâmetro de erro tiver um valor de invalid_grant, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do parâmetro para um erro de suberror invalid_grant:
| Valor do suberro | Description |
|---|---|
invalid_oob_value |
O valor da senha única é inválido. Este suberro só aplica o código de acesso único do e-mail |
Reposição Personalizada de Palavra-passe (SSPR)
Se você usar email e senha como método de autenticação em seu aplicativo, use a API de redefinição de senha de autoatendimento (SSPR) para permitir que os usuários clientes redefinissem suas senhas. Use esta 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 final | Description |
|---|---|
/start |
Seu aplicativo chama esse ponto de extremidade quando o usuário cliente seleciona Esqueceu a senha ou o link ou botão Alterar senha no aplicativo. Esse ponto de extremidade valida o nome de usuário (e-mail) do usuário e, em seguida, retorna um token de continuação para uso no fluxo de redefinição de senha. Se o seu aplicativo solicitar o uso de métodos de autenticação que não são suportados pelo Microsoft Entra, essa resposta de ponto de extremidade pode indicar ao seu aplicativo que ele precisa usar um fluxo de autenticação baseado em navegador. |
/challenge |
Aceita uma lista de tipos de desafio suportados pelo cliente e o token de continuação. Um desafio é emitido para uma das credenciais de recuperação preferidas. Por exemplo, o desafio oob emite uma senha única fora de banda para o e-mail associado à conta de usuário do cliente. Se o seu aplicativo solicitar o uso de métodos de autenticação que não são suportados pelo Microsoft Entra, essa resposta de ponto de extremidade pode indicar ao seu aplicativo que ele precisa usar um fluxo de autenticação baseado em navegador. |
/continue |
Valida o desafio emitido pelo ponto de /challenge extremidade e, em seguida, retorna um token de continuação para o /submit ponto de extremidade 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. Este ponto de extremidade emite outro token de continuação. |
/poll_completion |
Finalmente, o aplicativo pode usar o token de continuação emitido pelo /submit ponto de extremidade 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 suportados, quando faz uma chamada para o Microsoft Entra. Para fazer isso, o aplicativo usa o challenge_type parâmetro em suas solicitações. Este parâmetro contém valores predefinidos, que representam diferentes métodos de autenticação.
Para o fluxo SSPR, os valores do tipo de desafio são oob e redirecionar.
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.
Este diagrama indica que o aplicativo coleta nome de usuário (e-mail) e 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 (e-mail) e a nova senha na mesma tela. Neste caso, a aplicação guarda a palavra-passe e, em seguida, envia-a através do /submit ponto de extremidade onde é 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 ao /start ponto de extremidade 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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
client_id |
Sim | A ID do aplicativo (cliente) do aplicativo que você registrou no centro de administração do Microsoft Entra. |
username |
Sim | E-mail do usuário do cliente, como contoso-consumer@contoso.com. |
challenge_type |
Sim | Uma lista separada por espaços de cadeias de caracteres de tipo de desafio de autorização que o aplicativo suporta, como oob password redirect. A lista deve sempre incluir o tipo de redirect desafio. Para esta solicitação, espera-se que o valor contenha oob redirect. |
Resposta de sucesso
Exemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parâmetro | Description |
|---|---|
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 de redirecionamento em sua resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parâmetro | Description |
|---|---|
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 precisa alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação criada e suportada 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 componentes. |
Aqui estão os possíveis erros que você pode encontrar (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
A validação do parâmetro de solicitação falhou, como quando o challenge_type parâmetro inclui um tipo de desafio inválido ou a solicitação não incluiu client_id parâmetro, o valor da ID do cliente está vazio ou inválido. Use o error_description parâmetro para saber a causa exata do erro. |
user_not_found |
O nome de usuário não existe. |
unsupported_challenge_type |
O challenge_type valor do parâmetro não inclui o redirect tipo de desafio. |
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 ser um cliente público ou não estar habilitado para autenticação nativa. Use o suberror parâmetro para saber a causa exata do erro. |
unauthorized_client |
A ID do cliente usada na solicitação tem um formato de ID de cliente válido, mas não existe no locatário externo ou está incorreta. |
Se o parâmetro de erro tiver um valor de invalid_client, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do parâmetro para um erro de suberror invalid_client:
| Valor do suberro | Description |
|---|---|
nativeauthapi_disabled |
A ID do cliente de um aplicativo que não está habilitado para autenticação nativa. |
Etapa 2: Selecione um método de autenticação
Para continuar com o fluxo, o aplicativo usa o token de continuação adquirido na etapa anterior para solicitar que o Microsoft Entra selecione um dos tipos de desafio suportados para o usuário se autenticar. O aplicativo faz uma solicitação POST para o /challenge ponto de extremidade. 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ó suportamos OTP por e-mail.
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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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ços de cadeias de caracteres de tipo de desafio de autorização que o aplicativo suporta, como oob redirect. A lista deve sempre incluir o tipo de redirect desafio. Para esta solicitação, espera-se que o valor contenha oob redirect. |
Resposta de sucesso
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 | Description |
|---|---|
continuation_token |
Token de continuação que o Microsoft Entra retorna. |
challenge_type |
Tipo de desafio selecionado para o usuário autenticar. |
binding_method |
O único valor válido é prompt. Este parâmetro pode ser usado no futuro para oferecer mais maneiras ao usuário de inserir a senha única. Emitido se challenge_type é oob |
challenge_channel |
O tipo de canal através do qual a senha única foi enviada. No momento, nós suportamos e-mail. |
challenge_target_label |
Um e-mail ofuscado para onde a senha única foi enviada. |
code_length |
O comprimento da senha única que o Microsoft Entra gera. |
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 de redirecionamento em sua resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parâmetro | Description |
|---|---|
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 precisa alternar para um fluxo de autenticação baseado na Web. Nesse caso, recomendamos que você use uma biblioteca de autenticação criada e suportada 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 componentes. |
Aqui estão os possíveis erros que você pode encontrar (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
A validação do parâmetro de solicitação falhou, como quando o parâmetro inclui um tipo de desafio inválido ou falha na validação do challenge_type token de continuação. |
expired_token |
O token de continuação expirou. |
unsupported_challenge_type |
O challenge_type valor do parâmetro não inclui o redirect tipo de desafio. |
Etapa 3: Envie uma senha única
Em seguida, o aplicativo faz uma solicitação POST para o /continue ponto de extremidade. Na solicitação, o aplicativo precisa incluir as credenciais do usuário escolhidas na etapa anterior e o token de continuação emitido a partir do /challenge ponto de extremidade.
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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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 |
Sim | A senha única que o usuário cliente recebeu em seu e-mail. Substitua {otp_code} pela senha única que o usuário cliente recebeu em seu e-mail. Para reenviar uma senha única, o aplicativo precisa fazer uma solicitação ao /challenge ponto de extremidade novamente. |
Resposta de sucesso
Exemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| Parâmetro | Description |
|---|---|
expires_in |
Tempo em segundos antes do continuation_token expirar. O valor máximo de é 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
55200
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 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 (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
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 client_id o parâmetro, o valor da ID do cliente está vazio ou inválido ou o administrador de locatário externo não habilitou o SSPR e a OTP de e-mail para todos os usuários locatários. Use o error_description parâmetro para saber a causa exata do erro. |
invalid_grant |
O tipo de concessão é desconhecido ou não corresponde ao valor esperado do tipo de concessão. Use o suberror parâmetro para saber a causa exata do erro. |
expired_token |
O token de continuação expirou. |
Se o parâmetro de erro tiver um valor de invalid_grant, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do parâmetro para um erro de suberror invalid_grant:
| Valor do suberro | Description |
|---|---|
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 /continue ponto de extremidade para enviar a senha fazendo uma solicitação POST para o /submit ponto de extremidade.
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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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 palavra-passe do utilizador. 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 de sucesso
Exemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"poll_interval": 2
}
| Parâmetro | Description |
|---|---|
continuation_token |
Token de continuação que o Microsoft Entra retorna. |
poll_interval |
A quantidade mínima de tempo, em segundos, que o aplicativo deve aguardar entre as solicitações de sondagem para verificar o status da solicitação de redefinição de senha por meio do ponto de extremidade, consulte a /poll_completion 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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 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 (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
Falha na validação do parâmetro de solicitação, como uma validação do token de continuação. |
expired_token |
O token de continuação expirou. |
invalid_grant |
A subvenção enviada é inválida, tal como a palavra-passe submetida é demasiado curta. Use o suberror parâmetro para saber a causa exata do erro. |
Se o parâmetro de erro tiver um valor de invalid_grant, o Microsoft Entra incluirá um suberror parâmetro em sua resposta. Aqui estão os valores possíveis do suberror parâmetro:
| Valor do suberro | Description |
|---|---|
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 palavra-passe tem menos de 8 caracteres. Saiba mais sobre as políticas de senha do Microsoft Entra. |
password_too_long |
A nova palavra-passe 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 palavra-passe 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 é 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 incorre em algum atraso, o aplicativo pode usar o ponto de extremidade para pesquisar o /poll_completion Microsoft Entra para obter o status de redefinição de senha. A quantidade mínima de tempo, em segundos, que o aplicativo deve aguardar entre as solicitações de sondagem é retornada do /submit ponto de extremidade no poll_interval parâmetro.
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 | Necessário | Descrição |
|---|---|---|
tenant_subdomain |
Sim | O subdomínio do locatário externo que você criou. Na URL, substitua {tenant_subdomain} pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do seu locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o subdomínio do inquilino, saiba como ler os detalhes do inquilino. |
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 de sucesso
Exemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "succeeded",
"continuation_token":"czZCaGRSa3F0..."
}
| Parâmetro | Description |
|---|---|
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 ao /submit ponto de extremidade 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 /token ponto de extremidade, conforme explicado na etapa 5 do fluxo de inscrição. Isso significa que, depois que um usuário redefine sua senha com êxito, você pode conectá-lo diretamente ao seu aplicativo sem iniciar um novo fluxo de entrada. |
Aqui estão os possíveis status que o Microsoft Entra retorna (valores possíveis do status parâmetro):
| Valor de erro | Description |
|---|---|
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 /submit ponto de extremidade. |
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: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "b386ad47-...-0000",
"correlation_id": "72f57f26-...-3fa6"
}
| Parâmetro | Description |
|---|---|
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 componentes. |
Aqui estão os possíveis erros que você pode encontrar (possíveis valores do error parâmetro):
| Valor de erro | Description |
|---|---|
invalid_request |
Falha na validação do parâmetro de solicitação, como a validação do token de continuação. |
expired_token |
O token de continuação expirou. |
Próximos passos
- Referência da API OTP de e-mail de autenticação nativa.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários