​Role-​Based ​Access ​Control (​R​B​A​C)

How to manage access and permissions to your instance.

Overview

Kestra Enterprise supports Role-Based Access Control (RBAC), allowing you to manage access to Tenants, Namespaces, Flows and resources.

In Kestra you will find three types of entities:

• Users: Represents a person. To add users to your Kestra instance, you can do one of the following:
  • Invite users to your instance or tenant from the UI
  • Sync users from an external identity provider using SCIM
  • Create users directly using Terraform
• Groups: Represent a collection of Users and Service Accounts. Groups are a useful mechanism for providing the same roles to multiple Users or Service Accounts at once by binding a role to a Group.
• Service Accounts: Represents an application. They are considered Users when binding Role assignments.

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 (IAM page).

The image below shows the relationship between Users, Groups, Service Accounts, Roles, and Bindings:

Roles and Bindings

A Role is a collection of permissions that can be assigned to Users, Service Accounts, or Groups. These permissions are defined by a combination of a Permission (e.g., FLOWS, NAMESPACE, SECRET, etc.) and an Action ( e.g., CREATE). The Role itself does not grant any permissions. Through the IAM page, you are able to assign 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. Select any IAM entity (User, Group, etc.), and assign the desired Role. 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; make sure to test their access with the Impersonate feature.

Once a Role has been created, you can assign that Role to Users and Groups. Optionally, when you assign the Role to an entity (User, Group, or Service Account), you can specify the Binding to a specific Namespace(s). 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 User assigned to a Role specifying 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.

Impersonate

After assigning permissions to a User, Superadmins can impersonate Users to ensure their access is as intended. Impersonation switches your view immediately to that User's perspective and can be easily closed back to Superadmin view – a seamless way to test RBAC in one context.

Permissions

A Permission is a resource that can be accessed by a User or Group. Open the following to view all supported permissions:

Actions

An Action is a specific operation that can be performed on a Permission. Supported Actions:

• CREATE
• READ
• UPDATE
• DELETE

Currently supported roles

Currently, Kestra only creates an Admin role by default. That role grants full access to all resources.

Apart from Admin, Kestra has the managed Roles: Developer, Editor, Launcher, and Viewer. Each Role's permissions can be viewed from IAM - Roles. Superadmins can create additional Roles with custom permission combinations in addition to Kestra-managed roles. Users can be assigned multiple Roles.

Superadmin and Admin

Kestra provides two roles for managing your instance: Superadmin and Admin.

• Superadmin is a user type with elevated privileges for global control
• Admin is a customizable role that grants full access to all resources (scoped to a tenant if multi-tenancy is enabled).

Super Admin

Super Admin is a powerful type of user. Use the role sparingly and only for use cases that require it, such as creating a new tenant, troubleshooting tenant issues, or helping a user with a problem.

Without any Role or Binding, Super Admin has access to manage tenants, users, roles, and groups within a Kestra Enterprise instance. There are multiple methods to create a Superadmin user.

Through the UI

When you launch 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 your first User which will be automatically assigned the Superadmin privilege.

Through the CLI

To create a User with a Superadmin privilege from the CLI, use the --superadmin option:

kestra auths users create [email protected] TopSecret42 --superadmin

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

To set or revoke Superadmin privileges, use the following in the CLI:

kestra auths users set-superadmin [email protected] true # (use false to revoke)

Configuration

A Super Admin can also be created from the configuration file using the configuration below:

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

For more details, check the Enterprise Edition Configuration page.

Grant/Revoke Super Admin permissions

Through the UI

You can grant or revoke the Superadmin privilege using the switch in the User Edit page.

Through the CLI

To set an existing User with a Superadmin privilege from the CLI, use the dedicated command:

# Set a user as Super Admin
kestra auths users set-superadmin [email protected] true

# Revoke Super Admin privilege
kestra auths users set-superadmin [email protected] false

Admin

In Kestra, the notion of Admin user does not exist; instead we create an Admin Role with all permissions.

This role can be assigned to any User, Service Account, or Group. This allows you to have different types of admins, to grant admin permissions to a whole group, and to revoke those admin permissions at any time without having to delete any group or user.

When using multi-tenancy, Kestra assigns the Admin Role to the user who created the tenant by default.

Creating a User with an Admin Role

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 [email protected] TopSecret42 --admin

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

User lockout

Use the following configuration to change the lockout behavior after too many failed login attempts. 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.

Change password

If a user wants to change their password, they can do it on their profile. This page can be accessed through the profile in the bottom left corner of the UI. "Forgot Password" settings can be configured in your Kestra configuration under basic-auth.password-reset. Settings to consider are the cooldown time between reset requests and how many requests can be made in a given time window.

kestra:
  security:
    basic-auth:
      password-reset:
        cooldown: PT5M         # Minimum time required between two password reset emails for the same user
        rate-limit:
          max-requests: 10     # Maximum number of password reset requests allowed per client within the time window
          window: PT1H         # Time window during which password reset requests are counted for rate limiting

Reset password (by a Super Admin)

Kestra provides a "forgot password" functionality that your users can leverage to reset their password. This functionality is available on the login page, where users can click on the "Forgot password?" link. On top of that, a Super Admin can reset a user's password from the User Edit page by going to Instance - IAM - Users.

RBAC FAQ