Skip to main content

Boundary LDAP authentication

Learn how to set up Boundary’s new LDAP auth method and get a deep dive into how the feature can help you.

HashiCorp Boundary 0.13 includes several important preview features that enable organizations to integrate their directories directly with Boundary via the LDAP protocol. These previewed features will be initially enabled by the Boundary CLI, API, and SDK, as well as in HashiCorp Terraform, with admin UI support to come in the near future.

This post dives into more detail about Boundary’s support for LDAP auth method.

»What’s new

Organizations store usernames, passwords, email addresses, and groups, along with other data in their directories (popular directory servers include Active Directory and Free IPA). LDAP is an open, vendor-neutral application protocol for accessing and maintaining that directory data.

Boundary now includes an LDAP auth method that allows Boundary to delegate authentication to an LDAP directory. The first time a user successfully authenticates using an LDAP auth method, a new LDAP account is created using the user’s account login name. If groups are enabled for an LDAP auth method, then each time a user authenticates, their account’s group memberships are updated in Boundary. LDAP managed groups allow administrators to assign roles within Boundary based on an LDAP account’s group memberships.

»Keeping UX familiar

Creating a Boundary LDAP auth method is just like creating and interacting with other auth method types in Boundary. If you’re already familiar with OIDC auth methods, accounts, and managed groups, you’ll find the same domain types for the LDAP auth method and the same sorts of workflows enabled.

Also, if you're familiar with Vault's LDAP auth method, then you’ll see we’ve made every attempt to align Boundary’s LDAP and Vault’s LDAP auth method capabilities and configuration parameters. For example, both Boundary and Vault support Active Directory’s UserPrincipalName for login names and retrieving an account’s group membership from Active Directory’s Token Groups attribute.

We’ve also given back to the community by open sourcing LDAP client authentication in this GitHub repository: You can use it to integrate your services with LDAP servers for authentication, account, and group information.

»Command-line demo

As an introduction to Boundary’s new LDAP capabilities, we’ve put together a DIY command-line demo where you’ll learn how to:

  • Create an LDAP auth method
  • Set that new LDAP auth method as a primary auth method for the global scope
  • Create an LDAP managed group
  • Authenticate a user using LDAP

This demonstration uses a public read-only online LDAP test server. This test server allows you to authenticate (bind) as individual users and includes group membership data for those users. The users’ login names are associated with famous scientists, and our examples use the login name of einstein. All users in this test server have the same password: password.

If you’d like to use your own development LDAP server, you’ll need the appropriate configuration information. An exhaustive list, along with brief descriptions, of configuration parameters is here: LDAP Auth Method Attributes.

The following demonstration commands depend on a locally running boundary dev environment. If you’ve already got Boundary installed locally, then you can simply run it in a terminal using:

boundary dev 

The first step is to authenticate as an admin user via the dev environment’s preconfigured password auth method:

boundary authenticate password \
--auth-method-id ampw_1234567890 \  
--login-name admin

At this point, you’re ready to create an LDAP auth method in the global scope (this command requires that you’ve written password into a local file name bind-pass.txt):

boundary auth-methods create ldap \
-urls "ldap://" \
-bind-dn "cn=read-only-admin,dc=example,dc=com" \
-bind-password file://bind-pass.txt \
-user-dn "dc=example,dc=com" \
-user-attr "uid" \
-group-dn "dc=example,dc=com" \
-state active-public \

Set the BOUNDARY_AUTH_METHOD_ID environment variable, so you can use it in the commands that follow:

export BOUNDARY_AUTH_METHOD_ID=<ldap-auth-method-id>

Make this new LDAP auth method the primary auth method for the global scope, so a user will be automatically created when a new LDAP account successfully authenticates:

boundary scopes update \
-id global \
-primary-auth-method-id $BOUNDARY_AUTH_METHOD_ID

Create an LDAP managed group named test-grp for the new LDAP auth method that will include all LDAP accounts that belong to the Scientists group:

boundary managed-groups create ldap \
-name test-grp \
-group-names Scientists

Authenticate with an LDAP account:

boundary authenticate ldap -login-name einstein

Congratulations! You’ve successfully integrated Boundary with an LDAP server for authentication and managed groups.

»Learn more

You can learn more about Boundary’s new LDAP capabilities by exploring the domain documentation:

You can also explore the new Boundary LDAP Terraform resources:

Sign up for the latest HashiCorp news

By submitting this form, you acknowledge and agree that HashiCorp will process your personal information in accordance with the Privacy Policy.