Resumo e restrições de URI de redirecionamento (URL de resposta)
Para fazer o login de um usuário, seu aplicativo precisa enviar uma solicitação de login para o ponto de extremidade de autorização do Microsoft Entra, com um URI de redirecionamento especificado como um 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 códigos de autenticação e tokens de acesso 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.
O que é um URI de redirecionamento?
Um URI de redirecionamento, ou uma URL de resposta, é o local para onde o servidor de autenticação do Microsoft Entra envia o usuário quando este foi autorizado com sucesso e recebeu um token de acesso. Para fazer o login de um usuário, seu aplicativo precisa enviar uma solicitação de login com um URI de redirecionamento especificado como um parâmetro, de forma que, após o login bem-sucedido do usuário, o servidor de autenticação irá redirecioná-lo e emitir um token de acesso para o 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 irá redirecionar usuários nem enviar tokens para um URI que não foi adicionado ao registro do aplicativo. Os servidores de login do Microsoft Entra apenas redirecionam os usuários e enviam tokens para os URIs de redirecionamento 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 no seu aplicativo, você receberá uma mensagem de erro como, por exemplo, 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.
Devo adicionar um URI de redirecionamento a um registro de aplicativo?
Se você deve ou não adicionar um URI de redirecionamento ao registro do aplicativo depende do protocolo de autorização que seu aplicativo usa. Você precisa adicionar URIs de redirecionamento apropriados ao seu registro do aplicativo se o aplicativo estiver usando os seguintes protocolos de autorização:
- Fluxo de código de autorização OAuth 2.0
- Fluxo de credenciais de cliente do OAuth 2.0
- Fluxo de concessão implícita do OAuth 2.0
- OpenID Connect
- Protocolo SAML de logon único
Você não precisa adicionar URIs de redirecionamento ao registro do aplicativo se o aplicativo estiver usando os protocolos ou recursos de autorização a seguir.
- Autenticação Nativa
- Fluxo de código de dispositivo do OAuth 2.0
- Fluxo "em nome de" do OAuth 2.0
- Fluxo de credenciais de senha do proprietário do Recurso do OAuth 2.0
- Fluxo de Autenticação Integrada do Windows
- Provedor de Identidade (IdP) do SAML 2.0 para Logon Único
A qual plataforma devo adicionar meus URIs de redirecionamento?
Se o aplicativo que você está criando contiver um ou vários URIs de redirecionamento no registro do seu aplicativo, você precisa habilitar uma configuração de 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 estiver criando um aplicativo iOS usando um dos métodos a seguir, use a plataforma 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 requerem 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-oidccomo parte do caminho, não especifique.../ABC/response-oidcno URI de redirecionamento. Como o navegador da Web trata os caminhos diferenciando maiúsculas de minúsculas, os cookies associados a.../abc/response-oidcpodem ser excluídos se forem redirecionados para a URL de.../ABC/response-oidccom maiúsculas e minúsculas não correspondentes.
- Se o aplicativo incluir
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 équeryoufragment.Exemplos:
https://contoso.comé retornado comohttps://contoso.com/http://localhost:7071é retornado comohttp://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 comohttps://contoso.com/abchttps://contoso.com/abc/response-oidcé retornado comohttps://contoso.com/abc/response-oidc
Os URIs de redirecionamento não dão suporte a caracteres especiais:
! $ ' ( ) , ;Os URIs de redirecionamento não são compatíveis com 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 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:
- Os esquemas de URI
httpsão aceitáveis porque o redirecionamento nunca sai do dispositivo. Dessa forma, os dois URIs são aceitáveis:http://localhost/myApphttps://localhost/myApp
- Devido a intervalos de porta efêmeros geralmente exigidos por aplicativos nativos, o componente port (por exemplo,
:5001ou:443) é ignorado para fins de correspondência de um URI de redirecionamento. Como resultado, todos esses URIs são considerados equivalentes:http://localhost/MyApphttp://localhost:1234/MyApphttp://localhost:5000/MyApphttp://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,nativeouspa).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/MyWebAppnão corresponde ahttp://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:
- 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.
- 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).
- 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.
- Quando o Microsoft Entra ID envia uma resposta ao URI de redirecionamento “compartilhado”, ele envia o parâmetro de estado de volta ao aplicativo.
- 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.