Configure Active Directory (AD) authentication to access Sensu

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

Sensu requires username and password authentication to access the web UI, API, and sensuctl command line tool.

In addition to the built-in basic authentication provider, Sensu offers commercial support for using Microsoft Active Directory (AD) for authentication. The AD authentication provider is based on the LDAP authentication provider.

To use AD authentication for Azure, follow Microsoft’s tutorial to set up secure LDAP in your Azure account and create the host and certificates you need.

For general information about configuring authentication providers, see Use an authentication provider.

AD configuration examples

Example AD configuration: Minimum required attributes

type: ad
api_version: authentication/v2
metadata:
  name: activedirectory
spec:
  servers:
  - group_search:
      base_dn: dc=acme,dc=org
    host: 127.0.0.1
    user_search:
      base_dn: dc=acme,dc=org
{
  "type": "ad",
  "api_version": "authentication/v2",
  "spec": {
    "servers": [
      {
        "host": "127.0.0.1",
        "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
metadata:
  name: activedirectory
spec:
  groups_prefix: ad
  servers:
  - binding:
      password: YOUR_PASSWORD
      user_dn: cn=binder,cn=users,dc=acme,dc=org
    client_cert_file: /path/to/ssl/cert.pem
    client_key_file: /path/to/ssl/key.pem
    default_upn_domain: example.org
    include_nested_groups: true
    group_search:
      attribute: member
      base_dn: dc=acme,dc=org
      name_attribute: cn
      object_class: group
    host: 127.0.0.1
    insecure: false
    port: 636
    security: tls
    trusted_ca_file: /path/to/trusted-certificate-authorities.pem
    user_search:
      attribute: sAMAccountName
      base_dn: dc=acme,dc=org
      name_attribute: displayName
      object_class: person
  username_prefix: ad
{
  "type": "ad",
  "api_version": "authentication/v2",
  "spec": {
    "servers": [
      {
        "host": "127.0.0.1",
        "port": 636,
        "insecure": false,
        "security": "tls",
        "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem",
        "client_cert_file": "/path/to/ssl/cert.pem",
        "client_key_file": "/path/to/ssl/key.pem",
        "default_upn_domain": "example.org",
        "include_nested_groups": true,
        "binding": {
          "user_dn": "cn=binder,cn=users,dc=acme,dc=org",
          "password": "YOUR_PASSWORD"
        },
        "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"
  }
}

Example AD configuration: Use memberOf attribute instead of group_search

AD automatically returns a memberOf attribute in users’ accounts. The memberOf attribute contains the user’s group membership, which effectively removes the requirement to look up the user’s groups.

To use the memberOf attribute in your AD implementation, remove the group_search object from your AD config:

type: ad
api_version: authentication/v2
metadata:
  name: activedirectory
spec:
  servers:
    host: 127.0.0.1
    user_search:
      base_dn: dc=acme,dc=org
{
  "type": "ad",
  "api_version": "authentication/v2",
  "spec": {
    "servers": [
      {
        "host": "127.0.0.1",
        "user_search": {
          "base_dn": "dc=acme,dc=org"
        }
      }
    ]
  },
  "metadata": {
    "name": "activedirectory"
  }
}

After you configure AD to use the memberOf attribute, the debug log level will include the following log entries:

{"component":"authentication/v2","level":"debug","msg":"using the \"memberOf\" attribute to determine the group membership of user \"user1\"","time":"2020-06-25T14:10:58-04:00"}
{"component":"authentication/v2","level":"debug","msg":"found 1 LDAP group(s): [\"sensu\"]","time":"2020-06-25T14:10:58-04:00"}

AD specification

AD top-level attributes

type
description Top-level attribute that specifies the sensuctl create resource type. For AD definitions, the type should always be ad.
required true
type String
example
"type": "ad"
api_version
description Top-level attribute that specifies the Sensu API group and version. For AD definitions, the api_version should always be authentication/v2.
required true
type String
example
"api_version": "authentication/v2"
metadata
description Top-level map that contains 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",
      "port": 636,
      "insecure": false,
      "security": "tls",
      "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem",
      "client_cert_file": "/path/to/ssl/cert.pem",
      "client_key_file": "/path/to/ssl/key.pem",
      "default_upn_domain": "example.org",
      "include_nested_groups": true,
      "binding": {
        "user_dn": "cn=binder,cn=users,dc=acme,dc=org",
        "password": "YOUR_PASSWORD"
      },
      "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"
}

AD 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",
    "port": 636,
    "insecure": false,
    "security": "tls",
    "trusted_ca_file": "/path/to/trusted-certificate-authorities.pem",
    "client_cert_file": "/path/to/ssl/cert.pem",
    "client_key_file": "/path/to/ssl/key.pem",
    "default_upn_domain": "example.org",
    "include_nested_groups": true,
    "binding": {
      "user_dn": "cn=binder,cn=users,dc=acme,dc=org",
      "password": "YOUR_PASSWORD"
    },
    "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
description The prefix added to all AD groups. Sensu appends the groups_prefix with a colon. For example, for the groups_prefix ad and the group dev, the resulting group name in Sensu is ad:dev. Use the groups_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 appends the username_prefix with a colon. For example, for the username_prefix ad and the user alice, the resulting username in Sensu is ad:alice. Use the username_prefix when integrating AD users with Sensu RBAC role bindings and cluster role bindings. Users do not need to provide the username_prefix when logging in to Sensu.
required false
type String
example
"username_prefix": "ad"

AD 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"
trusted_ca_file
description Path to an alternative CA bundle file in PEM format to be used instead of the system’s default bundle. This CA bundle is used to verify the server’s certificate.
required false
type String
example
"trusted_ca_file": "/path/to/trusted-certificate-authorities.pem"
client_cert_file
description Path to the certificate that should be sent to the server if requested.
required false
type String
example
"client_cert_file": "/path/to/ssl/cert.pem"
client_key_file
description Path to the key file associated with the client_cert_file.
required false
type String
example
"client_key_file": "/path/to/ssl/key.pem"
binding
description The AD account that performs user and group lookups. If your sever supports anonymous binding, you can omit the user_dn or password attributes to query the directory without credentials. To use anonymous binding with AD, the ANONYMOUS LOGON object requires read permissions for users and groups.
required false
type Map
example
"binding": {
  "user_dn": "cn=binder,cn=users,dc=acme,dc=org",
  "password": "YOUR_PASSWORD"
}
group_search
description Search configuration for groups. See the group search attributes for more information. Remove the group_search object from your configuration to use the memberOf attribute instead.
required false
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"
}
default_upn_domain
description Enables UPN authentication when set. The default UPN suffix that will be appended to the username when a domain is not specified during login (for example, user becomes user@defaultdomain.xyz).

WARNING: When using UPN authentication, users must re-authenticate to apply any changes to group membership on the AD server since their last authentication. For example, if you remove a user from a group with administrator permissions for the current session (such as a terminated employee), Sensu will not apply the change until the user logs out and tries to start a new session. Likewise, under UPN, users cannot be forced to log out of Sensu. To apply group membership updates without re-authentication, specify a binding account or enable anonymous binding.

required false
type String
example
"default_upn_domain": "example.org"
include_nested_groups
description If true, the group search includes any nested groups a user is a member of. If false, the group search includes only the top-level groups a user is a member of.
required false
type Boolean
example
"include_nested_groups": true

AD 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. If your sever supports anonymous binding, you can omit this attribute to query the directory without credentials.
required false
type String
example
"user_dn": "cn=binder,cn=users,dc=acme,dc=org"
password
description Password for the user_dn account. If your sever supports anonymous binding, you can omit this attribute to query the directory without credentials.
required false
type String
example
"password": "YOUR_PASSWORD"

AD 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. 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. Combined with other filters as "(objectClass=<ObjectClass>)".
required false
type String
default "group"
example
"object_class": "group"

AD 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. 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. Combined with other filters as "(objectClass=<ObjectClass>)".
required false
type String
default "person"
example
"object_class": "person"

AD 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"

AD troubleshooting

The troubleshooting steps in the LDAP troubleshooting section also apply for AD troubleshooting.