a79e35da54
* add a new cred management files * adding credential management files * fixed type-os, added ent labels, grouped cli/ui * added reference links from concepts section and Vault integration section to new cred management pages * style guide and formatting enhancements * style guide and formatting enhancements * fixes internal link * docs: Updates for styles and standards * docs: Fix link structure * docs: Break out brokering/injection procedures * Apply batch suggestions from code review Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com> * docs: Clean up commented out code * docs: Rename index file per best practices * docs: Update page description meta content * docs: Add level 2 headings for organization --------- Co-authored-by: Robin Beck <stellarsquall@protonmail.ch> Co-authored-by: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
115 lines
5.9 KiB
Plaintext
115 lines
5.9 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Credential management
|
|
description: |-
|
|
An overview of credential management in Boundary
|
|
---
|
|
|
|
# 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](#credential-brokering) and [credential injection](#credential-injection-hcp-only).
|
|
|
|
To configure credential brokering or credential injection with static credentials, refer to [Manage static credentials with Boundary](/boundary/docs/configuration/credential-management/static-cred-boundary) and [Manage static credentials with Vault](/boundary/docs/configuration/credential-management/static-cred-vault).
|
|
|
|
## 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.
|
|
|
|
Learn more about [credential brokering](/boundary/tutorials/hcp-getting-started/hcp-getting-started-credentials).
|
|
|
|
Learn more about the [Vault dynamic secrets engine](/vault/docs/secrets).
|
|
|
|
## 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 available for the SSH target type, allowing users to inject the following credential types when accessing targets using SSH:
|
|
|
|
- SSH certificates
|
|
- Usernames and passwords
|
|
- Usernames and public keys
|
|
|
|
### 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.
|
|
|
|
Learn more about [credential injection](/boundary/tutorials/hcp-administration/hcp-ssh-cred-injection). |