Authentication

Sensu requires username and password authentication to access the Sensu dashboard, API, and command line tool (sensuctl). For Sensu’s default user credentials and more information about configuring Sensu role based access control, see the RBAC reference and guide to creating users.

In addition to built-in RBAC, Sensu includes enterprise-only support for authentication using external authentication providers. Sensu currently supports Microsoft Active Directory and standards-compliant Lightweight Directory Access Protocol tools like OpenLDAP.

ENTERPRISE ONLY: Authentication providers in Sensu Go require an enterprise license. To activate your enterprise license, see the getting started guide.

Managing authentication providers

You can view and delete authentication providers using sensuctl and the authentication providers API. To set up an authentication provider for Sensu, see the section on configuring authentication providers.

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

Configuring authentication providers

1. Write an authentication provider configuration definition

Write an authentication provider configuration definition.

For standards-compliant Lightweight Directory Access Protocol tools like OpenLDAP, see the LDAP configuration examples and specification. For Microsoft Active Directory, see the AD configuration examples and specification.

2. Apply the configuration using sensuctl

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

sensuctl create --file filename.json

You can verify that your provider configuration has been applied successfully using sensuctl.

sensuctl auth list

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

3. Integrate with Sensu RBAC

Now that you’ve configured an authentication provider, you’ll need to configure Sensu RBAC to give those users permissions within Sensu. Sensu RBAC allows management and access of users and resources based on namespaces, groups, roles, and bindings.

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

To enable permissions for external users and groups within Sensu, create a set of roles, cluster roles, role bindings, and cluster role bindings that map to the usernames and group names found in your authentication providers. Make sure to include the group prefix and username prefix when creating Sensu role bindings and cluster role bindings. See the RBAC reference for more information about configuring permissions in Sensu and implementation examples.

4. Log in to Sensu

Once you’ve configured the correct roles and bindings, log in to sensuctl and the Sensu dashboard using your single-sign-on username and password (no prefix required).

LDAP authentication

Sensu offers enterprise-only support for using a standards-compliant Lightweight Directory Access Protocol tool for authentication to the Sensu dashboard, API, and sensuctl. The Sensu LDAP authentication provider is tested with OpenLDAP. Active Directory users should head over to the Active Directory section.

LDAP configuration examples

Example LDAP configuration: Minimum required attributes

{
  "Type": "ldap",
  "api_version": "authentication/v2",
  "spec": {
    "servers": [
      {
        "host": "127.0.0.1",
        "binding": {
          "user_dn": "cn=binder,dc=acme,dc=org",
          "password": "P@ssw0rd!"
        },
        "group_search": {
          "base_dn": "dc=acme,dc=org"
        },
        "user_search": {
          "base_dn": "dc=acme,dc=org"
        }
      }
    ]
  },
  "metadata": {
    "name": "openldap"
  }
}

Example LDAP configuration: All attributes

{
  "type": "ldap",
  "api_version": "authentication/v2",
  "spec": {
    "servers": [
      {
        "host": "127.0.0.1",
        "port": 636,
        "insecure": false,
        "security": "tls",
        "binding": {
          "user_dn": "cn=binder,dc=acme,dc=org",
          "password": "P@ssw0rd!"
        },
        "group_search": {
          "base_dn": "dc=acme,dc=org",
          "attribute": "member",
          "name_attribute": "cn",
          "object_class": "groupOfNames"
        },
        "user_search": {
          "base_dn": "dc=acme,dc=org",
          "attribute": "uid",
          "name_attribute": "cn",
          "object_class": "person"
        }
      }
    ],
    "groups_prefix": "ldap",
    "username_prefix": "ldap"
  },
  "metadata": {
    "name": "openldap"
  }
}

LDAP specification

Top-level attributes

type
description Top-level attribute specifying the sensuctl create resource type. LDAP definitions should always be of type ldap.
required true
type String
example
"type": "ldap"
api_version
description Top-level attribute specifying the Sensu API group and version. For LDAP definitions, this attribute should always be authentication/v2.
required true
type String
example
"api_version": "authentication/v2"
metadata
description Top-level map containing the LDAP definition name. See the metadata attributes reference for details.
required true
type Map of key-value pairs
example
"metadata": {
  "name": "openldap"
}
spec
description Top-level map that includes the LDAP spec attributes.
required true
type Map of key-value pairs
example
"spec": {
  "servers": [
    {
      "host": "127.0.0.1",
      "binding": {
        "user_dn": "cn=binder,dc=acme,dc=org",
        "password": "P@ssw0rd!"
      },
      "group_search": {
        "base_dn": "dc=acme,dc=org"
      },
      "user_search": {
        "base_dn": "dc=acme,dc=org"
      }
    }
  ]
}

Spec attributes

servers
description An array of LDAP servers for your directory. During the authentication process, Sensu attempts to authenticate using each LDAP server in sequence.
required true
type Array
example
"servers": [
  {
    "host": "127.0.0.1",
    "binding": {
      "user_dn": "cn=binder,dc=acme,dc=org",
      "password": "P@ssw0rd!"
    },
    "group_search": {
      "base_dn": "dc=acme,dc=org"
    },
    "user_search": {
      "base_dn": "dc=acme,dc=org"
    }
  }
]

groups_prefix
description The prefix added to all LDAP groups. Sensu prepends prefixes with a colon. For example, for the groups prefix ldap and the group dev, the resulting group name in Sensu is ldap:dev. Use this prefix when integrating LDAP groups with Sensu RBAC role bindings and cluster role bindings.
required false
type String
example
"groups_prefix": "ldap"

username_prefix
description The prefix added to all LDAP usernames. Sensu prepends prefixes with a colon. For example, for the username prefix ldap and the user alice, the resulting username in Sensu is ldap:alice. Use this prefix when integrating LDAP users with Sensu RBAC role bindings and cluster role bindings. Users do not need to provide this prefix when logging in to Sensu.
required false
type String
example
"username_prefix": "ldap"

Server attributes

host
description LDAP server IP address or FQDN
required true
type String
example
"host": "127.0.0.1"
port
description LDAP server port
required true
type Integer
default 389 for insecure connections, 636 for TLS connections
example
"port": 636
insecure
description Skips SSL certificate verification when set to true. WARNING: Do not use an insecure connection in production environments.
required false
type Boolean
default false
example
"insecure": false
security
description Determines the encryption type to be used for the connection to the LDAP server: insecure (unencrypted connection, not recommended for production), tls (secure encrypted connection), or starttls (unencrypted connection upgrades to a secure connection).
type String
default "tls"
example
"security": "tls"
binding
description The LDAP account that performs user and group lookups.
required true
type Map
example
"binding": {
  "user_dn": "cn=binder,dc=acme,dc=org",
  "password": "P@ssw0rd!"
}
group_search
description Search configuration for groups. See the group search attributes for more information.
required true
type Map
example
"group_search": {
  "base_dn": "dc=acme,dc=org",
  "attribute": "member",
  "name_attribute": "cn",
  "object_class": "groupOfNames"
}
user_search
description Search configuration for users. See the user search attributes for more information.
required true
type Map
example
"user_search": {
  "base_dn": "dc=acme,dc=org",
  "attribute": "uid",
  "name_attribute": "cn",
  "object_class": "person"
}

Binding attributes

user_dn
description The LDAP account that performs user and group lookups. We recommend using a read-only account. Use the distinguished name (DN) format, such as cn=binder,cn=users,dc=domain,dc=tld.
required true
type String
example
"user_dn": "cn=binder,dc=acme,dc=org"
password
description Password for the user_dn account.
required true
type String
example
"password": "P@ssw0rd!"

Group search attributes

base_dn
description Tells Sensu which part of the directory tree to search. For example, dc=acme,dc=org searches within the acme.org directory.
required true
type String
example
"base_dn": "dc=acme,dc=org"
attribute
description Used for comparing result entries. This is combined with other filters as
"(<Attribute>=<value>)".
required false
type String
default "member"
example
"attribute": "member"
name_attribute
description Represents the attribute to use as the entry name.
required false
type String
default "cn"
example
"name_attribute": "cn"
object_class
description Identifies the class of objects returned in the search result. This is combined with other filters as "(objectClass=<ObjectClass>)".
required false
type String
default "groupOfNames"
example
"object_class": "groupOfNames"

User search attributes

base_dn
description Tells Sensu which part of the directory tree to search. For example, dc=acme,dc=org searches within the acme.org directory.
required true
type String
example
"base_dn": "dc=acme,dc=org"
attribute
description Used for comparing result entries. This is combined with other filters as
"(<Attribute>=<value>)".
required false
type String
default "uid"
example
"attribute": "uid"
name_attribute
description Represents the attribute to use as the entry name.
required false
type String
default "cn"
example
"name_attribute": "cn"
object_class
description Identifies the class of objects returned in the search result. This is combined with other filters as "(objectClass=<ObjectClass>)".
required false
type String
default "person"
example
"object_class": "person"

Metadata attributes

name
description A unique string used to identify the LDAP configuration. Names cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z).
required true
type String
example
"name": "openldap"

LDAP troubleshooting

In order to troubleshoot any issue with LDAP authentication, the first step should always be to increase log verbosity of sensu-backend to the debug log level. Most authentication and authorization errors are only displayed on the debug log level, in order to avoid flooding the log files.

NOTE: If you can’t locate any log entries referencing LDAP authentication, make sure the LDAP provider was successfully installed using sensuctl

Authentication errors

Here are some common error messages and possible solutions:

Error message: failed to connect: LDAP Result Code 200 "Network Error"

The LDAP provider couldn’t establish a TCP connection to the LDAP server. Verify the host & port attributes. If you are not using LDAP over TLS/SSL , make sure to set the value of the security attribute to "insecure" for plaintext communication.

Error message: certificate signed by unknown authority

If you are using a self-signed certificate, make sure to set the insecure attribute to true. This will bypass verification of the certificate’s signing authority.

Error message: failed to bind: ...

The first step for authenticating a user with the LDAP provider is to bind to the LDAP server using the service account specified in the binding object. Make sure the user_dn specifies a valid DN, and its password is the right one.

Error message: user <username> was not found

The user search failed, no user account could be found with the given username. Go look at the user_search object and make sure that:

  • The specified base_dn contains the requested user entry DN
  • The specified attribute contains the username as its value in the user entry
  • The object_class attribute corresponds to the user entry object class

Error message: ldap search for user <username> returned x results, expected only 1

The user search returned more than one user entry, therefore the provider could not determine which of these entries should be used. The user_search object needs to be tweaked so the provided username can be used to uniquely identify a user entry. Here’s few possible way of doing it:

  • Adjust the attribute so its value (which corresponds to the username) is unique amongst the user entries
  • Adjust the base_dn so it only includes one of the user entries

Error message: ldap entry <DN> missing required attribute <name_attribute>

The user entry returned (identified by <DN>) doesn’t include the attribute specified by name_attribute object. Therefore the LDAP provider could not determine which attribute to use as the username in the user entry. The name_attribute should be adjusted so it specifies a human friendly name for the user.

Error message: ldap group entry <DN> missing <name_attribute> and cn attributes

The group search returned a group entry (identified by <DN>) that doesn’t have the name_attribute attribute nor a cn attribute. Therefore the LDAP provider could not determine which attribute to use as the group name in the group entry. The name_attribute should be adjusted so it specifies a human friendly name for the group.

Authorization issues

Once authenticated, a user needs to be granted permissions via either a ClusterRoleBinding or a RoleBinding.

The way in which LDAP users and LDAP groups can be referred as subjects of a cluster role or role binding depends on the groups_prefix and username_prefix configuration attributes values of the LDAP provider. For example, for the groups prefix ldap and the group dev, the resulting group name in Sensu is ldap:dev.

Issue: Permissions are not granted via the LDAP group(s)

During authentication, the LDAP provider will print in the logs all groups found in LDAP, e.g. found 1 group(s): [dev]. Keep in mind that this group name does not contain the groups_prefix at this point.

The Sensu backend logs each attempt made to authorize an RBAC request. This is useful for determining why a specific binding didn’t grant the request. For example:

[...] the user is not a subject of the ClusterRoleBinding cluster-admin [...]
[...] could not authorize the request with the ClusterRoleBinding system:user [...]
[...] could not authorize the request with any ClusterRoleBindings [...]

Active Directory authentication

Sensu offers enterprise-only support for using Microsoft Active Directory (AD) for authentication to the Sensu dashboard, API, and sensuctl. The AD authentication provider is based on the LDAP authentication provider.

Active Directory configuration examples

Example AD configuration: Minimum required attributes

{
  "Type": "ad",
  "api_version": "authentication/v2",
  "spec": {
    "servers": [
      {
        "host": "127.0.0.1",
        "binding": {
          "user_dn": "cn=binder,cn=users,dc=acme,dc=org",
          "password": "P@ssw0rd!"
        },
        "group_search": {
          "base_dn": "dc=acme,dc=org"
        },
        "user_search": {
          "base_dn": "dc=acme,dc=org"
        }
      }
    ]
  },
  "metadata": {
    "name": "activedirectory"
  }
}

Example AD configuration: All attributes

{
  "type": "ad",
  "api_version": "authentication/v2",
  "spec": {
    "servers": [
      {
        "host": "127.0.0.1",
        "port": 636,
        "insecure": false,
        "security": "tls",
        "binding": {
          "user_dn": "cn=binder,cn=users,dc=acme,dc=org",
          "password": "P@ssw0rd!"
        },
        "group_search": {
          "base_dn": "dc=acme,dc=org",
          "attribute": "member",
          "name_attribute": "cn",
          "object_class": "group"
        },
        "user_search": {
          "base_dn": "dc=acme,dc=org",
          "attribute": "sAMAccountName",
          "name_attribute": "displayName",
          "object_class": "person"
        }
      }
    ],
    "groups_prefix": "ad",
    "username_prefix": "ad"
  },
  "metadata": {
    "name": "activedirectory"
  }
}

Active Directory specification

Top-level attributes

type
description Top-level attribute specifying the sensuctl create resource type. AD definitions should always be of type ad.
required true
type String
example
"type": "ad"
api_version
description Top-level attribute specifying the Sensu API group and version. For AD definitions, this attribute should always be authentication/v2.
required true
type String
example
"api_version": "authentication/v2"
metadata
description Top-level map containing the AD definition name. See the metadata attributes reference for details.
required true
type Map of key-value pairs
example
"metadata": {
  "name": "activedirectory"
}
spec
description Top-level map that includes the AD spec attributes.
required true
type Map of key-value pairs
example
"spec": {
  "servers": [
    {
      "host": "127.0.0.1",
      "binding": {
        "user_dn": "cn=binder,cn=users,dc=acme,dc=org",
        "password": "P@ssw0rd!"
      },
      "group_search": {
        "base_dn": "dc=acme,dc=org"
      },
      "user_search": {
        "base_dn": "dc=acme,dc=org"
      }
    }
  ]
}

Active Directory spec attributes

servers
description An array of AD servers for your directory. During the authentication process, Sensu attempts to authenticate using each AD server in sequence.
required true
type Array
example
"servers": [
  {
    "host": "127.0.0.1",
    "binding": {
      "user_dn": "cn=binder,cn=users,dc=acme,dc=org",
      "password": "P@ssw0rd!"
    },
    "group_search": {
      "base_dn": "dc=acme,dc=org"
    },
    "user_search": {
      "base_dn": "dc=acme,dc=org"
    }
  }
]

groups_prefix
description The prefix added to all AD groups. Sensu prepends prefixes with a colon. For example, for the groups prefix ad and the group dev, the resulting group name in Sensu is ad:dev. Use this prefix when integrating AD groups with Sensu RBAC role bindings and cluster role bindings.
required false
type String
example
"groups_prefix": "ad"

username_prefix
description The prefix added to all AD usernames. Sensu prepends prefixes with a colon. For example, for the username prefix ad and the user alice, the resulting username in Sensu is ad:alice. Use this prefix when integrating AD users with Sensu RBAC role bindings and cluster role bindings. Users do not need to provide this prefix when logging in to Sensu.
required false
type String
example
"username_prefix": "ad"

Active Directory server attributes

host
description AD server IP address or FQDN
required true
type String
example
"host": "127.0.0.1"
port
description AD server port
required true
type Integer
default 389 for insecure connections, 636 for TLS connections
example
"port": 636
insecure
description Skips SSL certificate verification when set to true. WARNING: Do not use an insecure connection in production environments.
required false
type Boolean
default false
example
"insecure": false
security
description Determines the encryption type to be used for the connection to the AD server: insecure (unencrypted connection, not recommended for production), tls (secure encrypted connection), or starttls (unencrypted connection upgrades to a secure connection).
type String
default "tls"
example
"security": "tls"
binding
description The AD account that performs user and group lookups.
required true
type Map
example
"binding": {
  "user_dn": "cn=binder,cn=users,dc=acme,dc=org",
  "password": "P@ssw0rd!"
}
group_search
description Search configuration for groups. See the group search attributes for more information.
required true
type Map
example
"group_search": {
  "base_dn": "dc=acme,dc=org",
  "attribute": "member",
  "name_attribute": "cn",
  "object_class": "group"
}
user_search
description Search configuration for users. See the user search attributes for more information.
required true
type Map
example
"user_search": {
  "base_dn": "dc=acme,dc=org",
  "attribute": "sAMAccountName",
  "name_attribute": "displayName",
  "object_class": "person"
}

Active Directory binding attributes

user_dn
description The AD account that performs user and group lookups. We recommend using a read-only account. Use the distinguished name (DN) format, such as cn=binder,cn=users,dc=domain,dc=tld.
required true
type String
example
"user_dn": "cn=binder,cn=users,dc=acme,dc=org"
password
description Password for the user_dn account.
required true
type String
example
"password": "P@ssw0rd!"

Active Directory group search attributes

base_dn
description Tells Sensu which part of the directory tree to search. For example, dc=acme,dc=org searches within the acme.org directory.
required true
type String
example
"base_dn": "dc=acme,dc=org"
attribute
description Used for comparing result entries. This is combined with other filters as
"(<Attribute>=<value>)".
required false
type String
default "member"
example
"attribute": "member"
name_attribute
description Represents the attribute to use as the entry name.
required false
type String
default "cn"
example
"name_attribute": "cn"
object_class
description Identifies the class of objects returned in the search result. This is combined with other filters as "(objectClass=<ObjectClass>)".
required false
type String
default "group"
example
"object_class": "group"

Active Directory user search attributes

base_dn
description Tells Sensu which part of the directory tree to search. For example, dc=acme,dc=org searches within the acme.org directory.
required true
type String
example
"base_dn": "dc=acme,dc=org"
attribute
description Used for comparing result entries. This is combined with other filters as
"(<Attribute>=<value>)".
required false
type String
default "sAMAccountName"
example
"attribute": "sAMAccountName"
name_attribute
description Represents the attribute to use as the entry name.
required false
type String
default "displayName"
example
"name_attribute": "displayName"
object_class
description Identifies the class of objects returned in the search result. This is combined with other filters as "(objectClass=<ObjectClass>)".
required false
type String
default "person"
example
"object_class": "person"

Active Directory metadata attributes

name
description A unique string used to identify the AD configuration. Names cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z).
required true
type String
example
"name": "activedirectory"

Active Directory troubleshooting

See the LDAP troubleshooting section.