Skip to main content

Authentication

This document provides a comprehensive overview of authentication and user identity management in the Avassa system. It covers authentication methods, access tokens, entity management, application authentication via Approles, and multi-factor authentication with TOTP and passkeys.

For information about access control and permissions, see Authorization.

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 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

The policies listed here determine what operations the token is authorized to perform. See Authorization for details on how policies control access.

Approles​

Approles is the way applications authenticate towards the system. It is undesirable to include access tokens or 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 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, from authenticating.

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.

Role-ID Management​

There are two approaches to managing the role-id:

  1. System-generated role-id: The role-id is generated by the system and should be extracted as part of the build process. This requires extracting the role-id from each system where the container will be deployed.

  2. Hard-wired role-id: For convenience, a role-id can be hard-wired to a specific value. This makes it easier to create containers that can run on multiple systems, since the role-id doesn't have to be extracted from each system as a step in the build process of the container. This approach simplifies container deployment across different environments.

Creating an Approle​

Create an approle with associated policies:

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

The policies assigned to the approle determine what the application can access once authenticated. See Authorization for how to define and manage policies.

To create an approle with a hard-wired role-id for easier container deployment:

supctl create strongbox authentication approles <<EOF
name: app
role-id: my-custom-role-id-value
token-policies:
  - app
EOF

This allows you to embed the same role-id in containers that will be deployed across multiple systems without needing to extract it during the build process.

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.

Multi-Factor Authentication​

Avassa supports multiple methods for enhancing authentication security beyond username and password. Both TOTP and passkeys can be configured to restrict user privileges until they are properly set up, ensuring users enable additional security measures before gaining full access to the system.

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 provide 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 passwords.

Users can be restricted to limited privileges until TOTP is configured. See the totp-enable policy in Authorization for how to enforce TOTP setup.

Passkeys​

Passkeys provide a modern, phishing-resistant authentication method based on WebAuthn/FIDO2 standards. Users who have authenticated using username and password can create and register passkeys for their account.

Passkeys offer several advantages:

  • Enhanced security: Cryptographic authentication without passwords
  • Convenience: Biometric or PIN-based authentication on supported devices
  • Phishing resistance: Passkeys are bound to specific domains

Similar to TOTP, users can be restricted to limited privileges until a passkey is configured. See the passkey-enable policy in Authorization for how to enforce passkey setup.

Creating a Passkey​

After authenticating with username and password, users can register a passkey through the authentication interface. The passkey is stored securely and can be used for subsequent logins without requiring a password.

Summary​

This document covers the fundamentals of authentication in Avassa:

  • Identity Management: Entities, aliases, and how users are represented in the system
  • Access Tokens: How tokens are created, scoped, and used for API access
  • Approles: Application authentication with split credentials for enhanced security
  • User Authentication: Built-in and external authentication methods
  • Multi-Factor Authentication:
    • TOTP: Time-based one-time passwords for additional security
    • Passkeys: Modern, phishing-resistant authentication using WebAuthn/FIDO2

For information about what authenticated users and applications can access, see Authorization.

For detailed API references, visit the Avassa API documentation.