Realms, Scopes, and Permissions

This document describes the access control design for the Arda Platform, including HTTP security realms, OAuth2 scope hierarchy, user roles, and tenant-based data scoping.

Key Definitions

Term	Definition
Realm	A named set of protected HTTP resources defined statically at design time. Access decisions are RBAC-based (role checked against realm definition).
Authenticator	A mechanism to authenticate a request: Bearer Token, JWT, OAuth2, etc.
OAuth2 Scope	A named permission encoded into the JWT access token, controlling what API endpoints and operations a client is authorized to use.
Application Scope	A dynamic set of data resources restricted to authorized users; defined at runtime. Access decisions are ABAC-based (user attributes matched against resource attributes).
RBAC	Role-Based Access Control: access decisions based on the user’s role against statically defined realm/class values.
ABAC	Attribute-Based Access Control: access decisions based on dynamic attributes of both the user and the specific resource. Tenant scoping is ABAC.

HTTP Security Realms (MVP0)

Four realms are defined for the initial implementation. Access is determined by the custom:role claim in the user’s JWT:

Realm	Access
PUBLIC	Any request, including unauthenticated
FREE	Users with lite, subscriber, or admin roles
LICENSED	Users with subscriber or admin roles
ARDA	Users with admin role only

User Roles

Role	Description
public	Minimal access; equivalent to unauthenticated interaction
lite	Authenticated user with freemium capabilities
subscriber	Regular user with a commercial subscription
admin	Arda-affiliated users with full access
system	Internal system processes

OAuth2 Scopes (Cognito Resource Server)

Custom scopes declared on the Cognito Resource Server. Each scope implicitly includes access to all less-privileged scopes:

system > arda > subscription > lite > public

Standard OIDC scopes used by the Web Client: openid, email, profile, phone

Application (Data) Scopes

Data entities in the system are assigned to one of two Application Scopes:

Scope Kind	Description
GLOBAL	Accessible by any user with the required Realm access
TENANT	Accessible only to users associated with the owning Tenant. Users with admin role can access all Tenant scopes.

A user may be associated with zero tenants (GLOBAL-only access) or one or more tenants (multi-tenant user; future capability).

Cognito Scope Configuration (MVP0)

The Web Client enables the following scopes: openid, email, profile, phone, tenant, role

The custom tenant and role scopes ensure these custom attributes are included in the issued tokens.

User Attributes in JWT

Attribute	JWT Claim	Description
User ID	sub	Always included
Email	email	If email scope requested
Full name	name	If profile scope requested
Tenant ID	custom:tenant	<tenant-name>::<tenant-uuid>
Role	custom:role	One of public, lite, subscriber, admin, system

Future Direction

1. More granular roles for fine-grained RBAC; tenant-configurable roles
2. Multi-tenant user associations qualified by per-tenant roles and access conditions
3. Facility-level or geography-based sub-scoping within tenants
4. Evaluate Cedar as an authorization policy language