Authorization (Authz), Policies & Grants
Relevant source files
The following files were used as context for generating this wiki page:
The Authorization (Authz) system in Forze provides a structured, document-backed framework for managing permissions, roles, and group memberships. It operates on a "Verify-then-Resolve" principle, ensuring that once an identity is authenticated, its access rights are determined through a set of logical policies and grants. The system is designed to be UUID-native, allowing authorization bindings to persist regardless of the specific Identity Provider (IdP) used for authentication.
Sources: skills/forze-auth-tenancy-secrets/SKILL.md, src/forze_identity/authz/application/specs.py
Architecture Overview
The authorization architecture is built upon several core entities: Principals, Permissions, Roles, and Groups. These entities are connected through "Bindings" and "Grants" to form a comprehensive access control list (ACL) or Role-Based Access Control (RBAC) model.
Core Components
- Policy Principal: The primary entity representing a user or service in the authorization system.
- Permission Definition: Logical definitions of specific actions (e.g.,
document:read). - Role Definition: Aggregations of permissions.
- Bindings: The bridge entities that connect Principals or Groups to Roles and Permissions.
The following diagram illustrates the relationship between these core authorization entities:
The diagram shows how permissions can be assigned directly to principals or inherited through roles and group memberships.
Sources: src/forze_identity/authz/application/specs.py:48-155, src/forze_identity/authz/domain/models/bindings.py
Logical Specifications (Specs)
Authorization in Forze is managed through DocumentSpec objects, which define the read/write models for each authorization entity. These specs are used by the ExecutionContext to resolve the appropriate ports for managing authz data.
| Resource Name | Purpose | Model Types (Read/Domain/Create) |
|---|---|---|
policy_principals | Manages authorization identity records. | ReadPolicyPrincipal, PolicyPrincipal, CreatePolicyPrincipalCmd |
permissions | Defines granular actions. | ReadPermissionDefinition, PermissionDefinition, CreatePermissionDefinitionCmd |
roles | Defines collections of permissions. | ReadRoleDefinition, RoleDefinition, CreateRoleDefinitionCmd |
groups | Manages collections of principals. | ReadGroup, Group, CreateGroupCmd |
Sources: src/forze_identity/authz/application/specs.py:48-89
Bindings and Delegation
Bindings represent the active assignment of rights. Unlike definitions, many bindings in Forze support only "Create" and "Delete" operations, functioning as immutable relationship records.
Delegation Grants
A Delegation Grant allows a principal to delegate specific permissions or roles to another principal. This is defined by the delegation_grant_spec, which utilizes the DelegationGrant domain model and ReadDelegationGrant read model.
Principal and Group Bindings
Bindings can be scoped to individual principals or broader groups:
- Role Bindings: Linking a principal or group to a
RoleDefinition. - Permission Bindings: Direct assignment of a
PermissionDefinitionto a principal or group. - Group Principal Binding: Assigning a
PolicyPrincipalto aGroup.
Sources: src/forze_identity/authz/application/specs.py:92-155, src/forze_identity/authz/domain/models/bindings.py
Authorization Resolution Flow
The resolution of authorization (checking if a principal has a permission) typically involves traversing the hierarchy of groups and roles.
This flowchart represents the logical sequence for determining access based on the bindings defined in the system.
Sources: src/forze_identity/authz/domain/models/bindings.py, skills/forze-auth-tenancy-secrets/SKILL.md
Implementation Notes
UUID-Native Identity
Forze authorization utilizes principal_id (UUID) which is shared with the AuthnIdentity. This ensures that if a user switches authentication methods (e.g., from Password to OIDC), their authorization grants and role assignments remain intact as long as the internal UUID is preserved.
Sources: skills/forze-auth-tenancy-secrets/SKILL.md
Tenant Unawareness
Certain authorization specs, such as the policy_principal_spec, are often configured as tenant-unaware document stores. This allows the system to evaluate a principal's eligibility and basic identity mapping before a specific TenantIdentity is bound to the execution context.
Sources: skills/forze-auth-tenancy-secrets/SKILL.md
Summary
The "Authorization (Authz), Policies & Grants" system provides a robust mechanism for decoupling identity verification from access control. By using a series of logical specifications and binding models, Forze enables developers to implement complex RBAC and ACL patterns that are both scalable and provider-agnostic. Significant logic resides in the DocumentSpec definitions and the relationships between Principals, Roles, and Permissions.