Security Realms and Permissions

These are preliminary notes to guide the early implementation of Authentication and Authorization on the platform.

Realm: A term adopted from common HTTP security practices that defines a set of protected resources. A realm has
unique name in the system. The protected resources typically are not “data” Functional Endpoints or
routes or services within an endpoint. Realms are defined statically in the system (at design time) and usually associated with RBAC (see below) authorization decisions.
Authenticator: A mechanism to authenticate a request to the system as done on behalf of a user. Typical
mechanisms include Bearer Token, Basic, JWT, OAuth2, etc. There may be multiple Authenticators of a given type depending on their configuration.
Oauth2 Scope: In OIDC and JWT-based OAuth2 systems, scopes define what actions or resources a client (application) is
authorized to perform on behalf of a user. They are encoded directly into the JWT access token (not the ID token).

An OAuth2 scope is a named string that represents a permission, such as:
- What user information the app is allowed to access
- What API endpoints the client is allowed to call
- What operations the client is allowed to perform

Application Scope: A dynamic set of resources that are restricted to be accessed only by users that are authorized to work with them.
they are defined at Runtime and their access rules are typically evaluated as part of an ABAC authorization decision.
RBAC: Role Based Access Control are all access decisions that can be done by examining the permissions of a user against
statically defined values in the system, typically Realms, Classes, etc…
ABAC: Attribute Based Access Control are access decisions that examine the user permissions against dynamic attributes of
the specific resources or data that it is trying to access. Decisions regarding Scope access fall in this category.

Cognito follows the OpenId standard and seems (to be confirmed) to use scopes to determine what user attributes to add to the Id Token:

Scope	Grants Access To…	Included In
`openid`	Required for ID token issuance	ID token
`email`	`email`, `email_verified` attributes	ID token
`profile`	`name`, `family_name`, `given_name`, `preferred_username`, etc.	ID token
`phone`	`phone_number`, `phone_number_verified`	ID token
`aws.cognito.signin.user.admin`	Allows AWS SDK/API to use user info (not for app)	Cognito admin APIs

Custom attributes (e.g., custom:department) are not tied to any standard scope but must be explicitly selected in the token claims settings.

✅ Allowed:
- Strings (max length: 2048 characters)
- Numbers (as strings)
- Boolean (as “true” or “false” string)

The User Pool will declare additional user attributes:
- tenant: A string representing the id of the tenant that is associated with the user. It will contain: <tenant-name>::<tenant-uuid>.
  In the future, when users may have multiple associated tenants, this information will need to be supported with a different mechanism
  using sub as a key.
- role: A String attribute that represents the functional permissions of the user. Initially there will only be four
  role values defined globally in the system that are not configurable:
  - public: Minimal access, equivalent to an unauthenticated interaction.
  - lite: Authenticated user with access to freemium or equivalent capabilities.
  - subscriber: Regular user subscribed to a Commercial license with Arda.
  - admin: Arda affiliated users with complete access to the system.
  - system: Internal system processes that need access to all resources in the system.
The Client App for UI access will enable all the standard scopes and the tenant and role scopes:
- openid, email, profile, phone, tenant, role.

Note

A user can be associated with no tenants, in which case they only have access to Global entities.
Although not in the first version of the system, a User can be associated with more than one Tenant, giving
it access to all the entities in all the Scopes for the tenants they are associated with.

Claim / Attribute	Description	Notes
`sub`	Unique user identifier (UUID)	Always included
`email`	User’s email address	If enabled + `email` scope requested
`email_verified`	Whether email is verified	If email is enabled
`name`	Full name of the user	If `name` attribute is selected
`cognito:username`	Cognito internal username	Always included
`phone_number`	User’s phone number	If attribute + scope are enabled
`custom:tenant`	The Tenant ID the user belongs to
`custom:role`	User’s role in the system	One of `public`, `lite`, `subscriber`, `admin`, `system`

Review the information on OAuth2
The system will define more granular Roles to provide fine-grained role RBAC capabilities. Roles will also be
definable by Tenants, in which case, they will serve as indexes for an RBAC resolution service that provides detail
on permissions and capabilities the role can access.
Association of Users with Tenants will be qualified by:
- The Roles that are active for the user when interacting with entities in the Scope.
- Other conditions that may limit their access based on specific attributes of the entities.
Tenant Scopes may be further divided into Facilities
or other finer grained scopes based on geography or other attributes.
Need to evaluate Cedar as a DSL to express authorization assertions.

Comments