Authorization - Core Concepts

warning

This page is currently under development, and its contents are subject to updates.

Core Entities

User

The fundamental actor in the system who can interact with various resources based on their roles and permissions.

• Can belong to multiple organizations
• Can have multiple platform roles (e.g., Farmer, Machinery Owner)
• Can have organization-specific roles within each organization
• Has attributes that influence permissions (location, certifications, etc.)

Organization

Represents a business entity in the system with its own hierarchy, roles, and permissions.

• Can operate in specific verticals and sectors
• Can have parent-child relationships with other organizations
• Can define custom roles for its members
• Manages its own set of resources and permissions

Vertical

High-level business domains that categorize the platform's services and trade.

• Examples: Amagator (Agro Machinery Aggregator), AgroCare (Agro Input Trade), AgroTrade (Agro Produce Trade)
• Influences available sectors and roles
• Affects permission scopes and policies
• Determines available features and services

Sector

Sub-categories within verticals that specify the exact domain of operation.

• Examples: Machinery, Farm, Fuel within Agro Machinery vertical
• Determines available platform roles
• Influences permission sets
• Specifies operational constraints

Platform Role

System-wide roles that define user and organization capabilities across the platform.

• Examples: Machinery Operator, Farmer, Supplier
• Requires agreement acceptance
• Associated with specific permissions
• Can be sector-specific
• Users and organizations may hold multiple PlatformRoles (e.g., Farmer and Supplier)

Organization Role

Organization-specific roles that define user capabilities within an organization.

• Examples: Owner, Manager, Supervisor
• Assigned to Users within an Organization
• Scoped to specific organization
• Can have organization-specific permissions
• Manages internal access control
• A User can hold multiple OrganizationRoles in one or more organizations

Permission

Defines allowed operations on specific resources.

• Combination of action and resource
• Can have conditions and constraints
• Can be role-specific
• Supports temporal validity

Scope

Defines the boundary of permissions and access control.

• Types: Platform, Organization, Vertical, Sector
• Hierarchical in nature
• Influences permission resolution
• Controls resource accessibility

Policy

Rules that govern access control decisions.

• Can be attribute-based
• Has priority levels
• Can be scoped to different levels
• Supports complex conditions

Resource

Any entity in the system that can be acted upon.

• Examples: Machinery, Agreements, Users
• Has associated permissions
• Can be scoped
• Supports hierarchical access

Relationships and Interactions

Connections Between Entities

User
├── PlatformRole (e.g., Farmer, Operator)
│   └── Linked to Sectors (e.g., Machinery, Farm, Fuel)
├── Organization (e.g., Company, Farm, Fuel Station)
│   └── OrganizationRole (e.g., Owner, Manager)
└── Vertical (e.g., Agro Machinery Aggregator)
    └── Sector (e.g., Machinery, Fuel, Farm)

User Relationships

Entity A	Entity B	Relationship Details
User	Organization	Many-to-Many (through membership)
User	PlatformRole	Many-to-Many (with agreements)
User	OrganizationRole	Many-to-Many (within organizations)

Entity B Explanation: Entity B represents the entities that the primary entity (Entity A) is related to. For example, a User can belong to multiple Organizations, hold multiple Platform Roles, or have specific Organization Roles within each Organization.

Organization Relationships

Entity A	Entity B	Relationship Details
Organization	Vertical	Many-to-Many
Organization	Sector	Many-to-Many
Organization	OrganizationRole	One-to-Many

Entity B Explanation: Entity B in this context refers to entities such as Verticals, Sectors, or Roles that are associated with the Organization.

PlatformRole Relationships

Entity A	Entity B	Relationship Details
PlatformRole	Permission	Many-to-Many (through RolePermission)
PlatformRole	Sector	Many-to-Many (Platform roles are sector-specific)
PlatformRole	PlatformRoleAgreement	One-to-Many

Entity B Explanation: Entity B indicates the related entities that interact with Platform Roles, such as Permissions, Sectors, or specific Agreements.

OrganizationRole Relationships

Entity A	Entity B	Relationship Details
OrganizationRole	Permission	Many-to-Many (through RolePermission)
OrganizationRole	Organization	Many-to-One (roles belong to specific organizations)

Entity B Explanation: Here, Entity B represents entities such as Permissions or Organizations linked to specific Organization Roles.

Permission Resolution

1. Check Platform Role permissions
2. Check Organization Role permissions
3. Apply Scope restrictions
4. Evaluate Policies
5. Check Resource constraints

Access Control Flow

1. Authentication

   • Verify user identity
   • Load user context

2. Context Resolution

   • Determine active roles
   • Load relevant scopes
   • Gather user attributes

3. Permission Evaluation

   • Check direct permissions
   • Apply role-based rules
   • Evaluate policies
   • Consider scope constraints

4. Policy Application

   • Apply attribute rules
   • Check temporal constraints
   • Evaluate conditions
   • Resolve conflicts

Examples

Platform Role Example

{
  "role": "Machinery Operator",
  "scope": "Platform",
  "requires_agreement": true,
  "permissions": ["operate_machinery", "view_assignments", "update_status"],
  "conditions": {
    "requires_license": true,
    "minimum_experience": "2y"
  }
}

Organization Role Example

{
  "role": "Branch Manager",
  "scope": "Organization",
  "permissions": ["manage_staff", "view_reports", "approve_transactions"],
  "conditions": {
    "branch_only": true,
    "maximum_transaction_amount": 50000
  }
}

Policy Example

{
  "name": "Working Hours Policy",
  "scope": "Sector",
  "sector": "Machinery",
  "conditions": {
    "time_range": "06:00-18:00",
    "working_days": ["MON", "TUE", "WED", "THU", "FRI", "SAT"],
    "weather_conditions": ["clear", "cloudy"]
  },
  "effect": "deny_if_not_match"
}

Summary of Entity Relationships and Roles

Entity	Description	Connections
User	Represents an individual who interacts with the platform.	- Can belong to one or more Organizations. - Holds one or more PlatformRoles. - Can have OrganizationRoles within organizations.
Organization	Represents a business entity (e.g., company, farm, or group) on the platform.	- Contains Users with OrganizationRoles. - Operates within a specific Vertical and Sector.
Vertical	A high-level grouping of services or trade offered by the platform. Examples: Agro Machinery Aggregator, Agro Input Trade, Agro Produce Trade.	- High-level business domains that categorize the platform's services and trade. - Influences the Sectors available for services/trade.
Sector	A sub-group within a vertical defining the domain or category of activity. Examples: Machinery, Farm, Fuel, Organization.	- Defines the PlatformRoles available for Users. - Organizations may specialize in one or more Sectors.
PlatformRole	Represents the role a User holds at the platform level, often tied to specific agreements. Examples: Machinery Operator, Farmer, Supplier.	- Assigned to Users based on the Sector they are involved in. - Users may hold multiple PlatformRoles (e.g., Farmer and Supplier).
OrganizationRole	Represents the role a User holds within a specific Organization. Examples: Owner, Manager, Supervisor.	- Assigned to Users within an Organization. - A User can hold multiple OrganizationRoles in one or more organizations.
Permission	Defines specific actions that can be performed on resources.	- Tied to a User, Role, or Policy. - Grants access to specific Resources.
Policy	Represents a set of rules governing access and actions within the platform.	- Links Users or Roles with Permissions. - Enforces platform or organization-level governance.
Resource	Represents entities or services requiring access control.	- Permissions determine how Users interact with the resource. - Examples: Machinery, Reports, Financial Data.

System Hierarchy and Authorization Flow