Identidade: OAuth 2.1, OIDC e JWT

O BoxOffice lança o seu app mobile. Alguém propõe o projeto óbvio: uma tela de login no app, o app envia e-mail e senha para POST /login, guarda a senha no celular "para o usuário não precisar digitar de novo" e a envia em toda requisição. Em uma semana, o time de produto também quer "Entrar com Google", um checkout web, um job noturno de conciliação em order que chama inventory sem nenhum usuário por trás, e um assistente de IA que age em nome do usuário. Um login caseiro não consegue expressar nada disso com segurança. Esta página trata dos padrões que conseguem: sessões e tokens, JWT, OAuth 2.1 e OpenID Connect, e dos modelos de autorização que decidem o que um chamador autenticado pode fazer.

Autenticação vs autorização

Duas perguntas diferentes são feitas em toda requisição:

Vocabulário usado abaixo: um principal é a entidade autenticada (um usuário ou um workload); uma credencial é o que ele apresenta para provar quem é; um token é o que ele recebe depois de se autenticar e apresenta no lugar da credencial; uma claim é uma afirmação dentro de um token ("sub": "acc-42"). Um bearer token funciona para quem o tiver em mãos, como dinheiro vivo.

Sessões vs tokens

Depois do login, o servidor precisa reconhecer o usuário na próxima requisição. Duas famílias de projeto:

flowchart LR
    subgraph s ["Sessão no servidor"]
        B1(["Navegador"]) -->|"Cookie: sid=9f2c…"| A1["app"]
        A1 -->|"GET session:9f2c"| R[("Redis")]
    end
    subgraph t ["Token autocontido (JWT)"]
        B2(["App"]) -->|"Authorization: Bearer eyJ…"| A2["gateway"]
        A2 -->|"verifica a assinatura localmente<br/>(chave pública em cache)"| A2
    end

Nenhum dos dois é "o moderno". Sistemas grandes combinam os dois: um JWT de vida curta (minutos) para APIs e um refresh token ou sessão revogável guardado no servidor. A latência de revogação passa a ser igual ao tempo de vida do access token — um número que você escolhe.

JSON Web Token (JWT)

Um JWT (RFC 7519) é formado por três partes codificadas em Base64URL separadas por pontos: header.payload.signature. Decodificado, um access token do BoxOffice fica assim:

header:  { "alg": "RS256", "typ": "at+jwt", "kid": "2026-10-a" }
payload: {
  "iss": "https://auth.boxoffice.com/realms/boxoffice",
  "sub": "acc-42",
  "aud": "boxoffice-api",
  "client_id": "boxoffice-mobile",
  "scope": "orders:read orders:write",
  "iat": 1792310400,
  "exp": 1792311300,
  "jti": "5b0e7c1a-6d1f-4c1e-9a43-0d6c2f6c9e10"
}
signature: RSASSA-PKCS1-v1_5( SHA-256( base64url(header) + "." + base64url(payload) ), private key )

O payload é codificado, não criptografado — qualquer um consegue lê-lo. Nunca coloque ali segredos ou dados pessoais que você não mostraria ao próprio usuário.

Com algoritmos assimétricos (RS256, ES256, EdDSA), o provedor de identidade assina com uma chave privada que nunca sai dele, e qualquer um verifica com a chave pública, publicada como um JWKS (JSON Web Key Set) no jwks_uri do provedor. Com HMAC simétrico (HS256), todo verificador tem o mesmo segredo e, portanto, também consegue forjar tokens — aceitável só quando emissor e verificador são o mesmo serviço.

Checklist de validação

A RFC 8725 (JWT Best Current Practices) é a referência¹. Um resource server precisa verificar:

public TokenOut issue(User user) {
    var now = Instant.now();
    var claims = new JWTClaimsSet.Builder()
            .issuer(issuer)
            .audience(audience)
            .subject(user.getId().toString())
            .claim("email", user.getEmail())
            .claim("name", user.getName())
            .claim("scope", user.getRole() == Role.ADMIN ? "user admin" : "user")
            .issueTime(Date.from(now))
            .expirationTime(Date.from(now.plus(ttl)))
            .jwtID(UUID.randomUUID().toString())
            .build();
    var header = new JWSHeader.Builder(JWSAlgorithm.RS256)
            .keyID(key.getKeyID())
            .type(JOSEObjectType.JWT)
            .build();
    try {
        var jwt = new SignedJWT(header, claims);
        jwt.sign(new RSASSASigner(key));
        return new TokenOut(jwt.serialize(), "Bearer", ttl.toSeconds());
    } catch (JOSEException e) {
        throw new IllegalStateException("could not sign the token", e);
    }
}

OAuth 2.1

OAuth é um framework de autorização delegada: uma aplicação cliente obtém um access token limitado e de vida curta para chamar uma API em nome de um usuário — ou em nome próprio — sem nunca manipular a senha do usuário. O usuário se autentica apenas no authorization server².

Clientes são confidenciais (rodam em um servidor, conseguem guardar um segredo: o BFF, um job em lote) ou públicos (rodam no dispositivo do usuário, não conseguem guardar segredo: o app mobile, uma single-page app — qualquer um pode descompilá-los ou lê-los).

O que o OAuth 2.1 muda

O OAuth 2.0 (RFC 6749, 2012) acumulou uma década de lições de segurança em documentos separados. O OAuth 2.1 — um draft do IETF que os consolida, junto com a Security Best Current Practice (RFC 9700) — é o que sistemas novos devem seguir³⁴:

Escolhendo o grant

flowchart TD
    q1{"Há um usuário<br/>envolvido?"} -->|não| cc["Client Credentials<br/>(job de conciliação)"]
    q1 -->|sim| q2{"O dispositivo consegue<br/>abrir um navegador?"}
    q2 -->|sim| pkce["Authorization Code + PKCE<br/>(app mobile, BFF web)"]
    q2 -->|não| dev["Device Authorization<br/>(smart TV, CLI)"]
    pkce --> q3{"Um serviço precisa chamar outro<br/>em nome do usuário?"}
    q3 -->|sim| tx["Token Exchange<br/>(assistant → order)"]

Authorization Code + PKCE para o app mobile

O app nunca vê a senha. Ele abre o navegador do sistema (não uma WebView embutida, onde o app poderia ler as teclas digitadas — RFC 8252⁵) no authorization server, o usuário faz login lá (com MFA ou uma passkey), e o app recebe um authorization code de vida curta e uso único por meio de um redirecionamento. Depois o app troca o código por tokens em uma requisição direta, pelo back-channel.

O PKCE (Proof Key for Code Exchange, pronuncia-se "pixy", RFC 7636⁶) amarra o código à instância do app que iniciou o fluxo:

1. O app gera um code_verifier aleatório (43–128 caracteres) e o mantém em memória.
2. Ele envia só code_challenge = BASE64URL(SHA-256(code_verifier)) na requisição de autorização.
3. Na troca pelo token, envia o code_verifier original; o servidor calcula o hash e compara.

Um app malicioso que registrou o mesmo esquema de redirecionamento e intercepta o código não tem o verifier, então o código é inútil.

sequenceDiagram
    autonumber
    actor Ana
    participant App as App BoxOffice
    participant Br as Navegador do sistema
    participant AS as auth (Keycloak)
    participant GW as API gateway
    participant O as order
    Ana->>App: toca em "Entrar"
    App->>App: cria state, nonce, code_verifier, code_challenge (S256)
    App->>Br: abre /authorize?response_type=code&client_id=boxoffice-mobile&scope=openid orders:write&code_challenge&state&nonce
    Br->>AS: GET /authorize
    AS->>Ana: página de login (senha + MFA, ou passkey)
    Ana->>AS: credenciais
    AS-->>Br: 302 https://app.boxoffice.com/cb?code=XYZ&state
    Br-->>App: redirecionamento entregue ao app (link HTTPS reivindicado)
    App->>App: confere o state
    App->>AS: POST /token {code, code_verifier, redirect_uri}
    AS->>AS: SHA-256(code_verifier) == code_challenge?
    AS-->>App: access_token (15 min) + refresh_token (rotativo) + id_token
    App->>GW: POST /orders  Authorization: Bearer access_token
    GW->>GW: verifica assinatura (JWKS em cache), iss, aud, exp, escopo
    GW->>O: POST /orders + X-Account-Id: acc-42
    O-->>App: 201 Created

O parâmetro state impede que um atacante injete o código dele na sessão da Ana (CSRF no callback); o nonce volta dentro do ID token e impede o reaproveitamento de um ID token antigo.

# 64 random URL-safe characters
verifier=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64)
# BASE64URL(SHA-256(verifier)), without '=' padding
challenge=$(printf '%s' "$verifier" | openssl dgst -sha256 -binary \
            | openssl base64 | tr '+/' '-_' | tr -d '=')
echo "verifier=$verifier"; echo "challenge=$challenge"

Onde o app mobile guarda os tokens. O access token fica em memória; o refresh token, no armazenamento seguro da plataforma (Keychain no iOS, armazenamento apoiado no Keystore no Android). O authorization server rotaciona o refresh token a cada uso: se uma cópia roubada e o app legítimo tentarem usar o mesmo, o servidor detecta o reuso e revoga a família inteira.

OpenID Connect: quem é o usuário?

O OAuth responde "este cliente pode chamar esta API?". De propósito, ele não diz ao cliente quem é o usuário — o access token é endereçado à API. O OpenID Connect (OIDC) acrescenta uma camada de identidade sobre o OAuth⁷:

• o escopo openid na requisição de autorização;
• o ID token — um JWT endereçado ao cliente (aud = o seu client_id) com sub, iss, exp, nonce, auth_time e, com os escopos profile/email, nome e e-mail;
• o endpoint UserInfo, para mais claims de perfil;
• discovery em /.well-known/openid-configuration, que lista os endpoints e o jwks_uri, para que clientes e resource servers se configurem só a partir da URL do emissor.

Checkout web: OIDC por meio de um Backend-for-Frontend

Para o navegador, a recomendação atual é não deixar token nenhum no JavaScript. Um BFF (Backend for Frontend) é um cliente confidencial no servidor: ele roda o fluxo OIDC, guarda os tokens e dá ao navegador só um cookie de sessão HttpOnly, Secure, SameSite⁸.

sequenceDiagram
    autonumber
    actor Ana
    participant Br as Navegador (SPA do checkout)
    participant BFF as BFF web (cliente confidencial)
    participant AS as auth (provedor OIDC)
    participant GW as API gateway
    Ana->>Br: clica em "Entrar"
    Br->>BFF: GET /login
    BFF-->>Br: 302 para o AS /authorize (code + PKCE, escopo openid, nonce)
    Br->>AS: login (passkey)
    AS-->>Br: 302 para o BFF /callback?code&state
    Br->>BFF: GET /callback?code&state
    BFF->>AS: POST /token {code, code_verifier, segredo do cliente ou private_key_jwt}
    AS-->>BFF: id_token + access_token + refresh_token
    BFF->>BFF: valida o id_token (assinatura, iss, aud, exp, nonce), guarda os tokens no servidor
    BFF-->>Br: Set-Cookie: session=… HttpOnly Secure SameSite=Lax
    Br->>BFF: GET /api/orders (cookie)
    BFF->>GW: GET /orders  Bearer access_token
    GW-->>BFF: 200 pedidos
    BFF-->>Br: 200 pedidos

Máquinas e delegação

Client Credentials: o job de conciliação

Quando não há usuário envolvido, o cliente se autentica como ele mesmo e recebe um token que representa o serviço. O job de conciliação de order pede exatamente o escopo de que precisa:

curl -s -X POST https://auth.boxoffice.com/realms/boxoffice/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=order-reconciler \
  -d client_secret="$ORDER_RECONCILER_SECRET" \
  -d scope=inventory:read

Melhor que um client secret: autenticar o cliente com um JWT assinado (private_key_jwt) ou com a sua identidade de workload (certificado mTLS ou o token da service account do Kubernetes) — nenhum segredo compartilhado para vazar (Zero Trust).

Token Exchange: o assistente agindo pelo usuário

O assistant de IA precisa chamar order em nome da Ana, com menos poder que o próprio token da Ana. O Token Exchange (RFC 8693) permite que um serviço troque o token que recebeu por um novo, com outra audiência e escopo mais estreito (aud=order, scope=orders:read), mantendo sub=acc-42 e registrando o ator (act: assistant). O log de auditoria então mostra "assistant, agindo por acc-42, leu o pedido 1042".

Tokens vinculados ao remetente

Um bearer token funciona para quem o roubar. Tokens vinculados ao remetente (sender-constrained) ficam amarrados a uma chave que o cliente legítimo possui: com DPoP (RFC 9449), o cliente assina uma pequena prova a cada requisição com uma chave privada no dispositivo; com tokens vinculados a mTLS (RFC 8705), o token fica amarrado ao certificado do cliente. Um token roubado sozinho fica inútil. APIs de nível financeiro os exigem; no BoxOffice, valem a pena nos endpoints de pagamento.

Passkeys

Passkeys (WebAuthn/FIDO2) substituem senhas por um par de chaves por site, guardado no dispositivo e desbloqueado por biometria. A chave privada nunca sai do dispositivo e a assinatura fica amarrada à origem do site, então elas resistem a phishing. Elas mudam como o usuário se autentica no authorization server; os fluxos OAuth/OIDC depois disso continuam iguais.

Validando tokens no gateway

O gateway é o primeiro ponto de aplicação (enforcement point): ele rejeita requisições sem token válido e repassa uma identidade confiável para dentro (veja Borda — API gateway).

Com Spring Security (também no Spring Cloud Gateway), a validação local é configuração:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.boxoffice.com/realms/boxoffice  # discovers jwks_uri, checks iss
          audiences: boxoffice-api                                 # rejects tokens for other APIs

/** Signature from the JWKS of auth, plus expiry, issuer and audience checks. */
@Bean
ReactiveJwtDecoder jwtDecoder(@Value("${spring.security.oauth2.resourceserver.jwt.jwk-set-uri}") String jwksUri,
                              @Value("${jwt.issuer}") String issuer,
                              @Value("${jwt.audience}") String audience) {
    var decoder = NimbusReactiveJwtDecoder.withJwkSetUri(jwksUri).build();
    decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(
            JwtValidators.createDefaultWithIssuer(issuer),     // exp, nbf, iss
            new JwtClaimValidator<List<String>>("aud", aud -> aud != null && aud.contains(audience))));
    return decoder;
}

@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    var cleaned = exchange.mutate()
            .request(r -> r.headers(h -> {
                h.remove("X-User-Id");
                h.remove("X-User-Email");
                h.remove("X-User-Scope");
            }))
            .build();
    return ReactiveSecurityContextHolder.getContext()
            .map(SecurityContext::getAuthentication)
            .filter(JwtAuthenticationToken.class::isInstance)
            .cast(JwtAuthenticationToken.class)
            .map(auth -> cleaned.mutate()
                    .request(r -> r.headers(h -> {
                        var jwt = auth.getToken();
                        h.set("X-User-Id", jwt.getSubject());
                        h.set("X-User-Email", jwt.getClaimAsString("email"));
                        h.set("X-User-Scope", jwt.getClaimAsString("scope"));
                    }))
                    .build())
            .defaultIfEmpty(cleaned)          // anonymous request on an open route
            .flatMap(chain::filter);
}

Modelos de autorização

A autenticação produziu uma identidade. Agora: esta identidade pode fazer esta ação sobre este objeto?

Escopos OAuth não são substitutos: um escopo limita o que o cliente pode fazer (orders:read), não quais objetos o usuário pode tocar. A verificação de posse — a correção do OWASP API1: BOLA — sempre roda no serviço que é dono dos dados⁹:

@GetMapping("/orders/{id}")
@PreAuthorize("hasAuthority('SCOPE_orders:read')")
public OrderOut get(@PathVariable UUID id, @AuthenticationPrincipal Jwt jwt) {
    Order order = repository.findById(id)
        .filter(o -> o.getAccountId().equals(jwt.getSubject()))  // ownership (BOLA)
        .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
    return OrderOut.from(order);                                 // explicit DTO (BOPLA)
}

package boxoffice.orders

import rego.v1

default allow := false

# owners can read their own orders
allow if {
    input.action == "read"
    input.resource.owner_id == input.user.sub
}

# support staff can read any order, never modify it
allow if {
    input.action == "read"
    "support" in input.user.roles
}

permit (
  principal,
  action == Action::"ReadOrder",
  resource
)
when { resource.owner == principal };

permit (
  principal in Role::"support",
  action == Action::"ReadOrder",
  resource
);

Motores de política (OPA, Cedar, OpenFGA) tiram as regras do código e as colocam em um artefato revisável e testável, compartilhado por vários serviços. O serviço continua fazendo a pergunta para cada objeto.

Como se conecta

flowchart LR
    AS["auth: provedor OIDC<br/>(servidor de autorização)"] --> PKCE["Authorization Code + PKCE<br/>app mobile, BFF web"]
    AS --> CC["Client Credentials<br/>job de reconciliação"]
    AS --> TX["Token Exchange<br/>assistant → order"]
    PKCE --> JWT["access token JWT de vida curta<br/>+ refresh token rotativo"]
    PKCE --> SESS["cookie de sessão do BFF<br/>store compartilhado → Caching"]
    JWT --> GW["gateway valida via JWKS<br/>iss, aud, exp → Borda"]
    GW --> SVC["cada serviço verifica a posse<br/>RBAC / ABAC / ReBAC"]
    SVC --> BOLA["corrige OWASP API1 (BOLA)"]
    CC --> WI["identidade de workload<br/>→ Zero Trust"]
    TX --> AI["agentes agindo pelo usuário<br/>→ Sistemas de IA"]

Componentes da paleta: auth · apigw (o primeiro ponto de aplicação) · client · mobile · cache (sessões no servidor) · orchestrator (o assistente agindo em nome do usuário). Cenários: rate-limiter, flash-sale, ai-assistant. Continua em: Borda — API gateway, Zero Trust, Caching — Redis, Sistemas de IA — agentes, Hands-on 4 — Gateway e identidade.

Pontos-chave