OAuth Token Revocation: Standards-Based Strategies for Limiting Credential Theft
Use OAuth revocation, introspection, refresh-token rotation, sender constraints, and least privilege to reduce the impact of stolen tokens.
OAuth Token Revocation: Standards-Based Strategies for Limiting Credential Theft
OAuth tokens are bearer credentials unless a deployment explicitly sender-constrains them. Anyone who obtains a valid bearer token may be able to use its granted privileges until it expires or is revoked. A resilient design therefore limits token lifetime and scope, detects replay, and provides a reliable way to terminate access.
This guide follows IETF standards and current GitHub documentation. It does not rely on anonymous breach stories or invented statistics.
Revocation and introspection solve different problems
OAuth defines two related server-side mechanisms:
- Token revocation (RFC 7009) lets an authorized client ask the authorization server to invalidate a token. Implementations must support refresh-token revocation and should support access-token revocation.
- Token introspection (RFC 7662) lets an authorized protected resource ask the authorization server whether a token is active and retrieve authorized metadata about it.
Introspection is not revocation. Reading an active response and then calling a revocation endpoint is provider-specific orchestration, not a universal OAuth workflow. Both endpoints require transport security and their own access controls; never copy example URLs or authentication methods into production without following your provider's documentation.
A practical defense model
1. Keep access tokens short-lived and narrowly scoped
Choose lifetimes based on the sensitivity of the operation, the client's ability to refresh safely, and the time required to detect abuse. There is no universal 5- or 15-minute requirement in the OAuth standards.
Restrict each access token to the minimum scopes and intended resource servers. RFC 9700 recommends audience restriction because a token accepted by fewer services has a smaller blast radius if leaked.
2. Protect refresh tokens against replay
Refresh tokens can mint new access tokens, so they require stronger protection than a simple expiration check. RFC 9700 requires public clients to use sender-constrained refresh tokens or refresh-token rotation.
With rotation, the authorization server issues a new refresh token on every successful refresh and invalidates the previous one. Reuse of an invalidated token can reveal replay and trigger revocation of the active token family.
3. Sender-constrain tokens where the ecosystem supports it
RFC 9700 recommends mechanisms such as mutual TLS or DPoP to bind a token to a client key. A copied token alone is then insufficient because the requester must also prove possession of the bound key.
Sender constraints do not replace secure storage, least privilege, or revocation. They add a meaningful barrier against replay of leaked token strings.
4. Revoke on security and lifecycle events
Define provider-supported revocation actions for events such as:
- user logout or account disablement;
- password or authentication-factor changes where policy requires it;
- client compromise or secret rotation;
- refresh-token replay detection;
- device loss, administrative termination, or suspicious session activity.
Preserve the audit trail before broad revocation when an investigation is active, then invalidate the affected grant or token family through the authorization server.
5. Treat CI credentials as workload identities
Prefer short-lived, repository-scoped workload credentials over long-lived personal tokens. GitHub documents that the Actions GITHUB_TOKEN is a per-job GitHub App installation token, limited to the repository and expiring when the job finishes or reaches its maximum lifetime.
Set explicit permissions for every workflow and grant only what the job needs. If an integration requires broader access, prefer a dedicated GitHub App or workload-identity federation over a personal credential shared across repositories.
6. Keep tokens out of logs and artifacts
Use the CI platform's secret store and redaction features, but do not assume redaction catches every transformed value. Avoid printing environment variables, command traces, authorization headers, or introspection responses containing sensitive metadata. Review third-party actions before granting them token access.
What a client-side JWT decoder can and cannot do
Inspect JWT Structure Locally
OpsecForge's browser-based JWT decoder can display a token's header and payload locally without sending it to an OpsecForge server.
Open JWT Decoder →Decoding is not validation. A decoder can help you inspect claims such as iss, aud, exp, and scope, but it cannot prove that the signature is valid, that the issuer is trusted, or that the token is still active. Production validation belongs in the resource server or a trusted authorization component that verifies the signature or uses authenticated introspection.
The OpsecForge JWT Decoder is a browser interface, not a CI API or secret scanner. The Env Sanitizer is likewise a browser tool for preparing text before sharing; it is not a substitute for repository secret scanning or a secrets manager.
Incident checklist for a suspected token leak
- Preserve relevant authorization, resource-server, CI, and network logs.
- Identify the issuer, client, subject, audience, scopes, token family, and affected resources.
- Revoke the exposed token or grant through the provider-supported interface.
- Rotate related client secrets or signing material only when exposure or policy warrants it.
- Remove the token from logs, artifacts, caches, and source history while preserving forensic evidence.
- Review subsequent use for unfamiliar sources, audiences, scopes, or actions.
- Replace long-lived credentials with scoped, short-lived, or sender-constrained alternatives.