Definição e restrições de URI de redirecionamento (URL de resposta)

Para autenticar um utilizador, a sua aplicação deve enviar um pedido de login ao terminal 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.

Em um aplicativo web de produção, por exemplo, o URI de redirecionamento geralmente é um ponto de extremidade público onde o seu aplicativo está sendo executado, como https://contoso.com/auth-response. Durante o desenvolvimento, é comum também adicionar o endpoint onde se executa a aplicação localmente, como https://127.0.0.1/auth-response ou http://localhost/auth-response. Certifique-se de que quaisquer ambientes de desenvolvimento/URIs de redirecionamento desnecessários não sejam expostos no aplicativo de produção. Isso pode ser feito com registros de aplicativos separados para desenvolvimento e produção.

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 autenticação única

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 a aplicação que está a criar contiver um ou vários URIs de redirecionamento no registo da aplicação, deverá 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 do URI de redirecionamento da aplicação 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)
• Apps iOS usando tecnologia multiplataforma 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 URI de redirecionamento devem começar com o esquema https, com exceções para alguns URI de redirecionamento de localhost.

• Os URI de redirecionamento são sensíveis a maiúsculas e minúsculas e devem corresponder ao caminho da URL do aplicativo que está 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 a .../abc/response-oidc podem ser excluídos se forem redirecionados para o URL com diferença de 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 final ('/') 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 no final 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 - ! $ ' ( ) , ;

• Os URIs de redirecionamento não suportam nomes de domínio internacionalizados

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 apenas permitem o início de sessão para utilizadores com contas corporativas ou de estudante.

Os parâmetros de consulta não são permitidos em URIs de redirecionamento para qualquer registo de aplicação configurado para iniciar sessão com utilizadores de contas pessoais da Microsoft, como Outlook.com (Hotmail), Messenger, OneDrive, MSN, Xbox Live ou Microsoft 365.

Público-alvo para início de sessão e 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 — Multiarrendatário)
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 do localhost

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 utiliza o comportamento associado a essa URL de redirecionamento (por exemplo, se é um redirecionamento web-, native-, ou do tipo spa).

  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 em vez de 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 esquema http com o endereço de loopback 127.0.0.1, deve atualmente modificar 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 registos de aplicações configurados para entrar em contas pessoais da Microsoft e contas corporativas ou de estudante. No entanto, os URIs curinga são permitidos para aplicações que estão configuradas para aceder apenas contas de trabalho ou de escola num tenant do Microsoft Entra de uma organização.

Para adicionar URIs de redirecionamento com coringas a registos de aplicações que fazem login em contas de trabalho ou escolares, use o editor de manifesto da aplicação em Registos de aplicações 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 abordagem de utilizar um 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 "partilhado" por aplicação para processar os tokens de segurança recebidos do endpoint 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 remove o HTML do parâmetro state, portanto, certifique-se de que não está a enviar 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 registo da aplicação no seu manifesto de aplicação.