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
Tipo de candidatura | Linguagens e 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 mais comuns | 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)
- 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
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 |
Aplicações que lidam com palavras-passe que os utilizadores inserem diretamente, em vez de redirecionar os utilizadores para o site de login alojado da Entra e deixar que a Entra trate da palavra-passe do utilizador de forma 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 |
Aplicações móveis ou de área de trabalho executadas no Windows ou numa máquina conectada a um domínio do Windows (AD ou Azure AD associado) usando o Fluxo de Autenticação Integrado do Windows em vez do gestor de contas 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 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
.
- 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 final ('
/
') na resposta. Isto aplica-se apenas quando o modo de resposta équery
oufragment
.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 no final na resposta.
Exemplos:
-
https://contoso.com/abc
é devolvido comohttps://contoso.com/abc
-
https://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 | Descrição |
---|---|---|
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 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.
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 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:
-
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
- 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 tipospa
).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 ahttp://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:
- Crie um URI de redirecionamento "partilhado" por aplicação para processar os tokens de segurança recebidos do endpoint 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 remove o HTML do parâmetro state, portanto, certifique-se de que não está a enviar 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 registo da aplicação no seu manifesto de aplicação.