Integrating identity providers
Overview
Boundary allows you to secure user access to your infrastructure endpoints (e.g., SSH, RDP, web/HTTPs, databases, kubectl, and any other TCP service) based on the user's identity. Before you configure role-based access controls to these endpoints, you must set up a user authentication method in Boundary. We recommend that you integrate Boundary with your existing identity provider to ensure a consistent and secure user authentication process across your organization. Boundary supports LDAP and OIDC, allowing it to integrate with various identity services and providers, including Active Directory, Microsoft Entra ID, Auth0, and Okta.
Prerequisites
We recommend that you have completed the following steps before implementing the guidance in this document:
- You have reviewed and implemented the HashiCorp Validated Design (HVD) for Boundary Solution Design
- You have a running Boundary cluster.
- You have valid administrator credentials for your Boundary cluster to configure the authentication method.
- You have your identity provider configuration details to establish a connection to Boundary.
- LDAP/Active Directory: Server address (URL and port), TLS certificates, binding DN, and password. Please refer to the LDAP auth method attributes documentation for more information.
- OIDC providers: Client ID, client secret, claims scopes, callback and redirect URLs. Please refer to the OIDC auth method attributes documentation for more information.
- You have configured the network firewall to allow Boundary servers to communicate with your identity provider over the required network ports and protocols, described in the HashiCorp Validated Design (HVD) for Boundary Solution Design.
Roles and responsibilities
Below is the list of roles and responsibilities related to integrating identity providers and configuring authentication methods in Boundary.
| Role | Responsibility |
|---|---|
| Platform Team | Configures and manages resources in Boundary. In relation to this use case, the platform team manages Boundary organizations, configures the authentication method, and creates and assigns the organization admin role. |
| Identity Management Team | LDAP/Active Directory: Manages LDAP user credentials and group memberships. Provides credentials to allow Boundary to query and authenticate users. OIDC: Manages the OIDC provider and user claims, registers Boundary as a new client with the provider, and provides necessary client credentials to the platform team. |
| Network Team | Configures network firewall rules to ensure Boundary servers can communicate with your identity providers over the required network ports and protocols. LDAP/Active Directory: Ensure port TCP-389 (LDAP) or TCP-636 (LDAPS) is open and accessible. OIDC: Ensure port TCP-443 (HTTPS) is open for secure communication with OIDC providers. |
| Security Team | Ensures compliance with organizational security policies and standards. |
| Boundary Organization Admin | Manages resources in a Boundary organization, configures managed groups leveraging LDAP groups or OIDC user claim attributes, and configures RBAC policies based on managed groups. |
Configuring authentication method
Many organizations choose to implement Boundary as a service, with a central platform team managing the daily operations while development teams utilize Boundary’s capabilities. Enabling this model requires a mechanism to isolate groups of resources within a single cluster. As mentioned above, the global scope is the outermost scope and serves as the entry point for initial administration, setup, and management of the organization scopes. Organizations hold IAM-related resources and project scopes. You create one or more project scopes within an org based on your business workflows. It is recommended that you create a project scope to organize Boundary resources such as host catalogs, targets, credential stores, and access controls by specific products or teams. A scope can be considered as a container for resources and permissions. Each scope has a permissions boundary that is isolated from other scopes on the same level, creating a defined blast radius.
For your users to securely connect to the targets, they need to be both authenticated and authorized. An authentication method is a resource that provides a mechanism for your users to authenticate to Boundary. It contains accounts that link an individual user to a set of credentials and groups. Principals are entities in Boundary that can be users or groups, and are assigned capabilities. We recommend that you assign users to groups and use these groups as principals in roles for simplified access control management. Roles in Boundary are a collection of zero or more grants that are assigned to principals and govern what actions they are authorized to perform. You can define roles within any scope. A role’s lifecycle is dependent on the existence of its scope, meaning the role is deleted if the scope containing the role is deleted. The diagram below illustrates the relationship between the different IAM components in Boundary.
You can configure authentication methods at either a global or organization scope level. It is recommended to configure an authentication method at the global scope level as illustrated in below diagram to provide a consistent authentication experience for all users across different business units. This approach is ideal for enterprise environments where multiple departments or teams use a central authentication system.
You can also configure the authentication method at the organization scope level to meet specific requirements. For instance, you can configure a password authentication method at the org level with a few accounts for your contractors to provide them access to your resources without integrating these accounts into your primary identity provider, such as Active Directory, Microsoft Entra ID, or Okta.
A user or group assigned to a role at the project scope level can only perform actions on resources within that specific project. For instance, a user assigned the developer role in the illustration above can access hosts associated with the app target solely within that project. Consider using an organization scope level role if you need to grant the same permissions to users or groups across multiple projects. Using project scope roles ensures that access permissions are tightly controlled and limited to specific projects, enhancing security by isolating access. In contrast, org scope roles provide a broader permission set that can simplify management and ensure consistency across multiple projects.
Boundary supports several authentication methods, enabling you to leverage your existing identity providers for user authentication. Below are the available authentication methods:
- LDAP
- OIDC
- Password
LDAP/Active Directory auth method
The LDAP auth method allows your users to login using their existing LDAP username and password credentials. The LDAP auth method connects directly to your organizations’ LDAP servers. Boundary must be able to communicate with the LDAP server over TCP/UDP-389, or TCP-636 for LDAPS. Please refer to LDAP Authentication for detailed instructions to configure the LDAP auth method.
We recommend you to set the authentication method status to private initially to validate the configuration without exposing it publicly. In this state, the authentication method is not visible to unauthenticated users but can still be used to authenticate users. Once testing is successful, set the authentication method status to public to allow all users to authenticate via LDAP.
When an authentication request is made through the auth method, Boundary verifies the provided credentials with the backend LDAP server through a service account. Authentication requests can be initiated using the Boundary UI, CLI, API, or the Boundary Desktop.
The first time a user successfully authenticates using an LDAP auth method, Boundary creates a new account using the user’s account login name. If groups are enabled for an LDAP auth method, then each time a user authenticates, Boundary updates their account’s group memberships. We recommend that you configure the managed group resource in Boundary to automatically associate the user account to the group based on the LDAP account’s associated groups. Managed groups allow you to assign roles within Boundary based on an LDAP account’s group memberships.
OIDC auth method
The OIDC auth methods allows Boundary users to authenticate via identity providers such as Okta, Auth0 or Microsoft Entra ID. The OIDC auth method allows a user’s browser to be redirected to a configured identity provider to complete their login. Once authenticated, the user is directed back to Boundary’s UI, CLI, API or Boundary Desktop. Please refer to the documents below for detailed instructions to configure the authentication method with your identity provider.
We recommend you to set the authentication method status to private initially to validate the configuration without exposing it publicly. In this state, the authentication method is not visible to unauthenticated users but can still be used to authenticate users. Once testing is successful, set the authentication method status to public to allow all users to authenticate via OIDC.
Authentication requests can be initiated using the Boundary UI, CLI, API, or Boundary Desktop. The first time a user successfully authenticates using OIDC provider auth method, Boundary creates a new account using the claims returned from the provider. We recommend that you configure the managed group resource in Boundary to automatically associate the user account to the group based on OIDC account attributes. You can configure managed groups with claims from the JSON Web Token (JWT), or the claims from the UserInfo endpoint.
Password auth method
The password auth method allows you to configure user accounts directly in Boundary.
You can consider password authentication method for the following use-cases:
- Initial setup and testing
- Allows you to quickly set up and test Boundary configurations.
- Ensures Boundary is properly configured and functioning before integrating with other authentication methods like LDAP or OIDC.
- Backup authentication method
- Serves as a fallback authentication mechanism if the primary method (e.g., LDAP or OIDC) fails or is unavailable.
- You can continue to access and manage Boundary even if external authentication systems experience downtime or connectivity issues.
- Isolated environments
- Allows you to authenticate users in isolated or air-gapped environments where external identity providers cannot be accessed.
- Temporary access
- You can grant temporary access to users, such as contractors or temporary staff, without integrating them into the primary identity provider.
Summary
In this section, you reviewed the recommended approach to securely authenticate users to Boundary. The preferred approach is to use your existing identity provider for centralized authentication management, enhanced security, and improved operational efficiency. You also reviewed the recommended approach to creating Boundary organizations and auth methods. Finally, you configured an auth method leveraging your existing identity provider. In the next section, we will cover managed groups to dynamically maintain groups of users based on specific criteria or rules such as LDAP groups or OIDC claims.