Configure LDAP authentication

Boundary can authenticate users against an external LDAP (Lightweight Directory Access Protocol) directory, such as OpenLDAP or Active Directory, using the LDAP auth method, so your team can log in with their existing directory credentials. Setting up an LDAP auth method takes three steps: create the auth method, optionally enable group-based access, and activate it.

Prerequisites

Network connectivity between your Boundary controller and the LDAP server.
The following information about your LDAP server:
- One or more LDAP URLs
- The base DN (distinguished name) under which to search for users
- The attribute that matches the username a user enters when they authenticate, such as uid for OpenLDAP or sAMAccountName for Active Directory
- Credentials for a bind account, if your LDAP server does not allow anonymous binds

Create an LDAP auth method

Log in to Boundary.
Select the scope in which you want to create the auth method.
Select Auth Methods, then click New.
Select LDAP, and complete the following fields:
- Name: (Optional) An optional name for identification purposes.
- Description: (Optional) An optional description of the auth method.
- URLs: (Required) One or more LDAP server URLs. Boundary tries each URL in the order you list them.
- User DN: (Optional) The base DN under which Boundary performs user searches.
- User Attr: (Optional) The attribute on a user entry that matches the login name a user enters, such as uid or sAMAccountName.
- Bind DN and Bind Password: (Optional) Credentials Boundary uses to search for and bind to LDAP entries. Required unless your LDAP server allows anonymous binds.
- Insecure TLS or Start TLS: (Optional) Configure how Boundary connects to the LDAP server.
Click Save.

$ boundary auth-methods create ldap \
  -scope-id $SCOPE_ID \
  -name "corp-ldap" \
  -description "LDAP auth method for corp directory" \
  -urls "ldaps://ldap.example.com" \
  -user-dn "ou=people,dc=example,dc=com" \
  -user-attr "uid" \
  -bind-dn "cn=boundary,dc=example,dc=com" \
  -bind-password "file://bind-password.txt"

The scope-id determines which scope contains the auth method. Set it to global or to an org scope ID. If you omit scope-id, Boundary uses the BOUNDARY_SCOPE_ID environment variable, or defaults to global.

Store the bind account's password in a file and reference it with the file:// scheme, as shown in the example, instead of passing it directly on the command line.

For Active Directory, the user attribute is typically sAMAccountName rather than uid:

$ boundary auth-methods create ldap \
  -scope-id $SCOPE_ID \
  -name "corp-ad" \
  -urls "ldaps://ad.example.com" \
  -user-dn "CN=Users,DC=example,DC=com" \
  -user-attr "sAMAccountName" \
  -bind-dn "CN=boundary,CN=Users,DC=example,DC=com" \
  -bind-password "file://bind-password.txt"

Refer to the auth-methods create command documentation for the full list of LDAP-specific options, including -discover-dn, -upn-domain, -certificate, -client-certificate, and -client-certificate-key.

Apply the following Terraform configuration:

resource "boundary_auth_method_ldap" "corp_ldap" {
  name        = "corp-ldap"
  description = "LDAP auth method for corp directory"
  scope_id    = "SCOPE_ID"
  urls        = ["ldaps://ldap.example.com"]
  user_dn     = "ou=people,dc=example,dc=com"
  user_attr   = "uid"
  bind_dn     = "cn=boundary,dc=example,dc=com"
  bind_password = "BIND_PASSWORD"
}

Replace scope_id, urls, user_dn, user_attr, bind_dn, and bind_password with the values for your scope and LDAP server.

Refer to the boundary_auth_method_ldap resource documentation for the full list of attributes.

Enable group-based access

Boundary can look up an authenticated user's LDAP group membership and use it to automatically assign the user to a managed group. You can use managed groups as principals in roles to grant access based on LDAP group membership.

Update the auth method to enable group lookups and specify where Boundary should search for groups:
```
$ boundary auth-methods update ldap \
  -id $LDAP_AUTH_METHOD_ID \
  -enable-groups \
  -group-dn "ou=groups,dc=example,dc=com" \
  -group-attr "cn"
```
If you use Active Directory and want Boundary to resolve nested group membership, set -use-token-groups instead of -group-dn and -group-attr. The -use-token-groups parameter uses the user's tokenGroups constructed attribute to find all security groups the user belongs to, including nested ones.

Create a managed group that matches one of your LDAP group names:

$ boundary managed-groups create ldap \
  -auth-method-id $LDAP_AUTH_METHOD_ID \
  -name "engineering" \
  -group-names "Engineering"

Add the managed group as a principal on a role to grant its members access. Refer to Manage access with roles to learn how to create roles and assign grants.

LDAP group membership is re-evaluated every time a user authenticates.

Activate the auth method

Boundary creates new LDAP auth methods in an inactive state. You must activate the auth method before users can log in with it.

Select Auth Methods, then select the LDAP auth method you created.
Select Manage, then select Change State.
Select Active Public to allow unauthenticated users to see and use the auth method to log in, or select Active Private to allow login without listing the auth method on the login page.

Set the state attribute on the boundary_auth_method_ldap resource so that Terraform activates the auth method when it applies the configuration:

resource "boundary_auth_method_ldap" "corp_ldap" {
  # ...
  state = "active-public"
}

Set the auth method as primary

Each scope has one primary auth method. Boundary automatically creates a user the first time someone authenticates successfully using the scope's primary auth method.

If the auth method is not primary for its scope, Boundary creates an account when a user first logs in, but it refuses to create the matching user, and the login fails. Either set the auth method as primary, as described in this section, or manually create a user and link it to the account.

$ boundary scopes update \
  -id $SCOPE_ID \
  -primary-auth-method-id $LDAP_AUTH_METHOD_ID

You can also set the is_primary_for_scope attribute on the boundary_auth_method_ldap Terraform resource, or select Make Primary from the auth method's Manage menu in the UI.

Troubleshooting

`Unable to authenticate`

If the auth method's bind-dn or bind-password attribute is incorrect, your LDAP server does not allow anonymous binds, or the end user's credentials are incorrect, authentication fails with the following error:

Error from controller when performing authentication

Error information:
  Kind:                Unauthenticated
  Message:             Unable to authenticate.
  Status:              401

Boundary returns this same generic error for any authentication failure, whether the cause is an invalid bind account, an invalid end-user password, or an unreachable LDAP server, so the error message alone doesn't tell you which check failed. Verify the bind account's credentials, confirm the account has permission to search the user-dn and group-dn you configured, and confirm your Boundary controller can reach the LDAP server over the network.

More information

Refer to the Auth method domain model topic for the full list of LDAP auth method attributes.
Refer to Filter managed groups for more information about LDAP managed group filtering.
Refer to the accounts domain model topic to learn how LDAP account attributes like full_name, email, and dn are populated on login.