Authorization

This document provides a comprehensive overview of authorization and policy management in the Avassa system. It covers policy types, configuration, evaluation principles, and practical usage for managing permissions and security.

For information about authentication and identity management, see Authentication.

Policy System Overview

Policies in Avassa exist on two levels:

Tenant Policies: Govern what a tenant can access.
User Policies: Define what a user or application can access within the scope of tenant policies.

Key features of policies:

Tokens must be associated with at least one policy to perform any operation.
Auto-created policies can be edited, deleted, or upgraded in a best-effort manner.
Policies use a hierarchical and path-based approach for access control.

Policy Principles

The policy system follows a number of principles:

By default everything is rejected: Only explicitly allowed operations are allowed.
The most specific rule wins: A top-level allow rule can be overruled by a more specific reject rule.
Multiple policies are permissive: If a token is associated with multiple policies, the most permissive policy wins.
Dual authorization: An operation must be allowed by both the tenant policies (assigned by the super-tenant) and the policies assigned to the token.

Types of Policies

Avassa policies are categorized into three main types:

1. REST API Policies

Define access to REST resources using a path-based approach with the most specific rule taking precedence.

Operations:

read - Checked against GET requests
create - Checked against POST requests
update - Checked against PATCH and PUT requests
execute - Checked against actions/RPCs (typically POST to endpoints)

Features:

Support hide-fields to restrict visibility of specific fields
Path wildcards supported (* and **)
Paths ending in ** apply to entire sub-trees

If multiple paths match a given request then the most specific path wins. If two paths are equally specific then allow overrides reject.

2. Capabilities

Grant elevated functionalities and control access to certain features:

system-admin: Only tenants with this policy may perform system administrative operations (e.g., block/unblock sites, rotate site and API certificates)
registry-pull: Allows a tenant to pull images from the registry
registry-push: Allows a tenant to push images into the registry
registry-global-pull: Can only be used by a tenant of kind 'system'

3. Volga Topics

Manage access to message topics for inter-service communication. Controls if creation, produce, and consume operations are allowed for a given topic. Topic names may contain a wildcard * at the end, with the longest match winning when evaluating rules.

Auto-Created Policies for New Tenants

When a new tenant is created, the system generates a set of default policies. These policies can be edited, deleted, or upgraded as needed:

Policy Name	Description
view	Allows viewing of configured data.
user	Grants normal users the ability to deploy and manage applications.
totp-enable	Restricts users to limited privileges until they enable one-time passwords (TOTP).
site-provider-tenant	Grants limited access for sub-tenants.
root	Full access for tenant administrators.
registry-push	Allows applications to push new images, e.g., for CI/CD pipelines.
registry-pull	Allows applications to pull images from the registry.
passkey-enable	Restricts users to limited privileges until they configure passkey-based authentication.
default	Minimal access, allowing users to view and refresh their tokens and log out.
app-owner-tenant	Grants application owners access to manage sub-tenants.

Policy Upgrade Behavior:

Unchanged policies: Upgraded seamlessly
Modified policies: Retain user edits where possible (best-effort)

Note: The totp-enable and passkey-enable policies can be used to enforce multi-factor authentication by restricting user privileges until the respective authentication method is configured. This ensures users set up additional security measures before gaining full access to the system. See Authentication for details on configuring TOTP and passkeys.

Example: Using Hide-Fields

The hide-fields option restricts visibility of specific fields even when read access is allowed:

- path: /v1/*/strongbox/authentication/userpass
  description: Do not show password to user.
  operations:
    read: allow
  hide-fields:
    - password

REST API Policy Evaluation

Most Specific Rule Precedence

REST API policies use the principle that the most specific rule takes precedence. For example:

General Access Rule

- path: /**
  description: Allow access to everything.
  operations:
    all: allow

Restriction on Authentication Subtree

- path: /v1/*/strongbox/authentication/**
  description: Prevent user from modifying authentication settings.
  operations:
    create: reject
    read: allow
    update: reject
    delete: reject
    execute: reject

Exception for Enabling TOTP

- path: /v1/*/strongbox/authentication/enable-totp
  description: Allow user to enable TOTP.
  operations:
    read: allow
    execute: allow

Combining Multiple Policies

When tokens are associated with multiple policies:

An operation is allowed if any policy permits it
For read operations with hide-fields, the intersection of all hide-fields restrictions applies

Multiple Policy Example

Policy A:

- path: /v1/resource
  operations:
    read: allow
  hide-fields:
    - field1
    - field2

Policy B:

- path: /v1/resource
  operations:
    read: allow
  hide-fields:
    - field2
    - field3

Result:

read is allowed
Only field2 is hidden (intersection of field1, field2, and field3)

Application and Subtenant Policies

Applications

Applications authenticate using tokens associated with specific policies. For details on how applications authenticate, see Authentication.

Grant Full Access to a Resource:

supctl create policy policies <<EOF
name: app
rest-api:
  rules:
    - path: /v1/*/strongbox/vaults/db/**
      operations:
        all: allow
EOF

Subtenants

Subtenants require associated policies to access system resources.

Define Subtenant Policies:

supctl create policy policies <<EOF
name: app-owner
rest-api:
  rules:
    - path: /**
      operations:
        all: allow
    - path: /v1/*/strongbox/system/**
      operations:
        all: reject
capabilities:
  registry-pull: allow
  registry-push: allow
EOF

Create a Subtenant:

supctl create tenants <<EOF
name: popcorn-systems
kind: application-owner
policies:
  - app-owner
EOF

Debugging and Logging Policies

Enable logging to troubleshoot policy evaluations:

Log Levels

none: No logging
reject: Log rejected requests
all: Log all requests (allowed and rejected)

Enable Logging

supctl create policy log <<EOF
level: all
EOF

View Logs

Logs are stored in the system:trace-log Volga stream:

supctl do volga topics system:logs consume --payload-only

Summary

This document covers the fundamentals of authorization and policy management in Avassa:

Policy Types: REST API policies, capabilities, and Volga topics
Policy Evaluation: Specificity rules, multi-policy combinations, and dual authorization
Auto-Created Policies: Default policies for new tenants and their purposes
Practical Usage: Application and subtenant policy configuration
Debugging: Policy logging and troubleshooting

For information about how users and applications authenticate to receive tokens, see Authentication.

For detailed API references, visit the Avassa API documentation.

Policy System Overview​

Policy Principles​

Types of Policies​

1. REST API Policies​

2. Capabilities​

3. Volga Topics​

Auto-Created Policies for New Tenants​

Example: Using Hide-Fields​

REST API Policy Evaluation​

Most Specific Rule Precedence​

General Access Rule​

Restriction on Authentication Subtree​

Exception for Enabling TOTP​

Combining Multiple Policies​

Multiple Policy Example​

Application and Subtenant Policies​

Applications​

Subtenants​

Debugging and Logging Policies​

Log Levels​

Enable Logging​

View Logs​

Summary​