Active Directory Authentication

BindPlane OP 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 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.

1sudo BINDPLANE_CONFIG_HOME=/var/lib/bindplane \
2  /usr/local/bin/bindplane init server \
3  --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.

1Configure authentication for the BindPlane server.
2? Choose an authentication method Active Directory
3
4Enter the IP Address of the Active Directory server.
5? Authentication Server Address 192.168.1.2
6
7Enter the port to connect to the Active Directory server over.
8? Authentication Server Port 389
9
10Configure TLS for communication with the Active Directory server.
11? Enable TLS No
12
13Enter the Base DN to use to search for your users.
14? Base DN dc=corp,dc=net
15
16Enter search filter to use for user look up.
17? User Search Filter (|(sAMAccountName=%s)(userPrincipalName=%s))
18
19Enter the DN and password of the user BindPlane will use to connect (bind) to the Active Directory server.
20? Bind Username (leave empty for anonymous simple authentication) bindplane-ldap
21? Bind Password (leave empty for anonymous simple authentication) *********

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

1auth:
2  type: active-directory
3  password: redacted
4  sessionSecret: redacted
5  ldap:
6    protocol: ldap
7    server: "192.168.1.2"
8    port: "389"
9    baseDN: dc=corp,dc=net
10    bindUser: bindplane-ldap
11    bindPassword: redacted
12    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 OP 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.

1auth:
2  type: active-directory
3  ldap:
4    protocol: ldap
5    server: "192.168.1.2"
6    port: 389
7    baseDN: dc=corp,dc=net
8    bindUser: bindplane-ldap
9    bindPassword: redacted
10    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.

1kubectl -n default create secret generic ldap-tls \
2  --from-file=ca.crt
3  --from-file=client.crt \
4  --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.

1auth:
2  type: active-directory
3  ldap:
4    protocol: ldap
5    server: "192.168.1.2"
6    port: 389
7    baseDN: dc=corp,dc=net
8    bindUser: bindplane-ldap
9    bindPassword: redacted
10    searchFilter: (|(sAMAccountName=%s)(userPrincipalName=%s))
11    tls:
12      insecure: false
13      ca:
14        secret: ldap-tls
15        subPath: ca.crt

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

1auth:
2  type: active-directory
3  ldap:
4    protocol: ldap
5    server: "192.168.1.2"
6    port: 389
7    baseDN: dc=corp,dc=net
8    bindUser: bindplane-ldap
9    bindPassword: redacted
10    searchFilter: (|(sAMAccountName=%s)(userPrincipalName=%s))
11    tls:
12      insecure: false
13      ca:
14        secret: ldap-tls
15        subPath: ca.crt
16      clientKeyPair:
17        secret: ldap-tls
18        crtSubPath: client.crt
19        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.

1searchFilter: "(|(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.

1searchFilter: "(&(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.

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

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

1export LDAPTLS_CACERT=ca.crt

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

1export LDAPTLS_KEY=client.key
2export 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