Guia de registro de aplicativo e OAuth para integração segura de aplicativos

By Mirko Peters · 2026-05-04

Registre seu aplicativo com OAuth 2.0. Entenda o fluxo de código de autorização para acesso seguro, parte essencial da concessão de código de autorização do OAuth 2.0.

Automatically translated with AI from the original post. Read the English original

Vamos combinar: acertar a autenticação e o registro do aplicativo não se resume a seguir protocolos sofisticados; trata-se de garantir que seus usuários, seus dados e sua organização continuem protegidos. Este guia desmistifica o registro de aplicativos e o OAuth 2.0, para que você possa criar uma autenticação segura e baseada em padrões com o Microsoft Entra ID (antigo Azure AD) ou com o provedor de sua escolha.

Vamos detalhar as etapas e os conceitos de que você precisa, desde entender o motivo por trás do OAuth até colocar a mão na massa e fazê-lo funcionar em aplicativos web, móveis ou SaaS. Ao longo do caminho, você encontrará definições claras, orientações práticas e um roteiro pensado para manter sua integração no rumo certo e evitar os deslizes comuns que atrapalham desenvolvedores que estão começando com OAuth. Seja você alguém que está explorando o tema pela primeira vez ou ajustando uma configuração empresarial avançada, este é o lugar certo para desenvolver com confiança e entender os identificadores necessários para sua aplicação.

Guia de registro de aplicativo e OAuth — Definição

O registro de aplicativo é o processo de criar e configurar uma identidade de aplicativo em um provedor de identidade (como Azure AD, Google ou Auth0), para que o aplicativo possa solicitar autenticação e autorização com segurança. Normalmente envolve atribuir um ID de cliente, um segredo de cliente ou certificado, definir URIs de redirecionamento, configurar permissões/escopos e definir os tipos de concessão permitidos.

8 fatos surpreendentes sobre o guia de registro de aplicativo e OAuth

• Segredos de cliente podem vazar pelos logs: Muitos desenvolvedores registram sem perceber IDs de cliente e segredos durante a depuração, expondo as credenciais do registro do aplicativo, a menos que as políticas de log sejam reforçadas. Trate sempre os identificadores com cuidado.
• URIs de redirecionamento são mais rigorosos do que você imagina: Provedores OAuth costumam exigir URIs de redirecionamento com correspondência exata (incluindo barras finais e o esquema), e diferenças sutis podem quebrar fluxos que parecem corretamente configurados no registro do seu aplicativo.
• Clientes públicos não exigem segredos, mas ainda precisam de proteção: Aplicativos nativos e de página única são tratados como clientes públicos, sem segredos de cliente, mas ainda devem usar PKCE e abordagens seguras de redirecionamento para evitar a interceptação do código.
• Escopos não garantem privilégio mínimo por padrão: Ao registrar aplicativos, escopos padrão ou telas de consentimento podem solicitar permissões amplas; restrições explícitas de escopo e consentimento incremental são essenciais para aplicar o privilégio mínimo.
• A revogação de tokens não é suportada em todos os lugares: Nem todos os provedores de identidade respeitam a revogação de tokens ou oferecem logout imediato entre sessões; por isso, o registro do aplicativo precisa incluir políticas de gerenciamento de sessão e de tokens de atualização.
• Os metadados do registro de aplicativo são uma superfície de ataque: Nomes, logos e URIs de redirecionamento de aplicativos expostos publicamente podem ajudar atacantes a criar phishing convincente ou ataques de redirecionamento aberto, caso não sejam bem gerenciados.
• A automação de provisionamento pode configurar permissões incorretamente: Automações de CI/CD que criam registros de aplicativo costumam conceder permissões de API excessivas ou deixam de registrar os URIs de redirecionamento necessários, o que leva a falhas silenciosas ou exposição de segurança.
• A experiência de consentimento afeta decisões de segurança: Usuários e administradores frequentemente concedem consentimento amplo porque as janelas de consentimento são confusas; projetar solicitações de consentimento claras e mínimas no registro do aplicativo e no guia de OAuth reduz a concessão excessiva de acesso.

Entendendo os fundamentos do OAuth 2.0 e do Entra ID

O OAuth 2.0 é a base dos fluxos de autenticação modernos, permitindo que aplicativos acessem com segurança dados e recursos do usuário sem jamais ver uma senha. Esta é uma visão geral do processo OAuth. Em sua essência, o OAuth 2.0 define como um usuário (o “proprietário do recurso”), um aplicativo (o “cliente”) e um provedor de identidade (o “servidor de autorização”) trabalham juntos para que os usuários continuem no controle de suas informações.

Mas o que acontece quando você quer autenticar usuários, e não apenas autorizar o acesso a dados? É aí que entra o OpenID Connect, adicionando identidade segura e login sobre o OAuth 2.0. Usando o OpenID Connect, provedores como o Microsoft Entra ID e o Google permitem que seus aplicativos verifiquem quem são os usuários e solicitem permissões com escopo definido para recursos adicionais, em uma experiência unificada.

Se você ouvir termos como “client ID”, “authorization endpoint” ou “access token”, não se sinta sobrecarregado. Todos eles se relacionam a definir quem está falando com quem e o que cada um pode fazer. O Microsoft Entra ID, em particular, usa esses protocolos para oferecer aos desenvolvedores uma base baseada em padrões, adequada desde aplicativos corporativos de locatário único até produtos SaaS multilocatário de grande escala.

Entender esses fundamentos significa que você está construindo sobre uma base comprovada. Escolher o fluxo OAuth certo para o seu cenário — por exemplo, o code flow para aplicativos web ou o device flow para smart TVs — garante um logon seguro e simples, em que os usuários podem confiar e que a sua equipe de conformidade vai apreciar.

Guia de registro de aplicativos e OAuth: erros comuns com OAuth 2.0 e Entra ID

Este guia de registro de aplicativos e OAuth lista erros frequentes que as equipes cometem ao implementar o OAuth 2.0 com o Microsoft Entra ID (Azure AD) e como eles afetam a segurança, a funcionalidade e a experiência do usuário.

• Misturar conceitos do OAuth 2.0 com os do OpenID Connect (por exemplo, esperar ID tokens onde só são emitidos access tokens).
• Usar fluxos OAuth de forma incorreta, tratando o implicit flow como adequado para aplicativos modernos em vez do Authorization Code com PKCE.

• Registrar URIs de redirecionamento de forma incorreta (esquema errado, barra final ou uso de localhost em produção).
• Usar configurações de cliente público para aplicativos confidenciais, ou vice-versa, causando erros de token ou expondo segredos.
• Não definir as permissões de API/escopos corretos ou esquecer de conceder o consentimento de administrador quando necessário.

• Incorporar segredos de cliente em código do lado do cliente ou em repositórios públicos.
• Não rotacionar segredos/certificados regularmente ou não remover credenciais expiradas do registro do aplicativo.
• Usar segredos de longa duração sem necessidade, em vez de certificados de curta duração ou identidades gerenciadas.

• Não validar os tokens corretamente (emissor, audiência, assinatura, nonce, exp).
• Armazenar access tokens ou refresh tokens de forma insegura (local storage no navegador, sem proteção).
• Confiar no conteúdo dos tokens sem verificar os escopos/funções retornados pelo Entra ID.

• Presumir que o consentimento do usuário equivale à permissão do aplicativo, sem perceber que algumas permissões exigem consentimento de administrador.
• Solicitar permissões/escopos em excesso, o que gera risco desnecessário e aumenta as recusas durante o consentimento.

• Não tratar a rotação e as políticas de revogação de refresh tokens do Entra ID, levando a logoffs inesperados.
• Usar refresh tokens em clientes públicos sem proteções adequadas (use PKCE e tempos de vida de token apropriados).

• Não configurar corretamente as definições de multilocatário para aplicativos que devem funcionar em vários locatários.
• Usar os endpoints errados (específicos do locatário versus common) e enfrentar problemas de logon ou de consentimento.

• Não testar o comportamento do aplicativo quando o Acesso Condicional, o MFA ou as políticas de conformidade de dispositivos são aplicados.
• Presumir que os tokens sempre serão emitidos nas mesmas condições: as políticas podem bloquear ou exigir etapas adicionais de autenticação.

• Seguir fluxos OAuth legados ou padrões do Azure AD v1 em vez das recomendações da plataforma de identidade da Microsoft (v2).
• Usar exemplos da comunidade sem verificar se implementam práticas seguras (PKCE, armazenamento seguro, validação adequada).

• Não registrar em log as falhas de autenticação ou erros na emissão de tokens, o que dificulta o diagnóstico.
• Exibir mensagens de erro brutas para os usuários, em vez de traduzi-las em orientações acionáveis.

Use este guia de registro de aplicativos e OAuth para revisar sua implementação, seguir as melhores práticas da plataforma de identidade da Microsoft e reduzir riscos de segurança e operacionais ao integrar o OAuth 2.0 com o Entra ID.

Pré-requisitos de registro de aplicativo para configuração do OAuth

Antes de começar pelas telas de registro e colar o nome do seu aplicativo em um portal, confirme alguns requisitos essenciais. Primeiro, você precisa de acesso ao centro de administração do Microsoft Entra da sua organização, ou ao console apropriado do provedor de identidade que estiver usando. Não há atalho nesse ponto. Sem as permissões corretas, você vai travar antes mesmo de avançar.

Em seguida, defina que tipo de aplicação você está criando e quais identificadores serão necessários para o funcionamento dela. É uma aplicação web, uma aplicação de página única, um aplicativo móvel ou talvez um serviço automatizado? Cada tipo tem requisitos próprios de autenticação e autorização. Decidir isso no início orienta as configurações de segurança que você escolherá depois.

Também é importante mapear quem vai usar sua aplicação. Ela será usada apenas por pessoas da sua própria organização (locatário único)? Ou precisa atender usuários de outras empresas ou do público em geral (multilocatário)? Isso afeta as configurações de registro, os diretórios de usuários aplicáveis e o fluxo de consentimento que seus usuários verão.

Por fim, reúna detalhes técnicos, como as URLs permitidas para redirecionamento de entrada, quais plataformas você vai oferecer (iOS, Android, Windows?) e quais permissões (ou “escopos”) sua aplicação precisará solicitar. Alinhar esses detalhes economiza muito tempo durante a configuração e evita problemas comuns, como URIs inválidos ou tipos de conta incompatíveis depois.

Como registrar seu aplicativo no Microsoft Entra ID

Registrar seu aplicativo no Microsoft Entra ID (antigamente Azure AD) prepara o terreno para toda a autenticação e o acesso a APIs. O processo começa no centro de administração do Entra, onde você criará um novo registro de aplicativo, dando à sua aplicação uma identidade única (chamada de “ID do cliente”) dentro do diretório da sua organização.

Você informará um nome para o aplicativo e depois selecionará quem pode usá-lo: apenas a sua organização, várias organizações ou qualquer conta da Microsoft. Essa etapa é crucial, especialmente para aplicativos SaaS e B2B, porque determina o alcance da aplicação e como o consentimento do locatário será gerenciado.

Depois de escolher o público, você configura os detalhes da plataforma. Para aplicativos web, você adicionará um URI de redirecionamento; para aplicativos móveis ou de página única, as configurações específicas de cada plataforma garantem uma experiência de login fluida. O portal do Entra orienta você na inclusão de credenciais, como segredos de cliente ou certificados, que a aplicação usará para comprovar sua identidade.

Concluir o registro alinha sua aplicação aos padrões do OAuth 2.0 e garante que o fluxo de autenticação permaneça seguro e em conformidade. Seja para um cenário de locatário único ou multilocatário, entender essas configurações desde cedo cria uma base sólida para a escalabilidade e as necessidades de integração futuras.

Principais benefícios de registrar seu aplicativo no Microsoft Entra ID

• Gerenciamento centralizado de identidades: gerencie a autenticação, a autorização e as identidades de usuários do seu aplicativo a partir de um único locatário do Entra ID.
• Fluxos OAuth seguros: aproveite o suporte nativo ao OAuth 2.0 e ao OpenID Connect para implementar login seguro, emissão de tokens e acesso delegado.
• Single sign-on (SSO): ofereça SSO sem interrupções entre Microsoft 365, Azure e outros serviços integrados, para melhorar a experiência do usuário e reduzir solicitações de senha.
• Controle granular de permissões: defina e gerencie permissões de API detalhadas, experiências de consentimento e acesso com privilégio mínimo, tanto para permissões delegadas quanto para permissões de aplicativo.
• Acesso condicional e políticas de segurança: aplique MFA, conformidade de dispositivos, localização e políticas baseadas em risco para proteger o acesso aos aplicativos e os dados confidenciais.
• Segredos e credenciais de aplicativos gerenciados: armazene e renove com segurança os segredos de cliente, certificados e a configuração de multilocatário, com práticas de gerenciamento do ciclo de vida que mantenham a integridade dos usos do aplicativo.
• Integração com os serviços da plataforma Microsoft: acesse o Microsoft Graph, as APIs do Azure, o Teams e outros recursos da plataforma usando tokens padronizados e modelos de consentimento.
• Suporte a aplicativos híbridos e multiplataforma: autentique usuários em cenários web, mobile, desktop e de serviço para serviço, com protocolos de identidade consistentes e garantindo que cada aplicativo use os identificadores corretos.
• Monitoramento e auditoria: use logs, relatórios de entrada e insights de segurança para detectar anomalias, investigar incidentes e manter a conformidade.
• Escalabilidade e preparação para o ambiente corporativo: aproveite a infraestrutura global do Entra ID, as opções de multilocatário e os recursos corporativos para dar suporte a bases de usuários em crescimento e a necessidades organizacionais complexas.
• Ferramentas para desenvolvedores e documentação: use SDKs, códigos de exemplo e o guia de registro de aplicativo & OAuth para acelerar a implementação e resolver cenários comuns de problemas.

Configurando URIs de redirecionamento e configurações de plataforma para aplicativos do Entra ID

Definir os URIs de redirecionamento corretos durante o registro do aplicativo parece simples, mas essa etapa é decisiva para a segurança. Os URIs de redirecionamento informam ao Entra ID para onde enviar os usuários (junto com os tokens) após uma tentativa de login bem-sucedida. Ao configurá-los, o Entra aplica regras rígidas: nada de domínios curinga, nada de esquemas de URI perigosos e nenhuma brecha que invasores possam explorar.

Se você estiver criando um aplicativo de página única (SPA), normalmente vai usar uma URL HTTPS apontando para o domínio do seu aplicativo, o que garante uma comunicação segura para que o aplicativo obtenha os dados. Aplicativos nativos precisam de esquemas de URI vinculados ao nome do pacote ou do bundle do aplicativo, o que impede que aplicativos aleatórios sequestrem tokens no mesmo dispositivo. Aplicativos web geralmente usam seus endpoints de callback de login, e cada um deles precisa estar explicitamente listado.

Configurações incorretas nesse ponto levam aos clássicos erros de "incompatibilidade de URI de redirecionamento" e, pior, abrem espaço para que invasores interceptem tokens. Dedicar tempo para mapear cada plataforma em que seu aplicativo será executado, junto com os URIs de redirecionamento correspondentes, ajuda a garantir uma autenticação fluida e tranquilidade.

Lembre-se de atualizar o registro do seu aplicativo sempre que alterar URLs de clientes, adicionar plataformas ou expandir ambientes (como teste e produção). Manter esses URIs bloqueados e organizados é o primeiro passo para deixar o fluxo de tokens à prova de falhas.

Fluxos OAuth e fundamentos do gerenciamento de tokens

O OAuth 2.0 é construído em torno de um conjunto de fluxos de autorização que atendem a diferentes casos de uso: logins web, autenticações em aplicativos móveis, chamadas de servidor para servidor ou aplicativos executados sem a presença de um usuário. O mais popular e seguro deles é o fluxo de código de autorização, projetado para manter tokens sensíveis fora de navegadores e aplicativos móveis, colocando a segurança em primeiro lugar.

Depois que um usuário é autenticado e concede consentimento, seu aplicativo recebe um código de curta duração. Ele precisa trocar esse código no endpoint de token por tokens de acesso e de atualização. Esses tokens concedem acesso limitado no tempo aos dados: quando expiram, o token de atualização pode solicitar um novo token de acesso para manter a sessão ativa.

O gerenciamento de tokens não se resume a controlar datas de expiração; trata-se de manter os tokens seguros em todas as etapas. Isso envolve usar comunicação segura (como HTTPS), nunca expor segredos em código do lado do cliente e aplicar o princípio do privilégio mínimo ao solicitar escopos.

Esta seção prepara você para entender como o OAuth gerencia as trocas críticas entre usuários, aplicativos e plataformas, e como um gerenciamento de tokens robusto sustenta fluxos de trabalho persistentes e seguros, tanto para usuários finais quanto para sistemas automatizados.

Implementando o fluxo de código de autorização do OAuth

1. Inicie a autorização: seu aplicativo redireciona o usuário para o endpoint de autorização do Entra ID, incluindo detalhes como o ID do cliente, os escopos solicitados e um parâmetro state exclusivo e aleatório para proteção contra CSRF.
2. O usuário concede permissão: o usuário analisa a tela de consentimento, que mostra claramente quais permissões seu aplicativo precisa, e aprova o acesso.
3. Receber o código de autorização: Após o consentimento, o Entra ID redireciona de volta para o URI de redirecionamento especificado, enviando um código de autorização temporário e o valor de state que você definiu inicialmente.
4. Trocar o código por tokens: Seu backend envia com segurança o código, junto com as credenciais do seu cliente (e o code verifier do PKCE, se usado), para o endpoint de token do Entra. Se a verificação for bem-sucedida, você recebe de volta tokens de acesso (e, com frequência, tokens de atualização).
5. Usar os tokens para acessar APIs: Seu aplicativo agora anexa o token de acesso a cada requisição de API, comprovando a autorização em nome do usuário. Tokens de acesso são válidos por pouco tempo, o que minimiza a exposição, enquanto os tokens de atualização obtêm novos tokens de acesso para sessões contínuas.

Seguir essas etapas na ordem certa fecha brechas de segurança e ajuda a prevenir ataques como interceptação de código ou uso indevido de tokens, especialmente quando você trabalha com clientes públicos ou lida com dados sensíveis.

Melhores práticas para gerenciar a expiração de tokens de acesso e de atualização

1. Armazene os tokens com segurança: use soluções de armazenamento seguras fornecidas pelo sistema operacional, como o Keychain no iOS, o Keystore no Android ou gerenciadores de segredos criptografados no servidor. Nunca fixe tokens no código do aplicativo (hard-code) nem os exponha em logs.
2. Respeite a validade dos tokens: monitore o valor de expiração (claim exp) de cada token e renove-o proativamente antes que expire, para evitar falhas em requisições de API e uma má experiência para o usuário.
3. Dê suporte à rotação de tokens: sempre use o token de atualização mais recente em cada requisição; descarte rapidamente tokens reutilizados ou obsoletos. Isso limita o impacto caso um token seja comprometido.
4. Limite as permissões por token: solicite apenas os escopos de que você precisa e prefira tokens de acesso de curta duração. Isso reduz drasticamente o dano caso um token vaze ou seja roubado.

Como proteger implementações de OAuth em diferentes contextos

Fazer a integração OAuth corretamente vai além de cumprir etapas: trata-se de construir camadas de segurança que se encaixem na arquitetura do seu aplicativo e nos seus padrões de uso. Seja qual for o ambiente do seu app, no navegador, em um celular ou totalmente na nuvem, você precisa de estratégias de autenticação adequadas a cada contexto.

Tecnologias como o PKCE (Proof Key for Code Exchange) protegem o fluxo de código para clientes públicos, impedindo que invasores interceptem códigos e os troquem por tokens. Por outro lado, para aplicativos executados em ambientes seguros, segredos de cliente e certificados são as melhores ferramentas para comprovar identidade e gerenciar confiança.

Um armazenamento cuidadoso de tokens e um olhar atento aos níveis de privilégio ajudam a evitar vazamentos acidentais e limitam o alcance do dano caso algo dê errado. Ao escolher as ferramentas de segurança certas, PKCE, segredos, certificados e escopos bem definidos, você reduz drasticamente a superfície de ataque e aumenta as chances de uma operação tranquila e em conformidade.

A seguir estão estratégias testadas e comprovadas para combater ameaças comuns e adaptar sua configuração de OAuth a uma proteção robusta em todos os tipos de aplicativos e ambientes.

Como o PKCE protege a autorização OAuth em clientes públicos

O PKCE (Proof Key for Code Exchange) é essencial ao usar OAuth em aplicativos móveis e baseados em navegador, ou seja, clientes públicos, nos quais não é possível armazenar um segredo. Ao iniciar o fluxo de código de autorização, seu aplicativo gera um "code verifier" aleatório e um "code challenge" com hash. Esses valores acompanham o usuário e a requisição final de token. Mesmo que um invasor capture um código de autorização, ele não consegue trocá-lo por um token sem esse verifier secreto, o que torna os ataques de interceptação de código quase impossíveis no Microsoft Entra ID e em plataformas semelhantes.

Gerenciamento de segredos de cliente, certificados e credenciais federadas

• Segredos de cliente: usados por aplicativos confidenciais, como serviços de backend confiáveis, para comprovar sua identidade no endpoint de token. Armazene os segredos em cofres seguros, faça a rotação deles regularmente e nunca os inclua no código do aplicativo executado no cliente.
• Certificados: para maior garantia, use certificados X.509 em vez de segredos simples, a fim de reforçar a segurança dos identificadores da sua aplicação. Certificados permitem uma validação mais segura por meio de pares de chaves pública/privada e são ideais para setores regulados ou aplicativos com requisitos rigorosos de conformidade.
• Credenciais federadas: para configurações do tipo "traga sua própria identidade", use credenciais federadas, como a identidade federada do Microsoft Entra ou provedores externos. Isso permite a autenticação sem lidar diretamente com segredos, reduzindo a sobrecarga de gerenciamento.
• Tratamento em pipelines: em fluxos de CI/CD, injete e faça a rotação de segredos e certificados conforme necessário, sem nunca fixá-los no controle de código-fonte. Alertas automáticos de expiração adicionam mais uma camada de resiliência.

Como proteger tokens e reduzir a exposição de privilégios

• Armazene tokens apenas em locais seguros (cofres do sistema operacional, ambientes de servidor criptografados), nunca em armazenamentos acessíveis ao usuário.
• Transmita sempre os tokens por HTTPS ou canais seguros: HTTP simples expõe os tokens a interceptação.
• Solicite o mínimo de permissões ("escopos") para cada token. Nunca peça mais do que o seu aplicativo precisa.
• Audite regularmente o uso de tokens e as atribuições de privilégios para evitar o acúmulo de permissões que passa despercebido.

Melhores práticas de OAuth em aplicativos móveis e nativos

Aplicativos móveis e nativos enfrentam desafios próprios: dispositivos são perdidos, aplicativos compartilham espaço de armazenamento e os usuários esperam um login rápido e quase invisível. Por isso, seguir as melhores práticas de OAuth no iOS, no Android e em desktop, usando SDKs nativos e mecanismos de armazenamento comprovados, faz toda a diferença.

O SDK certo (como o MSAL para o Microsoft Entra ID) cuida de boa parte do trabalho pesado: gerencia os tokens, trata a lógica de renovação e se integra ao armazenamento seguro do sistema operacional. Para tokens sensíveis, esses SDKs escolhem por padrão o repositório mais seguro, lidando com as particularidades de cada dispositivo ou sistema operacional.

Não negligencie a experiência do usuário: links universais, links profundos e fluxos no navegador do sistema ajudam o usuário a concluir o login sem confusão e sem risco de phishing. Quando configurados corretamente, seu aplicativo encaminha o usuário para uma visualização web do sistema, segura e confiável, e depois o traz de volta em segurança ao aplicativo assim que o login é concluído, sem pop-ups e sem vazamento de tokens.

Essas práticas foram pensadas não apenas para manter os tokens protegidos, mas também para construir a confiança do usuário final, aumentando a adoção e reduzindo os chamados de suporte no futuro.

Links universais e autenticação nativa de primeira parte

Links universais (no iOS) e esquemas de aplicativo (no Android) tornam a autenticação do usuário muito mais segura. Ao usar links verificados pelo sistema operacional e vinculados à identidade do seu aplicativo, você impede que aplicativos mal-intencionados interceptem os redirecionamentos de login e capturem tokens que não lhes pertencem. A autenticação nativa utiliza navegadores confiáveis do sistema, de modo que quem faz o login é o usuário real, eliminando phishing, espionagem de tokens e logins acidentais em aplicativos não relacionados. Combinadas, essas ferramentas oferecem uma experiência fluida e segura, praticamente imune às ameaças comuns de OAuth em dispositivos móveis.

Solução de problemas de erros de OAuth e cenários avançados

Integrações de OAuth raramente funcionam perfeitamente na primeira tentativa: erros e casos extremos fazem parte do processo. Com frequência, os problemas surgem por URIs de redirecionamento divergentes, códigos expirados ou segredos de cliente incorretos, que podem paralisar os fluxos de autenticação e afetar o uso dos aplicativos. Esta seção vai ajudar você a interpretar as respostas de erro, rastrear trocas que falharam e resolver os problemas antes que cheguem à central de suporte.

Além do básico, alguns cenários, como a comunicação entre aplicativos servidor a servidor, o login de dispositivos IoT ou a necessidade de garantias de protocolo mais fortes, exigem extensões especializadas do OAuth ou fluxos não interativos. Contas de serviço, mutual TLS e fluxos de código de dispositivo foram criados especificamente para atender a esses requisitos.

Com orientações sobre falhas comuns e casos de uso avançados, você terá mais preparo para solucionar problemas, projetar e manter soluções OAuth robustas, mesmo à medida que o ecossistema de aplicativos se torna mais complexo.

Seja você um erro teimoso no endpoint de token ou se preparando para a realidade do dia a dia (onde dispositivos com entrada limitada e serviços sem interface estão em toda parte), estes conteúdos vão manter suas integrações estáveis e seguras.

Interpretando respostas de erro de OAuth e falhas na troca de código

• URI de redirecionamento inválido: ocorre quando o redirecionamento não corresponde à lista registrada. Verifique cuidadosamente os valores e as diferenças entre maiúsculas e minúsculas.
• Código de autorização expirado: o usuário demora demais ou os códigos são reutilizados. Use-os sempre uma única vez e logo após recebê-los.
• Credenciais de cliente incompatíveis: o segredo ou certificado informado estava errado. Verifique as credenciais e renove-as quando necessário.
• Escopo ou recurso inválido: a API ou os escopos solicitados não são permitidos ou foram digitados incorretamente. Verifique a configuração e as permissões do aplicativo.

Contas de serviço, dispositivos de entrada limitada e extensões do OAuth

• Contas de serviço (fluxo de credenciais de cliente): permitem que aplicativos se autentiquem sem um usuário, ideal para automação e tarefas servidor a servidor.
• Fluxo de código de dispositivo: destinado a smart TVs e dispositivos IoT, solicita que o usuário conclua o login em outro dispositivo. Serve para casos em que não há navegador disponível.
• Extensão mutual TLS: usa certificados tanto no servidor quanto no cliente, aumentando a segurança de integrações sensíveis e garantindo que o aplicativo utilize métodos de autenticação fortes.
• Registro dinâmico de clientes: automatiza a integração de aplicativos em grandes sistemas SaaS ou multilocatário, simplificando o gerenciamento de credenciais em escala.

Guia de registro de aplicativos e OAuth no Entra ID

Prós

• Gerenciamento centralizado de identidades: integra-se ao Microsoft Entra ID para manter uma identidade consistente de usuários e aplicativos em todos os serviços.
• Controles de segurança robustos: oferece suporte a OAuth 2.0, OpenID Connect, acesso condicional e permissões granulares (escopos e funções).
• Protocolos padrão do setor: utiliza os padrões OAuth/OIDC, amplamente suportados, o que simplifica a interoperabilidade com ferramentas e bibliotecas de terceiros.
• Configuração detalhada de aplicativos: permite configurar URIs de redirecionamento, certificados e segredos, permissões de API e opções de personalização visual para os aplicativos.
• Modelo de consentimento granular: oferece suporte a permissões delegadas e de aplicativo, com fluxos de consentimento de administrador para limitar aplicativos com privilégios excessivos.
• Recursos empresariais: oferece suporte a aplicativos multilocatário, colaboração B2B e integração com os serviços do Microsoft 365 e do Azure.
• Monitoramento e auditoria: logs, entradas e trilhas de auditoria integrados para registros de aplicativos e fluxos OAuth, ajudando na conformidade e na solução de problemas.
• Ferramentas para desenvolvedores e SDKs: amplo conjunto de SDKs da plataforma de identidade da Microsoft, documentação e exemplos de início rápido que agilizam a implementação.

Contras

• Complexidade para iniciantes: a configuração e os modelos de permissão (URIs de redirecionamento, URLs de resposta, fluxos implícito versus código de autorização, escopos) podem confundir novos desenvolvedores.
• Curva de aprendizado íngreme nos recursos de segurança: acesso condicional, identidades gerenciadas e configurações avançadas de token exigem conhecimento mais profundo de segurança para serem configurados com segurança.
• Risco de proliferação de permissões: consentimentos inadequados ou permissões amplas para aplicativos podem gerar aplicativos com privilégios excessivos se não forem revisados regularmente.
• Nuances no gerenciamento de tokens: o tratamento de tokens de atualização, tempos de vida dos tokens e revogação de tokens tem comportamentos específicos de cada plataforma, que podem causar problemas de integração.
• Considerações sobre limites de locatário: o comportamento de aplicativos multilocatário e as solicitações de consentimento de administrador aumentam a complexidade operacional em cenários entre locatários.
• Mudanças de interface e terminologia: a Microsoft atualiza periodicamente a interface e a nomenclatura do Entra (Azure AD → Entra ID), o que pode causar divergências ou confusão na documentação.
• Dependência do ecossistema Microsoft: o forte acoplamento aos recursos do Entra ID pode limitar a portabilidade para provedores de identidade que não são da Microsoft sem retrabalho.
• Potencial de configuração incorreta: configurações equivocadas de registro de aplicativos (por exemplo, URIs de redirecionamento, URLs de resposta, configurações do fluxo implícito) podem criar brechas de segurança ou interromper os fluxos de autenticação.

Próximos passos e principais recursos da comunidade para o sucesso com OAuth

Pronto, você configurou o OAuth e ele está funcionando, mas não tire o pé do acelerador ainda: garanta que a aplicação que obtém os tokens esteja configurada corretamente. Ter o básico funcionando é apenas o primeiro passo. Se você realmente quer que sua aplicação se destaque e mantenha seus usuários seguros, é hora de explorar os recursos extras. Comece a analisar bibliotecas de cliente avançadas, experimente o Microsoft Graph e conheça os novos recursos de identidade que podem tornar sua integração mais robusta e mais fluida para todos os envolvidos.

Você também não precisa descobrir tudo sozinho. A documentação do Microsoft Entra ID é extensa, com guias atualizados, exemplos de código e todas as especificações técnicas que você provavelmente vai querer ter à mão. Crie o hábito de verificar atualizações, especialmente porque os padrões de OAuth e de identidade em nuvem continuam evoluindo.

Satisfeito com o registro do seu aplicativo? Ótimo. Agora veja como outras pessoas do mercado estão sendo criativas. Explore fóruns de desenvolvedores, fóruns oficiais de discussão e até os repositórios no GitHub das bibliotecas de autenticação. Se você travar em algum ponto, é bem provável que alguém já tenha resolvido exatamente o mesmo problema ou, pelo menos, reclamado dele com veemência suficiente para que alguém respondesse.

Se você gosta de testar e aprender na prática, conheça as avaliações gratuitas, os locatários de teste e os recursos em visualização pública disponíveis. Eles permitem quebrar coisas (com segurança) e descobrir o que funciona antes de implantar mudanças para seus usuários reais. E não se esqueça: OAuth e segurança são esforços coletivos, então compartilhe suas conquistas e dúvidas. Isso mantém todo o ecossistema transparente e em crescimento, ajudando todos a entender o fluxo do OAuth.

Checklist do Guia de registro de aplicativos e OAuth - Entra ID

• Planeje o tipo de aplicativo e o modelo de acesso: decida entre locatário único, multilocatário ou contas pessoais da Microsoft, e determine se é um SPA, aplicativo web, móvel, daemon ou serviço.
• Registre o aplicativo no Entra ID: crie um novo registro de aplicativo com um nome claro e os tipos de conta compatíveis.
• Configure os URIs de redirecionamento: adicione os URIs de redirecionamento/callback corretos para cada plataforma (https, esquema personalizado, localhost para desenvolvimento).
• Defina as configurações de plataforma do aplicativo: habilite as opções de plataforma SPA, web e dispositivos móveis e desktop, e configure os fluxos implícitos/de concessão conforme necessário.
• Crie e gerencie segredos de cliente: gere segredos de cliente para clientes confidenciais, anote a data de expiração e armazene-os com segurança (Key Vault).
• Use certificados para autenticação: carregue certificados de chave pública para clientes confidenciais em produção, em vez de segredos de longa duração.
• Configure as permissões de API: adicione os escopos e as permissões do Microsoft Graph ou de APIs personalizadas que o aplicativo exige.
• Conceda o consentimento de administrador quando necessário: solicite e registre o consentimento de administrador para permissões delegadas que exigem consentimento em todo o locatário.
• Defina e exponha escopos personalizados (se for uma API): adicione escopos em "Expor uma API" e defina os nomes dos escopos, as descrições e os nomes de exibição para o consentimento de administrador.
• Configure funções de aplicativo (se necessário): defina funções de aplicativo e delegadas para controle de acesso baseado em funções e atribua-as a usuários, grupos ou aplicativos clientes.
• Configure o CORS para SPAs que chamam APIs: adicione as origens permitidas na API ou configure as políticas de CORS do gateway.
• Escolha o fluxo do OAuth 2.0: selecione o Código de Autorização (com PKCE para clientes públicos), Credenciais de Cliente para aplicativos daemon ou Código de Dispositivo, conforme apropriado.
• Implemente o PKCE para clientes públicos: exija o Proof Key for Code Exchange para SPAs e aplicativos nativos, a fim de evitar a interceptação do código.
• Valide os tokens corretamente: verifique emissor, público-alvo (audience), assinatura, expiração e as declarações (claims) necessárias, usando as bibliotecas de identidade da Microsoft ou a lógica de validação de JWT.
• Use as Microsoft Authentication Libraries (MSAL): prefira o MSAL para aquisição, cache e renovação de tokens, além de um tratamento seguro em todas as plataformas.
• Configure o acesso condicional e o MFA (se necessário): aplique políticas ao registro do aplicativo ou aos fluxos de entrada dos usuários para impor controles de segurança.
• Monitore os logs de entrada e de auditoria: habilite o registro em log e revise os eventos de entrada, os consentimentos e as operações de administração nos logs do Entra ID.
• Aplique o princípio do menor privilégio: solicite apenas as permissões necessárias e prefira o consentimento incremental para minimizar a exposição.
• Renove segredos e certificados regularmente: implemente rotação automatizada e alertas para credenciais próximas do vencimento.
• Proteja o código e o armazenamento do lado do cliente: evite guardar segredos em aplicativos clientes, use armazenamento seguro e as boas práticas de cada plataforma.
• Teste os fluxos de entrada e de tokens em desenvolvimento/homologação: valide os fluxos de autenticação, a duração dos tokens, a lógica de renovação, o tratamento de erros e a experiência de consentimento.
• Prepare a documentação para usuários e administradores: inclua as etapas de consentimento, as permissões necessárias e orientações para solução de problemas.
• Revise e atualize periodicamente o registro dos aplicativos: audite permissões, funções, segredos e registros para identificar aplicativos obsoletos ou não utilizados.
• Aplique proteções de rede e de API: considere o API Management, WAF, limitação de taxa (rate limiting) e service endpoints para proteger as APIs de back-end.

token de acesso do Azure, uso de OAuth, autenticação OAuth

O que é o guia de registro de aplicativo e OAuth e por que ele é importante?

Um guia de registro de aplicativo e OAuth explica como registrar um aplicativo cliente em um provedor de identidade (por exemplo, usando o Azure) e implementar os fluxos de autorização do OAuth 2.0 para que sua aplicação possa solicitar acesso a recursos protegidos com segurança. Isso é fundamental, seja você desenvolvendo aplicações web, SPAs, aplicativos de desktop ou back-ends de servidor web, porque a aplicação precisa de um ID de aplicativo (application ID ou app ID), de um client ID e de um client secret (para clientes confidenciais) para obter um token de acesso e, quando apropriado, receber um token de ID.

Como registro um aplicativo do Azure e obtenho o application ID e o app ID?

Para registrar um aplicativo do Azure, acesse o portal do Azure, crie um novo registro de aplicativo, informe um nome e os URIs de redirecionamento e anote o client ID (application ID) exibido na visão geral do aplicativo. Se a sua aplicação for um cliente confidencial (servidor web ou aplicação web tradicional), crie um client secret para usar junto com o client ID. Esse aplicativo registrado é usado na autorização e para solicitar tokens de acesso aos serviços da Microsoft.

Qual fluxo de autorização do OAuth 2.0 devo usar para aplicações de página única (SPAs)?

Aplicações de página única devem usar o fluxo de código de autorização com PKCE (proof key for code exchange) em vez do fluxo implícito, garantindo que a aplicação obtenha tokens de forma segura. O fluxo de código com PKCE permite que a aplicação troque o código por um access token com segurança a partir de um cliente baseado em navegador, possibilitando que aplicações de página única usem OAuth sem expor client secrets no navegador.

Como funciona a solicitação de autorização e quais parâmetros são obrigatórios?

Uma solicitação de autorização é enviada ao endpoint de autorização do provedor de identidade e normalmente inclui client_id (ID do app), response_type (por exemplo, code), redirect_uri, scope e state. Para aplicações de página única que usam o fluxo de código com PKCE, você também inclui code_challenge e code_challenge_method. O usuário se autentica e concede consentimento (consentimento OAuth), e o servidor de autorização retorna um código para o redirect URI, que a aplicação pode trocar por um access token.

Como implemento a troca do código por um access token?

Após receber o código de autorização, a aplicação cliente envia uma requisição POST ao endpoint de token contendo o code, o client_id (e o client_secret para clientes confidenciais), o redirect_uri e grant_type=authorization_code. No caso do PKCE, você inclui o code_verifier. O endpoint de token responde com um access token, um id token (quando solicitado) e, possivelmente, um refresh token para obter um novo access token quando o atual expirar.

Como obtenho um access token e o utilizo para chamar APIs?

Obtenha um access token concluindo o fluxo de autorização OAuth 2.0 escolhido e chamando o endpoint de token. Com o access token em mãos, envie-o no cabeçalho Authorization com o esquema Bearer ao chamar serviços da Microsoft ou outras APIs (por exemplo, Google Agenda ou APIs personalizadas). Valide os tokens no servidor web ou no lado do recurso para garantir que as requisições da aplicação estejam autorizadas.

O que fazer quando o access token expira e como obter um novo refresh token?

Quando o access token expirar, use o refresh token (se fornecido) para solicitar um novo access token ao endpoint de token com grant_type=refresh_token. Alguns fluxos ou provedores emitem um novo refresh token na renovação; outros reutilizam o mesmo refresh token. Se não houver refresh token disponível (clientes públicos ou fluxos de curta duração), redirecione o usuário de volta para a aplicação para realizar uma nova solicitação de autorização.

Preciso de registros de aplicativo separados para aplicações web e para aplicativos móveis ou de desktop?

Frequentemente, sim, você precisa de registros separados quando os tipos de aplicação diferem significativamente (por exemplo, servidor web tradicional, aplicações de página única e aplicativos de desktop), pois redirect URIs, client secrets e fluxos permitidos variam. Usar registros separados permite configurar fluxos de autorização e redirect URIs específicos para cada tipo de aplicação.

Qual é a diferença entre o registro de aplicativo cliente e o aplicativo em um locatário?

O registro de aplicativo cliente é a entrada de registro específica no provedor de identidade (o aplicativo do Azure) que contém configurações como redirect URIs e secrets. Um aplicativo em um locatário indica que o registro existe em um determinado locatário do Azure AD e pode receber funções e permissões dentro desse locatário. Um único registro de aplicativo pode ser multilocatário ou de locatário único, conforme a sua necessidade.

Como solicito acesso aos serviços da Microsoft e quais permissões são necessárias?

Solicite acesso especificando os escopos que sua aplicação precisa na solicitação de autorização. Para os serviços da Microsoft, configure as permissões de API no registro do aplicativo do Azure e, em seguida, peça que os usuários concedam consentimento (consentimento OAuth) ou que um administrador conceda consentimento em todo o locatário. A aplicação solicita escopos como User.Read ou escopos de APIs personalizadas nas solicitações de aplicação e usa o access token para chamar os serviços.

Como proteger client secrets e evitar o vazamento de credenciais em aplicações de página única?

Aplicações de página única não devem armazenar client secrets, porque o código executado no navegador pode ser inspecionado. Use o fluxo de código de autorização com PKCE para que a aplicação obtenha um access token com segurança, sem client secret. Para aplicações confidenciais (servidor web), armazene o client id e o client secret do lado do servidor, onde não ficam expostos aos usuários.

Qual é o papel do redirect URI e por que ele deve corresponder ao registro do aplicativo?

O redirect URI é o endereço para onde o provedor de identidade envia a resposta de autorização (código ou token). Ele deve corresponder ao redirect URI registrado no registro do aplicativo para evitar o sequestro da resposta de autorização. Use correspondência exata ou padrões permitidos, conforme definido pelo provedor; qualquer divergência fará com que a troca de token falhe.

Como fazer com que os usuários se autentiquem e recebam um id token além de um access token?

Para receber um id token, solicite o escopo openid e inclua um response_type que dispare a emissão do id token (fluxo de código de autorização com openid). O id token contém declarações de identidade sobre o usuário autenticado. Use o id token para conectar o usuário ao seu aplicativo cliente e o access token para chamar APIs downstream.

Quais fluxos de autorização específicos se aplicam a aplicativos web tradicionais versus aplicativos de página única?

Aplicativos web tradicionais (lado do servidor) normalmente usam o fluxo de código de autorização com credenciais de cliente (client id e client secret) e trocam o código no servidor web. Aplicativos de página única usam a concessão de código de autorização com PKCE e sem client secret. Aplicativos de desktop também usam PKCE. Escolha o fluxo com base no tipo de aplicativo e no local onde os segredos podem ser armazenados com segurança.

Um mesmo registro de aplicativo pode ser usado para vários aplicativos cliente, ou devo criar um registro para cada aplicativo?

Você pode usar um único registro de aplicativo para vários aplicativos cliente se eles compartilharem a mesma configuração e os mesmos redirect URIs, mas as melhores práticas costumam recomendar registros separados para aplicativos distintos, a fim de isolar permissões, redirect URIs e o gerenciamento do ciclo de vida. Considere se o aplicativo pode precisar de escopos de permissão diferentes ou de comportamentos de consentimento do administrador diferentes.

Como validar tokens no meu servidor web ou API?

Seu servidor web ou API deve validar a assinatura, o emissor (issuer), o público-alvo (audience, ou seja, o app id ou application id) e a expiração do access token ou do id token. Use o documento de descoberta do provedor para obter as chaves de assinatura e siga as bibliotecas de validação recomendadas para sua plataforma. A validação garante que apenas solicitações de aplicativos autenticados e autorizados sejam aceitas.

Qual é o processo para solicitar um access token para um serviço de back-end usando credenciais de cliente?

Para cenários servidor a servidor, registre um aplicativo no Azure, conceda permissões de aplicativo e depois use o fluxo de credenciais de cliente: faça um POST para o endpoint de token com grant_type=client_credentials, client_id, client_secret e scope/resource. O endpoint de token retorna um access token que o back-end pode usar para chamar serviços da Microsoft ou APIs protegidas.

Como lidar com o consentimento do OAuth e o consentimento do administrador em aplicativos multilocatário?

Quando seu aplicativo está registrado como multilocatário, usuários de outros locatários podem consentir com permissões delegadas durante a solicitação de autorização. Para permissões que exigem consentimento do administrador, um administrador deve conceder o consentimento para o seu locatário. Inclua instruções e uma URL de consentimento para os administradores de locatário concederem o consentimento OAuth em escala.

Quais etapas de solução de problemas devo seguir se minha solicitação de autorização falhar?

Confirme se o aplicativo está registrado no portal da Microsoft, se o redirect URI corresponde, se o client id e o secret estão corretos, se os escopos são válidos e se o tipo de concessão e os parâmetros PKCE (se usados) estão corretos. Verifique as mensagens de erro retornadas pelo endpoint de autorização ou de token e consulte os logs do cliente e do servidor. O Stack Overflow e a documentação do provedor podem ajudar com códigos de erro específicos.

Como posso integrar APIs de terceiros, como o Google Agenda, ao meu aplicativo registrado?

Para integrar o Google Agenda ou outras APIs de terceiros, implemente os fluxos de autorização OAuth 2.0 exigidos por esses provedores. Seu aplicativo deve solicitar os escopos corretos para a API de terceiros e gerenciar ciclos de vida de token separados. Talvez seja necessário registrar aplicativos cliente separados em cada provedor e coordenar a obtenção de access tokens para cada serviço.

Quando devo usar o fluxo de código de dispositivo ou outros fluxos especiais para determinados dispositivos?

Use o fluxo de código de dispositivo para dispositivos com entrada limitada, nos quais não há navegador disponível. Esse fluxo permite que o usuário acesse uma URL de verificação em outro dispositivo para se autenticar. Ele é um dos fluxos de autorização específicos oferecidos, ao lado dos fluxos de código de autorização, credenciais de cliente e refresh token, para atender a diferentes tipos de fatores de forma dos aplicativos.