Configure Active Directory (AD) authentication

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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "username_prefix": "ad"
}

AD server attributes

host
description AD server IP address or FQDN.
required true
type String
example 
host: 127.0.0.1
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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_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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "attribute": "member"
}
name_attribute
description Represents the attribute to use as the entry name.
required false
type String
default "cn"
example 
name_attribute: cn
{
  "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
{
  "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
{
  "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
{
  "attribute": "sAMAccountName"
}
name_attribute
description Represents the attribute to use as the entry name.
required false
type String
default "displayName"
example 
name_attribute: displayName
{
  "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
{
  "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
{
  "name": "activedirectory"
}

AD troubleshooting

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