Estude OpenID Connect com foco em padrão, arquitetura, segurança e implementação técnica.
Visão macro da arquitetura OIDC com foco em autenticação, autorização e proteção de APIs.
Era uma vez, no Reino de Federápolis, onde Lady OAuth reinava sozinha com suas autorizações. Mas os súditos perguntavam: "Sabemos que podemos entrar, mas quem sou eu realmente?" Foi então que Lord OIDC apareceu com seu pergaminho mágico, trazendo não apenas chaves de acesso, mas também identidade verificada...
O que é o OpenID Connect (OIDC)?
OIDC é uma camada de identidade sobre o OAuth 2.0, alinhada às práticas do OAuth 2.1. Permite que usuários se identifiquem com provedores de identidade (Google, Microsoft etc.).
Como o OIDC se diferencia do OAuth 2.0?
OAuth 2.0 → autorização (acesso a recursos) - Lady OAuth pergunta: "O que você pode fazer?"
OIDC → autenticação (verificação de identidade) - Lord OIDC declara: "Quem você é!"
Qual é o objetivo principal do OIDC?
Oferecer autenticação segura e interoperável por meio de tokens JSON (JWT).
Após anos reinando, Lady OAuth percebeu que algumas práticas antigas estavam causando vulnerabilidades no reino. "É hora de uma reforma!" declarou ela. "OAuth 2.1 será minha nova constituição - mais simples, mais segura, e sem as práticas que causaram problemas!" Assim, ela removeu caminhos perigosos, tornou PKCE obrigatório e simplificou as regras para proteger melhor seus súditos.
OAuth 2.1 é uma evolução e consolidação do OAuth 2.0, incorporando as melhores práticas de segurança que se desenvolveram ao longo dos anos. Não é uma versão completamente nova, mas sim uma "limpeza da casa" que remove práticas inseguras e torna obrigatórias as práticas recomendadas.
Remove vetores de ataque conhecidos e torna práticas seguras obrigatórias
Menos opções confusas, diretrizes mais claras para desenvolvedores
Alinhado com as realidades atuais de aplicações web e mobile
Se você já usa boas práticas OAuth 2.0:
Se você ainda usa práticas antigas:
"OAuth 2.1 não é revolução, é evolução inteligente. Pegamos o que funcionava bem e removemos o que causava problemas."
No grande teatro de Federápolis, três atores principais sobem ao palco: "Quem eu sou?" grita o primeiro (Identidade). "Você é realmente quem diz ser?" questiona o segundo (Autenticação). "O que você pode fazer aqui?" pergunta o terceiro (Autorização). Lady OAuth e Lord OIDC aplaudem - cada um tem seu papel fundamental no espetáculo da segurança digital!
O que é identidade digital?
Conjunto de atributos que identificam o usuário (nome, e-mail, sub).
🎪 É como o bilhete de identidade que IDA Token carrega em seu medalhão!
O que é autenticação?
Processo de confirmar quem é o usuário.
🔍 Lord OIDC examina cuidadosamente: "Prove que você é quem diz ser!"
O que é autorização?
Processo de definir o que o usuário pode acessar.
🗝️ Lady OAuth entrega as chaves: "Você pode entrar nestas salas, mas não naquelas!"
Um sistema pode autenticar sem autorizar?
Sim — autenticar identifica; autorizar define permissões.
🚪 É como reconhecer um visitante (autenticação) mas ainda decidir se ele pode entrar na biblioteca secreta (autorização)!
Lord OIDC desenrola um pergaminho dourado: "Cada habitante do nosso reino tem um nome e uma função. Alex Client é nosso mensageiro, Lady OAuth comanda o Authorization Server, Seraph Resource protege os tesouros, e os cidadãos são nossos End Users. Conhecer estes nomes é a primeira sabedoria do Reino!"
| Termo | Descrição | 🎭 Personagem |
|---|---|---|
| End User | Usuário final que se autentica. | Os Cidadãos do Reino |
| Client / RP (Relying Party) | Aplicação que confia no provedor de identidade. | Alex Client - O Mensageiro |
| Authorization Server / IdP | Servidor que autentica e emite tokens. | Lady OAuth + Lord OIDC |
| Resource Server | API que protege recursos e valida tokens. | Seraph Resource - O Guardião |
| Scopes | Permissões solicitadas (ex: openid, email). |
Cartas de Permissão de Lady OAuth |
| Claims | Informações sobre o usuário dentro do token. | Segredos gravados no medalhão de IDA Token |
Lord OIDC ergue sua varinha e revela os portais mágicos de seu castelo: "Cada portal tem sua função! O '/authorize' é onde os visitantes batem à porta, o '/token' é onde as trocas secretas acontecem, o '/userinfo' revela segredos pessoais, e o '/.well-known/openid-configuration' é meu livro de regras aberto a todos. Nele, publico o jwks_uri, a URL exata do cofre das chaves públicas — que pode variar conforme o provedor!"
Principais endpoints:
/authorize - 🚪 A Grande Porta onde Alex Client bate para iniciar sua jornada/token - 🔄 A Câmara Secreta onde códigos viram tokens preciosos/userinfo - 👤 O Espelho Mágico que revela detalhes do usuário autenticado/.well-known/openid-configuration - 📋 O Pergaminho das Regras do Reinojwks_uri - 🗝️ URL do cofre de chaves públicas, publicada pelo provedor no documento de DiscoveryEscopo obrigatório:
openid - 🎫 A senha mágica que transforma OAuth em OIDC. Sem ela, Lady OAuth trabalha sozinha!
Escopos padrão adicionais:
profile, email, address, phone - 📝 Cartas de permissão específicas que IDA Token pode carregar
Alex Client se aproxima de Pixie PKCE: "Qual caminho nos leva aos tokens?" Pixie sorri: "A Estrada Real (Authorization Code + PKCE) é o caminho de todos os mensageiros, com ou sem segredo de cliente; a Ponte Perigosa (Implicit) foi demolida; o Caminho Híbrido é legado para casos específicos."
A Estrada Real - o caminho padrão para todos os tipos de cliente
✨ Pixie PKCE protege o code em toda a jornada; a autenticação do cliente confidencial continua sendo uma proteção adicional.
A Ponte Perigosa - FECHADA para reformas
🚧 Seraph Resource colocou barreiras: "Caminho muito perigoso!"
O Caminho Híbrido - para magos avançados
🧙♂️ Lord OIDC reserva este caminho para desenvolvedores experientes!
No salão real, três irmãos se apresentam: IDA Token, elegante com seu medalhão de identidade, brilha com orgulho - "Eu sou a verdade sobre quem você é!" Ace Token, com seu escudo de guerreiro, proclama - "Eu carrego suas permissões de batalha!" E das sombras, Rex Token sussurra - "Eu sou o guardião do tempo, renovando o que expira." Cada um tem sua personalidade, tempo de vida e missão especial no reino!
Claims obrigatórios:
iss, sub, aud, exp, iat
💎 IDA sussurra: "Carrego a essência de quem você é, assinada pelo próprio Lord OIDC!"
Claims comuns:
scope, client_id, sub
🛡️ Ace declara: "Sou sua espada para abrir os cofres de Seraph Resource!"
🌙 Rex murmura das sombras: "Quando meus irmãos adormecem, eu desperto para trazer nova vida. Mas guarde-me bem - sou precioso demais para ficar exposto!"
Seraph Resource reúne todos os personagens: "Escutem bem, companheiros! Nossa força está na vigilância constante. IDA e Ace, vocês devem ser verificados em cada entrada. Pixie PKCE, nunca deixe códigos soltos pelo caminho. Rex Token, mantenha-se sempre nas sombras seguras. E Alex Client, lembre-se: state e nonce são seus amuletos de proteção contra invasores!"
alg e a assinatura com o JWKS (conjunto de chaves públicas) - 🔐 Selo de Lord OIDCiss (issuer) - 👑 Origem realaud (audience) - 🎯 Destinatário corretoexp (expiration) - ⏰ Tempo ainda válidononce (se usado) - ✨ Magia única🔬 Seraph examina cada token como um detetive experiente!
state é recomendado contra CSRF; com PKCE, o OAuth 2.1 permite dispensá-lo - 🎲 Dado mágico de Alexnonce para ID tokens - 🌟 Estrela única de IDA🦹♀️ Pixie PKCE sussurra encantamentos de proteção!
| Tipo de App | Flow Recomendado | Client Secret | Token Storage | 🎭 Estilo |
|---|---|---|---|---|
| Web App (Server) | Authorization Code + PKCE | ✅ Sim | Session/Memory | 🏰 Castelo Fortificado |
| SPA (Frontend) | Auth Code + PKCE | ❌ Não | Memory Only | 🦋 Mensageiro Ágil |
| Mobile App | Auth Code + PKCE | ❌ Não | Secure Storage | 📱 Espelho Mágico |
| API/Service | Client Credentials | ✅ Sim | Não aplicável | 🤖 Golem Automático |
Um login para múltiplas aplicações
Conectar diferentes domínios de identidade
No reino, às vezes as coisas dão errado. Alex Client chega desesperado: "Meus tokens foram rejeitados!" Devia, agora uma doutora experiente, examina os sintomas. Seraph Resource resmunge sobre assinaturas inválidas. Pixie PKCE aponta erros de CORS. E Rex Token sussurra sobre rotações mal feitas. Aqui estão os casos mais comuns que a Dra. Devia trata em seu consultório digital!
🚪 "Alto lá!" - grita o guarda. "Alex Client não está na lista de convidados!"
Possíveis causas:
🩺 Dra. Devia prescreve: Verificar configuração no IdP e no client.
⏰ Seraph Resource examina Ace Token e balança a cabeça: "Este guerreiro expirou! Virou pó há horas!"
Possíveis causas:
exp claim) - Ace virou fantasma🩺 Dra. Devia prescreve: Chamar Rex Token para renovação automática, sincronizar relógios.
🌐 Pixie PKCE tenta voar entre os reinos, mas guardas invisíveis (CORS) a impedem: "Você não pode vir deste reino!"
Possíveis causas:
🩺 Dra. Devia prescreve: Configurar CORS no IdP, usar proxy em desenvolvimento.
Devia orgulhosamente apresenta sua oficina: "Aqui estão as ferramentas que todo desenvolvedor do Reino da Identidade Federada deve conhecer! JWT.io é meu microscópio para examinar tokens, OIDC Debugger é meu laboratório de testes, e estas bibliotecas são meus assistentes mágicos. E veja só - os próprios Lord OIDC e Lady OAuth endossam estes provedores de confiança!"
// Configuração
const config = {
authority: 'https://your-idp.com',
client_id: 'your-spa-client-id',
redirect_uri: 'https://yourapp.com/callback',
response_type: 'code',
scope: 'openid profile email',
post_logout_redirect_uri: 'https://yourapp.com'
};
// Gerar PKCE
function base64url(bytes) {
const byteArray = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
const binary = Array.from(byteArray, byte => String.fromCharCode(byte)).join('');
return btoa(binary)
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// Iniciar login
async function login() {
const codeVerifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const digest = await crypto.subtle.digest(
'SHA-256',
new TextEncoder().encode(codeVerifier)
);
const codeChallenge = base64url(digest);
const state = crypto.randomUUID();
const nonce = crypto.randomUUID();
sessionStorage.setItem('code_verifier', codeVerifier);
sessionStorage.setItem('oidc_state', state);
sessionStorage.setItem('oidc_nonce', nonce);
const params = new URLSearchParams({
response_type: config.response_type,
client_id: config.client_id,
redirect_uri: config.redirect_uri,
scope: config.scope,
state,
nonce,
code_challenge: codeChallenge,
code_challenge_method: 'S256'
});
window.location.href = `${config.authority}/authorize?${params}`;
}
// No callback, valide state antes de trocar o code por tokens.
function readAuthorizationResponse() {
const params = new URLSearchParams(window.location.search);
const expectedState = sessionStorage.getItem('oidc_state');
if (!expectedState || params.get('state') !== expectedState) {
throw new Error('Resposta OAuth com state ausente ou inválido.');
}
const code = params.get('code');
const codeVerifier = sessionStorage.getItem('code_verifier');
const expectedNonce = sessionStorage.getItem('oidc_nonce');
if (!code || !codeVerifier) {
throw new Error('Resposta OAuth sem code ou code_verifier.');
}
if (!expectedNonce) {
throw new Error('Nonce da solicitação OIDC não encontrado.');
}
return { code, codeVerifier, expectedNonce };
}
// Após a troca, passe o ID Token já validado por uma biblioteca OIDC confiável.
function validateCallback(validatedIdToken, expectedNonce) {
if (!expectedNonce || validatedIdToken.nonce !== expectedNonce) {
throw new Error('ID Token com nonce ausente ou inválido.');
}
sessionStorage.removeItem('oidc_state');
sessionStorage.removeItem('oidc_nonce');
sessionStorage.removeItem('code_verifier');
return true;
}
import jwt
import requests
def validate_id_token(token, issuer, client_id, nonce):
discovery_response = requests.get(
f"{issuer}/.well-known/openid-configuration", timeout=5
)
discovery_response.raise_for_status()
config = discovery_response.json()
jwks = jwt.PyJWKClient(config["jwks_uri"], cache_keys=True, timeout=5)
key = jwks.get_signing_key_from_jwt(token).key
claims = jwt.decode(
token,
key,
algorithms=["RS256", "ES256"],
audience=client_id,
issuer=issuer,
options={"require": ["iss", "sub", "aud", "exp", "iat", "nonce"]},
)
if claims.get("nonce") != nonce:
raise ValueError("nonce inválido")
return claims
# Passe o nonce aleatório enviado na solicitação de autenticação.
Para explicações detalhadas de todos os conceitos OAuth 2.1 e OIDC, visite nosso:
Dicionário com explicações para leigos e técnicos, usando as metáforas dos personagens do Reino OIDC.
Acompanhe o Authorization Code Flow passo a passo, do login até o sucesso:
Fluxo passo a passo explicado para leigos e técnicos - quando tudo funciona perfeitamente!