Identity and Policy Fundamentals

This document provides a comprehensive overview of user identity management and policies in the Avassa system. It covers authentication methods, access tokens, policy types, configuration, evaluation principles, and practical usage for managing permissions and security.

---

Identity and User Management

Most operations towards the Avassa API require an access token. An access token can either represent an authenticated user, a system process, or an application.

All authenticated users are represented as a canonical entity. Each entity has zero or more entity aliases associated with it. An entity alias is a bridge between the authentication service and the canonical entity representing the user. For example, a user that authenticates through a username/password service gets connected with the canonical user entity through an userpass entity alias, whereas the same user when authenticated through an OIDC identity service will be connected through a different entity alias to the same canonical entity.

It is possible to associate different restrictions and policies to each entity, and authentication service. It is, for example, possible to limit the session length of users connecting through the OIDC identity service, or allow apply a different set of policies to users authenticated through the userpass identity service.

Entity

An entity represents a canonical user identity. It may have a list of policies associated with it, and a number of entity aliases. In most cases the policies are assigned by the identity service.

Entity Alias

An entity alias represents a user authenticated through some specific identity service, such as a username/password or Open ID Connect service.

Access Tokens

An access token is created by the identity service when a user or application authenticates towards the system. Different identity services may assign different policies and restrictions to the token, as well as different TTLs, number of times it can be used, and renewal conditions.

The scope of an access token is the site where it was created.

Viewing Token Information

Use the token-info command to view a token's policies:

supctl do token-info

Sample Output:

display-name: userpass-joe@popcorn-systems.com
tenant: popcorn-systems
policies:
  - default
  - user

Approles

Approles is the way applications authenticate towards the system. It is undesirable to include access tokens other credentials in the application. Instead the application authentication credentials are split up into two parts, one part is embedded in the application and one is provided by the scheduler when the application is started.

The part embedded in the application is called a role-id and should be treated as sensitive information. The role-id should be extracted from the system as part of the build process. The role-id is valid throughout the system, i.e., on all sites.

The other part, the secret-id, is provided by the scheduler when the application is started and is also sensitive information. The secret-id is only valid on the site where the application instance is scheduled.

The application uses the role-id and secret-id in combination to authenticate towards the system. The idea is to block rogue applications from gaining access, even if they have managed to be scheduled, and to block applications that have gained access to the role-id, but not been started by the scheduler, to authenticate.

The role-id and secret-id can be thought of as a username and password, where both are secret. See the Programming with Strongbox tutorial for an example.

For security reasons the secret-id is only valid for one login, and only for 30 minutes, by default. This can be modified in the definition of the approle but keeping the secret-id-num-uses to 1 makes the system less susceptible to someone gaining access by stealing the role-id and the secret-id of an application.

User Authentication

Users are authenticated through some identity service. There is a built-in username/password service where users can be added, and there is an interface available for authenticating users through external OpenID Connect servers.

When a user is successfully authenticated an access token is created, and access policies are assigned to the token, as well as other properties such as expiration time.

Different authentication services may assign different sets of policies to the same user.

TOTP

Strongbox has support for RFC 6238 TOTP passwords, i.e., Google Authenticator passwords. It can function both as a password validation server, and as a password generator client.

It can be configured in two different ways. It can generate the secret key and provides a QR code that can be consumed by the Google Authenticator application, as well as a configuration URL.

It can also be configured using a URL that has been provided by some other authentication entity.

Regardless of how it was configured it can both validate and generate TOTP password.

---

Policy System Overview

Policies in Avassa exist on two levels:

1. Tenant Policies: Govern what a tenant can access.
2. 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 access until users 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	Similar to totp-enable, but for passkey-based logins.
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)

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.

Create Application Policies:

supctl create strongbox authentication approles <<EOF
name: app
token-policies:
  - app
EOF

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 identity and policy management in Avassa:

• Identity Management: Entities, aliases, access tokens, and authentication methods including Approles and TOTP
• Policy Types: REST API policies, capabilities, and Volga topics
• Policy Evaluation: Specificity rules, multi-policy combinations, and debugging
• Practical Usage: Application authentication, subtenant management, and logging

For detailed API references, visit the Avassa API documentation.