ENTERPRISE: Role based access controls are available for Sensu Enterprise users only.

Role Based Access Controls

Reference Documentation

What are Role Based Access Controls for Sensu Enterprise?

Role-based access controls (RBAC) are a system for restricting access to authorized users according to a role, or job function. RBAC for Sensu Enterprise enables administrators to grant the correct level access to many different development and operations teams, without requiring them to maintain yet another user registry.

How does Sensu provide RBAC?

The Sensu Enterprise Dashboard provides comprehensive and granular Role-Based Access Controls (RBAC), with support for using a Lightweight Access Directory Provider (LDAP), GitHub.com, GitHub Enterprise, and/or GitLab for authentication. Roles can be defined to grant or restrict access to monitoring data based on datacenters, Sensu subscriptions, and even specific API endpoints (see the Enterprise API reference documentation for more information).

Supported RBAC drivers

Sensu Enterprise currently includes the following authentication drivers for RBAC:

RBAC for the Sensu Enterprise Console API

As of Sensu Enterprise Dashboard version 1.12, RBAC configurations may be applied to the Sensu Enterprise Console API. Access to the Sensu Enterprise Console API is controlled by access tokens, which correspond to a role definition (see the roles specification accessToken attribute, below). RBAC for the Console API provides granular controls for restricting access to specific API endpoints and HTTP methods (e.g. it is possible to allow HTTP GET access to the Clients API, but not DELETE access; see the roles specification methods attribute, below).

Providing an access token

In a header:

$ curl -H "Authorization: token TOKEN" https://localhost:3000/events

As a parameter:

$ curl https://localhost:3000/events?token=TOKEN

RBAC configuration

Example RBAC definition

The following is an example RBAC configuration using the RBAC for LDAP authentication driver, a JSON configuration file located at /etc/sensu/dashboard.json.

{
  "dashboard": {
    "host": "0.0.0.0",
    "port": 3000,
    "...": "",
    "ldap": {
      "server": "localhost",
      "port": 389,
      "basedn": "cn=users,dc=domain,dc=tld",
      "binduser": "cn=binder,cn=users,dc=domain,dc=tld",
      "bindpass": "secret",
      "roles": [
        {
          "name": "guests",
          "members": [
            "guests_group"
          ],
          "datacenters": [
            "us-west-1"
          ],
          "subscriptions": [
            "webserver"
          ],
          "readonly": true
        },
        {
          "name": "operators",
          "members": [
            "operators_group"
          ],
          "datacenters": [],
          "subscriptions": [],
          "readonly": false
        }
      ]
    }
  }
}

RBAC definition specification

DRIVER attributes

Role based access controls for Sensu Enterprise are configured within the { "dashboard": { "DRIVER": {} } } configuration scope, where DRIVER is one of the following:

roles attributes

Role attributes are defined within the corresponding RBAC DRIVER configuration scope; e.g.: { "dashboard": { "DRIVER": { "roles": [] } } }. The roles attribute is always a JSON array (i.e. "roles": []), containing JSON hashes of role definitions. The following role definition specification is common across all RBAC drivers.

EXAMPLE
{
  "dashboard": {
    "...": "...",
    "ldap": {
      "...": "...",
      "roles": [
        {
          "name": "example_role",
          "members": ["example_group"],
          "datacenters": [],
          "subscriptions": ["example_application"],
          "readonly": false
        }
      ]
    }
  }
}
ATTRIBUTES
name
description
The name of the role.
required
true
type
String
example
"name": "operators"
members
description
An array of the LDAP groups, GitHub Teams, or GitLab Groups that should be included as members of the role.
required
true (unless fallback is true)
type
Array
allowed values
Any LDAP group name, GitHub organization/team pair, or GitLab Group name. NOTE: For LDAP group names, Sensu Enterprise supports the following LDAP group object classes: group, groupOfNames, groupOfUniqueNames and posixGroup. NOTE: A GitHub Team with a URL of github.com/orgs/sensu/teams/docs would be entered as sensu/docs. NOTE: A GitLab Group with a URL of gitlab.com/groups/heavywater would be entered as heavywater.
example
"members": [
  "myorganization/devs",
  "myorganization/ops"
]
fallback
description
Sets the role as a fallback role, which is assigned to users that are successfully authenticated but not authorized by any other role. NOTE: Only a single fallback role can be defined. NOTE: The fallback attribute can’t be used in conjunction with the the members attribute.
required
true (unless members is defined)
type
Boolean
default
false
example
"fallback": true
datacenters
description
An array of the datacenters (i.e. matching a defined Sensu API endpoint name value) that members of the role should have access to. Provided values will be used to filter which datacenters members of the role will have access to. NOTE: omitting this configuration attribute or providing an empty array will allow members of the role access to all configured datacenters.
required
false
type
Array
example
"datacenters": [
  "us-west-1",
  "us-west-2"
]
subscriptions
description
An array of the subscriptions that members of the role should have access to. Provided values will be used to filter which subscriptions members of the role will have access to. NOTE: omitting this configuration attribute or providing an empty array will allow members of the role access to all subscriptions.
required
false
type
Array
example
"subscriptions": [
  "webserver"
]
readonly
description
Used to restrict “write” access (i.e. preventing members of the role from being able to create stashes, silence checks, etc).
required
false
type
Boolean
default
false
example
"readonly": true
accessToken
description
A unique token for authenticating against the Sensu Enterprise Console API as a member of that role.
required
false
type
String
allowed values
any length string that only contains URL-friendly characters. PRO TIP: we recommend using a random string generator for access tokens; e.g.:
openssl rand -base64 40 | tr -- '+=/' '-_~'.
example
"accessToken": "OrIXC7ezuq0AZKoRHhf~oIl-98dX5B23hf8KudfcqJt5eTeQjDDGDQ__"
methods
description
The methods definition scope, used to configure access to the Sensu Enterprise Console API.
required
false
type
Hash
example
"methods": {
  "head": [
    "none"
  ],
  "get": [],
  "post": [
    "results",
    "stashes"
  ],
  "delete": [
    "stashes"
  ]
}

methods attributes

Sensu Enterprise Console API access controls may be fine tuned using the { "dashboard": { "DRIVER": { "roles": [ { "methods": {} } ] } } } configuration scope.

EXAMPLE
{
  "dashboard": {
    "...": "...",
    "ldap": {
      "...": "...",
      "roles": [
        {
          "name": "example_role",
          "members": ["example_group"],
          "datacenters": [],
          "subscriptions": ["example_application"],
          "accessToken": "j3sJ8itFn9d9ooFYdN9erW3ZN6i8C9V3",
          "methods": {
            "get": [],
            "post": [
              "clients",
              "stashes"
            ],
            "delete": [
              "none"
            ]
          }
        }
      ]
    }
  }
}
SPECIFICATION
get
description
Used to configure HTTP GET access to one or more Sensu Enterprise Console API endpoints.
required
false
type
Array of Strings
allowed values
aggregates, checks, clients, events, results, stashes, subscriptions, and datacenters.
default
[] (an empty array, which is equivalent to “allow all”)
example
"methods": {
  "get": [
    "clients",
    "checks",
    "events"
  ]
}
post
description
Used to configure HTTP POST access to one or more Sensu Enterprise Console API endpoints.
required
false
type
Array of Strings
allowed values
aggregates, checks, clients, events, results, stashes, subscriptions, and datacenters.
default
[] (an empty array, which is equivalent to “allow all”)
example
"methods": {
  "post": [
    "clients",
    "checks",
    "events"
  ]
}
delete
description
Used to configure HTTP DELETE access to one or more Sensu Enterprise Console API endpoints.
required
false
type
Array of Strings
allowed values
aggregates, checks, clients, events, results, stashes, subscriptions, and datacenters.
default
[] (an empty array, which is equivalent to “allow all”)
example
"methods": {
  "delete": [
    "clients",
    "checks",
    "events"
  ]
}
head
description
Used to configure HTTP HEAD access to one or more Sensu Enterprise Console API endpoints.
required
false
type
Array of Strings
allowed values
aggregates, checks, clients, events, results, stashes, subscriptions, and datacenters.
default
[] (an empty array, which is equivalent to “allow all”)
example
"methods": {
  "head": [
    "clients",
    "checks",
    "events"
  ]
}

Start your FREE trial today.

Already using Sensu Core? Upgrade to Sensu Enterprise today to take advantage of its enterprise console, added-value features, built-in integrations, FREE annual training, and enterprise-class support.