Active Directory

How to configure Bindplane to use Active Directory for Authentication

This feature is only available for Bindplane Enterprise and Google Editions.

Bindplane supports Active Directory for authentication. Active Directory allows users to offload authentication and authorization duties to their Active Directory server. Bindplane's Role-Based Access Control works in conjunction with Active Directory.

1. Prerequisites

Before you begin, make sure the following requirements are met.

You have a Bindplane Enterprise or Bindplane for Google License key
The Bindplane server has network access to the Active Directory Server's Hostname or IP address
You know the Base Distinguished Name (base dn) of your Active Directory server.
You understand that the first user to log into Bindplane will become the Bindplane administrator
- Additional users will need to be invited by the administrator

2. Configuration

Active Directory configuration will differ depending on the platform Bindplane is deployed to. Linux users should follow the Linux section. Kubernetes Helm users should follow the Kubernetes section.

2.1. Linux

If you have not previously installed Bindplane, review the installation procedure here.

On the Linux server hosting Bindplane, execute the init command to reconfigure Bindplane.

sudo BINDPLANE_CONFIG_HOME=/var/lib/bindplane \
  /usr/local/bin/bindplane init server \
  --config /etc/bindplane/config.yaml

Respond to the prompts until you reach the "Choose an authentication method" prompt. Select "Active Directory".

In this example, the Active Directory server's IP address is 192.168.1.2. The Bind username is bindplane-ldap. For "Base DN", we are using dc=corp,dc=net, which will allow any Active Directory user to authenticate to Bindplane using their sAMAccountName or userPrincipalName name.

Configure authentication for the Bindplane server.
? Choose an authentication method Active Directory

Enter the IP Address of the Active Directory server.
? Authentication Server Address 192.168.1.2

Enter the port to connect to the Active Directory server over.
? Authentication Server Port 389

Configure TLS for communication with the Active Directory server.
? Enable TLS No

Enter the Base DN to use to search for your users.
? Base DN dc=corp,dc=net

Enter search filter to use for user look up.
? User Search Filter (|(sAMAccountName=%s)(userPrincipalName=%s))

Enter the DN and password of the user Bindplane will use to connect (bind) to the Active Directory server.
? Bind Username (leave empty for anonymous simple authentication) bindplane-ldap
? Bind Password (leave empty for anonymous simple authentication) *********

The configuration file at /etc/bindplane/config.yaml will look like this.

auth:
  type: active-directory
  password: redacted
  sessionSecret: redacted
  ldap:
    protocol: ldap
    server: "192.168.1.2"
    port: "389"
    baseDN: dc=corp,dc=net
    bindUser: bindplane-ldap
    bindPassword: redacted
    searchFilter: (|(sAMAccountName=%s)(userPrincipalName=%s))

Once Bindplane is configured and restarted, log into Bindplane to become the Organization Administrator.

If you have trouble logging in, proceed to the Troubleshooting section.

2.1.1. TLS

TLS is supported. When re-run the init command from step 2.1. Select yes when prompted to enable TLS.

2.2. Kubernetes

Bindplane is deployed to Kubernetes using the Bindplane Helm Chart.

If you have not previously deployed Bindplane, review Kubernetes Installation guide before proceeding.

The Helm chart supports Active Directory by configuring the auth.type and auth.ldap value options. In this example, the values file contains the same values used in the Linux example.

auth:
  type: active-directory
  ldap:
    protocol: ldap
    server: "192.168.1.2"
    port: "389"
    baseDN: dc=corp,dc=net
    bindUser: bindplane-ldap
    bindPassword: redacted
    searchFilter: (|(sAMAccountName=%s)(userPrincipalName=%s))

Deploy or update your existing Helm deployment to include the new authentication options.

2.2.1. TLS

The Bindplane Helm chart supports TLS and mutual TLS. Before configuring TLS, you must create a Kubernetes secret containing the TLS certificate authority and optional mutual TLS client certificate key-pair.

In this example, the CA certificate is located at ca.crt and the (optional) client keypair is located at client.crt and client.key. Update the namespace and file names to match your environment.

kubectl -n default create secret generic ldap-tls \
  --from-file=ca.crt
  --from-file=client.crt \
  --from-file=client.key

Once the secret ldap-tls is created, update your values file to include the TLS options.

For TLS, configure the TLS certificate authority.

auth:
  type: active-directory
  ldap:
    protocol: ldap
    server: "192.168.1.2"
    port: "389"
    baseDN: dc=corp,dc=net
    bindUser: bindplane-ldap
    bindPassword: redacted
    searchFilter: (|(sAMAccountName=%s)(userPrincipalName=%s))
    tls:
      insecure: false
      ca:
        secret: ldap-tls
        subPath: ca.crt

For mutual TLS, configure the TLS certificate authority and client key-pair.

auth:
  type: active-directory
  ldap:
    protocol: ldap
    server: "192.168.1.2"
    port: "389"
    baseDN: dc=corp,dc=net
    bindUser: bindplane-ldap
    bindPassword: redacted
    searchFilter: (|(sAMAccountName=%s)(userPrincipalName=%s))
    tls:
      insecure: false
      ca:
        secret: ldap-tls
        subPath: ca.crt
      clientKeyPair:
        secret: ldap-tls
        crtSubPath: client.crt
        keySubPath: client.key

2.3. Restrict Access

Despite being able to authenticate, users require an invitation before they can successfully log into Bindplane. This means you do not need to restrict which LDAP users and groups can authenticate.

If you wish to restrict the user base, you can do so by updating your search filter to include an Active Directory group.

The default search filter will attempt to match the user's username to sAMAccountName or userPrincipalName.

searchFilter: "(|(sAMAccountName=%s)(userPrincipalName=%s))"

You can restrict the search filter by including a memberOf filter. In this example, we are requiring that the user be part of the bindplane group.

searchFilter: "(&(memberOf=CN=bindplane,CN=Users,DC=bluemedora,DC=localnet)(|(sAMAccountName=%s)(userPrincipalName=%s)))"

Working with search filters can be difficult and error-prone, see the Troubleshooting section for example usage of the ldapsearch command.

3. Troubleshooting

3.1 LDAP Search

The ldapsearch utility is useful for interacting with Active Directory. You can use it to describe a user or group.

ldapsearch -x \
  -H ldap://192.168.1.2 \
  -D bindplane-ldap \
  -w 'redacted' \
  -b dc=corp,dc=net

If you are using TLS, set the following environment variable.

export LDAPTLS_CACERT=ca.crt

If you are using mutual TLS, set the following environment variables in addition to LDAPTLS_CACERT.

export LDAPTLS_KEY=client.key
export LDAPTLS_CERT=client.crt

3.2 Third Party Documentation

Search filter names https://learn.microsoft.com/en-us/windows/win32/ad/naming-properties
Understanding search filters https://confluence.atlassian.com/kb/how-to-write-ldap-search-filters-792496933.html

PreviousAuthentication NextOpenID Connect

Last updated 14 days ago

Was this helpful?