Skip to main content

Casbin Engine Configuration

When using the architect generate authorization-policy --engine casbin command, you can provide an engine-specific configuration file using the --engine-config <path_to_file.yaml_or_json> option. This file allows you to define the initial set of roles, the permissions granted to these roles, and user-to-role assignments for bootstrapping your Casbin policies.

The CasbinEngineAdapter expects this configuration file to be in YAML or JSON format and to contain a top-level key named casbin. Under this key, you can define the policy structure.

Expected Structure​

The CasbinEngineAdapter looks for the following structure within the bootstrap_config dictionary (which is parsed from your --engine-config file):

casbin:
  roles_to_permissions:
    # Defines which permissions are granted to which roles.
    # <role_name>:
    #   - <permission_name_1>
    #   - <permission_name_2>
    # Permission names should correspond to the 'permission_name' (op.name)
    # of the 'permission' components discovered in your application.
    # These will be translated into Casbin 'p' (policy) rules.

  user_to_role_assignments:
    # Defines which users are assigned to which roles.
    # <user_identifier>: <role_name_or_list_of_role_names>
    # These will be translated into Casbin 'g' (grouping/role) rules.

Sections Explained:​

  1. casbin (Top-Level Key): This is the primary key the CasbinEngineAdapter looks for in the configuration file. All Casbin-specific bootstrap configurations should be nested under this key.

  2. roles_to_permissions (Dictionary, Optional):

    • Purpose: Defines which permissions are granted to specific roles. This section directly influences the generation of Casbin p (policy) rules.
    • Structure:
      • Each key is a role_name (e.g., admin, editor, viewer).
      • The value for each role_name is a list of permission_name strings. These permission_name strings must match the unique names of the "permission" components defined in your Architect application (typically derived from ComponentOperation.name where component_type == "permission").
    • Example: 
      casbin:
        roles_to_permissions:
          administrator:
            - "permission_manage_all_users"
            - "permission_view_system_logs"
            - "permission_configure_settings"
          content_editor:
            - "permission_create_article"
            - "permission_edit_own_article"
            - "permission_publish_article"
    • Resulting Casbin p rules (conceptual, depends on declared_permissions details and CLI options like --include-scope): 
      p, administrator, user_resource, manage  # If "permission_manage_all_users" maps to this
      p, administrator, system_logs, view     # If "permission_view_system_logs" maps to this
      # ... and so on

  3. user_to_role_assignments (Dictionary, Optional):

    • Purpose: Defines initial assignments of users to roles. This section directly influences the generation of Casbin g (grouping/role) rules.
    • Structure:
      • Each key is a user_identifier (e.g., user_alice, employee_007). This is the subject (sub) in the g rule.
      • The value can be either:
        • A single role_name string (e.g., administrator).
        • A list of role_name strings if a user should be assigned to multiple roles (e.g., [editor, reviewer]).
    • Example: 
      casbin:
        user_to_role_assignments:
          alice_user_id: "administrator"
          bob_user_id: "content_editor"
          carol_user_id:
            - "content_editor"
            - "forum_moderator"
    • Resulting Casbin g rules: 
      g, alice_user_id, administrator
      g, bob_user_id, content_editor
      g, carol_user_id, content_editor
      g, carol_user_id, forum_moderator

Handling the --grant-full-access-to <principal_id> CLI Flag​

If you use the architect generate authorization-policy --grant-full-access-to <principal_id> flag (e.g., --grant-full-access-to admin_user_id or --grant-full-access-to service_account_xyz):

  • The CLI will add a special key _default_admin_grants to the root of the bootstrap_config dictionary (not under the casbin key). The value will be a list of all permission_name strings discovered in your application. The <principal_id> provided to the flag will also be passed along.
  • The CasbinEngineAdapter will detect this _default_admin_grants key.
    • It will ensure that the specified <principal_id> is assigned a role (typically "admin" or a similarly privileged role, which might be created if not present in your engine-config.yaml) that has all discovered permissions.
    • If a role like "admin" is defined in your engine-config.yaml under casbin.roles_to_permissions, the permissions from _default_admin_grants will be merged (added without duplication) into this role. The <principal_id> will then be assigned to this role.

This allows you to easily grant a specific user or system principal superuser-like access without needing to list every single permission for them in your config file, while still allowing you to define other roles and their specific permissions.

Complete Example (engine-config.yaml)​

# This is the top-level key the CasbinEngineAdapter looks for.
casbin:
  # Defines which permissions are granted to which roles.
  # These will be translated into Casbin 'p' (policy) rules. The role used by `--grant-full-access-to` will typically be 'admin'.
  roles_to_permissions:
    # The '--grant-full-access-to <principal_id>' flag will typically merge with/create this role for the given principal.
    # Specific permission for admin
    admin:
      - "permission_view_dashboard_summary"
    # Editors can list all content
    editor:
      - "permission_create_content"
      - "permission_edit_own_content"
      - "permission_list_all_content"
    # Viewers can also list all content
    viewer:
      - "permission_list_all_content"
      - "permission_view_published_content"

  # Defines which users are assigned to which roles.
  # These will be translated into Casbin 'g' (grouping/role) rules.
  user_to_role_assignments:
    user_001_alice: "admin"
    user_002_bob: "editor"
    user_003_charlie:
      - "viewer"
      - "editor" # Charlie is both a viewer and an editor
    user_004_david: "viewer"

# Other top-level keys in this file will be ignored by the CasbinEngineAdapter
# but might be used by other engine adapters if this file is multi-purpose.
# For example:
# spicedb:
#   ... (SpiceDB specific config) ...

By structuring your --engine-config file this way, you can effectively bootstrap your Casbin policies when using the architect generate policy-data command. Remember that the actual permission_name strings must correspond to the permissions defined and discovered within your Architect application.