Role-based access control (RBAC) reference

Sensu’s role-based access control (RBAC) helps different teams and projects share a Sensu instance. RBAC allows you to specify actions users are allowed to take against resources, within namespaces or across all namespaces, based on roles bound to the user or to one or more groups the user is a member of.

• Namespaces partition resources within Sensu. Sensu entities, checks, handlers, and other namespaced resources belong to a single namespace.
• Roles create sets of permissions (e.g. get and delete) tied to resource types. Cluster roles apply permissions across namespaces and include access to cluster-wide resources like users and namespaces.
• Users represent a person or agent that interacts with Sensu. Users can belong to one or more groups.
• Role bindings assign a role to a set of users and groups within a namespace. Cluster role bindings assign a cluster role to a set of users and groups cluster-wide.

RBAC configuration applies to sensuctl, the API, and the web UI.

Namespaces

Namespaces help teams use different resources (like entities, checks, and handlers) within Sensu and impose their own controls on those resources. A Sensu instance can have multiple namespaces, each with their own set of managed resources. Resource names must be unique within a namespace but do not need to be unique across namespaces.

To create and manage namespaces, configure sensuctl as the default admin user or create a cluster role with namespaces permissions.

Default namespaces

Every Sensu backend includes a default namespace. All resources created without a specified namespace are created within the default namespace.

Manage namespaces

You can use sensuctl to view, create, and delete namespaces. To get help with managing namespaces with sensuctl:

sensuctl namespace help

View namespaces

You can use sensuctl to view all namespaces within Sensu:

sensuctl namespace list

Create namespaces

You can use sensuctl to create a namespace. For example, the following command creates a namespace called production:

sensuctl namespace create production

Namespace names can contain alphanumeric characters and hyphens and must begin and end with an alphanumeric character.

Delete namespaces

To delete a namespace:

sensuctl namespace delete [NAMESPACE-NAME]

Assign a resource to a namespace

You can assign a resource to a namespace in the resource definition. Only resources that belong to a namespaced resource type (like checks, filters, and handlers) can be assigned to a namespace.

For example, to assign a check called check-cpu to the production namespace, include the namespace attribute in the check definition:

type: CheckConfig
api_version: core/v2
metadata:
  name: check-cpu
  namespace: production
spec:
  check_hooks: null
  command: check-cpu.sh -w 75 -c 90
  handlers:
  - slack
  interval: 30
  subscriptions:
  - system
  timeout: 0
  ttl: 0

{
  "type": "CheckConfig",
  "api_version": "core/v2",
  "metadata": {
    "name": "check-cpu",
    "namespace": "production"
  },
  "spec": {
    "check_hooks": null,
    "command": "check-cpu.sh -w 75 -c 90",
    "handlers": ["slack"],
    "interval": 30,
    "subscriptions": ["system"],
    "timeout": 0,
    "ttl": 0
  }
}

See the reference docs for the corresponding resource type to create resource definitions.

Namespace specification

Attributes

"name": "production"

Namespace example

This example is in yml and wrapped-json formats for use with sensuctl create:

type: Namespace
api_version: core/v2
metadata: {}
spec:
  name: default

{
  "type": "Namespace",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "name": "default"
  }
}

Resources

Permissions within Sensu are scoped to resource types, like checks, handlers, and users. You can use resource types to configure permissions in Sensu roles and cluster roles.

Namespaced resource types

Namespaced resources must belong to a single namespace. You can access namespaced resources by roles and cluster roles.

Cluster-wide resource types

Cluster-wide resources cannot be assigned to a namespace. You can access cluster-wide resources only by cluster roles.

Special resource types

You can access special resource types by both roles and cluster roles.

Users

A user represents a person or an agent that interacts with Sensu. You can assign users and groups to one or more roles. Users and groups inherit all permissions from each role assigned to them.

Use your Sensu username and password to configure sensuctl or log in to the web UI.

Default users

During the Sensu backend installation process, you create an administrator username and password and a default namespace.

This is the admin user that you can use to manage all aspects of Sensu and create new users.

After you configure sensuctl, you can change the admin user’s password with the change-password command.

Sensu also includes an agent user, which is used internally by the Sensu agent. You can configure agent user credentials with the user and password agent configuration flags.

Manage users

To test the password for a user created with Sensu’s built-in basic authentication:

sensuctl user test-creds USERNAME --password 'password'

An empty response indicates valid credentials. A request-unauthorized response indicates invalid credentials.

To change the password for a user:

sensuctl user change-password USERNAME --current-password CURRENT_PASSWORD --new-password NEW_PASSWORD

You can also use sensuctl to reset a user’s password or generate a password hash.

To disable a user:

sensuctl user disable USERNAME

To re-enable a disabled user:

sensuctl user reinstate USERNAME

View users

You can use sensuctl to see a list of all users within Sensu.

To return a list of users in yaml format for use with sensuctl create:

sensuctl user list --format yaml

Create users

You can use sensuctl to create users. For example, the following command creates a user with the username alice, creates a password, and assigns the user to the ops and dev groups.

Passwords must have at least eight characters.

sensuctl user create alice --password='password' --groups=ops,dev

Assign user permissions

To assign permissions to a user:

1. Create the user.
2. Create a role (or a cluster role for cluster-wide access).
3. Create a role binding (or cluster role binding) to assign the role to the user.

User specification

Attributes

"username": "alice"

"password": "USER_PASSWORD"

"groups": ["dev", "ops"]

"disabled": false

"password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm"

User example

The following example is in yml and wrapped-json formats for use with sensuctl create.

type: User
api_version: core/v2
metadata: {}
spec:
  disabled: false
  groups:
  - ops
  - dev
  password: USER_PASSWORD
  password_hash: $5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm
  username: alice

{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "username": "alice",
    "password": "USER_PASSWORD",
    "password_hash": "$5f$14$.brXRviMZpbaleSq9kjoUuwm67V/s4IziOLGHjEqxJbzPsreQAyNm",
    "disabled": false,
    "groups": ["ops", "dev"]
  }
}

Groups

A group is a set of users within Sensu. You can assign groups to one or more roles, and you can assign users to one or more groups. Groups inherit all permissions from each role assigned to them.

Groups are not a resource type within Sensu. You can create and manage groups only within user definitions.

Default groups

Sensu includes a default cluster-admins group that contains the default admin user and a system:agents group used internally by Sensu agents.

Manage groups

Assign a user to a group

Groups are created and managed within user definitions. You can use sensuctl to add users to groups.

To add a user to a group:

sensuctl user add-group USERNAME GROUP

To set the groups for a user:

sensuctl user set-groups USERNAME GROUP1[,GROUP2, ...[,GROUPN]]

Remove a user from a group

You can use sensuctl to remove users from groups.

To remove a user from a group:

sensuctl user remove-group USERNAME GROUP

To remove a user from all groups:

sensuctl user remove-groups USERNAME

Roles and cluster roles

A role is a set of permissions that control access to Sensu resources. Roles specify permissions for resources within a namespace. Cluster role can include permissions for cluster-wide resources.

You can use role bindings to assign roles to user and groups. To avoid recreating commonly used roles in each namespace, create a cluster role and use a role binding (not a cluster role binding) to restrict permissions within a specific namespace.

To create and manage roles cluster-wide, configure sensuctl as the default admin user or create a cluster role with roles permissions. To create and manage roles within a namespace, create a role with roles permissions within that namespace.

Cluster roles

Cluster roles can specify access permissions for cluster-wide resources like users and namespaces as well as namespaced resources like checks and handlers. They can also be used to grant access to namespaced resources across all namespaces (for example, to run sensuctl check list --all-namespaces) when used in conjunction with cluster role bindings.

Cluster roles use the same specification as roles and can be managed using the same sensuctl commands with cluster-role substituted for role.

To create and manage cluster roles, configure sensuctl as the default admin user or create a cluster role with permissions for clusterroles.

Default roles

Every Sensu backend includes:

Manage roles and cluster roles

You can use sensuctl to view, create, edit, and delete roles and cluster roles.

To get help managing roles with sensuctl:

sensuctl role help

To edit a role:

sensuctl edit role [ROLE-NAME] [flags]

View roles and cluster roles

You can use sensuctl to see a list of roles within Sensu:

sensuctl role list

To see the permissions and scope for a specific role:

sensuctl role info admin

To view cluster roles, use the cluster-role command:

sensuctl cluster-role list

Create roles

You can use sensuctl to create a role. For example, the following command creates an admin role restricted to the production namespace.

sensuctl role create prod-admin --verb='get,list,create,update,delete' --resource='*' --namespace production

After you create a role, create a role binding (or cluster role binding) to assign the role to users and groups. For example, to assign the prod-admin role created above to the oncall group, create this role binding:

sensuctl role-binding create prod-admin-oncall --role=prod-admin --group=oncall

Create cluster-wide roles

You can use sensuctl to create a cluster role. For example, the following command creates a global event reader role that can read only events across all namespaces within Sensu.

sensuctl cluster-role create global-event-reader --verb='get,list' --resource='events'

Delete roles and cluster roles

To delete a role:

sensuctl role delete [ROLE-NAME]

Role and cluster role specification

Role and cluster role attributes

"name": "admin"

"namespace": "production"

"rules": [
  {
    "verbs": ["get", "list"],
    "resources": ["checks"],
    "resource_names": [""]
  }
]

Rule attributes

A rule is an explicit statement that grants a particular permission to a resource.

"verbs": ["get", "list"]

"resources": ["checks"]

"resource_names": ["check-cpu"]

Role and cluster role examples

These examples are in yml and wrapped-json formats for use with sensuctl create.

Role example

type: Role
api_version: core/v2
metadata:
  name: namespaced-resources-all-verbs
  namespace: default
spec:
  rules:
  - resource_names: []
    resources:
    - assets
    - checks
    - entities
    - events
    - filters
    - handlers
    - hooks
    - mutators
    - rolebindings
    - roles
    - silenced
    verbs:
    - get
    - list
    - create
    - update
    - delete

{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "namespaced-resources-all-verbs",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resource_names": [],
        "resources": [
          "assets", "checks", "entities", "events", "filters", "handlers",
          "hooks", "mutators", "rolebindings", "roles", "silenced"
        ],
        "verbs": ["get", "list", "create", "update", "delete"]
      }
    ]
  }
}

Cluster role example

type: ClusterRole
api_version: core/v2
metadata:
  name: all-resources-all-verbs
spec:
  rules:
  - resource_names: []
    resources:
    - assets
    - checks
    - entities
    - events
    - filters
    - handlers
    - hooks
    - mutators
    - rolebindings
    - roles
    - silenced
    - cluster
    - clusterrolebindings
    - clusterroles
    - namespaces
    - users
    - authproviders
    - license
    verbs:
    - get
    - list
    - create
    - update
    - delete

{
  "type": "ClusterRole",
  "api_version": "core/v2",
  "metadata": {
    "name": "all-resources-all-verbs"
  },
  "spec": {
    "rules": [
      {
        "resource_names": [],
        "resources": [
          "assets", "checks", "entities", "events", "filters", "handlers",
          "hooks", "mutators", "rolebindings", "roles", "silenced",
          "cluster", "clusterrolebindings", "clusterroles",
          "namespaces", "users", "authproviders", "license"
        ],
        "verbs": ["get", "list", "create", "update", "delete"]
      }
    ]
  }
}

Role bindings and cluster role bindings

A role binding assigns a role or cluster role to users and groups within a namespace. A cluster role binding assigns a cluster role to users and groups across namespaces and resource types.

Cluster role bindings use the same specification as role bindings and can be managed using the same sensuctl commands with cluster-role-binding substituted for role-binding.

To create and manage role bindings within a namespace, create a role with rolebindings permissions within that namespace, and log in by configuring sensuctl.

To create and manage cluster role bindings, configure sensuctl as the default admin user or create a cluster role with permissions for clusterrolebindings.

Make sure to include the groups prefix and username prefix for the authentication provider when creating Sensu role bindings and cluster role bindings. Without an assigned role or cluster role, users can sign in to the web UI but can’t access any Sensu resources. With the correct roles and bindings configured, users can log in to sensuctl and the web UI using their single-sign-on username and password (no prefixes required).

Manage role bindings and cluster role bindings

You can use sensuctl to view, create, and delete role bindings and cluster role bindings.

To get help managing role bindings with sensuctl:

sensuctl role-binding help

View role bindings and cluster role bindings

You can use sensuctl to see a list of role bindings within Sensu:

sensuctl role-binding list

To see the details for a specific role binding:

sensuctl role-binding info [BINDING-NAME]

To see a list of cluster role bindings:

sensuctl cluster-role-binding list

Create role bindings and cluster role bindings

You can use sensuctl to see a create a role binding that assigns a role:

sensuctl role-binding create [NAME] --role=NAME [--user=username] [--group=groupname]

To create a role binding that assigns a cluster role:

sensuctl role-binding create [NAME] --cluster-role=NAME [--user=username] [--group=groupname]

To create a cluster role binding:

sensuctl cluster-role-binding create [NAME] --cluster-role=NAME [--user=username] [--group=groupname]

Delete role bindings and cluster role bindings

To delete a role binding:

sensuctl role-binding delete [ROLE-NAME]

Role binding and cluster role binding specification

"roleRef": {
  "type": "Role",
  "name": "event-reader"
}

"subjects": [
  {
    "type": "User",
    "name": "alice"
  }
]

roleRef specification

"type": "Role"

"name": "event-reader"

subjects specification

"type": "User"

"name": "alice"

"name": "ad:alice"

Role binding and cluster role binding examples

These examples are in yml and wrapped-json formats for use with sensuctl create.

Role binding example

type: RoleBinding
api_version: core/v2
metadata:
  name: event-reader-binding
  namespace: default
spec:
  role_ref:
    name: event-reader
    type: Role
  subjects:
  - name: bob
    type: User

{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "event-reader-binding",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "event-reader",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "bob",
        "type": "User"
      }
    ]
  }
}

Cluster role binding example

type: ClusterRoleBinding
api_version: core/v2
metadata:
  name: cluster-admin
spec:
  role_ref:
    name: cluster-admin
    type: ClusterRole
  subjects:
  - name: cluster-admins
    type: Group

{
  "type": "ClusterRoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "cluster-admin"
  },
  "spec": {
    "role_ref": {
      "name": "cluster-admin",
      "type": "ClusterRole"
    },
    "subjects": [
      {
        "name": "cluster-admins",
        "type": "Group"
      }
    ]
  }
}

Role and role binding example

The following role and role binding give a dev group access to create and manage Sensu workflows within the default namespace.

{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "workflow-creator",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resource_names": [],
        "resources": ["checks", "hooks", "filters", "events", "filters", "mutators", "handlers"],
        "verbs": ["get", "list", "create", "update", "delete"]
      }
    ]
  }
}
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "dev-binding",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "workflow-creator",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "dev",
        "type": "Group"
      }
    ]
  }
}

Role and role binding example with a group prefix

In this example, if a groups_prefix of ad is configured for Active Directory authentication, the role and role binding will give a dev group access to create and manage Sensu workflows within the default namespace.

{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "workflow-creator",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resource_names": [],
        "resources": ["checks", "hooks", "filters", "events", "filters", "mutators", "handlers"],
        "verbs": ["get", "list", "create", "update", "delete"]
      }
    ]
  }
}
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "dev-binding-with-groups-prefix",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "workflow-creator",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "ad:dev",
        "type": "Group"
      }
    ]
  }
}

Example workflows

Assign user permissions within a namespace

To assign permissions to a user:

1. Create the user.
2. Create a role.
3. Create a role binding to assign the role to the user.

For example, the following configuration creates a user alice, a role default-admin, and a role binding alice-default-admin, giving alice full permissions for namespaced resource types within the default namespace. You can add these resources to Sensu using sensuctl create.

{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "disabled": false,
    "username": "alice"
  }
}
{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "default-admin",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resource_names": [],
        "resources": [
          "assets", "checks", "entities", "events", "filters", "handlers",
          "hooks", "mutators", "rolebindings", "roles", "searches", "silenced"
        ],
        "verbs": ["get", "list", "create", "update", "delete"]
      }
    ]
  }
}
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "alice-default-admin",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "default-admin",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "alice",
        "type": "User"
      }
    ]
  }
}

Assign group permissions within a namespace

To assign permissions to group of users:

1. Create at least one user assigned to a group.
2. Create a role.
3. Create a role binding to assign the role to the group.

For example, the following configuration creates a user alice assigned to the group ops, a role default-admin, and a role binding ops-default-admin, giving the ops group full permissions for namespaced resource types within the default namespace. You can add these resources to Sensu using sensuctl create.

{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "disabled": false,
    "username": "alice"
  }
}
{
  "type": "Role",
  "api_version": "core/v2",
  "metadata": {
    "name": "default-admin",
    "namespace": "default"
  },
  "spec": {
    "rules": [
      {
        "resource_names": [],
        "resources": [
          "assets", "checks", "entities", "events", "filters", "handlers",
          "hooks", "mutators", "rolebindings", "roles", "searches", "silenced"
        ],
        "verbs": ["get", "list", "create", "update", "delete"]
      }
    ]
  }
}
{
  "type": "RoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "ops-default-admin",
    "namespace": "default"
  },
  "spec": {
    "role_ref": {
      "name": "default-admin",
      "type": "Role"
    },
    "subjects": [
      {
        "name": "ops",
        "type": "Group"
      }
    ]
  }
}

Assign group permissions across all namespaces

To assign cluster-wide permissions to group of users:

1. Create at least one user assigned to a group.
2. Create a cluster role.
3. Create a cluster role binding) to assign the role to the group.

For example, the following configuration creates a user alice assigned to the group ops, a cluster role default-admin, and a cluster role binding ops-default-admin, giving the ops group full permissions for namespaced resource types and cluster-wide resource types across all namespaces. You can add these resources to Sensu using sensuctl create.

{
  "type": "User",
  "api_version": "core/v2",
  "metadata": {},
  "spec": {
    "disabled": false,
    "username": "alice",
    "groups": ["ops"]
  }
}
{
  "type": "ClusterRole",
  "api_version": "core/v2",
  "metadata": {
    "name": "default-admin"
  },
  "spec": {
    "rules": [
      {
        "resource_names": [],
        "resources": [
          "assets", "checks", "entities", "events", "filters", "handlers",
          "hooks", "mutators", "rolebindings", "roles", "silenced",
          "cluster", "clusterrolebindings", "clusterroles",
          "namespaces", "users", "authproviders", "license"
        ],
        "verbs": ["get", "list", "create", "update", "delete"]
      }
    ]
  }
}
{
  "type": "ClusterRoleBinding",
  "api_version": "core/v2",
  "metadata": {
    "name": "ops-default-admin"
  },
  "spec": {
    "role_ref": {
      "name": "default-admin",
      "type": "ClusterRole"
    },
    "subjects": [
      {
        "name": "ops",
        "type": "Group"
      }
    ]
  }
}