OAuth Resource Enforcement#

OAuth Resource Enforcement is the per-client access control layer in Better Auth's OAuth provider, introduced in PR #9648. It replaces the previous flat validAudiences list with a persistent entity-based system that models each protected resource explicitly and enforces which OAuth clients are authorized to access it.

The system has two interlocking parts:

• oauthResource — a first-class database entity representing a protected resource server (e.g., https://api.example.com), carrying per-resource token policy (TTLs, scope allowlists, signing config, custom claims).
• oauthClientResource — a join table that links specific clients to specific resources, enabling per-client entitlement checks at token issuance.

The enforcePerClientResources flag determines whether the linkage table is consulted: when true (the default), every client must be explicitly linked to a resource before it can request tokens for it; when false, all enabled resources are implicitly available to any client 1.

Data Model#

oauthResource Table#

Defined in packages/oauth-provider/src/schema.ts, each row represents a protected resource server with the following key fields:

oauthClientResource Join Table#

Defined in packages/oauth-provider/src/schema.ts, this table links clients to resources. Composite uniqueness of (clientId, resourceId) is enforced by using a deterministic primary key: the row id is set to ${clientId}::${resourceId} at write time, making duplicate inserts a no-op against the PK constraint 1.

Known issue (v1.7.0-rc.2): When advanced.database.generateId: "uuid" is configured, the core UUID transformer rejects the composite string ID and substitutes a random UUID instead. This breaks the PK-based uniqueness mechanism, leaving no compound unique constraint on (clientId, resourceId). See issue #10531 for details and possible fixes.

enforcePerClientResources Flag#

Configured on the oauthProvider plugin, this flag defaults to true — the secure-by-default posture per RFC 8707 §3. The resolved value is logged at plugin initialization so operators can confirm which default applies .

Resource Policy Resolution Pipeline#

When a client includes an RFC 8707 resource parameter in a token or authorization request, resolveResourcePolicy() in resources.ts executes these steps in order:

1. Resolve resource parameter to a list of identifiers
2. Look up oauthResource rows — missing or disabled resources → invalid_target error
3. Per-client linkage check — if enforcePerClientResources is true, verify each resource is linked to the requesting client via oauthClientResource
4. Intersect requested scopes with each resource's allowedScopes (narrowing only, never widening)
5. Pick the shortest accessTokenTtl and refreshTokenTtl across all requested resources
6. Validate signing config compatibility — conflicting signingAlgorithm or signingKeyId across resources raises invalid_request
7. Merge per-resource customClaims, stripping RFC 9068 reserved claim names

Client-Resource Linking#

Admin Endpoints#

The oauthResource/endpoints.ts exposes two admin-only endpoints for managing linkage:

• POST /admin/oauth2/resources/:identifier/clients/:client_id — Links a client to a resource. The insert is idempotent: a duplicate write (detected via UNIQUE PK conflict) returns { linked: true, alreadyLinked: true } rather than an error .
• DELETE /admin/oauth2/resources/:identifier/clients/:client_id — Unlinks a client from a resource. Idempotent — no error if the link doesn't exist .

Both endpoints respect the resourcePrivileges RBAC callback configured on the plugin, gating access with the "link" and "unlink" actions respectively.

Dynamic Client Registration (DCR)#

Clients can declare resources at registration time via RFC 7591 §2 extension 1:

{
  "client_name": "my-client",
  "redirect_uris": ["https://client.example.com/callback"],
  "resources": ["https://api.example.com"]
}

Resources are validated (must exist and not be disabled) before client creation. Client-resource links are created transactionally with client creation — no half-created state is possible. Duplicate entries in the resources array result in exactly one oauthClientResource row.

Resource Seeding#

The plugin's resources option seeds oauthResource rows at boot. Behavior is controlled by resourceSeedMode :

Key Files#