Control Access

Sensu administrators control access by authentication and authorization.

Authentication verifies user identities to confirm that users are who they say they are. Sensu requires username and password authentication to access the web UI, API, and sensuctl command line tool. You can use Sensu’s built-in basic authentication provider or configure external authentication providers.

NOTE: For API-specific authentication, see the API overview and Use API keys to authenticate to Sensu.

Authorization establishes and manages user permissions: the extent of access users have for different Sensu resources. Configure authorization with role-based access control (RBAC) to exercise fine-grained control over how they interact with Sensu resources.


Sensu web UI and sensuctl command line tool users can authenticate via built-in basic authentication provider or Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC) when external authentication providers are configured by the administrator.

Sensu agents authenticate to the Sensu backend using either basic or mutual transport layer security (TLS) authentication.

Use built-in basic authentication

Sensu’s built-in basic authentication provider allows you to create and manage user credentials (usernames and passwords) with the users API, either directly or using sensuctl. The basic authentication provider does not depend on external services and is not configurable.

Sensu hashes user passwords using the bcrypt algorithm and records the basic authentication credentials in etcd.

Use an authentication provider

COMMERCIAL FEATURE: Access authentication providers in the packaged Sensu Go distribution. For more information, see Get started with commercial features.

In addition to built-in authentication, Sensu includes commercial support for authentication using external authentication providers via Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC).

Configure authentication providers

1. Write an authentication provider configuration definition

Save your configuration definition to a file, such as authconfig.yaml or authconfig.json.

2. Apply the configuration with sensuctl

Log in to sensuctl as the default admin user and use sensuctl to apply the configuration to Sensu:

sensuctl create --file authconfig.yml
sensuctl create --file authconfig.json

Use sensuctl to verify that your provider configuration was applied successfully:

sensuctl auth list

The response will list your authentication provider types and names:

 Type     Name    
────── ────────── 
 ldap   openldap  

Manage authentication providers

View and delete authentication providers with the authentication providers API or these sensuctl commands.

To view active authentication providers:

sensuctl auth list

To view configuration details for an authentication provider named openldap:

sensuctl auth info openldap

To delete an authentication provider named openldap:

sensuctl auth delete openldap


After you set up authentication, configure authorization via role-based access control (RBAC) to give those users permissions within Sensu. 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. See Create a read-only user for an example.

  • Namespaces partition resources within Sensu. Sensu entities, checks, handlers, and other namespaced resources belong to a single namespace.
  • Roles create sets of permissions (like GET and DELETE) tied to resource types. Cluster roles apply permissions across all namespaces and may include access to cluster-wide resources like users and namespaces.
  • 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 across all namespaces.

To enable permissions for external users and groups within Sensu, you can create a set of roles, cluster roles, role bindings, and cluster role bindings that map to the usernames and group names in your authentication provider.

After you configure an authentication provider and establish the roles and bindings to grant authenticated users the desired privileges, those users can log in via sensuctl and the web UI using a single-sign-on username and password. Users do not need to provide the username prefix for the authentication provider when logging in to Sensu.