Contorno e restrições de URI de redirecionamento (URL de resposta)

Para entrar em um usuário, seu aplicativo deve enviar uma solicitação de logon para o ponto de extremidade de autorização do Microsoft Entra, com um URI de redirecionamento especificado como parâmetro. O URI de redirecionamento é um recurso de segurança crítico que garante que o servidor de autenticação do Microsoft Entra envie apenas códigos de autorização e tokens de acesso para o destinatário pretendido. Este artigo descreve os recursos e restrições de URIs de redirecionamento na plataforma de identidade da Microsoft.

O que é um URI de redirecionamento?

Um URI de redirecionamento, ou URL de resposta, é o local para onde o servidor de autenticação do Microsoft Entra envia o usuário depois que ele autoriza e recebe um token de acesso com êxito. Para entrar em um usuário, seu aplicativo deve enviar uma solicitação de login com um URI de redirecionamento especificado como parâmetro, portanto, depois que o usuário entrar com êxito, o servidor de autenticação redirecionará o usuário e emitirá um token de acesso ao URI de redirecionamento especificado na solicitação de login.

Por que os URIs de redirecionamento precisam ser adicionados a um registro de aplicativo?

Por motivos de segurança, o servidor de autenticação não redirecionará usuários nem enviará tokens para um URI que não seja adicionado ao registro do aplicativo. Os servidores de login do Microsoft Entra apenas redirecionam usuários e enviam tokens para redirecionar URIs que foram adicionados a um registro de aplicativo. Se o URI de redirecionamento especificado na solicitação de login não corresponder a nenhum dos URIs de redirecionamento que você adicionou em seu aplicativo, você receberá uma mensagem de erro como AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application.

Para obter mais informações sobre códigos de erro, consulte Códigos de erro de autenticação e autorização do Microsoft Entra.

Devo adicionar um URI de redirecionamento a um registro de aplicativo?

Se você deve adicionar um URI de redirecionamento ao registro do seu aplicativo depende do protocolo de autorização que seu aplicativo usa. Você deve adicionar URIs de redirecionamento apropriados ao registro do aplicativo se o aplicativo estiver usando os seguintes protocolos de autorização:

• Fluxo de código de autorização do OAuth 2.0
• Fluxo de credenciais do cliente OAuth 2.0
• Fluxo de concessão implícito do OAuth 2.0
• OpenID Connect
• Protocolo SAML de início de sessão único

Você não precisará adicionar URIs de redirecionamento ao registro do aplicativo se o aplicativo estiver usando os seguintes protocolos ou recursos de autorização.

• Autenticação nativa
• Fluxo de código do dispositivo OAuth 2.0
• OAuth 2.0 em nome do fluxo
• Fluxo de credenciais de senha do proprietário do recurso OAuth 2.0
• Fluxo de autenticação integrado do Windows
• SAML 2.0 Identity Provider (IdP) para logon único

A que plataforma devo adicionar o(s) meu(s) URI(s) de redirecionamento?

Se o aplicativo que você está criando contiver um ou vários URIs de redirecionamento no registro do aplicativo, você precisará habilitar uma configuração de fluxo de cliente público. As tabelas a seguir fornecem orientação sobre o tipo de URI de redirecionamento que você deve ou não adicionar com base na plataforma na qual está criando seu aplicativo.

Configuração de URI de redirecionamento de aplicativo Web

Configuração de URI de redirecionamento de aplicativos móveis e de desktop

Se você estiver criando um aplicativo iOS usando um dos seguintes métodos, use a plataforma de aplicativos móveis e de desktop para adicionar um URI de redirecionamento:

• Aplicativos iOS usando SDKs herdados (ADAL)
• Aplicativos iOS usando SDKs de código aberto (AppAuth)
• Aplicativos iOS usando tecnologia cross-plat que não suportamos (Flutter)
• Aplicativos iOS implementando nossos protocolos OAuth diretamente
• Aplicativos macOS usando tecnologia cross-plat que não suportamos (Electron)

Aplicativos que não exigem um URI de redirecionamento

Quais são as restrições de URIs de redirecionamento para aplicativos Microsoft Entra?

O modelo de aplicativo Microsoft Entra especifica as seguintes restrições para redirecionar URIs:

• Os URIs de redirecionamento devem começar com o esquema https, com exceções para alguns URIs de redirecionamento de host local.

• Os URIs de redirecionamento diferenciam maiúsculas de minúsculas e devem corresponder ao caminho da URL do seu aplicativo em execução.

  Exemplos:

  • Se seu aplicativo incluir como parte de seu caminho .../abc/response-oidc, não especifique .../ABC/response-oidc no URI de redirecionamento. Como o navegador da Web trata os caminhos como diferenciadores de maiúsculas e minúsculas, os cookies associados podem .../abc/response-oidc ser excluídos se redirecionados para o URL incompatível com maiúsculas e minúsculas .../ABC/response-oidc .

• Os URIs de redirecionamento não configurados com um segmento de caminho são retornados com uma barra à direita ('/') na resposta. Isto aplica-se apenas quando o modo de resposta é query ou fragment.

  Exemplos:

  • https://contoso.com é devolvido como https://contoso.com/
  • http://localhost:7071 é devolvido como http://localhost:7071/

• Os URIs de redirecionamento que contêm um segmento de caminho não são acrescentados com uma barra à direita na resposta.

  Exemplos:

  • https://contoso.com/abc é devolvido como https://contoso.com/abc
  • https://contoso.com/abc/response-oidc é devolvido como https://contoso.com/abc/response-oidc

• Os URIs de redirecionamento não suportam caracteres especiais - ! $ ' ( ) , ;

Número máximo de URIs de redirecionamento e comprimento de URI

O número máximo de URIs de redirecionamento não pode ser aumentado por motivos de segurança. Se o seu cenário exigir mais URIs de redirecionamento do que o limite máximo permitido, considere a seguinte abordagem de parâmetro de estado como a solução. A tabela a seguir mostra o número máximo de URIs de redirecionamento que você pode adicionar a um registro de aplicativo na plataforma de identidade da Microsoft.

Você pode usar um máximo de 256 caracteres para cada URI de redirecionamento adicionado a um registro de aplicativo.

Redirecionar URIs em objetos de aplicativo versus entidade de serviço

• Sempre adicione URIs de redirecionamento somente ao objeto do aplicativo.
• Nunca adicione valores de URI de redirecionamento a uma entidade de serviço porque esses valores podem ser removidos quando o objeto da entidade de serviço é sincronizado com o objeto do aplicativo. Isso pode acontecer devido a qualquer operação de atualização que dispara uma sincronização entre os dois objetos.

Suporte a parâmetros de consulta em URIs de redirecionamento

Os parâmetros de consulta são permitidos em URIs de redirecionamento para aplicativos que só entram em usuários com contas corporativas ou de estudante.

Os parâmetros de consulta não são permitidos em URIs de redirecionamento para qualquer registro de aplicativo configurado para entrar em usuários com contas pessoais da Microsoft, como Outlook.com (Hotmail), Messenger, OneDrive, MSN, Xbox Live ou Microsoft 365.

Público de início de sessão de registo da aplicação	Suporta parâmetros de consulta no URI de redirecionamento
Contas somente neste diretório organizacional (somente Contoso - Locatário único)
Contas em qualquer diretório organizacional (Qualquer diretório do Microsoft Entra — Multi-inquilino)
Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra - Multilocatário) e contas pessoais da Microsoft (como Skype e Xbox)
Apenas contas pessoais da Microsoft

Regimes apoiados

HTTPS: O esquema HTTPS (https://) é suportado para todos os URIs de redirecionamento baseados em HTTP.

HTTP: O esquema HTTP (http://) é suportado apenas para URIs localhost e deve ser usado somente durante o desenvolvimento e teste de aplicativos locais ativos.

Exceções de host local

De acordo com as seções 8.3 e 7.3 do RFC 8252, os URIs de redirecionamento "loopback" ou "localhost" vêm com duas considerações especiais:

1. http Os esquemas de URI são aceitáveis porque o redirecionamento nunca sai do dispositivo. Como tal, ambos os URIs são aceitáveis:
   • http://localhost/myApp
   • https://localhost/myApp
2. Devido a intervalos de portas efêmeras frequentemente exigidos por aplicativos nativos, o componente de porta (por exemplo, :5001 ou :443) é ignorado para fins de correspondência de um URI de redirecionamento. Como resultado, todos esses URIs são considerados equivalentes:
   • http://localhost/MyApp
   • http://localhost:1234/MyApp
   • http://localhost:5000/MyApp
   • http://localhost:8080/MyApp

Do ponto de vista do desenvolvimento, isto significa algumas coisas:

• Não registre vários URIs de redirecionamento em que apenas a porta é diferente. O servidor de login escolhe um arbitrariamente e usa o comportamento associado a esse URI de redirecionamento (por exemplo, se é um webredirecionamento -, native-, ou spa-type).

  Isso é especialmente importante quando você deseja usar fluxos de autenticação diferentes no mesmo registro de aplicativo, por exemplo, a concessão de código de autorização e o fluxo implícito. Para associar o comportamento de resposta correto a cada URI de redirecionamento, o servidor de logon deve ser capaz de distinguir entre os URIs de redirecionamento e não pode fazer isso quando apenas a porta é diferente.

• Para registrar vários URIs de redirecionamento no localhost para testar fluxos diferentes durante o desenvolvimento, diferencie-os usando o componente path do URI. Por exemplo, http://localhost/MyWebApp não corresponde a http://localhost/MyNativeApp.

• O endereço de loopback IPv6 ([::1]) não é suportado no momento.

Prefira 127.0.0.1 a localhost

Para evitar que seu aplicativo seja quebrado devido a firewalls mal configurados ou interfaces de rede renomeadas, use o endereço 127.0.0.1 de loopback literal IP no URI de redirecionamento em vez de localhost. Por exemplo, https://127.0.0.1.

No entanto, não é possível usar a caixa de texto Redirecionar URIs no portal do Azure para adicionar um URI de redirecionamento baseado em loopback que use o http esquema:

Para adicionar um URI de redirecionamento que usa o http esquema com o endereço de 127.0.0.1 loopback, você deve modificar atualmente o atributo replyUrlsWithType no manifesto do aplicativo.

Restrições sobre curingas em URIs de redirecionamento

URIs curinga como https://*.contoso.com podem parecer convenientes, mas devem ser evitados devido a implicações de segurança. De acordo com a especificação OAuth 2.0 (seção 3.1.2 da RFC 6749), um URI de ponto de extremidade de redirecionamento deve ser um URI absoluto. Como tal, quando um URI curinga configurado corresponde a um URI de redirecionamento, as cadeias de caracteres de consulta e os fragmentos no URI de redirecionamento são removidos.

Atualmente, não há suporte para URIs curinga em registros de aplicativos configurados para entrar em contas pessoais da Microsoft e contas corporativas ou de estudante. No entanto, os URIs curinga são permitidos para aplicativos configurados para entrar somente em contas corporativas ou de estudante no locatário do Microsoft Entra de uma organização.

Para adicionar URIs de redirecionamento com curingas a registros de aplicativos que entram em contas corporativas ou de estudante, use o editor de manifesto do aplicativo em Registros de aplicativos no portal do Azure. Embora seja possível definir um URI de redirecionamento com um curinga usando o editor de manifesto, recomendamos que você siga a seção 3.1.2 do RFC 6749. e use apenas URIs absolutos.

Se o seu cenário exigir mais URIs de redirecionamento do que o limite máximo permitido, considere a seguinte abordagem de parâmetro de estado em vez de adicionar um URI de redirecionamento curinga.

Usar um parâmetro de estado

Se você tiver vários subdomínios e seu cenário exigir que, após a autenticação bem-sucedida, redirecione os usuários para a mesma página a partir da qual eles começaram, usar um parâmetro de estado pode ser útil.

Nesta abordagem:

1. Crie um URI de redirecionamento "compartilhado" por aplicativo para processar os tokens de segurança recebidos do ponto de extremidade de autorização.
2. Seu aplicativo pode enviar parâmetros específicos do aplicativo (como URL de subdomínio onde o usuário se originou ou qualquer coisa como informações de marca) no parâmetro state. Ao usar um parâmetro de estado, proteja-se contra a proteção CSRF, conforme especificado na seção 10.12 da RFC 6749.
3. Os parâmetros específicos do aplicativo incluem todas as informações necessárias para que o aplicativo renderize a experiência correta para o usuário, ou seja, construa o estado apropriado do aplicativo. O ponto de extremidade de autorização do Microsoft Entra retira HTML do parâmetro state, portanto, certifique-se de que não está passando conteúdo HTML nesse parâmetro.
4. Quando o Microsoft Entra ID envia uma resposta para o URI de redirecionamento "compartilhado", ele envia o parâmetro state de volta para o aplicativo.
5. O aplicativo pode usar o valor no parâmetro state para determinar para qual URL enviar o usuário posteriormente. Certifique-se de validar a proteção CSRF.

Próximos passos

Saiba mais sobre o registro do aplicativo Manifesto do aplicativo.