O Que É OAuth? «Iniciar Sessão com Google» e Acesso Delegado Explicados

O OAuth é um padrão aberto que permite a um utilizador dar a uma app acesso limitado à sua conta noutro serviço, sem entregar a palavra-passe. Quando clica em «Ligar Google Calendar» e vê um ecrã a perguntar «Permitir que esta app veja os seus eventos?», isso é OAuth. A app recebe um token apenas para o que aprovou, e pode revogá-lo a qualquer momento. A mesma mecânica, com uma camada extra chamada OpenID Connect, alimenta o «Iniciar sessão com Google» e botões semelhantes.

Porque é que o OAuth importa quando cria com IA

O OAuth aparece em duas situações comuns ao criar uma app:

1. Início de sessão social. Quer que os seus utilizadores façam «Iniciar sessão com Google» (ou Apple, Microsoft, GitHub) em vez de criar mais uma palavra-passe. Veja como adicionar início de sessão à sua app.
2. Ligar às contas dos utilizadores noutros serviços. A sua app precisa de ler o calendário de um utilizador, publicar na conta social dele, buscar ficheiros ao seu drive na nuvem ou sincronizar dados de contabilidade.

Nos dois casos, o seu construtor de IA pode escrever o código, mas alguns passos só podem ser feitos por si: criar uma app de programador no fornecedor, obter um client ID e um client secret, registar URLs de retorno e, para algumas permissões, passar a revisão do fornecedor. Perceber como funciona o OAuth torna esses passos — e os erros que produzem — muito menos misteriosos. Para a visão geral do início de sessão, veja o que é a autenticação.

Uma analogia do dia a dia

Pense numa chave de cartão de hotel. No check-in, a receção confirma quem é e entrega-lhe um cartão que abre o seu quarto e o ginásio — não os outros quartos, nem as zonas de funcionários — e deixa de funcionar no check-out. O cartão não contém o seu passaporte. Se o perder, a receção cancela-o e emite outro.

• A receção é o servidor de autorização (a página de início de sessão da Google).
• A verificação de identidade é você a iniciar sessão na Google.
• O cartão é o token de acesso.
• «Só quarto e ginásio» são os âmbitos que aprovou.
• O check-out é o token expirar, ou você revogar o acesso.

A app que está a usar nunca vê a sua palavra-passe da Google, apenas o cartão.

Como funciona o OAuth, passo a passo

O fluxo mais comum para apps web é o fluxo de código de autorização. Eis o que acontece quando um utilizador liga o Google Calendar a uma app de agendamento:

1. Clique. O utilizador clica em «Ligar Google Calendar».
2. Redirecionamento para o fornecedor. A app envia o navegador para a Google com o seu client ID, os âmbitos que pede (ler eventos do calendário) e o URI de redirecionamento para onde a Google deve devolver o utilizador.
3. Iniciar sessão e consentir. O utilizador inicia sessão na Google (se ainda não o tiver feito) e vê um ecrã de consentimento com as permissões pedidas. Clica em Permitir.
4. De volta com um código. A Google redireciona o navegador para o URI de redirecionamento da app, com um código de autorização de curta duração e de uso único.
5. Troca no servidor. O servidor da app envia esse código, juntamente com o client secret, diretamente à Google e recebe um token de acesso (e muitas vezes um token de atualização).
6. Usar a API. O servidor chama a API do Google Calendar com o token de acesso e obtém os eventos do utilizador.

O callback do passo 4 tem um aspeto assim:

https://yourapp.com/auth/google/callback?code=4/0Adeu5B...&state=x7Kq9

E a resposta com o token, no passo 5, é JSON como este:

{
  "access_token": "ya29.a0Af...",
  "expires_in": 3599,
  "refresh_token": "1//0gL...",
  "scope": "https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

O ponto de design importante: a troca do token acontece de servidor para servidor, pelo que o client secret e os tokens nunca precisam de passar pelo navegador.

OAuth vs OpenID Connect vs o seu próprio início de sessão

Muitas apps combinam os três: início de sessão com email e palavra-passe, mais «Iniciar sessão com Google» via OIDC, mais ligações OAuth separadas a outros serviços.

Termos-chave

Ideias erradas comuns

• «OAuth é um sistema de início de sessão.» O OAuth simples concede acesso; é o OpenID Connect que trata da identidade. Usar um token de acesso sozinho como prova de quem é alguém já causou falhas de segurança reais.
• «A app fica com a minha palavra-passe.» Nunca fica. É esse o objetivo.
• «Pedir mais âmbitos não faz mal.» Os utilizadores desconfiam de pedidos amplos, e fornecedores como a Google podem exigir uma revisão da app para âmbitos sensíveis ou restritos. Peça apenas o que precisa.
• «O client secret pode ir para o frontend.» Tudo o que está no código do navegador é público. Mantenha-o em segredos do lado do servidor.
• «Funciona nos testes, por isso vai funcionar em produção.» Os fornecedores costumam limitar apps não verificadas — por exemplo, a utilizadores de teste listados — e o URI de redirecionamento do seu domínio real tem de ser registado à parte.
• «Os tokens duram para sempre.» Os tokens de acesso expiram rapidamente, e os utilizadores podem revogar o acesso. A sua app tem de lidar com ambos os casos com elegância.

O que pedir ao seu construtor de IA

• «Acrescenta «Iniciar sessão com Google» com OpenID Connect usando uma biblioteca de autenticação bem mantida — não escrevas o fluxo OAuth à mão.»
• «Usa o fluxo de código de autorização com PKCE e verifica o parâmetro state.»
• «Lê o client ID e o client secret a partir de variáveis de ambiente no servidor.»
• «Pede apenas os âmbitos de que precisamos: acesso só de leitura ao calendário.»
• «Diz-me todos os URLs de redirecionamento que tenho de registar na consola do fornecedor, para a pré-visualização, para o URL publicado e para o meu domínio personalizado.»
• «Guarda os tokens de atualização cifrados na base de dados e trata os tokens expirados ou revogados pedindo ao utilizador que volte a ligar.»
• «Deixa os utilizadores desligar a integração na página de definições.»

OAuth e Mythex

O Mythex não tem um sistema de início de sessão integrado para os utilizadores finais das apps que cria; a documentação descreve uma abordagem de traga o seu próprio: escolhe uma biblioteca de autenticação ou um fornecedor alojado, guarda as respetivas chaves como segredos do projeto, e o agente escreve o código. A receita para adicionar autenticação tem um prompt inicial para isto. Também vai encontrar o OAuth no próprio Mythex: pode iniciar sessão com a Google, ligar o GitHub para sincronizar repositórios usa OAuth do GitHub, e os assistentes de IA que se ligam ao Mythex por MCP passam por uma página de consentimento OAuth. Para mais, veja o que é a autenticação e o que é a autenticação de dois fatores.

Perguntas