Dan HeathandRobin Beck
5ce6515156
* docs: IA reorganization * docs: Updates * docs: Updates * docs: Fix links * docs: Updates * docs: Fix a typo * docs: Fix client agent topic * docs: Update Client Agent nav * docs: Fix conflict * docs: Fix a typo in Client Agent docs (#5853) * docs: Fix client agent topic * docs: Updates * docs: Updates * docs: Updates * docs: Updates * docs: Fixes get started and operations links * docs: Update nav * docs: Partials * docs: Unix partials * docs: Worker partials * docs: Updates * docs: Update workers and targets * docs: Updates * docs: Updates * docs: Fixes link * docs: Updates after sync review * docs: Updates from review feedback * docs: Move worker filter examples * docs: Fix links * docs: Updates for filters based on working session * docs: Fixes broken links * docs: Add links to other filter topics * docs: Update list intro * docs: Adds link * docs: Fixes redirects * docs: Fixes redirects * docs: Deleted mysql page from TOC * docs: Add versioned redirect * docs: Adds versioned redirects * docs: Adds versioned redirects * docs: Update redirects * docs: Update redirects * docs: Redirect fixes * docs: Update redirect format * docs: Fix a typo * docs: Fixes redirects * docs: Fixes redirect * docs: Adds links out to client agent troubleshooting * uses /etc/boundary.d/ as recommended installation directory (#6003) * docs: Updates legacy io links * docs: Fixes redirects * docs: Fix redirect * docs: Restoring deleted file --------- Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
132 lines
6.4 KiB
Plaintext
132 lines
6.4 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.
|
|
---
|
|
|
|
# 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 either TCP targets or SSH targets.
|
|
Brokered credentials can take the form of a token, username and password, SSH private key, certificate, 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.
|
|
|
|
Credential injection is required for the SSH target type, allowing users to inject the following credential types when they access targets using SSH:
|
|
|
|
- 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 broker additional credentials to 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
|
|
|
|
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. |