Recursos · 43
OAuth e OpenID Connect: verifique uma integração de ponta a ponta.
Separe o login, a delegação e as permissões de dados e, em seguida, teste redirecionamentos, tokens, sessões e revogação. O guia
Atualizado · 9 min
O que este guia ajuda a alcançar
- Separar identidade de autorização
- Rejeitar redirecionamentos e tokens não intencionais
- Testar negações com o mesmo cuidado que os sucessos
- Verificar a remoção de acesso após a saída ou incidente
Verificação rápida
- Qual provedor e emissor são esperados?
- O URI de redirecionamento está registrado corretamente?
- Um token de ID está sendo usado incorretamente como token de acesso?
- Cada recurso verifica a propriedade?
- Qual acesso sobrevive à revogação?
Método passo a passo
- 1
Desenhar o fluxo implantado
Identificar cliente público ou confidencial, navegador, servidor de autorização, API e provedor OIDC. Registrar por onde os códigos e tokens trafegam, quem os armazena e quais funções são concedidas. Um diagrama de vendas não estabelece a implantação real.
Entregável: fluxo, limites de confiança e proprietários de componentes.
- 2
Verificar a transação de login.
Usar o fluxo de código com PKCE apropriado para o cliente. Verificar S256, vinculação de transação, redirecionamentos registrados e proteção contra solicitações falsificadas. Testar URI inesperado, verificador incorreto, código reproduzido e emissor inesperado. A RFC 9700 separa os requisitos e recomendações por tipo de cliente.
Entregável: resultados de testes de permissão e negação.
- 3
Validar o token correto.
A API valida seu token de acesso de acordo com o formato e as regras do provedor: assinatura ou introspecção, emissor, público-alvo, expiração e permissões. O cliente OIDC valida separadamente o token de identidade. Uma assinatura válida não estabelece que o token pertence a esta API.
Entregável: contrato de validação e testes de público-alvo e expiração.
- 4
Verificar permissões de negócios
Testar um objeto pertencente a outra conta, uma função inferior, um campo privado e uma operação administrativa. Um escopo ou gateway autenticado não substitui as verificações do lado do servidor no recurso solicitado. Usar contas e dados de teste autorizados.
Entregável: matriz de função, objeto, operação e negação esperada.
- 5
Exercitar expiração e revogação
Separar sessão local, sessão do provedor, token de acesso e token de atualização. Testar saída, perda de dispositivo, alteração de função, rotação da chave de assinatura e indisponibilidade do provedor. Documentar o tempo de acesso residual em vez de presumir que o logout revoga tudo imediatamente.
Entregável: linha do tempo de remoção de acesso e exceções.
- 6
Observar sem expor segredos
Registrar referência de transação, decisão de validação, categoria de erro e versão de configuração. Excluir códigos, tokens e segredos. Preparar diagnóstico, desligamento da integração e reversão para uma configuração validada; reproduzir testes após alterações de provedor.
Entregável: procedimento operacional e verificações de regressão.
Exemplo prático fictício
Situação ilustrativa
Situação ilustrativa: dois clientes usam um provedor de identidade. Um token válido para o primeiro é apresentado à API do segundo cliente.
Decisão e evidências esperadas
A API rejeita o público-alvo errado, registra um rastreamento sem token e não retorna dados. A negação se torna um teste de regressão.
Distinguir os mecanismos
| Mecanismo | Finalidade | Verificação ou limitação |
|---|---|---|
| OAuth 2.0 | Delegar acesso a recursos | Permissões de objetos no servidor |
| OpenID Connect | Estabelecer identidade por meio de um token de ID validado | Validação de emissor, público-alvo e transação |
| Sessão do aplicativo | Manter o login do aplicativo | Expiração, invalidação e proteção de sessão |
Indicadores de gestão
| Indicador | O que mede | Primeira ação |
|---|---|---|
| Corrigir negações | Casos proibidos realmente bloqueados | Corrigir toda aceitação inesperada |
| Atraso na revogação | Tempo até que o acesso relevante desapareça | Verificar sessões e tokens separadamente |
| Falhas de validação | Rejeições por causa e versão | Separar ataques de erros de configuração |
Erros comuns
- Confundir autenticação com autorização
- Aceitar qualquer público-alvo após verificar a assinatura
- Registrar URIs de redirecionamento amplo
- Registrar tokens para facilitar Depuração
Perguntas frequentes
O PKCE substitui todos os controles?
Não. Ele protege a troca de código no fluxo pretendido; a validação de token, redirecionamentos, autorização de negócios e sessões ainda precisam ser verificados.
Um JWT é uma permissão?
JWT é um formato. As declarações só se tornam utilizáveis após a validação e aplicação das suas regras de API.
A validação deve ser construída do zero?
Prefira uma biblioteca mantida e documentação do provedor e, em seguida, teste sua configuração. Uma biblioteca correta ainda pode ser configurada incorretamente.
Que provas guardar para uma verificação útil?
Guardar contexto da conta, funções, recurso e respostas API. Uma autenticação bem-sucedida não prova permissões corretas; não registar segredos de sessão.
OAuth/OIDC: público e acesso
As notas detalhadas desta edição estão disponíveis em inglês.
Which token belongs to which recipient? A testable validation contract
A secure OAuth/OIDC integration connects each token to its purpose, issuer and intended recipient. An ID token tells the OIDC client about authentication; an access token is presented to a protected resource. Successful sign-in alone does not authorise a read, a change or an AI agent’s tool call.
This reference covers a specific profile: an API consuming JWT access tokens under RFC 9068. OAuth 2.0 does not require every access token to use JWT. Clients must treat their access tokens as opaque; the resource server owns the validation contract. The examples below are fictional, with no secret or usable signature.
Four objects with distinct purposes
| Object | Recipient and purpose | Boundary to retain |
|---|---|---|
| Authorisation code | Authorisation server token endpoint: redeem the code within the intended transaction. | The code is not an API permission; check binding to the client, redirect and PKCE. |
| ID token | OIDC client: validate identity and transaction; aud contains its client_id. | Do not reuse it as an API access credential; apply the OIDC rules for the relevant flow. |
| Access token | Resource server: access within the grant; its audience identifies the intended resource. | Validate the token, then operation and object permissions. The client must not depend on its internal content. |
| Refresh token | Authorisation server token endpoint: obtain new access tokens. | Do not send it to the resource server; its lifecycle differs from the local session. |
Eight controls for the validation contract
| Control | Rule and scope | Evidence without tokens |
|---|---|---|
| Profile and typ | For RFC 9068, check typ = at+jwt or application/at+jwt. Other profiles need their own rules; “any signed JWT” is too broad a contract. | Configured profile and a rejected ID/access token confusion case. |
| Algorithm and keys | Verify the signature with the expected issuer’s keys and algorithms allowed by configuration. RFC 9068 excludes alg = none; a received value does not set policy by itself. | Cryptographic policy version and result, with no secret material. |
| Issuer iss | Compare exactly with the expected issuer. A similar host, path or suffix does not establish trust. | Configuration reference and issuer_mismatch reason. |
| Audience aud | The expected recipient must appear in aud. An audience array is possible; finding the recipient does not replace other checks. | Expected resource and a test using a token intended for another API. |
| Expiry exp | Current time must precede exp; any small clock leeway is an explicit policy. The teaching fixture uses zero seconds of leeway. | Test clock, configured leeway and an exercised expiry boundary. |
| Scopes and object | Bind each scope to the resource and operation. Then check ownership, tenant and business policy on the server. RFC 9068 does not define all this authorisation. | Action, test object, applied rule and a cross-tenant denial. |
| OIDC transaction and PKCE | If nonce was sent, verify its presence and equality in the ID token. RFC 9700 requires PKCE for public clients and recommends it for confidential clients; bind the challenge to the transaction, with S256 recommended. | Wrong nonce, replayed code and wrong code_verifier tests in the authorised flow. |
| Access lifetime and removal | Separate access-token expiry, renewal and application session. RFC 9700 requires sender constraint or rotation to detect refresh-token replay for public clients. | Residual access timeline, user departure and an exercised revocation procedure. |
Read fictional claims without treating them as proof
Teaching clock: 2026-10-22 at 10:00:00 UTC. The JSON contains a readable header and claims only; no signed JWT serialization is supplied. exp is 10:05:00 UTC and iat is 09:59:00 UTC. The .example domains and identifiers belong solely to this scenario.
{
"header": {
"typ": "at+jwt",
"alg": "RS256",
"kid": "training-key-01"
},
"claims": {
"iss": "https://identity.example/",
"sub": "training-subject-17",
"aud": "https://api.example/evidence",
"exp": 1792663500,
"iat": 1792663140,
"jti": "training-event-001",
"client_id": "training-console",
"scope": "evidence:read"
}
}Decoding JSON does not validate a signature or establish trust in keys. Where stated, cryptography is an exercise assumption, never a check performed by this page. The profile also has required claims including sub, client_id, iat and jti: the eight-control table is not a complete validator. A subject does not necessarily identify a person; jti alone does not implement replay protection.
Ten review cases: decision, limit and expected evidence
01 · Token intended for the API: continue to business checks
Situation: iss, aud, typ and exp match the fictional contract; evidence:read is present. Signature verification is assumed solely for the exercise.
Decision: continue to operation and object checks, without automatically declaring “access allowed”. Expected evidence: business rule and test object reviewed separately.
02 · Assumed correct signature, wrong audience
Change: aud targets https://api.example/billing rather than the evidence resource. Other assumptions remain the same.
Decision: reject this token for this API. A correct signature does not change its recipient. Expected evidence: no resource content returned and a token-free audience failure record.
03 · Different issuer with plausible claims
Change: iss is https://other-identity.example/. An HTTPS URL does not make it equivalent to the configured issuer.
Decision: reject the issuer match. Expected evidence: exact comparison with https://identity.example/ and a regression test.
04 · Expiry reached at the exact second
Change: exp equals the test clock, 10:00:00 UTC, with zero seconds of leeway in this fixture.
Decision: reject as expired. “Now is before exp” is false at equality; this example does not establish a universal clock policy. Expected evidence: tests before, at and after the boundary under the real policy.
05 · ID token presented as an access token
Change: a fictional ID token has typ = JWT and aud = training-console. It targets the OIDC client.
Decision: reject it as an RFC 9068 JWT access token. Validating it at the OIDC client does not turn it into an access token. Expected evidence: separate validation rules for each token type.
06 · Write scope presented for a read operation
Change: scope is evidence:write while the call requires evidence:read.
Decision: deny the read under the exercise policy, which defines no write → read implication. Scope names and relationships belong to the contract. Expected evidence: an explicit operation/scope matrix, without inferring permissions from names.
07 · Readable JSON, unverified cryptography
Situation: the JSON is readable and values appear to match, but cryptographic validation and trusted keys are not established.
Decision: stop acceptance; the state is unverified. Expected evidence: configured library output and trust-contract checks. Reading claims alone must not release protected data.
08 · Correct token, another tenant’s object
Situation: test token checks are assumed to pass. The requested object belongs to another tenant and business policy denies this read.
Decision: deny the object. evidence:read does not grant access to every account’s evidence. Expected evidence: server-side cross-tenant test and no leakage through content or returned fields.
09 · Audience array containing the expected resource
Change: aud contains https://api.example/evidence and https://api.example/archive. The expected resource is listed.
Decision: this audience check can pass; continue all other checks. An array is not a wildcard. Expected evidence: scopes remain meaningful for the resource, with no ambiguous grant.
10 · ID token nonce differs from the transaction
Separate OIDC transaction, outside the API cases: sent nonce = training-transaction-A; received nonce = training-transaction-B.
Decision: reject the ID token for this transaction under OIDC Core §3.1.3.7. This does not replace PKCE or API rules. Expected evidence: compare with the original transaction and test missing nonce when one was sent.
Six useful acceptance-review records
- Map clients, issuers, APIs and expected audiences, with an owner for each boundary.
- Versioned validation contract: format, libraries, trusted keys, algorithms and clock leeway.
- Action, scope, tenant and object matrix; state denials and the permission implications actually defined.
- Synthetic fixtures, a fixed clock, negative variants and observed results in the authorised environment.
- Separate session, access-token and refresh-token timelines during departure, revocation and provider outage.
- Redacted log: internal transaction reference, policy version, decision reason and date; exclude tokens, codes and secrets.
Primary sources and reading scope
- IETF · RFC 9700 · OAuth 2.0 Security BCP · BCP 240 · January 2025
§2.1.1 PKCE · §2.2 replay · §2.3 privilege restriction · §4.14 refresh tokens - IETF · RFC 9068 · JWT access token profile · Standards Track · October 2021
§2.1 typ · §2.2 claims · §4 validation · §6 client treats access tokens as opaque - OpenID Foundation · OpenID Connect Core 1.0 · Final · incorporating errata set 2 · 2023-12-15
§2 ID Token · §3.1.3.7 issuer, audience, expiry and nonce - IETF · RFC 8725 · JWT Best Current Practices · BCP 225 · February 2020
§3.1 algorithms · §3.8–3.9 issuer and audience · §3.11–3.12 token type separation - IETF · RFC 6749 · OAuth 2.0 framework · Standards Track · October 2012 · read with RFC 9700
§1.3.1 authorization code · §1.4 access token · §1.5 refresh token · §3.3 scope
Sources reviewed on
Referências oficiais
As referências apoiam o método. Adapte as verificações ao seu contexto; elas não são uma certificação. Os títulos das referências originais e os documentos de origem podem estar em outro idioma.
Referências consultadas em .
