HashiCorp Developer AI Private beta now available Sign up today
Boundary
Identity management

LDAP authentication

  • 18min
  • |
  • Boundary

Deployment

Lightweight Directory Access Protocol (LDAP) is a standards-based protocol that sits on top of TCP/IP and allows clients to perform a variety of operations in a directory server, including storing and retrieving data, searching for data matching a given set of criteria, authenticating clients, and more. LDAP is an open, vendor-neutral application protocol for accessing and maintaining that directory data.

Boundary now includes an LDAP auth method which 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.

This tutorial provides an example of setting up LDAP as an authentication method for Boundary using HCP Boundary or Boundary's dev mode.

LDAP authentication method overview

  1. Get setup
  2. LDAP setup
  3. Create an auth method
  4. Authentication states
  5. Authenticate a user
  6. Define a managed group

Prerequisites

OR

  • A Windows environment with Active Directory. This scenario uses the community based Vagrant environment for a Windows Server based Active Directory project.

  • Vagrant 2.2 or newer is required if you choose to use the Vagrant environment for an Active Directory Server. This scenario was last tested with version 2.3.7.

  • VirtualBox 6.1.34 or newer is also needed if using the Vagrant environment for an Active Directory Server.

  • If you follow along on a Linux based host, you will need xdg-open. Sometimes this utility is part of an xdg-utils meta-package that you can install with your OS package manager. Check your distribution specific documentation for details on how to install xdg-open.

Note

If you use the Vagrant environment for Windows paired with HCP Boundary, a free ngrok account is also required to create a publicly routable address. Instructions for installing and configuring ngrok are provided later on.

Get setup

In this tutorial, you will test the LDAP auth method using HCP Boundary or by running a Boundary controller locally using dev mode.

The HCP Quickstart tutorials provide an overview of getting started with an HCP Boundary cluster.

If you have an HCP Boundary cluster deployed, the Access HCP Boundary tutorial provides an overview of configuring your local machine to authenticate with your HCP cluster.

This tutorial currently provides Admin Console UI and CLI workflows for setting up LDAP authentication.

To proceed with the UI workflow:

  1. Open the Admin Console UI by entering your HCP Boundary Cluster URL into a browser (such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud).

  2. Enter the admin login name and password you created when you deployed the new instance and click Sign In.

Admin UI Login Admin UI Login

You are now logged into your HCP Boundary instance's Global scope via the web UI. This is the default scope for all new Boundary clusters. You can now proceed to the Providers section to proceed with the Admin Console UI workflow.

LDAP setup

To enable an LDAP auth method an administrator must first configure their LDAP server, and then Boundary.

If you do not want to set up an LDAP server, this tutorial provides a workflow using an online LDAP test server.

Alternatively, you can use Vagrant to set up Active Directory by selecting the Active Directory tab below. For HCP Boundary, ngrok is also required to expose the local LDAP server to Boundary.

Note

Be aware that using ngrok creates a publicly routable address for the postgres container. If you do not wish to use ngrok, consider using the online LDAP test server, or running Boundary in dev mode.

If you want to use your own development LDAP server, you will need the appropriate configuration information about the LDAP server you wish to use. For an exhaustive list of configuration parameters, refer to: LDAP auth method attributes.

Select a workflow to continue the tutorial.

You can use an online LDAP test server provided by forumsys.com to complete this tutorial without setting up an LDAP server. To deploy an LDAP server using Active Directory instead, select the Active Directory tab.

The online LDAP server at ldap.forumsys.com is a public, read-only test server. In this public server, all user passwords are password. You may also bind to individual Users (uid).

The following group is also provided, and will be used to test Boundary's managed group access:

ou=scientists,dc=example,dc=com

Auth method creation

To enable an LDAP auth method, an administrator must configure Boundary with parameters which specify how to connect, bind, and search the directory for a user and their associated groups. Care has been taken to use the same parameters used for configuring Vault's LDAP auth methods.

The LDAP auth method configuration options are categorized and detailed below.

Tip

Detailed knowledge of LDAP is not required to proceed with the tutorial. To skip to the next section, visit Create the auth method for the provider.

Connection parameters:

These values are used to establish a connection between Boundary and the directory server. That connection can be either insecure, TLS or mTLS.

  • urls (string, required) - A set of LDAP URLs that specifies a set of LDAP servers to connect to. Examples: ldap://ldap.myorg.com, ldaps://ldap.myorg.com:636. If there's more than one URL configured, the directories will be tried in order if there are errors during the connection process. The URL scheme must be either ldap or ldaps. The port is optional. If you don't specify a port, then a default of 389 is used for ldap and a default of 689 is used for ldaps.
  • start_tls (bool, optional) - If true, issues a StartTLS command after establishing an unencrypted connection.
  • insecure_tls (bool, optional) - If true, skips LDAP server SSL certificate verification.
  • certificates (string, optional) - CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded.
  • client_certificate (string, optional) - Client certificate to provide to the LDAP server for mTLS connections, must be x509 PEM encoded.
  • client_certificate_key (string, optional) - Client certificate private key used with the ClientTLSCert for mTLS connections to the LDAP server, must be x509 PEM encoded.

Bind parameters

Before authenticating an end user, Boundary must first find the end user’s entry in the directory. There are two alternate methods of resolving the user entry Boundary uses to authenticate the end user: Search or User Principal Name. When you use Search, the bind can be either anonymous or authenticated. User Principal Name is a method of specifying users supported by Active Directory. More information on UPN can be found here.

Binding - Authenticated search

These parameters allow Boundary to bind (aka authenticate) using the credentials provided when searching for the user entry used to authenticate the end user:

  • bind_dn (string, optional) - Distinguished name of entry to bind when performing user and group search. Example: cn=vault,ou=Users,dc=example,dc=com
  • bind_password (string, optional) - Password to use along with binddn when performing user search.

Binding - Anonymous search

These parameters allow Boundary to bind anonymously to the directory when searching for the user entry used to authenticate the end user:

  • discover_dn (bool, optional) - If true, use anonymous bind to discover the bind DN of a user.
  • anon_group_search (bool, optional) - Use anonymous binds when performing LDAP group searches. Defaults to false.

Binding - User principal name (AD)

Active Directory uses UPNs (userPrincipalNames) as a user’s logon name. The following parameter allows Boundary to construct a user’s UPN from the username provided during authentication:

  • upn_domain (string, optional) - userPrincipalDomain used to construct the UPN string for the authenticating user. The constructed UPN will appear as [username]@UPNDomain Example: example.com, which will cause Boundary to bind as username@example.com when authenticating the user.

Search parameters: user entries

Before authenticating an end user, Boundary must first find the end user’s entry in the directory. The following parameters are used when searching for the user’s entry:

  • user_dn (string, optional) - Base DN under which to perform user search. Example: ou=Users,dc=example,dc=com
  • user_attr (string, optional) - Attribute on user attribute entry matching the username passed when authenticating. Examples: cn, uid
  • user_filter (string, optional) - Go template used to construct a LDAP user search filter. The template can access the following context variables: [UserAttr, Username]. The default userfilter is ({{.UserAttr}}={{.Username}}) or (userPrincipalName={{.Username}}@UPNDomain) if the upndomain parameter is set. The user search filter can be used to restrict what user can attempt to log in. For example, to limit login to users that are not contractors, you could write (&(objectClass=user)({{.UserAttr}}={{.Username}})(!(employeeType=Contractor)))

Search parameters: group entries

Once a user has been authenticated, the LDAP auth method must know how to resolve which groups the user is a member of. The configuration for this can vary depending on your LDAP server and your directory schema.

There are two main strategies when resolving group membership - the first is searching for the authenticated user object and following an attribute to groups it is a member of. The second is to search for group objects of which the authenticated user is a member of. Both methods are supported.

  • group_filter (string, optional) - Go template used when constructing the group membership query. The template can access the following context variables: [UserDN, Username]. The default is (|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}})), which is compatible with several common directory schemas. To support nested group resolution for Active Directory, instead use the following query: (&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}})).
  • group_dn (string, required) - LDAP search base to use for group membership search. This can be the root containing either groups or users. Example: ou=Groups,dc=example,dc=com.
  • group_attr (string, optional) - LDAP attribute to follow on objects returned by GroupFilter in order to enumerate user group membership. Examples: for GroupFilter queries returning group objects, use: cn. For queries returning user objects, use: memberOf. The default is cn.

Create auth method for the provider

To set up a new auth method for your provider you need the appropriate connection, binding, and search parameters for your LDAP server.

The following parameters are needed for the LDAP test server:

You can create auth methods using the Admin Console, CLI, or Terraform.

The Boundary Admin Console provides a UI for creating and managing LDAP resources, including auth methods and managed groups.

Open the Admin Console UI by entering your HCP Boundary Cluster URL into a browser (such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud).

Enter the admin login name and password you created when you deployed the new instance and click Sign In.

Admin Console Login Admin Console Login

Start by navigating to the Auth Methods settings view using the menu on the left side of the Admin Console. Select New and click LDAP.

Admin Console new LDAP auth method Admin Console new LDAP auth method

Fill out the form details using the settings gathered from the LDAP server.

Admin Console new LDAP auth method form Admin Console new LDAP auth method form

Add the following:

  • Name: LDAP-test-auth
  • Description: Test server LDAP auth method

Connection

  • Server address: ldap://ldap.forumsys.com

Authenticated search

  • Bind DN cn=read-only-admin,dc=example,dc=com
  • Bind Password password

User entries

  • User DN dc=example,dc=com
  • User Attribute uid

Group entries

  • Group DN dc=example,dc=com

Toggle the switch beside Enable Groups.

Once the form is completed, click Save.

The new authentication method has now been created. To the right of the new auth method's details, notice the state is set to Inactive. Before you can use it, the new auth method must be switched to an active state.

Next we will review the available authentication states and activate the new LDAP auth method.

Authentication states

An LDAP auth method can be in one of several different states. The current state of an auth method affects how endpoints respond to requests and, in some cases, whether access to an endpoint requires authentication.

State change operations

  • MakeInactive transitions an auth method from either the Active Private or the Active Public state into the Inactive state.
  • MakePrivate transitions an auth method from either the Inactive or the Active Public state into the Active Private state. If transitioning from the Inactive state, the transition will only succeed if the configuration is valid.
  • MakePublic transitions an auth method from either the Inactive or the Active Private state into the Active Public state. If transitioning from the Inactive state, the transition will only succeed if the configuration is valid.

Three different states exist for an authentication method:

  • inactive users can not authenticate with inactive auth methods and the inactive auth methods are not listed for unauthenticated users.
  • active-private users can authenticate with active-private auth methods and active-private auth methods are not listed for unauthenticated users.
  • active-public users can authenticate active-public auth methods and active-public auth methods are listed for unauthenticated users.

If a change is made from active-public or active-private to inactive, all in-flight authentications will succeed unless the auth method’s configuration is modified while the request is in-flight.

Activate the LDAP auth method

Now that a new LDAP auth method has been created, you can activate it and assign it as the default login type for the global scope.

Auth methods can be activated using the CLI, Admin Console, or using Terraform.

Currently the login type is set as inactive, and won't allow authentication.

$ boundary authenticate ldap -auth-method-id $BOUNDARY_AUTH_METHOD_ID -login-name einstein
Please enter the password (it will be hidden):
Error from controller when performing authentication

Error information:
  Kind:                Unauthenticated
  Message:             Unable to authenticate.
  Status:              401
  context:             Error from controller when performing authentication

You must set the new auth method to an active state before it will be allowed.

Under the settings for the new auth method, select Inactive from the menu in the upper-right side of the page and change its state by clicking Public.

Admin Console change auth method state Admin Console change auth method state

The login type is now allowed.

Set LDAP as primary login

Global and organization scopes may have auth methods in Boundary, and each scope has one primary auth-method ID. Boundary automatically creates a user upon first successful authentication via the scope’s primary auth method, which will be used by scopes with only one auth method available.

When migrating the database, Boundary will produce a log of any auth methods which resulted in no primary auth method being set for the scope.

Set the new LDAP auth method as the primary auth method for the global scope.

Under the settings for the new auth method, select Manage from the menu in the upper-right side of the page.

Admin Console primary auth method Admin Console primary auth method

A confirmation window will be displayed to inform you that new users that sign in via LDAP will automatically be added to the new auth method. Click OK to continue.

Authenticate using LDAP

With the LDAP auth method set to active-public, Boundary users can authenticate via the CLI, Admin Console, or Boundary Desktop app. Boundary administrators will usually follow a CLI or Admin Console workflow, while clients and end-users can use the CLI or the Boundary Desktop app.

The Boundary Desktop app is currently available for MacOS and Windows users.

Ensure that the latest version of the Boundary Desktop app is installed from the releases page before attempting to login with OIDC. The minimum version of the app allowing LDAP login is 1.7.0.

  1. Launch the Boundary Desktop app and enter the Boundary Cluster URL.

    The Cluster URL was copied from the HCP portal, such as https://e58fe114-7624-431c-994d-b6670e90b03J.boundary.hashicorp.cloud. Click Submit.

    Desktop App Url Desktop App Url

  2. Select LDAP.

    Enter the following LDAP credentials:

    • Login Name: einstein
    • Password : password

    Click Sign in.

The Boundary Desktop App provides a view of Targets and Sessions.

To continue learning about assigning LDAP accounts to a managed group to control permissions grants, ensure you can also log in using the Admin Console or CLI.

Define a managed group

In Boundary, the managed group resource represents a collection of accounts. A collection is automatically maintained by evaluating a filter defined in the managed group's configuration against the information returned by auth method's identity provider (IdP).

You can associate accounts with zero or more managed groups within the same auth method, and you can associate grants with a managed group when they are used as a principal within a role.

Membership in a managed group is defined when an LDAP auth method is used for authentication. Membership is determined by matching the LDAP group names against an LDAP account's associated groups, and every authentication updates the group membership comparison.

According to the Online LDAP Test Server, two groups exist for testing LDAP:

The scientists group contains the following users:

Verify LDAP account details

Earlier, you authenticated with the einstein user account. First, check that this account is associated with the LDAP auth method.

  1. Log back into Boundary as the admin user.

    Select the einstein user menu in the top-right corner of the page and click Sign Out.

    From the Sign In page, select the password auth method.

    Enter the admin user account details, then click Sign In.

Next, select the new auth method called LDAP-test-auth.

  1. Navigate to the Auth Methods page in the Global scope. Select the LDAP-test-auth auth method.

  2. Select the Accounts tab.

  3. Notice the new account with the following details:

    • Dn: uid=einstein,dc=example,dc=com
    • Group Names: Scientists

This information is populated by the LDAP server for any accounts that have authenticated using LDAP.

Create the managed group

We know that the einstein user belongs to the Scientists LDAP group.

Create a new Boundary managed group, specifying the Scientists group name to define the managed group membership.

  1. Navigate to the Auth Methods page in the Global scope. Select the LDAP-test-auth auth method.

  2. Select the Managed Groups tab.

  3. Click Create Managed Group.

  4. Fill in the form details with the following:

    • Name: science-group
    • Group Names: Scientists

    Click Add, then Save.

With the managed group configured, the next time our user authenticates it will belong to the managed group.

Create a role

With the managed group created and automatically managing group membership, the next step is to apply permissions to the group by creating a role.

After you create a role, the managed group is added as a role principal and grants are assigned to the role. To learn more about group principals, check out the Manage Users and Groups tutorial. To understand how permissions are granted, check out the Manage Roles tutorial.

First, create a new role in the global scope.

  1. Navigate to the Roles page in the Global scope.

  2. Click New Role. Fill in the following role details:

    • Name: read-roles

    Click Save.

  3. On the Settings page, Click Edit Form. Select a scope underneath Global, such as Generated org scope, quick-start-org, or any other org you have created.

    Click Save.

Assign grants to roles

Use the grant ids=*;type=role;actions=list,read, which selects any role ID and allows you to perform list and read actions. Include the grant ids=*;type=scope;actions=list,read, which selects any scope and allows you to perform list and read actions. To learn more about setting permission grants, check out the Permission Grant Formats documentation.

  1. Select the Grants tab.

  2. In the New Grant field, enter the following:

  3. Click Add.

  4. In the New Grant field, enter the following:

  5. Click Add, then Save.

Add managed group as a role principle

Next, add the new managed group as a role principal so the group will inherit any grants associated with the role.

  1. From the read-roles role page, select the Principals tab.

  2. Add the managed group as a role principal.

    Click + Add Principals.

    Check the box beside the science-group managed group.

    Select role principal Select role principal

    Click the Add Principals button.

With the grants in place the LDAP user should automatically be allowed to list and read roles upon authentication.

Test managed group membership

Test that the LDAP user belongs to the managed group, and has inherited the defined role principals.

  1. Log back in using the LDAP auth method.

  2. Select the admin user menu in the top-right corner of the page and click Sign Out.

  3. Authenticate using the new auth method.

    Select the auth method called LDAP-test-auth.

    Enter the following LDAP credentials:

    • Login Name: einstein
    • Password : password

    Click Sign In.

  4. After successful authentication you are automatically redirected to the Admin Console. Select global scope.

  5. Check that you are now able to view the Roles page.

    Admin Console view roles Admin Console view roles

You have now finished configuring an LDAP auth method and a role with an associated managed group principal.

Cleanup and teardown

  1. Remove any unwanted test auth methods from your HCP Boundary cluster. This can be done by deleting the auth method in the Admin Console UI, or by providing your auth method ID using the CLI:

    $ boundary auth-methods delete -id amoidc_40fr5jkLpk

  2. Delete the read-roles role within the Admin Console.

  3. If following the Active Directory workflow, clean up Vagrant and ngrok.

    Stop ngrok by locating the terminal where ngrok is running, then execute ctrl + c.

    Clean up Vagrant by destroying the Windows virtual machine.

    $ vagrant destroy

Next steps

This tutorial demonstrated the steps to add an LDAP authentication method and define role principals using a managed group.

You set up an LDAP auth method with Boundary, and verified that you can authenticate using an LDAP account. After that, you created a managed group that determined membership based on the LDAP groups associated with user accounts. Finally, you verified that users belonging the the managed group inherited grants assigned by a role principal.

To learn more about the basics of managing user accounts, check out the Manage Users and Groups and Manage Roles tutorials.

Collection Overview

Identity management

 Next

OIDC authentication with Auth0

Deployment