Psono Documentation

# Tenants and Delegated Administration

# Overview

Tenants let a superuser organize users and groups into administrative ownership scopes. Administrative roles can then be assigned globally or for selected tenants. This makes it possible, for example, to let a department administrator manage only the users and groups owned by that department.

Tenant administration is available in both the Community Edition and the Enterprise Edition.

WARNING

A tenant is an administrative boundary, not a separate vault, login realm, database, or cryptographic boundary. Tenant membership does not grant access to secrets or groups. Access to groups, shares, and secrets is still controlled by the normal group memberships and share permissions.

Users and groups can belong to no tenant, one tenant, or multiple tenants. A tenant can therefore represent a department, subsidiary, customer, region, or any other administrative scope.

# Requirements

Tenant and administrative-role management is available in the Admin Portal when MANAGEMENT_ENABLED is enabled on the server. Only a superuser can create tenants, change direct tenant memberships, manage administrative roles, or assign those roles. See Finalize the installation for how to create the first superuser.

A user with an active administrative-role assignment can access the Admin Portal without being promoted to superuser. The role assignment determines which pages and resources that user can access.

# Create And Populate A Tenant

  1. Log in to the Admin Portal as a superuser.
  2. Open Settings -> Tenants.
  3. Create a tenant and enter a unique name and an optional description.
  4. Open the tenant and use Tenant users and Tenant groups to add existing users and groups.

Tenant membership by itself grants no administrative privileges. To delegate administration, assign an administrative role as described below.

# Delegate Administration

Administrative access consists of two independent parts:

  • A role defines what an administrator can do through capabilities such as viewing users, deleting sessions, or managing group memberships.
  • A role assignment defines where the role applies: globally or in one or more tenants.

To assign a role for selected tenants:

  1. Open Settings -> Administrative roles.
  2. Select Role assignments and create an assignment.
  3. Select the user and role.
  4. Clear Global scope and select one or more active tenants.
  5. Save the assignment.

The built-in roles include Full Administrator, User Administrator, Group Administrator, Read-only Auditor, and Fileserver Administrator. The Enterprise Edition adds roles for identity providers, policies, and gateways. Built-in roles cannot be modified, but a superuser can create custom roles from the capabilities shown in the Admin Portal.

Only user- and group-related capabilities can be limited to tenants. System information, system-wide statistics, fileserver infrastructure, identity providers, policies, and gateways require global scope. A full-access role must also be global. The Admin Portal only offers tenant scope for compatible roles.

TIP

An administrator does not have to be a member of a tenant to administer it. Administrative access comes from the role assignment, not from the administrator's own tenant membership.

# Scope Behavior

A tenant-scoped administrator can see and manage a user or group when at least one of its active tenants overlaps with the administrator's scope. Related operations, such as deleting sessions, resetting second factors, managing group memberships, and managing group share rights, use the tenant of the user or group they belong to.

When creating a user, a tenant-scoped administrator must select at least one active tenant from their own scope. A globally scoped administrator can create a user without assigning a tenant.

If a user or group belongs to multiple tenants, each matching tenant administrator manages the same underlying object. An update is not limited to one tenant. Deleting a user or group shared by multiple tenants requires an additional confirmation because the object is deleted for every owning tenant.

WARNING

Tenant scope does not require a group's members to belong to the same tenant. A tenant administrator who can manage a group can therefore see and manage that group's memberships even when individual members belong to other tenants.

Superusers and users with active administrative-role assignments are protected from management by delegated user administrators.

# Automatic Assignment

# Default Tenants For New Objects

The server can automatically assign every newly created user or group to configured tenants. Add the tenant UUIDs to settings.yaml:

DEFAULT_USER_TENANTS:
  - 00000000-0000-0000-0000-000000000001
DEFAULT_GROUP_TENANTS:
  - 00000000-0000-0000-0000-000000000001

Multiple tenants can be specified. The equivalent environment variables accept comma-separated UUIDs:

export PSONO_DEFAULT_USER_TENANTS=00000000-0000-0000-0000-000000000001,00000000-0000-0000-0000-000000000002
export PSONO_DEFAULT_GROUP_TENANTS=00000000-0000-0000-0000-000000000001

The UUID is visible in the URL when editing a tenant in the Admin Portal.

Default assignments are additive: explicitly selected tenants are kept as well. They apply only when an object is created, including users created through registration or the createuser command. Changing the settings does not update existing users or groups. Verify tenant UUIDs carefully because unknown UUIDs are ignored.

When a user creates a group in the regular Psono client, that group also receives all of the user's currently active tenant memberships. This is a snapshot at creation time; later changes to the user's tenants do not change existing groups.

# Identity Provider Groups

TIP

Automatic tenant assignment from LDAP, SAML, OIDC, and SCIM groups is only available in the Enterprise Edition.

An external identity-provider group can be assigned to one or more tenants without mapping it to a Psono group:

  1. Open the provider's Groups view in the Admin Portal.
  2. Find the external LDAP, SAML, OIDC, or SCIM group and edit it.
  3. Select the tenants to assign to members of that external group.

Managing these assignments requires the globally scoped identity_providers.manage capability.

Only active tenants are assigned automatically. For LDAP, SAML, and OIDC, the assignment is applied when a user next logs in. For SCIM, it is applied when group membership is provisioned or changed; assigning a tenant to an existing SCIM group also processes its current members immediately. If an authentication provider uses SCIM for provisioning, SCIM group memberships are the source for tenant assignment.

External-group tenant assignment and mapping an external group to a Psono group are independent features:

  • Tenant assignment determines which delegated administrators can manage the user.
  • Psono group mapping determines the user's group membership and access to shares.

WARNING

Identity-provider tenant assignment is additive and does not revoke existing tenant memberships. Removing a user from an external group, removing a tenant from the external group, or deactivating the tenant does not delete a tenant membership that was assigned earlier. Remove obsolete memberships directly from the tenant in the Admin Portal.

# Deactivate Or Delete A Tenant

Deactivating a tenant preserves its users, groups, and administrative-role assignments but removes the tenant from effective delegated-administration scope. Reactivating it restores the existing relationships. Automatic identity-provider assignment also ignores inactive tenants.

To delete a tenant, first remove all of its user memberships, group memberships, and administrative-role assignment scopes. The server prevents deletion while any of these relationships remain.

# Design Considerations

  • Use separate tenants where administrative responsibility differs, not merely to organize vault entries.
  • Give custom roles only the capabilities required for their task.
  • Remember that a shared user or group is one object jointly administered through every assigned tenant.
  • Review direct tenant memberships when identity-provider group membership changes because automatic assignment does not revoke them.
  • Policies and Enterprise Edition license limits are server-wide or use their own assignments; they are not calculated per tenant.

← Administrative Roles →