threshold/website/content/docs/concepts/credential-management.mdx

---
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](#credential-brokering) and [credential injection](#credential-injection).

To configure credential brokering or credential injection with static credentials, refer to [Create a static credential store](/boundary/docs/configuration/credential-management/static-cred-boundary) and [Create a Vault credential store](/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.

![Credential brokering diagram](/img/credential-brokering.png)

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 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

Additional credentials can be brokered to SSH targets after the session is establised using injected credentials.

### Security considerations

Consider a scenario where a user wants to access a target using SSH.

![Credential injection diagram](/img/credential-injection.png)

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).