Robert Main
18f469105c
* Update website folder to indicate deprecation Adds an alert banner to the top of all MDX files within `/website` to indicate deprecation * Update website README
152 lines
7.5 KiB
Plaintext
152 lines
7.5 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Credential management
|
|
description: >-
|
|
Learn about using credential brokering or credential injection to authenticate users. Understand the benefits and security considerations of each method.
|
|
---
|
|
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
|
|
# Credential management
|
|
|
|
When users connect to a remote machine, they typically need a set of credentials for authentication.
|
|
After they connect to the machine, they may also require another set of credentials to access services or other machines within the network.
|
|
|
|
There are two credential management paradigms in Boundary, credential brokering and credential injection.
|
|
|
|
## Credential brokering
|
|
|
|
Credential brokering is the process by which credentials are fetched from a credential store, and then returned back to the user.
|
|
|
|
The user must already be authorized to connect to a specific target to have credentials for that target brokered back to them.
|
|
|
|
Credentials are brokered when the session is established.
|
|
|
|
The credential brokering process works as follows:
|
|
|
|
1. The user authenticates to Boundary using either the CLI or desktop app.
|
|
1. The user requests a connection to the target.
|
|
|
|
The controller fetches credentials from the credential store and passes the credentials to the user.
|
|
1. The user establishes a connection to the session.
|
|
|
|
The controller assigns the job to a worker, and the worker establishes a session to the target.
|
|
1. The user enters the credentials.
|
|
|
|
The user is authenticated to the target.
|
|
|
|
You can attach brokered credentials to SSH, TCP, or RDP targets.
|
|
Brokered credentials can take the form of a token, username password, username password domain, JSON blob, or an unstructured secret stored in Vault, for example.
|
|
|
|
### Security considerations
|
|
|
|
Consider a scenario where a user wants to access a target using SSH.
|
|
|
|
|
|
|
|
In this scenario, the user must be authorized to access the target.
|
|
If they are authorized, they can authenticate themselves to the machine using credentials that were brokered, or returned, back to them.
|
|
|
|
If the user is not authorized to access the target, they will not be able to retrieve brokered credentials for that target.
|
|
|
|
<img
|
|
type="image/gif"
|
|
src="https://www.datocms-assets.com/2885/1681998722-boundary-credential-brokering-animated.gif"
|
|
alt="Boundary credential brokering animated"
|
|
/>
|
|
|
|
If a user wants to abstract the authentication process using brokered credentials, they can use the `boundary connect` ssh-style command, and pass credentials to sshpass, PuTTY, or another such tool.
|
|
In this scenario, while the brokered credential may not be visible to the user, they still interact with the brokered credentials to perform authentication.
|
|
|
|
<img
|
|
type="image/gif"
|
|
src="https://www.datocms-assets.com/2885/1681998732-boundary-terminal.gif"
|
|
alt="Pass credentials using the boundary connect command"
|
|
/>
|
|
|
|
Additionally, with Vault's dynamic secrets engine, an administrator could configure their environment such that secrets are essentially one-time passwords, as the credentials are revoked after the session is terminated.
|
|
|
|
## Credential injection
|
|
|
|
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
|
|
|
|
Credential injection is the process by which a credential is fetched from a credential store and then passed on to a worker for authentication to a remote machine.
|
|
|
|
With credential injection, the user never sees the credential required to authenticate to the target.
|
|
|
|
This provides a passwordless experience for the user, as the worker does both session establishment and authentication to the target on behalf of the user.
|
|
This process differs from credential brokering, where credentials are returned to the user rather than injected into the session on worker nodes.
|
|
|
|
The credential injection process works as follows:
|
|
|
|
1. The user authenticates to Boundary.
|
|
1. The user requests a connection to a target.
|
|
|
|
The controller fetches credentials from the credential store.
|
|
1. The user establishes a connection to the session.
|
|
|
|
The controller assigns the job to a worker, and the worker establishes a session to the target.
|
|
Then the controller passes credentials to the worker.
|
|
The worker authenticates to the target, and the user is then authenticated to the target.
|
|
|
|
### Target types
|
|
|
|
Credential injection is required for the RDP and SSH target types.
|
|
|
|
<Note>
|
|
|
|
RDP credential injection is currently in beta.
|
|
For more information about known issues, configuration requirements, and compatibility with Windows, refer to [RDP credential injection compatibility](/boundary/docs/credentials/rdp-testing-and-compatibility-matrix).
|
|
|
|
</Note>
|
|
|
|
You can inject the following credential types when you access SSH targets:
|
|
|
|
- SSH certificates
|
|
- Usernames and passwords
|
|
- Usernames and public keys
|
|
|
|
Keyboard-interactive authentication is not supported for credential injection.
|
|
When you use Username password credentials, ensure that your SSH server is configured to allow password authentication.
|
|
|
|
You can inject username password domain credentials when you access RDP targets in Windows environments that use Active Directory or NTLMv2 for authentication.
|
|
|
|
You can broker additional credentials to RDP or SSH targets after the session is established using injected credentials.
|
|
|
|
### Security considerations
|
|
|
|
Consider a scenario where a user wants to access a target using SSH.
|
|
|
|
|
|
|
|
In this scenario, the user must be authorized to access the target.
|
|
If they are authorized, they have the ability to connect to the worker.
|
|
Upon connecting to the worker, the worker attempts to establish a remote session to the target, and attempts authentication on behalf of the user.
|
|
|
|
<img
|
|
type="image/gif"
|
|
src="https://www.datocms-assets.com/2885/1681998728-boundary-credential-injection-animated.gif"
|
|
alt="Boundary credential injection animated"
|
|
/>
|
|
|
|
If the user is not authorized to access the target, the credentials are not injected on their behalf, nor are the credentials brokered back to them.
|
|
|
|
## Tutorial
|
|
|
|
Refer to the [Broker static credentials to your first target](/boundary/tutorials/get-started-hcp/hcp-getting-started-credentials) tutorial to practice configuring credential brokering.
|
|
|
|
Refer to the [Manage SSH keys with HCP Boundary and Vault](/boundary/tutorials/hcp-administration/hcp-ssh-cred-injection) tutorial to practice configuring credential injection.
|
|
|
|
## More information
|
|
|
|
Refer to [Credentials in Boundary](/boundary/docs/credentials) to learn more about how Boundary centralizes credential management to enhance security.
|
|
|
|
To configure credential brokering or credential injection with static credentials, refer to the following topics:
|
|
|
|
- [Create a static credential store](/boundary/docs/credentials/static-cred-boundary)
|
|
- [Create a Vault credential store](/boundary/docs/credentials/static-cred-vault).
|
|
|
|
Refer to [Secrets engines](/vault/docs/secrets) to learn more about the Vault dynamic secrets engine. |