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

Um URI de redirecionamento ou uma URL de resposta é o local para o qual o servidor de autorização do Microsoft Entra envia o usuário quando ele é autorizado e recebe um código de autorização ou um token de acesso. Para conectar um usuário, seu aplicativo precisa enviar uma solicitação de logon para o ponto de extremidade de autorização do Microsoft Entra, com um URI de redirecionamento especificado como um parâmetro. O servidor de autenticação do Microsoft Entra verificará se o URI de redirecionamento recebido foi adicionado ao registro do aplicativo. O URI de redirecionamento é um recurso de segurança crítico que garante que os códigos de autorização e os tokens de acesso sejam enviados apenas para o destinatário pretendido. Este artigo descreve os recursos e as restrições dos URIs de redirecionamento na plataforma de identidade da Microsoft.

Por que um URI de redirecionamento precisa ser adicionado a um registro de aplicativo

Por motivos de segurança, o servidor de autorização do Microsoft Entra não redirecionará usuários nem enviará tokens para um URI que não é adicionado ao registro do aplicativo. Os servidores de logon do Entra só redirecionam usuários e enviam tokens para URIs de redirecionamento que foram adicionados a um registro de aplicativo. Se o URI de redirecionamento especificado na solicitação de logon não corresponder a nenhuma das URIs de redirecionamento que você adicionou no 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 os códigos de erro, confira Códigos de erro de autenticação e autorização do Microsoft Entra.

Quais plataformas exigem um URI de redirecionamento?

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

Configuração do URI de redirecionamento do aplicativo Web

Tipo de aplicativo	Linguagens/estruturas típicas	Plataforma usada para adicionar o URI de redirecionamento no registro de aplicativo
Um aplicativo Web tradicional em que a maior parte da lógica do aplicativo é executada no servidor	Node.js, Web, ASP.NET, Python, Java, ASP.NET Core, PHP, Ruby, Blazor Server	Web
Um aplicativo de página única em que a maior parte da lógica da interface do usuário é executada em um navegador da Web comunicando-se com o servidor Web principalmente usando as APIs Web	JavaScript, Angular, React, Blazor WebAssembly, Vue.js	SPA (Aplicativo de Página Única)

Configuração do URI de redirecionamento de aplicativos móveis e da área de trabalho

Tipo de aplicativo	Linguagens/estruturas típicas	Plataforma usada para adicionar o URI de redirecionamento no registro de aplicativo
Um aplicativo iOS ou macOS, exceto os cenários listados abaixo desta tabela	Swift, Objective-C, Xamarin	IOS/macOS
Um aplicativo Android	Java, Kotlin, Xamarin	Android
Um aplicativo que é executado nativamente em um dispositivo móvel ou em um computador desktop	Node.js Electron, área de trabalho do Windows, UWP, React Native, Xamarin, Android, iOS/macOS	Aplicativos móveis e para desktop

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

• Aplicativos iOS que usam SDKs herdados (ADAL)
• Aplicativos iOS que usam o SDKs de código aberto (AppAuth)
• Aplicativos iOS que usam uma tecnologia multiplataforma à qual não damos suporte (Flutter)
• Aplicativos iOS que implementam nossos protocolos OAuth diretamente
• Aplicativos macOS que usam uma tecnologia multiplataforma à qual não damos suporte (Electron)

Aplicativos que não exigem um URI de redirecionamento

Tipo de aplicativo	Exemplos/notas	Fluxo OAuth associado
Aplicativos que são executados em dispositivos sem teclado	Aplicativos que são executados em smart TVs, dispositivos IoT ou impressoras	Fluxo do código do dispositivo saiba mais
Aplicativos que processam senhas que os usuários inserem diretamente, em vez de redirecioná-los para o site de logon hospedado do Entra e permitir que o Entra processe a senha do usuário de maneira segura.	Você só deve usar esse fluxo quando outros fluxos mais seguros, como o fluxo de código de autorização, não forem viáveis, porque ele não é tão seguro.	Fluxo de credencial de senha do proprietário do recurso saiba mais
Aplicativos móveis ou de área de trabalho que são executados no Windows ou em um computador conectado a um domínio do Windows (ingressado no AD ou no Azure AD) com o Fluxo de Autenticação Integrada do Windows em vez do gerenciador de contas da Web	Um aplicativo móvel ou da área de trabalho que deve ser conectado automaticamente depois que o usuário entrar no sistema de computadores Windows com uma credencial do Entra	Fluxo de Autenticação Integrada do Windows saiba mais

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

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

• Os URIs de redirecionamento precisam começar com o esquema https, com exceções para alguns URIs de redirecionamento de localhost.

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

  Exemplos:

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

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

  Exemplos:

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

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

  Exemplos:

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

• Os URIs de redirecionamento não dão suporte a 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 gerado por motivos de segurança. Se o seu cenário exigir mais URIs de redirecionamento do que o limite máximo permitido, considere a abordagem de parâmetro de estado como 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.

Contas sendo conectadas	Número máximo de URIs de redirecionamento	Descrição
Contas corporativas ou de estudante da Microsoft em qualquer locatário do Microsoft Entra de qualquer organização	256	O campo signInAudience no manifesto do aplicativo é definido como AzureADMyOrg ou AzureADMultipleOrgs.
Contas pessoais e contas corporativas e de estudante da Microsoft	100	O campo signInAudience no manifesto do aplicativo é definido como AzureADandPersonalMicrosoftAccount.

Você poderá usar no máximo de 256 caracteres para cada URI de redirecionamento que adicionar a um registro de aplicativo.

Redirecionar URIs no aplicativo vs. objetos de entidade de serviço

• Sempre adicione URIs de redirecionamento apenas ao objeto de aplicativo.
• Nunca adicione valores de URI de redirecionamento a uma entidade de serviço, porque esses valores podem ser removidos quando o objeto de entidade de serviço for sincronizado com o objeto de aplicativo. Isso pode ocorrer devido a qualquer operação de atualização que dispare 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ó conectam 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 conectar usuários com as contas pessoais Microsoft, como o Outlook.com (Hotmail), o Messenger, o OneDrive, o MSN, o Xbox Live ou o Microsoft 365.

Público-alvo para entrada do registro de aplicativo	Dá suporte a 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 – Multilocatário)
Contas em qualquer diretório organizacional (qualquer diretório Microsoft Entra - Multilocatário) e contas pessoais da Microsoft (como Skype e Xbox)
Somente contas Microsoft pessoais

Esquemas compatíveis

HTTPS: o esquema HTTPS (https://) tem suporte para todos os URIs de redirecionamento baseados em HTTP.

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

Exemplo de URI de redirecionamento	Validade
https://contoso.com	Válido
https://contoso.com/abc/response-oidc	Válido
https://localhost	Válido
http://contoso.com/abc/response-oidc	Inválido
http://localhost	Válido
http://localhost/abc	Válido

Exceções de localhost

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

1. Os esquemas de URI http são aceitáveis porque o redirecionamento nunca sai do dispositivo. Dessa forma, os dois URIs são aceitáveis:
   • http://localhost/myApp
   • https://localhost/myApp
2. Devido a intervalos de porta efêmeros geralmente exigidos por aplicativos nativos, o componente port (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, isso significa algumas coisas:

• Não registre vários URIs de redirecionamento em que apenas a porta é diferente. O servidor de logon escolhe um aleatoriamente e usa o comportamento associado a esse URI de redirecionamento (por exemplo, se for um redirecionamento do tipo web, native ou 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 precisa conseguir 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.

• No momento, não há suporte para o endereço de loopback do IPv6 ([::1]).

Prefira 127.0.0.1 a localhost

Para impedir que o aplicativo seja interrompido por firewalls configurados incorretamente ou por adaptadores de rede renomeados, use o endereço de loopback literal do IP 127.0.0.1 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 URIs de redirecionamento no portal do Azure para adicionar um URI de redirecionamento baseado em loopback que usa o esquema http:

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

Restrições em curingas em URIs de redirecionamento

URIs de 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 do RFC 6749), um URI de ponto de extremidade de redirecionamento deve ser um URI absoluto. Dessa forma, quando um URI curinga configurado corresponde a um URI de redirecionamento, cadeias de caracteres de consulta e fragmentos no URI de redirecionamento são removidos.

No momento, não há suporte para URIs curinga em registros de aplicativo configurados para entrar em contas Microsoft pessoais e contas corporativas ou de estudante. No entanto, URIs curinga são permitidos em 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 aos registros de aplicativo que entram em contas corporativas ou de estudante, use o editor de manifesto do aplicativo em Registros de aplicativo no portal do Azure. Embora seja possível definir um URI de redirecionamento com um curinga usando o editor de manifesto, é altamente recomendável seguir a seção 3.1.2 da RFC 6749. e usam apenas URIs absolutos.

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

Usar um parâmetro de estado

Se você tiver vários subdomínios e o cenário exigir isso, após a autenticação bem-sucedida, você vai redirecionar os usuários à mesma página de onde eles começaram. Pode ser útil usar um parâmetro de estado.

Nesta abordagem:

1. Crie um URI de redirecionamento "compartilhado" por aplicativo para processar os tokens de segurança que você recebe do ponto de extremidade da autorização.
2. Seu aplicativo pode enviar parâmetros específicos do aplicativo (como a URL de subdomínio de origem do usuário ou qualquer coisa, como informações de identidade visual) no parâmetro de estado. Ao usar um parâmetro de estado, considere a proteção contra CSRF, como 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 processe 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 o HTML do parâmetro de estado. Portanto, não transmita conteúdos HTML nesse parâmetro.
4. Quando o Microsoft Entra ID envia uma resposta ao URI de redirecionamento “compartilhado”, ele envia o parâmetro de estado de volta ao aplicativo.
5. Assim, o aplicativo pode usar o valor do parâmetro de estado para determinar a URL de destino do usuário. Não se esqueça de garantir a proteção contra CSRF.

Aviso

Essa abordagem permite que um cliente comprometido modifique os parâmetros adicionais enviados no parâmetro de estado, redirecionando, assim, o usuário para uma URL diferente, que é a ameaça de redirecionamento aberta descrita na RFC 6819. Portanto, o cliente deve proteger esses parâmetros criptografando o estado ou verificando-o por outros meios, como validar o nome de domínio no URI de redirecionamento em relação ao token.

Próximas etapas

Saiba mais sobre o manifesto do aplicativo do registro de aplicativos.