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
| Tipo de candidatura | Linguagens/Frameworks típicos | Plataforma para adicionar URI de redirecionamento no Registro de aplicativo |
|---|---|---|
| Um aplicativo Web tradicional onde 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 onde a maior parte da lógica da interface do usuário é executada em um navegador da Web que se comunica com o servidor da Web principalmente usando APIs da Web | JavaScript, Angular, React, Blazor WebAssembly Vue.js | Aplicação de página única (SPA) |
Configuração de URI de redirecionamento de aplicativos móveis e de desktop
| Tipo de candidatura | Linguagens/Frameworks típicos | Plataforma para adicionar URI de redirecionamento no Registro de aplicativo |
|---|---|---|
| Um aplicativo iOS ou macOS excluindo os cenários listados abaixo desta tabela | Swift, Objective-C, Xamarin | IOS/macOS |
| Uma aplicação Android | Java, Kotlin, Xamarin | Android |
| Um aplicativo que é executado nativamente em um dispositivo móvel ou computador desktop | Node.js electron, ambiente de trabalho Windows, UWP, React Native, Xamarin, Android, iOS/macOS | Aplicações móveis e de ambiente de trabalho |
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
| Tipo de aplicação | Exemplos/notas | Fluxo OAuth associado |
|---|---|---|
| Aplicações em execução em dispositivos sem teclado | Aplicações executadas em smart TV, dispositivo IoT ou impressora | Fluxo de código do dispositivo saiba mais |
| Aplicativos que lidam com senhas que os usuários entram diretamente, em vez de redirecionar os usuários para o site de login hospedado do Entra e permitir que o Entra manipule 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 não forem tão seguros. | Fluxo de credenciais de senha do proprietário do recurso saiba mais |
| Aplicativos móveis ou de área de trabalho executados no Windows ou em uma máquina conectada a um domínio do Windows (AD ou Azure AD ingressado) usando o Fluxo de Autenticação Integrado do Windows em vez do gerenciador de contas da Web | Uma aplicação de ambiente de trabalho ou móvel que deve iniciar sessão automaticamente depois de o utilizador ter iniciado sessão no sistema Windows PC com uma credencial Entra | Windows Integrated Auth Flow saiba mais |
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-oidcno 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-oidcser excluídos se redirecionados para o URL incompatível com maiúsculas e minúsculas.../ABC/response-oidc.
- Se seu aplicativo incluir como parte de seu caminho
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 équeryoufragment.Exemplos:
https://contoso.comé devolvido comohttps://contoso.com/http://localhost:7071é devolvido comohttp://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 comohttps://contoso.com/abchttps://contoso.com/abc/response-oidcé devolvido comohttps://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.
| Contas a iniciar sessão | Número máximo de URIs de redirecionamento | Description |
|---|---|---|
| Contas escolares ou profissionais da Microsoft no locatário do Microsoft Entra de qualquer organização | 256 | signInAudience no manifesto do aplicativo é definido como AzureADMyOrg ou AzureADMultipleOrgs |
| Contas pessoais da Microsoft e contas corporativas e de estudante | 100 | signInAudience no manifesto do aplicativo está definido como AzureADandPersonalMicrosoftAccount |
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.
| 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 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:
httpOs 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/myApphttps://localhost/myApp
- Devido a intervalos de portas efêmeras frequentemente exigidos por aplicativos nativos, o componente de porta (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, 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-, ouspa-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/MyWebAppnão corresponde ahttp://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:
- Crie um URI de redirecionamento "compartilhado" por aplicativo para processar os tokens de segurança recebidos do ponto de extremidade de autorização.
- 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.
- 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.
- 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.
- 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.
Aviso
Essa abordagem permite que um cliente comprometido modifique os parâmetros adicionais enviados no parâmetro state, redirecionando assim o usuário para uma URL diferente, que é a ameaça de redirecionador aberto descrita na RFC 6819. Portanto, o cliente deve proteger esses parâmetros criptografando o estado ou verificando-o por algum outro meio, como validar o nome de domínio no URI de redirecionamento em relação ao token.
Próximos passos
Saiba mais sobre o registro do aplicativo Manifesto do aplicativo.