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/macOS para autenticação nativa.

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

A API de autenticação nativa do Microsoft Entra 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.

Pré-requisitos

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

2. 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.

3. 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 conforme necessário, pois esses atributos são aqueles que o Microsoft Entra espera que seu aplicativo envie.

4. Associe o registro do seu aplicativo ao fluxo de usuários.

5. 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.

6. Para o fluxo SSPR, habilite a redefinição de senha de autoatendimento para usuários clientes no locatário externo. 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

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 

Resposta de sucesso

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

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

{
    "continuation_token": "AQABAAEAAA…",
} 

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" 
} 

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [ 
        1003037 
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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:

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:

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…

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
} 

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"
}

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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}

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

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..."
} 

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

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:

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…

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..."
}

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" 
} 

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}

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]*$"
            }
        }
    ],
}

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

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" 
} 

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": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "suberror": "password_too_weak"
}

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

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:

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...

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..."
} 

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" 
} 

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...", 
    "error_codes": [
        552003
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd" 
}

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

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:

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 

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..."
}

Resposta de erro

Exemplo:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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.

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.

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

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.

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 

Resposta de sucesso

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

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

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" 
} 

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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:

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... 

Resposta de sucesso

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
} 

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

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
} 

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" 
} 

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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 

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..."
}

Resposta de erro

Exemplo:

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

{ 
    "error": "invalid_grant", 
    "error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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:

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:

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 

Resposta de sucesso

Exemplo:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

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" 
} 

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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:

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... 

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
} 

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" 
} 

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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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}

Resposta de sucesso

Exemplo:

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

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
} 

Resposta de erro

Exemplo:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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:

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}

Resposta de sucesso

Exemplo:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

Resposta de erro

Exemplo:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

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:

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... 

Resposta de sucesso

Exemplo:

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

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
} 

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

Resposta de erro

Exemplo:

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

{ 
    "error": "expired_token", 
    "error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        552003 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 

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

Conteúdos relacionados

• Configure um provedor de declarações personalizado.