Skip to main content

Generating Authorization Artifacts

Castlecraft Architect provides CLI commands to help you generate essential artifacts for setting up authorization in your application. These artifacts are derived from the "permission" components defined within your project.

The primary commands for this purpose are:

  • architect generate authorization-model
  • architect generate authorization-policy
  • architect generate permission-schema

1. Generating the Authorization Model​

The authorization model defines the structure of your access control rules (e.g., request definition, policy definition, role definition, matchers in Casbin). Architect can generate a baseline model for supported engines based on the permissions discovered in your application.

Command: architect generate authorization-model

Usage:

$ architect generate authorization-model [OPTIONS]

Key Options:

  • --engine TEXT: Specify the authorization engine you're using (e.g., casbin). Defaults to casbin.
  • --include-scope: For engines like Casbin, this flag determines how resources with scopes are represented. If set, a permission with a resource my_resource and scope my_scope might be represented as my_resource:my_scope in the model/policy. If not set, it would just be my_resource.
  • -o, --output FILE: Path to save the generated model file (e.g., ./auth_model.conf for Casbin). If omitted, the model is printed to the console.

Example (Casbin):

architect generate authorization-model --engine casbin --include-scope -o ./casbin_model.conf

This command will generate a casbin_model.conf file tailored for the permissions defined in your project, considering scopes.

2. Generating Bootstrap Authorization Policy​

Once you have an authorization model, you need policies (rules) that define who can do what. Architect can help bootstrap these policies, especially for setting up initial roles and permissions.

Command: architect generate authorization-policy

Usage:

$ architect generate authorization-policy [OPTIONS]

Key Options:

  • --engine TEXT: (Required) The name of the authorization engine (e.g., casbin).
  • --engine-config FILE: Path to a YAML or JSON file containing engine-specific bootstrap configuration. This file typically defines roles, user-to-role assignments, and role-to-permission mappings. (See Casbin Engine Configuration for an example).
  • --grant-full-access-to TEXT: A powerful option to specify a principal identifier (e.g., a user ID or a service account name) that should be granted all discovered permissions. This is useful for creating an initial superuser or admin.
  • -o, --output FILE: Path to save the generated policy data (e.g., ./bootstrap_policy.csv for Casbin). If omitted, policies are printed to the console.
  • --include-scope: Similar to the model generation, this affects how scoped permissions are represented in the policy.
  • --default-domain TEXT: For multi-tenant or domain-based policies, this specifies a default domain (defaults to *).

Example (Casbin):

architect generate authorization-policy --engine casbin \
  --engine-config ./my_casbin_bootstrap_config.yaml \
  --grant-full-access-to "admin_user_id" \
  --include-scope \
  -o ./bootstrap_policy.csv

This command generates a bootstrap_policy.csv file based on the definitions in my_casbin_bootstrap_config.yaml, grants full access to admin_user_id, and includes scopes in policy rules.

3. Generating a Permission Schema​

For advanced use cases or integration with custom tools, Architect can output a JSON schema detailing all permissions discovered within your project. This schema describes the action, resource, and scope for each permission.

Command: architect generate permission-schema

Usage:

$ architect generate permission-schema [OPTIONS]

Key Options:

  • -o, --output FILE: Path to save the generated JSON schema file. If omitted, the schema is printed to the console.

Example:

architect generate permission-schema -o ./permissions.json

This command will create a permissions.json file containing a structured representation of all your application's permissions. This can be useful for:

  • Auditing defined permissions.
  • Feeding into custom policy generation tools.
  • Building UIs that display available permissions.

By using these architect generate commands, you can significantly streamline the setup of your application's authorization layer, ensuring consistency between your defined permissions and your authorization engine's configuration.