Role-Based Access Control (RBAC)

The Role itself does not grant any permissions to anyone.

Through the Access UI page, you are able to attach a Role to a User, Service Account, or Group, which creates a Binding.

This Binding grants the permissions defined by that Role to the User, Service Account, or Group.

A Binding can be optionally limited to specific namespaces. When a Binding is tied to a namespace, it automatically grants permissions to all child namespaces. For example, a Role attached to the prod namespace automatically grants access to the prod.engineering namespace as well.

Note that you can configure a default role so that all new Users are automatically assigned that Role. This is especially useful to grant a default set of permissions to all new Users who join your Kestra instance via SSO.

In short, Roles encapsulate permission boundaries that can be attached to Users, Service Accounts, or Groups across tenants and namespaces.

Here’s a table summarizing the key differences between an Admin and a Super Admin:

::

Super Admin

Without any Role or Binding, Super Admin has access to manage tenants, users, roles, and groups within a Kestra Enterprise instance.

kestra auths users create admin@kestra.io TopSecret42 --superadmin

# schema:
kestra auths users create <username> <password> \
--tenant=<tenant-id> --superadmin

kestra auths users set-superadmin user@email.com true # (use false to revoke)

kestra:
  security:
    superAdmin:
      username: <username>
      password: <password>
      tenantAdminAccess:
        - <optional>

Through the UI

When launching Kestra for the first time, if no prior action has been made through the CLI, you will be invited to setup Kestra through the Setup Page.

This interface invites you to create the first User which will automatically create the role Admin and bind the User to the role.

Later, you can create a new User or pick an existing User and assign the Admin role to it from the Access page.

Through the CLI

To create a User with an Admin Role from the CLI, use the --admin option:

kestra auths users create prod.admin@kestra.io TopSecret42 --admin

# schema:
kestra auths users create <username> <password> --admin

::

Users, Groups and Service Accounts

In Kestra you will find three types of entities:

• Users: represents a person
• Groups: represents a collection of Users and Service Accounts
• Service Accounts: represents an application

All theses entities can be assigned to a Role, which define what resources the User, Group, or Service Account can access.

Note that these entities don’t belong to namespaces, but their permissions can be limited to specific namespaces via Bindings (Access page).

There is no limit to the number of Roles that can be bound to an entity. They can have zero, one, or more Roles attached, giving specific permissions, optionally tied to one or more namespaces.

By default, Kestra >= 0.22 will lock the user for the lock-duration period after a threshold number of failed attempts performed within the monitoring-window duration. The snippet below lists the default values for those properties — you can adjust them based on your preferences:

kestra:
  security:
    login:
      failed-attempts:
        threshold: 10
        monitoring-window: PT5M
        lock-duration: PT30M

The key attributes are:

• threshold: Sets the number of allowed failed attempts before a user is locked out.
• monitoring-window: Defines the period during which failed login attempts are counted before triggering a lock. Super Admin can unlock the user manually by resetting their password from the user’s detail page.
• lock-duration: Defines how long the account remains locked.

In the above configuration, a user is allotted 10 failed login attempts in a 5-minute window before they are locked out. They must wait 30 minutes to try again, be unlocked by an Admin, or reset their password by clicking on the “Forgot password” link and following the instructions in the email.

The Admin role is a collection of permissions that can be assigned to Users, Service Accounts, or Groups. This allows you to grant multiple users with admin permissions if needed, and you can revoke only specific admin permissions at any time without having to delete the user.

Admin roles can be assumed by multiple users or groups, and some user may later be granted a lower or a higher permission boundary. In the same way, some users may initially be Admins but then their permission may be revoked. The Admin role enables all these patterns in a flexible way.

You can think of Users as authentication mechanism (who you are), and Roles as authorization mechanism (what you are allowed to do). Decoupling authentication from authorization allows you to grant permissions to multiple users or groups at once by attaching a single Role to a Group.

A Binding is an immutable object. If a Binding no longer reflects the desired permissions, you can delete the existing Binding and create a new one for the same User, Service Account, or Group but with different Roles and/or namespaces. This is a safety feature to prevent accidental changes to existing permissions.