Table of Contents

User Permissions

The User Permissions module allows you to manage users and roles.

First use

When you start a cluster that uses User Permissions for the first time, configure DefaultUserAccountLogin. This setting provides the initial user account created during the database migration, so that you can sign in and administer users, roles, and permissions. Without it, a restrictive configuration such as DefaultBehavior: Deny can leave a new local cluster with no user account able to access the application.

For local development, define this value as a user- or machine-level environment variable:

UserPermissions__DefaultUserAccountLogin=<your email address>

The double underscore (__) maps to the UserPermissions:DefaultUserAccountLogin configuration path used by .NET. Defining it globally means the same development account is available regardless of the cluster you are currently working on, without adding a personal email address to each cluster's configuration file. Restart the cluster after creating or changing the environment variable so that its backend reads the new value.

Important

Set the variable before the first database migration. The default account is created during that migration; adding or changing the setting afterwards does not create or rename an existing account.

Configuration

The behavior of the user permissions mechanism can be configured in the cluster backend configuration via the appsettings.json file or environment variables.

{
  "UserPermissions": {
    "DefaultUserAccountLogin": "[email protected]",
    "DefaultBehavior": "Deny",
    "DefaultAllowedFunctions": ["Dashboard"],
    "CreateUserAccountIfNotExists": false,
    "DefaultUserAccountRole": 1
  }
}

DefaultUserAccountLogin

By defining the DefaultUserAccountLogin option, a user with this login will be created when the database is migrated.

Note

If you set a value which is not an email, a service account will be created instead of a user account. The DefaultUserAccountLogin value will be used as service identifier.

DefaultBehavior

The default behavior is restrictive (Deny), which is the strongly recommended setting:

  • An unknown user (a user not listed in the user account table) will not be able to access the application.
  • A known user without permissions will not have access to any resources.
Warning

Avoid setting DefaultBehavior to Allow in production environments. When set to Allow:

  • Any user who successfully authenticates — even one with no account in the database — gains unrestricted access to all application resources (or, if License Management is used, all resources enabled by License Management).
  • A known user with no explicit permissions is treated as having access to everything (or, if License Management is used, every function allowed by the current license).

Only use Allow in controlled, non-production environments where you explicitly want open access.

Important

If your cluster uses License Management (its use is optional), DefaultBehavior: Allow does not bypass it. License Management is applied upstream of DefaultBehavior: functions disabled by License Management stay disabled, regardless of the DefaultBehavior value. Setting DefaultBehavior to Allow only grants access to functions that License Management already allows for the current license — it cannot re-enable a function that License Management has turned off.

DefaultAllowedFunctions

You can define which functions will be allowed by default for everyone using the DefaultAllowedFunctions option.

Important

DefaultAllowedFunctions does not support inheritance between functions. If a feature depends on multiple functions, you must add each required function explicitly.

CreateUserAccountIfNotExists and DefaultUserAccountRole

By setting the CreateUserAccountIfNotExists option to true, a user account will be created automatically when a user logs in for the first time if it does not already exist in the database.

The new user account is assigned a default role, chosen in this order:

  1. The role checked as Assigned to automatically created accounts in the role form. Each tenant chooses its own role: at most one role can be checked, and it cannot be an Editor role, since automatically created accounts are Client accounts.
  2. Otherwise, on a mono-tenant cluster only, the role whose ID is set in DefaultUserAccountRole. The value of DefaultUserAccountRole should correspond to an existing role ID in the database.
  3. Otherwise, no role: the permissions of the user then follow DefaultBehavior and DefaultAllowedFunctions.
Note

DefaultUserAccountRole is ignored on a multi-tenant cluster: the role IDs differ from one tenant database to another, so a single ID cannot designate the same role in every tenant. Check the default role in each tenant instead.

Multi-tenant clusters

On a multi-tenant cluster, a user who is not yet a member of a tenant cannot reach it, so their account cannot be created there. Map the TenantIdentifier user property to the claim of the token holding the tenant identifier. At the first login, the user is admitted into this tenant, their account is created in its database, and the user account synchronization makes them a member of the tenant in TenantManagement.

A user who is already known in another tenant keeps their names and type: the account created in the new tenant does not overwrite them. To only create accounts for users who are not yet a member of any tenant of the cluster, set Authentication:TenantClaimAdmission to UsersWithoutTenant.

Note

This fonctionality can be useful when using an authentication provider limited to specific domains (e.g., Azure AD) to automatically create user accounts for authenticated users with a restricted role.

SendTemporaryPasswordEmail

By default, creating a user triggers sending an email to the user to provide their temporary password. You can disable automatic email sending by setting the SendTemporaryPasswordEmail property to false.