Define Roles and Permissions with RBAC

Kestra Enterprise supports Role-Based Access Control (RBAC) to manage access to tenants, namespaces, flows, and resources.

Kestra has three types of entities:

• Users: Represent 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
  • Automate user onboarding, offboarding, and group management from inside a flow using IAM tasks

• 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: Represent an application. They are treated as users when binding role assignments.

All these entities can be assigned to a role, which defines what resources the user, group, or service account can access. These entities do not belong to namespaces, but their permissions can be limited to specific namespaces via bindings on the 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. Each permission is a combination of a resource (e.g., FLOW, EXECUTION, SECRET) and one or more actions (e.g., EXECUTE, VIEW, DELETE). A role alone grants nothing — it must be attached to a user, service account, or group via a binding on the IAM page.

Users, service accounts, and groups can hold any number of roles simultaneously. Bindings can be scoped to one or more namespaces — scoped access automatically extends to all child namespaces (for example, binding to prod also grants access to prod.engineering). You can configure a default role to assign it automatically to new users joining via SSO. Use Impersonate to verify a user’s effective permissions after assigning roles.

Impersonate

After assigning permissions to a user, Instance Owners can impersonate users to verify their access is correct. Impersonation switches your view to that user’s perspective and can be closed back to the Instance Owner view at any time.

Resources

A resource is a category of product entity or capability that can be controlled through RBAC. Each resource has its own set of allowed actions.

Core resources (namespace-scoped — bindings can restrict access to specific namespaces):

Apps and features (tenant-scoped):

Administration (tenant-scoped):

Actions

Each resource defines its own set of allowed actions. Not every action applies to every resource.

Common actions (available on most resources):

Resource-specific actions:

MCP server permissions

MCP_SERVER is a first-class RBAC resource that controls access to Kestra MCP servers. Supported actions are VIEW, LIST, CREATE, UPDATE, and DELETE.

Default role assignments:

In addition to these permissions, access to a private MCP server is also flow-scoped: a user can connect to a private server only if they have FLOW: EXECUTE on at least one namespace that contains a flow with an McpToolTrigger pointing at that server.

Managed roles

Kestra ships five managed roles. Each role’s full permission set is visible under IAM → Roles. Instance Owners can create additional custom roles on top of these. Users can hold multiple roles.

Instance Owner and Admin

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

• Instance Owner 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).

Instance Owner

Instance Owner is a powerful user type with instance-wide privileges. Use it sparingly — only for tasks that require it, such as creating tenants, troubleshooting, or helping a user.

Unlike tenant-scoped roles, Instance Owner operates across all tenants and does not require any Role or Binding. Instance Owners access instance-wide controls through the Instance Owner console, which covers tenant management, instance IAM, infrastructure, and governance.

For how to create Instance Owner users and manage the privilege, see Instance Owner.

Admin

Kestra has no Admin user type; Admin is a role with full permissions.

This role can be assigned to any user, service account, or group. This allows you to have different types of admins, grant admin permissions to a whole group, and revoke those permissions at any time without deleting 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 with no prior CLI setup, you are prompted to set up Kestra through the Setup Page.

This creates the first user, automatically assigns the Admin role, and binds it.

Later, create a new user or select an existing user and assign the Admin role from the Access tab in IAM.

Through the CLI

To create a user with the 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

User lockout

Use the following configuration to change the lockout behavior after too many failed login attempts. By default, Kestra locks the user for the lock-duration period after a threshold number of failed attempts within the monitoring-window duration. The snippet below lists the default values — 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.
• lock-duration: Defines how long the account remains locked.

With the configuration above, a user gets 10 failed login attempts in a 5-minute window before lockout. They must wait 30 minutes, be unlocked by an Admin, or reset their password using the Forgot Password link. An Instance Owner can also unlock a user manually from the user’s detail page.

Change password

Users can change their password from their profile, accessible via the user avatar 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 a password as an Instance Owner

Users can reset their password via the Forgot Password link on the login page. An Instance Owner can also reset a user’s password from the User Edit page at Instance Owner → Instance IAM → Users.

RBAC FAQ