Clients & Access
A client is anything that requests tokens — a web app, a mobile app, a backend service, or an AI agent. PBAC controls what each client can access through a layered model: registration establishes identity, software statements declare capabilities, and policy decides what's actually granted.
Clients
A client is an OAuth 2.0 client registered with the AS. Every token request comes from a client.
| Property | Purpose |
|---|---|
client_id | Unique identifier |
client_type | CONFIDENTIAL (can hold secrets) or PUBLIC (cannot — SPAs, mobile apps) |
client_secret | Authentication credential (confidential clients only) |
redirect_uris | Allowed redirect targets for authorization code flows |
token_endpoint_auth_method | How the client authenticates: client_secret_basic, client_secret_post, private_key_jwt |
dpop_bound_access_tokens | Whether tokens are sender-constrained via DPoP |
software_statement | Claims from the client's software statement (the capability model) |
Clients are created through one of four registration methods:
| Method | Trust source | When to use |
|---|---|---|
| Admin API | Operator creates directly | Setup, test clients, operator-managed |
| Software-statement DCR | Signed JWT from a trusted issuer | Federated ecosystems, self-service |
| Plain DCR | Public client policy data | Self-registration without a statement |
| CIMD | Metadata document fetched from URL | Zero-config MCP clients, AI agents |
Software statements
A software statement is a signed JWT that describes what a client is and what it should be able to do. It's the trust mechanism that scales PBAC beyond manually provisioned clients.
When a client registers with a software statement, the AS parses it and stores its claims. At every subsequent token and introspect request, those claims are available to OPA as input.context.client.software_statement. Policy rules evaluate these claims to decide what resources and scopes the client can access.
Software statement claims typically include the client's software_id, granted_resources (what resource types and scopes it claims), and any domain-specific attributes. OPA can override, restrict, or extend these claims via entitlement policies.
The resource model
PBAC models what you're protecting as a hierarchy of types, servers, and instances:
Resource Type — category of data (e.g., Patient Record, Account)
└── Resource Server — API that hosts it (e.g., https://api.example.com/fhir)
└── Resource — specific instance (e.g., patient/123)
└── Scopes — actions (read, write, delete)
Resource types
A resource type defines a category of data and the actions (scopes) that can be taken on it. Types can be hierarchical — a parent type can have child types that inherit its scopes.
Token requests are scoped to resource types. When a client requests resource_type=urn:example:Patient with scope=read, OPA evaluates whether that client is entitled to that type+scope combination.
Resource servers
A resource server (RS) is an API endpoint that hosts resources and validates tokens via /introspect. Each RS is linked to a client record (the RS authenticates as a client when calling introspect) and has a resource_indicator URI that clients use in token requests.
Resources
A resource is a specific instance of a resource type, hosted on a resource server. Resources can have an owner subject — enabling owner-based access rules. At introspect time, the RS identifies the specific resource and action, and OPA evaluates whether the token's permissions cover that specific instance.
Scopes
Scopes define the actions available on a resource type. They're linked to both resource types (defining what actions exist) and individual resources (restricting which actions are available on a specific instance). When OPA evaluates a token request, it intersects the requested scopes with what the client's entitlements allow.
Entitlements
Entitlements are policy data overrides that modify what clients can access. They operate at two levels:
- By
client_id— override entitlements for a specific client - By
software_id— override entitlements for all clients from a software family
This lets you restrict a partner's access after a policy change (read only instead of read+write), grant temporary elevated access, or enforce different rules for different deployments of the same software — all without re-registering clients or modifying Rego rules.
How it connects
At every evaluation, OPA sees the client's identity, its software statement claims, any entitlement overrides, and the requested resource. The client doesn't need to know about entitlements or policy rules — it just requests tokens and presents them. The policy plane handles the rest.
Next steps
- Policy Model — How policy rules evaluate client requests
- Token Lifecycle — What happens after registration