Role Based Access Controls

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

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
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"
]
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__"
fallback
description Used to give an authenticated user the attributes defined in that role if that user is not found in any other defined dashboard role.
required false
type Boolean
default false
example
{
  "name": "readonly_fallback",
  "datacenters": [],
  "subscriptions": [],
  "fallback": true,
  "readonly": true
}
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"
  ]
}