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.
If the DefaultUserAccountRole is set, the new user account will be assigned this role by default. The value of DefaultUserAccountRole should correspond to an existing role ID in the database.

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.