RFC: Stateless OAuth Client Identity for Ephemeral (DCR) Clients on a Doorkeeper-style Provider

A developer proposes a design pattern for handling stateless OAuth client identity on Doorkeeper-style providers, using a JWS-based client_id for dynamically registered, ephemeral clients such as MCP agents. The approach avoids unbounded database growth by keeping client registration stateless, while requiring persisted grants and tokens with cleanup based on time and revocation state. The design includes an optional denylist extension for per-client revocation with bounded state.

Category | Informational / Design Pattern | Status | Draft — distilled from production experience | Applies to | Rails + Doorkeeper OAuth providers Ruby , serving MCP or other dynamically-registered clients | Author | Aotokitsuruya（蒼時弦也） | Date | 2026-06-21 | Audience | Engineers who must host OAuth for dynamically-registered, one-time, unbounded clients typically MCP agents on top of Doorkeeper | This document records a reusable design: when an OAuth client is dynamically registered RFC 7591 DCR , one-time, and unbounded in number the MCP client is the canonical case , how to carry it on a Doorkeeper-style provider with a stateless JWS client identity — so the database never accumulates an unbounded client-registration table — and how to then handle the Access Grant / Access Token lifecycle, cleanup, revocation, and "Active Session" modeling correctly. Core conclusion: the client can be stateless a JWS , but grants and tokens necessarily persist. The real engineering problem is not "whether to store" but "how the persisted rows get reclaimed — correctly, promptly, and completely." Cleanup MUST be keyed on time and revocation state alone , never on the client/application dimension, which under this design is dynamic and non-recurring. Statelessness is a deliberate trade with real costs §4.5 ; this document states them rather than hiding them. An optional security extension a client subject denylist, §16 recovers per-client revocation at the price of a bounded amount of state — a deliberate hybrid, not pure statelessness. Normative guidance uses RFC 2119 keywords MUST / SHOULD / MAY . Code is a recommended shape, not a drop-in library; §15 lists the collaborators an adopter must supply. - Terminology - Problem Statement — and where CIMD fits - Architecture Overview - Stateless Client Identity JWS as client id - Doorkeeper Integration — application class and by uid - Grant / Token Model, Custom Attributes, and Authorize-time Population - Coexistence with Classic OAuth — Type Dispatch - Lifecycle & Cleanup — the core problem - Active Session Modeling — a decoupled metadata record - Revocation — scope it; do not use the library-wide revoke all for - Security Considerations - Operational Considerations - Pitfalls / Landmines - Decision Log - Reusability Checklist — collaborators an adopter must supply - Future Work / Unverified Extensions - References DCR — Dynamic Client Registration RFC 7591 . A client registers at runtime to obtain its client id . CIMD — Client ID Metadata Document. An alternative where the client id is an HTTPS URL the authorization server fetches to obtain the client's metadata; no server-issued identity §2.1 . Ephemeral client — a one-time client. Each instance / connection may run its own DCR and produce a non-reused client id ; the count is unbounded. MCP clients behave this way. Stateless client identity — the client's identity is encoded in a self-contained, server-signed string a JWS , verified by signature rather than by a lookup; the server stores no client-registration row. An optional denylist extension, §16, adds a bounded post-verification lookup — a hybrid. — a stable per-registration subject identifier a UUIDv7 , embedded in the JWS and recorded client subject by value on each grant/token. It is the true client-isolation key §5 . derived id — an integer deterministically derived from client subject , used as the provider's application id surrogate. It is dynamic, non-recurring, and has no backing row. It is plumbing, not an isolation key. denylist — a small set of client subject s blocked at a gate after resolution; a bounded amount of state that recovers per-client revocation §16, unverified . call-time boundary — the resource server's check, on every request, that the presented token is acceptable not revoked, not expired, right audience, owner still a member . It is the real authorization gate; this document scopes itself to the provider side and treats the boundary as adopter-supplied §15 . SoT — Single Source of Truth.- Normative keywords MUST / MUST NOT / SHOULD / SHOULD NOT / MAY follow RFC 2119. A traditional OAuth provider assumes a bounded set of long-lived clients, registered by humans or a controlled process — so storing each client with a secret in an oauth applications table is reasonable. MCP and similar agent / native-app ecosystems breaks that assumption: Clients self-register via DCR , not human registration. Clients are often one-time : each desktop instance, reinstall, or even each connection may register anew. The count is unbounded — there is no natural cap. Public clients no secret — a native app cannot keep a secret, so it uses PKCE. Persisting an oauth applications row per DCR would grow an unbounded table of mostly-dead rows . That is the problem this design solves. Key insight the heart of this design :making theclientstateless solves unbounded growth of theclient table. Butgrants and tokens still persist, so the unbounded-growth problemmovesto the access-grant and access-token tables. Anyone adopting this patternMUSTtreat "grant/token reclamation" as a first-class design problem §8 , not an afterthought. A standards-track alternative is emerging. With CIMD , the client id is an HTTPS URL the authorization server fetches to read the client's metadata document — there is no server-issued identity at all, which sidesteps the unbounded-table problem differently. The 2025-11-25 MCP authorization revision elevated CIMD to SHOULD and demoted DCR to MAY , with a registration preference order: pre-registration → CIMD → DCR → ask the user. As of mid-2026, CIMD support across clients and servers is still low in practice , so DCR remains a pragmatic choice where CIMD is not yet viable. A robust provider SHOULD support DCR for those clients and SHOULD become CIMD-compatible accept a URL client id and fetch its metadata as adoption grows — the two coexist behind the same resolution dispatch §7 . The stateless JWS-as- client id pattern in this document is one way to implement DCR without an unbounded registry. It remains preferable to CIMD when there is no client-hosted metadata URL , when identities must be issued offline , or when the AS needs to control identity expiry and rotation itself . Where CIMD fits the deployment, prefer it; this pattern is for the DCR path. ┌────────────────────────────────────────────────────────────────┐ │ Layer Owner State? │ ├────────────────────────────────────────────────────────────────┤ │ Client identity JWS signed client id STATELESS none │ │ OAuth flow Doorkeeper authz code + PKCE — │ │ Credentials/SoT access tokens / access grants PERSISTED │ │ Session metadata side table last seen, name PERSISTED thin │ │ Resource server the call-time boundary adopter-supplied│ └────────────────────────────────────────────────────────────────┘ Normative division of responsibility: - The client-identity layer MUST write no per-client-registration row. A bounded denylist keyed only on revoked subjects §16 is permitted — it is not a registration table and does not grow with registrations. - Grants and tokens are the SoT for whether a call is authenticated. - The session-metadata layer holds only what a token cannot express display name, last-seen ; it is observational and MUST NOT be the authority that gates a call. - The resource server MUST complete its call-time boundary resolve the token to scope / tenant / audience / membership before any action runs. That boundary is the adopter's; this document specifies the provider side. The DCR endpoint accepts RFC 7591 metadata redirect uris , client name , scope , … , validates it , and issues a JWS as the client id , writing nothing to the database. The endpoint is unauthenticated, so two validations are non-negotiable before issuance: redirect uri validation per RFC 7591 / RFC 8252 §7 — accept loopback §7.3 , private-use scheme §7.1 , or claimed- https §7.2, the form RFC 8252 prefers ; reject non-loopback http , wildcards, and open-redirect-prone values. This is an existing DCR / native-app requirement, not a new one: skipping it issues a signed open-redirect that PKCE does not fully contain. rate limiting of the endpoint §11 . A recommended ClientIdentity collaborator adopter-supplied; see §15 . The metadata it embeds is the validated RFC 7591 subset this design consumes — the wire names client name , redirect uris , scope the resolved Identity 's requested scope is just the alias for scope . class ClientIdentity ISSUER = "https://issuer.example" this AS's signing-domain tag see note below LIFETIME = 90.days ALG = "ES256" Identity = Struct.new :subject, :client name, :redirect uris, :requested scope, keyword init: true issue → the JWS string that becomes the client id. metadata MUST already have its redirect uris validated RFC 7591 / 8252 §7 — see above. def self.issue metadata now = Time.current.to i payload = { iss: ISSUER, sub: SecureRandom.uuid v7, iat: now, exp: now + LIFETIME.to i, reg: metadata } JWT.encode payload, KeyStore.active private key, ALG, kid: KeyStore.active kid end resolve → an Identity, or nil when the JWS does not verify fail closed . Pure signature verification — NO database lookup. The optional denylist §16 is a separate gate run AFTER resolution, not here, so this stays stateless. def self.resolve client id payload, = JWT.decode client id.to s, nil, true, algorithm: ALG, iss: ISSUER, verify iss: true, verify expiration: true, required claims: %w iss sub exp , leeway: 30 do |header| KeyStore.verification key header "kid" unknown/retired kid → nil → verification fails end reg = payload "reg" || {} Identity.new subject: payload "sub" , client name: reg "client name" , redirect uris: Array reg "redirect uris" , requested scope: reg "scope" rescue JWT::DecodeError nil end end this JWS is an iss note:internalartifact, not an OAuth/OIDC token that leaves the AS's trust domain. Its iss is a private signing-domain tag,notthe OAuth issuer URL of RFC 8414/9207; it stillMUSTbe verified so the signature is bound to this AS's key namespace. The library shown is ruby-jwt ; treat the option names as illustrative and confirm against your JWT library. A presented client id is verified by signature resolve above : signature, iss , and exp with a small leeway for clock skew, §11 , and the required claims must be present. An unknown kid a retired key yields no verification key and fails. Any failed check MUST fail closed treated as "no such client" and MUST NOT leak which check failed. If the denylist extension §16 is enabled, its gate runs after this, also fail-closed. | Property | Mechanism | |---|---| | Survives restarts | Verification is by signature, not a lookup; a restart does not affect an existing client id | | No registration table | Registration writes no row | | Retirable | exp lapses → the client re-registers; rotating the signing key invalidates every client id it signed | | Retirement is not restart-triggered | Only expiry or key rotation retires an identity — both controllable | Adopters MUST NOTuse "restart" as a retirement mechanism, andMUST NOTtreat the JWS as a session or a credential. It is anidentity: it authenticatesnothingabout whoever presents it. Anyone holding a client id JWS can begin an authorization; access requires completing PKCE and user consent, so the JWS grants nothing on its own §11 . The credential is the access token. Enabling the denylist extension §16 deliberately trades a slice of "no lookup" for per-client revocability — a hybrid, chosen knowingly. The signing key is asymmetric ES256 . A recommended KeyStore collaborator: - Keep the active private key in a secret store env / secret manager , never in source. - The JWS header's kid is a fingerprint of the public key; verification key kid is a lookup in a small map of kid → public key . Planned rotation: hold both the outgoing and incoming keys in the map for a grace period ≥ the JWS LIFETIME for zero forced re-registration . Sign new identities with the incoming key while still verifying the outgoing one; drop the outgoing key only after the grace period. Emergency rotation key compromise deliberately collapses the grace period and forces all clients to re-register — see §4.5. Statelessness is a deliberate trade. The costs are real and MUST be weighed: No single-client revocation without the §16 extension . There is no per-client row, so there is no per-client off switch. A compromised or abusive client id can otherwise be retired only by waiting out its exp or rotating the signing key which retires everyone . The §16 denylist extension blocks future authorizations for a subject — but already-issued tokens stay valid until their own expiry, so it MUST be coupled with token revocation §10 , and revocation immediacy remains bounded by the token TTL. Key-rotation blast radius. Rotating the signing key invalidates every client id it signed. Planned rotation needs the multi- kid grace period §4.4 ; emergency rotation forces all clients to re-register at once. Identifier size. A signed JWS client id is ~300–500 bytes ES256, base64url . It travels in authorize URLs mind URL-length limits , redirects, and logs, and its client subject is recorded by value on every grant and token §6 — modest storage amplification. Anyone who can read those logs can also decode the JWS payload it is signed, not encrypted , so keep no sensitive data in reg . In particular client name embedded in reg is client-supplied and may carry user- or device-identifying text; since it rides in those same URLs and logs, treat it as possibly sensitive — evaluate per deployment, or resolve it out of band instead of embedding. Acceptable, but not free. This is the single bridge that lets a stateless client sit on Doorkeeper, and it is a supported extension point . config/initializers/doorkeeper.rb the config this design depends on application class "OauthApplication" force pkce public clients MUST use PKCE S256 grant flows %w authorization code default scopes :mcp custom access token attributes :workspace id, :audience, :client subject §6 access token expires in 2.hours see §8.1 / §12.2 on TTL The hook fires for BOTH the authorize and the token endpoints, so it MUST be guarded — record active session lives only on the authorize controller §6.2 . after successful authorization do |controller, ctx| controller.send :record active session if controller.respond to? :record active session, true end In config/routes.rb — NOT this initializer: controllers is a routes DSL method. use doorkeeper do controllers authorizations: "oauth/authorizations" the authorize-time hook §6.2 end class OauthApplication < ApplicationRecord include ::Doorkeeper::Orm::ActiveRecord::Mixins::Application Doorkeeper calls this to resolve a presented client id Doorkeeper::OAuth::Client.find / .authenticate . nil → "no such client" fail closed . def self.by uid uid identity = ClientIdentity.resolve uid verify the JWS, do not look up a row return unless identity virtual uid, identity end An in-memory record marked "persisted but never saved". def self.virtual uid, identity instantiate "id" = derived id identity.subject , stable integer surrogate plumbing, not isolation "uid" = uid, "name" = identity.client name.presence || "MCP Client", "redirect uri" = identity.redirect uris.join "\n" , "scopes" = identity.requested scope.presence || Doorkeeper.config.default scopes.to s, "confidential" = false, public client "secret" = nil end client subject UUID → a stable positive bigint for Doorkeeper's integer application id. Mask to 63 bits so it always fits a signed bigint and stays non-negative. def self.derived id subject OpenSSL::Digest::SHA256.digest subject.to s .unpack1 "Q " & 0x7FFF FFFF FFFF FFFF end end Normative points: instantiate marks the object not a new record it relies on ActiveRecord::Persistence.instantiate setting @new record = false , so assigning it to a grant/token sets only the foreign key and does not autosave autosave fires only for new records . Adopters MUST use instantiate , not new . This leans on an ActiveRecord behavior; re-verify across Rails versions, not only Doorkeeper versions, and include the model's NOT-NULL columns in the hash. derived id MUST be a deterministic function of client subject landing in a positive bigint. Doorkeeper compares grant.application id == client.id integer comparison across the authorize and token requests, so the surrogate must be stable and non-nil. On the surrogate is a 63-bit hash, so two distinct derived id collisions: client subject s can in principle collide the birthday bound applies to the distinct client subject s carried by all un-cleaned grants/tokens at once , not just "live" registrations — negligible at realistic scale, but not zero . Two defenses, with different reach:- At the token exchange , a collision is non-exploitable: the PKCE code verifier is bound to the specific authorization, so a colliding client cannot redeem another's code. PKCE covers only the exchange. - Everywhere else — revocation, segmentation, session identity — never use derived id as a key; PKCE does not protect those. Key them on client subject , the true isolation key §8.5, §10, §9, Pitfalls 4/ 15 . - At the Verified against Doorkeeper 5.9.1:the authorization-code→token exchange validates the grant with grant.application id == client.id integer comparison, authorization code request.rb ; it doesnotdereference the application row. The core handshake is therefore correct with no application row present. Doorkeeper flows custom attributes from the grant onto the token it slices grant.attributes by custom access token attributes at issuance . Under that mechanism, adopters MUST add a database column for each on both the grant and token tables the slice reads from the grant . | Attribute | Purpose | Why by value | |---|---|---| audience | RFC 8707 audience binding; the token is valid only for this server | security invariant | workspace id / tenant key | the tenant the token is bound to | resolve the tenant at call time | client subject | which client = the JWS sub | the server keeps no client registry; this is the isolation key, recorded by value | Normative:any dimension you will later use to identify a client / revoke / list sessionsMUSTbe recorded by value on the token; youMUST NOTrely on resolving it through application id dynamic noise with no backing row . Custom attributes reach the token only if they are first set on the grant during authorization. Subclass the provider's authorization controller and set them in a before action : class Oauth::AuthorizationsController < Doorkeeper::AuthorizationsController before action :bind audience, :resolve tenant, :record client subject, only: %i new create private current resource owner — Doorkeeper-provided: the signed-in member. Honor the client's RFC 8707 resource , then set the audience to the validated resource; fall back to the canonical value only when none was sent. def bind audience resource = validate requested resource params :resource → the validated resource, or renders invalid target params :audience = resource || CANONICAL AUDIENCE CANONICAL AUDIENCE: this server's RFC 9728 resource id end → a tenant id the owner may authorize for, validated against its memberships; renders invalid target on a tenant the owner cannot authorize never raw from input . def resolve tenant params :workspace id = authorized tenant id for current resource owner, params end Fail-secure: trust only the verified JWS subject, overwriting any supplied value. def record client subject params :client subject = ClientIdentity.resolve params :client id &.subject end Invoked from the guarded after successful authorization hook §5 , which fires for both the authorize and token endpoints — the guard ensures this runs only here. def record active session identity = ClientIdentity.resolve params :client id client id is present on the authorize request McpSession.authorize tenant: Tenant.find params :workspace id , user: current resource owner, client subject: params :client subject , already set, fail-secure, by the before action client name: identity&.client name, expires at: Time.current + Doorkeeper.config.access token expires in end end How do theseDoorkeeper's params reach the grant? PreAuthorization reads them from the request params and slices them by custom access token attributes onto the grant when it is created; at token exchange the same slice copies them to the token. So setting them in a before action — which runs before the new / create action builds the pre-authorization — lands them on the grant. Verified against Doorkeeper 5.9.1. Helper contracts the adopter supplies: validate requested resource resource → the resource when it names this server RFC 8707 §2 / RFC 9728 id , else renders invalid target ; authorized tenant id for owner, params → a tenant id the owner may authorize for, else renders invalid target ; CANONICAL AUDIENCE → this server's canonical resource identifier the value it publishes via RFC 9728 . If one provider must serve both "classic persisted OAuth clients" and "stateless DCR clients" and, later, CIMD URL clients , they do not conflict in Doorkeeper's core; they conflict in your customization layer , which collapses to a single discriminator question. | Seam | How to coexist | |---|---| by uid resolution | super uid | | Authorize endpoint | The DCR-specific invariants audience binding, tenant binding, session recording MUST activate only on the DCR branch, and SHOULD live in a concern loaded only there, so they cannot leak onto classic OAuth | | Global config | default scopes , grant flows , TTLs are global switches. Per-context-adjustable ones custom access token expires in , per-request scope SHOULD be dispatched in a block | | Resource servers | Each endpoint guards itself; naturally no conflict. If a token-introspection endpoint RFC 7662 is exposed, it MUST answer consistently for both client types — return client subject not the raw JWS as the client id, and align active with the call-time boundary, not the decoupled session view. Introspection necessarily reads the credential tables; the decoupled session's query savings §9.2 apply only to the session list, not to introspection | Anti-pattern:writing the DCR-specific audience/tenant invariants asunconditionalbefore-actions hijacks every authorization and blocks classic clients. TheyMUSTbe conditional on the resolved type. Do notstand up two Doorkeeper providers to coexist one dispatching by uid serves all . Donotmake DCR clients persisted again to coexist — one-time clients explode the client table, which is the whole reason for statelessness. - Each authorization → one grant short TTL, typically 10 minutes; revoked at token exchange . - Each token issuance → one token row. - Without refresh tokens, an expired token requires re-running the full authorization flow which needs user consent , so DCR token TTLs are often set long days/weeks . This is a UX-vs-security trade — see §11 and §12.2. It assumes human-in-the-loop consent ; if a host can complete consent non-interactively, the long-TTL-for-UX rationale collapses — prefer short TTL with automated re-consent, which also shrinks the leak window. Doorkeeper's own StaleRecordsCleaner exposed via rake doorkeeper:db:cleanup runs queries shaped, conceptually , like: clean revoked : where.not revoked at: nil .where revoked at < now .in batches &:delete all clean expired : where.not expires in: nil .where created at < now - ttl .where <adapter-specific expiration SQL < now .in batches &:delete all Verified fact Doorkeeper 5.9.1 :both queries keyonlyon revoked at / created at + expires in — theynevertouch application id . Consequences: - The dynamic, non-recurring application id §5 has no effect on cleanup — cleanup deletes each row by its own time/revocation state and never needs to know which client it belonged to. - Adopters MUST clean up by time + revocation only. A dependent: :delete all cascade from the application would never help here anyway there is no application row to cascade from , so it plays no part. application id is not a usable discriminator for cleanup or segmentation per-registration noise with no backing row ; use audience / client subject instead §8.5 .- The oauth applications table stays empty; there is nothing to clean there. A row escapes both queries only when revoked at IS NULL and expires in IS NULL an "immortal" row . Normative:under this reclamation model, adoptersMUST NOTissue non-expiring tokens expires in always set . With that held, every row is eventually reclaimed: revoked rows by clean revoked prompt, TTL-independent , naturally expired rows by clean expired after their TTL .No immortal rows, no unreachable rows. This boundsstorage; it does not bound a leaked token's validity window — see §11. Wrap the native cleaner so the logic is a class method reproducible in any environment console, test, rake — not only where the schedule runs — and schedule it as a job: class OauthCredentialCleanupJob < ApplicationJob queue as :default def self.cleanup tokens = Doorkeeper.config.access token model grants = Doorkeeper.config.access grant model Doorkeeper::StaleRecordsCleaner.new tokens.where refresh token: nil .clean expired Doorkeeper.config.access token expires in Doorkeeper::StaleRecordsCleaner.new tokens .clean revoked Doorkeeper::StaleRecordsCleaner.new grants .clean expired Doorkeeper.config.authorization code expires in Doorkeeper::StaleRecordsCleaner.new grants .clean revoked end def perform = self.class.cleanup end config/recurring.yml Solid Queue production: oauth credential cleanup: class: OauthCredentialCleanupJob schedule: every hour Two cadences, not one. clean revoked SHOULD run frequently e.g. hourly regardless of TTL, so a revocation is reflected in storage promptly; clean expired only needs to keep pace with the TTL. Do not collapse both into a single "run every TTL" schedule — under a long TTL that would let revoked rows pile up. A single hourly job calling all four steps satisfies both.- SQLite is supported by the native cleaner's adapter-specific expiration SQL; other adapters not in the support table degrade to the coarse created at filter with a warning — provide a custom expiration time sql there. Refresh-token caveat: clean expired skips rows with a non-null refresh token they may be refreshed . If you enable refresh tokens §12.2 , those rows are reclaimed only by clean revoked or refresh-token rotation — design that lifecycle explicitly before turning refresh on. This document's cleanup model assumes no refresh tokens. Single TTL DCR-only : the native cleanup as scheduled is sufficient. Mixed TTL long DCR + short classic OAuth : clean expired 's coarse filter created at < now - globalTTL is keyed to a single global TTL. If the global is the longest value, short-TTL tokens linger until that window. Run a segmented cleanup : StaleRecordsCleaner accepts any relation + an explicit ttl, so segment by audience or scope and pass each segment's TTL. If a segment uses a longer custom access token expires in , the global access token expires in MUST be ≥ the largest segment TTL, or the coarse filter under-collects. Requirement: show "which clients a member authorized, when each was last seen, and whether each is still live." An Active Session is closer to a client than to a token : one authorization aggregates many rotating tokens, so the session persists across token rotation and is not 1:1 with a token . Model it as a decoupled metadata record , keyed by tenant, member, client subject , holding its own validity window plus the observational fields a token cannot express. A recommended shape adopter-supplied : Table: tenant id, user id, client subject unique together , client name, expires at, last seen at, timestamps class McpSession < ApplicationRecord RECENCY = 1.hour deployment-set display window scope :active, - { where last seen at: RECENCY.ago.. } shown vs hidden Born at consent; the validity window is advanced on each re-authorization. def self.authorize tenant:, user:, client subject:, client name:, expires at: find or initialize by tenant id: tenant.id, user id: user.id, client subject: client subject .update client name: client name, expires at: expires at = now + access token expires in end Observed on each authenticated call, throttled to a minute do not write the auth-hot path hard . def self.touch seen tenant:, user id:, client subject: rec = find by tenant id: tenant.id, user id: user id, client subject: client subject return if rec.nil? || rec.last seen at && rec.last seen at 1.minute.ago rec.update column :last seen at, Time.current end Held vs discarded — its own lifecycle, independent of token cleanup. def self.prune expired = where expires at: ..Time.current .delete all end Display and retention are two orthogonal filters: shown vs hidden = last seen at within the recency window; held vs discarded = the session's own expires at passed. You could instead define active = EXISTS a non-revoked, unexpired token for tenant, member, client subject . That existence query is the same shape as the scoped-revoke scan §10 and needs no extra index either — so "avoiding an index" is not a real reason to prefer one over the other. The honest trade-off is: | Option | Benefit | Cost | |---|---|---| Decoupled | the session is a client-level record that persists across token rotation; the list renders without touching the credential tables | brief staleness after a revoke the record ages out by its own expiry / recency | | Token-projected | the list is exact at all times | a credential-table existence query on every render, and coupling a client-level view to token-level rows | The choice turns on one observable property: does the list offer a per-row revoke action? Display-only list no per-row revoke → decoupled is the right default. The list is observational; the real gate is the call-time boundary, which rejects a revoked/expired token regardless of what the list shows; brief staleness is harmless. A new token under the same authorization keeps the session legitimately live, which last-seen recency reflects exactly. List drives revocation a per-row revoke control → decoupled is the wrong default. An operator acting on a stale row could revoke the wrong thing, or see a just-revoked client still shown as live. There the session MUST reflect true credential state — either project liveness from tokens, or revoke-and-remove the session record in one step so the action the operator just took is visibly reflected . Evaluate this against your roadmap, not only today's UI: if a per-row revoke action is planned §16 , adopt the revoke-synced shape now — decoupled-vs-projected is a schema decision costly to reverse later. Prefer decoupled where it applies the common display-only case because the session is conceptually a client that persists across token rotation, and the list renders without touching the credential tables. - The session's prune expired by its own expiry is independent of token cleanup — two independent entities, two reclamations. Intentional, not a smell. - Member-removal revocation §10 acts on tokens. For a display-only list the session record simply ages out; for a revocation-driving list, remove/expire the session record at revocation time §9.2 . When access must be cut off member removal now; per-client "end session" via §16 , the credential must actually stop working, not merely disappear from a list. Verified fact Doorkeeper 5.9.1 :the built-in revoke all for application id, resource owner keys only on application id, resource owner — it hasno tenant filter. Because one stateless client client subject → one derived id can be authorized in multiple tenants by the same user, revoke all for would over-revoke across tenants in a multi-tenant deployment. Normative: - In a multi-tenant deployment, revocation MUST be scoped to the full granularity it targets and MUST NOT use revoke all for . In a strictly single-tenant deployment the over-revoke risk does not arise; revoke all for is then acceptable. Member removal scopes by tenant id, resource owner id ; a per-client "end session" adds client subject . - Revocation MUST act on both tokens and any unredeemed grants an in-flight grant could otherwise be exchanged into a token after revocation — a race window . Per-token revocation revoking a single token by its id is cheap and needs no client registry; expose it together with an enumeration entry §11/§15 so a leaked token can actually be located and killed without waiting out a long TTL. On member removal: revoke that member's credentials for this tenant, scoped. def revoke member credentials user id now = Time.current.utc Doorkeeper::AccessToken, Doorkeeper::AccessGrant .each do |model| model.where resource owner id: user id, workspace id: id, revoked at: nil .update all revoked at: now end end - After revocation the token is immediately inactive the call-time boundary checks revoked at , and the scheduled cleaner's clean revoked reclaims the row — a closed loop: revoke → reclaim . - Member removal SHOULD combine active revocation above with the call-time membership re-check as defense in depth : even if a revoke is missed, the boundary still denies a removed member. Audience binding RFC 8707 . RFC 8707 is client-driven : the client sends one or more resource parameters, and the AS applies an audience restriction. The verifiable invariant: a provider MUST NOT unconditionally overwrite a validly-sent resource . Validate each resource against the set the resource-owner is authorized to mint tokens for — not merely "names this server" : a server exposing several resource variants must not let a client bind a token to a variant outside the owner's grant the same authorization check resolve tenant already applies to the tenant . Set the token's audience to the validated resource s , falling back to the canonical value only when none is sent a single-audience deployment collapses to it , and handle multiple resource values explicitly rather than silently keeping one. The audience is expressed on the token RFC 7519 aud / RFC 7662 and MUST be compared at the call-time boundary. DCR redirect uri validation. The DCR endpoint is unauthenticated; it MUST validate redirect uris at registration per RFC 7591 / RFC 8252 §7 loopback or private-use scheme; reject non-loopback http , wildcards before issuing a client id . Skipping this issues a signed open-redirect that PKCE does not fully contain. client subject fail-secure. MUST trust only the sub from the verified JWS; a same-named value in the request MUST be overwritten §6.2 . JWS is not a credential. The client id JWS appears in authorize URLs and logs and is not a secret. It authenticates nothing about the presenter; security comes from PKCE possession + audience + user consent . Do not treat JWS validity as an access-control lever or replay defense. Its payload is signed, not encrypted — readable by anyone with the log. PKCE. A stateless client is public no secret , so the provider MUST force pkce with S256 RFC 7636 / RFC 8252 . PKCE is also what makes a derived id collision non-exploitable at the token exchange §5 — but only there. DCR endpoint abuse / DoS. Statelessness stops the client table from growing, but each issued client id can drive authorizations that create grant/token rows — so the DoS surface moves to those tables. Rate-limit the DCR/authorize/token endpoints Rails 8 ships rate limit ; Doorkeeper supports throttling — neither is on by default . Note the DCR endpoint has no stable client identity to limit by, so it can only be limited coarsely per-IP/global , which an attacker can evade by rotating IPs; the real defense for grant/token DoS is the tight cleanup schedule §8.4 plus a bounded token TTL. Token leak window vs long TTL. With long TTLs and no refresh, a leaked bearer token stays valid for that TTL, and member-removal / membership-recheck do not help if the member is still valid. To kill a leaked token you must first find it: the decoupled session §9 is client-level and carries no token id, so provide an admin entry that enumerates a member's live tokens by cheap, no registry . Provide that, or prefer short access tokens + refresh rotation OAuth 2.0 Security BCP — long TTL with neither leaves a multi-week leak window. tenant, owner, client subject and revokes by id Member removal is immediate. Removal MUST revoke the member's credentials §10 , and the boundary SHOULD independently re-check membership. Tenant is a selector, not a source. A tenant named in the request MUST only be matched against the token's tenant, never used as its source. Fail closed. Any failed boundary check MUST collapse to one unauthenticated outcome, not leaking whether a resource exists. A denylist §16 lookup failure MUST also fail closed. Clock skew. Cleanup and exp / expires in checks compare against wall-clock time. In a multi-node deployment a cleaner whose clock runs fast can delete a token slightly before its real expiry, and verifiers can disagree on validity. Keep nodes on NTP, allow a small leeway on exp verification §4.1 , and centralize the comparison on a single clock source e.g. the database's now via the provider's expiration SQL . Note this centralizes , not eliminates, skew — and a per-node non-shared SQLite deployment does not get this benefit; there, let a single node own expiry decisions and give verifiers adequate leeway . Key rotation. Rotating the signing key retires every client id ; use the multi- kid grace period §4.4 for planned rotation. Audit a named compensating control . Discarding the client table also discards the natural registration history — so the only trace of who registered when is the audit log. Security-relevant events DCR registration, authorization, revocation, member removal SHOULD be logged; for a design that deliberately keeps no client registry, registration audit is the compensating control for after-the-fact investigation, not an optional nicety. - Adopters SHOULD NOT add or remove indexes on, or migrate, the OAuth provider's own tables for their feature's query patterns. Adding columns through the provider's own custom access token attributes mechanism is supported the provider knows about them ; reaching in to re-index the provider's tables for your access pattern fights the library across upgrades. - You will not need such an index: scoped revocation §10 filters by resource owner id already indexed by the provider plus the tenant key — a tiny scan within one owner's rows, run rarely; and the decoupled Active Session §9 does not query the credential tables at all. This is a "you won't need it" observation, not the reason the session is decoupled — that reason is in §9.2. - The provider's default application id index becomes high-cardinality and unused under this design every registration is a distinct id , but it is harmless write overhead bounded by live rows. Leaving it respects the provider's schema ownership. - With no refresh and human-in-the-loop re-authorization, token TTL SHOULD be set long to avoid frequent consent — but weigh the leak window §11 : pair a long TTL with per-token revocation §10 , or prefer enabling refresh tokens with a designed cleanup lifecycle, §8.4 where the blast radius matters. - When using a per-segment custom access token expires in , the global TTL MUST be ≥ the largest segment TTL §8.5 . Verified fact Doorkeeper 5.9.1 : revoke previous authorization code token calls revoke previous tokens grant.application, ... → application.id with no safe-navigation; under stateless identity grant.application loaded by the application id association, which has no backing row is nil → nil.id → NoMethodError. revoke previous authorization code token and revoke previous client credentials token MUST NOT be enabled until the nil-application path is handled return a virtual application for the grant.application association, or guard the nil . reuse access token is not in the same crash class: its matching reads application&.scopes safe-navigated and, in the authorization-code flow, the client is the virtual app non-nil . It still involves the application object, so verify before enabling — but it does not crash on a nil application the way revoke previous does. Verdict: leave it off — this design needs no token reuse, and enabling it only adds matching over the virtual app to re-verify for no benefit. | | Pitfall | Consequence | Rule | |---|---|---|---| | 1 | Persist one-time clients | client table grows unbounded | use a stateless JWS or CIMD | | 2 | Assume statelessness removes unbounded growth | grant/token tables grow instead | treat cleanup as first-class | | 3 | Expect an application cascade to clean up | no application row → it cannot help | clean by time/revocation | | 4 | Use application id as a cleanup/revoke/segment key | dynamic noise; collision mis-targets | use audience / client subject | | 5 | Issue non-expiring tokens this model | immortal rows | expires in always set | | 6 | One "every TTL" cleanup cadence | revoked rows pile up under long TTL | run clean revoked frequently; clean expired per TTL | | 7 | Single global coarse filter under mixed TTL | short-TTL tokens linger | segmented StaleRecordsCleaner | | 8 | Decoupled session for a list that drives revocation | operator acts on a stale/just-revoked row | decoupled only for display-only lists; project or revoke-sync when a per-row revoke action exists | | 9 | Revoke with library-wide revoke all for multi-tenant | cross-tenant over-revoke | scope by tenant, owner , client subject | | 10 | Revoke tokens but not grants | in-flight grant race | revoke both | | 11 | DCR invariants as unconditional before-actions | hijacks classic OAuth authorization | conditional on resolved type | | 12 | Enable revoke previous | dereference nil application → crash | handle the virtual application first | | 13 | Build the virtual app with new instead of instantiate | autosaves an application row | use instantiate | | 14 | Leave the DCR endpoint unthrottled / its redirect uris unvalidated | grant/token DoS; signed open-redirect | rate-limit; validate redirect uris RFC 8252 §7 before issuing | | 15 | derived id treated as the isolation key | collision → wrong-client confusion | client subject is the isolation key; PKCE backstops only the exchange | | 16 | Unconditionally overwrite the client's resource | breaks RFC 8707 client-driven audience | set audience to the validated resource; canonical is fallback | | Decision | Trade-off | Conclusion | |---|---|---| | Persisted client vs stateless JWS | one-time clients explode the table | stateless hard requirement for DCR | | DCR vs CIMD | CIMD is now SHOULD low support today ; DCR is MAY | DCR where CIMD isn't viable; become CIMD-compatible as it lands §2.1 | | Signing algorithm | symmetric vs asymmetric | ES256 asymmetric, ships with Ruby's OpenSSL | application id surrogate | nil breaks validate grant 's integer compare | non-nil per-registration derived id, masked to a positive 63-bit integer; client subject by value is the true isolation key | | Custom prune vs the library's native cleaner | the native StaleRecordsCleaner already covers it and supports SQLite | native cleaner, wrapped in a scheduled job/class method | | Token-derived session vs decoupled session | projection is exact but couples client-level to token-level; decoupled is simpler but briefly stale | decoupled for display-only lists; project or revoke-sync when the list drives revocation | revoke all for vs scoped revoke | the built-in lacks a tenant filter | scoped by tenant, owner in multi-tenant; revoke all for acceptable only single-tenant | | Touch the provider's schema vs leave it | re-indexing the provider's tables is intrusive and unnecessary | leave the provider's schema alone | | Per-client revocation | full statelessness gives it up | optional denylist + per-token revoke extension §16 — a deliberate bounded-state hybrid, unverified | This document specifies the provider-side design; an adopter MUST supply these collaborators to reach an equivalent mechanism: - — ClientIdentity issue metadata → JWS , resolve client id → Identity|nil pure verify, no lookup §4.1 . Identity exposes subject / client name / redirect uris / requested scope . - DCR registration validation — validate redirect uris RFC 7591 / 8252 §7 and rate-limit the endpoint before issue §4.1, §11 . - — KeyStore active private key , active kid , verification key kid ; keys from a secret store; multi- kid rotation grace period §4.4 . - — returns an OauthApplication.by uid instantiate d virtual app; derived id deterministic, a positive 63-bit integer §5 . - The authorize-time hook — bind audience honor + validate resource , canonical fallback , resolve tenant , record client subject verified JWS , record active session ; helper contracts per §6.2. - Custom-attribute columns on both grant and token tables + custom access token attributes §6.1 . - The Active Session record — table + authorize / touch seen / prune expired / active scope; decoupled for display-only, projected/revoke-synced if it drives revocation §9 . - The call-time boundary resource-server side — token acceptable + audience + tenant + membership, fail closed §3, §11 . - Cleanup — a scheduled job wrapping the native cleaner revoked + expired, tokens and grants ; expires in never nil; clean revoked frequent, clean expired per TTL §8.4 . - Revocation — scoped by tenant, owner , tokens and grants; never revoke all for in multi-tenant §10 . - Token enumeration + revoke entry — list a member's un-revoked tokens by tenant, owner, client subject and revoke by id, so a leaked token can be killed without waiting out the TTL §11 . - Rate limiting — on DCR/authorize/token endpoints not on by default §11 . - Audit log — DCR registration / authorization / revocation events §11 . - Config initializer : force pkce S256 , single grant flows , application class , guarded after successful authorization §5 . Routes: use doorkeeper { controllers authorizations: "oauth/authorizations" } the controllers DSL belongs in routes, not the initializer . - Mixed TTL → segmented StaleRecordsCleaner , discriminator = audience; global TTL ≥ the largest segment §8.5 . - revoke previous left off unless the nil-application path is handled §12.3 . - If using the denylist §16 : consult it as a gate after resolution not inside resolve , fail closed, couple it with per-token/scoped revocation. The following are design sketches, NOT implemented or validated. Treat them as direction, not normative guidance. Per-client identity revocation a bounded-state security extension . Full statelessness gives up the single-client off switch §4.5 . Reintroduce a bounded amount of state — a small— as a deliberate hybrid stateless-core identity + a bounded denylist : client subject denylist- Consult the denylist as a gate after signature verification not inside resolve , which stays a pure verify ; a denied subject is treated as no client. - The lookup MUST fail closed a denylist-store failure denies; it does not open . Couple it with token revocation. The denylist blocks future authorizations for a subject; already-issued tokens are killed only by revoking them by tenant, user, client subject §10 . Neither alone suffices.- A denylist entry must live at least max client id exp, longest token TTL , then be reclaimed by its own TTL-based GC — fold that into the §8 reclamation story so the hybrid's state stays genuinely bounded §8.3's closure does not otherwise cover it . - Driving it from the Active Session record revoking a session revokes its tokens and denylists its subject is one natural shape — and it is what a per-row revoke action in a session list §9.2 would call. Unimplemented and unverified here; validate growth, expiry, and read-path cost before adoption. - Consult the denylist as a CIMD compatibility §2.1 . Accept an HTTPS-URL client id alongside JWS client ids, fetching the client's metadata document, as CIMD adoption grows. The resolution dispatch §7 is the natural seam. Token introspection RFC 7662 . If exposed, answer consistently across client types — return client subject as the client id and align active with the call-time boundary, not the session view §7 . - RFC 6749 — The OAuth 2.0 Authorization Framework - RFC 7591 — OAuth 2.0 Dynamic Client Registration Protocol - RFC 7636 — Proof Key for Code Exchange PKCE - RFC 7662 — OAuth 2.0 Token Introspection - RFC 8252 — OAuth 2.0 for Native Apps redirect uri rules, §7 - RFC 8414 — OAuth 2.0 Authorization Server Metadata AS discovery - RFC 8707 — Resource Indicators for OAuth 2.0 - RFC 9728 — OAuth 2.0 Protected Resource Metadata the canonical resource identifier / audience - RFC 2119 — Key words for use in RFCs - OAuth 2.0 Security Best Current Practice short-lived access tokens, refresh rotation - Model Context Protocol — Authorization 2025-11-25 revision; DCR → MAY, CIMD direction - Doorkeeper 5.9.x — application class / by uid , custom access token attributes , custom access token expires in , StaleRecordsCleaner , rake doorkeeper:db:cleanup - Solid Queue — recurring tasks config/recurring.yml "Verified fact" notes were checked against Doorkeeper 5.9.1 source and SQLite behavior; the instantiate no-autosave behavior is an ActiveRecord property — re-verify the relevant sections against your Doorkeeper and Rails versions and your database adapter before relying on them. JWT option names follow ruby-jwt; confirm against your library.