diff --git a/website/content/docs/concepts/credential-management.mdx b/website/content/docs/concepts/credential-management.mdx new file mode 100644 index 000000000..0d83e92e0 --- /dev/null +++ b/website/content/docs/concepts/credential-management.mdx @@ -0,0 +1,111 @@ +--- +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). + +## 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. + + 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. + + 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 HCP only + +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. + +![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. + + 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). \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 21f9cd195..e7b0d4f69 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -211,6 +211,10 @@ "title": "Service Discovery", "path": "concepts/service-discovery" }, + { + "title": "Credential Management", + "path": "concepts/credential-management" + }, { "title": "Security", "routes": [ diff --git a/website/public/img/credential-brokering.png b/website/public/img/credential-brokering.png new file mode 100644 index 000000000..27e3dce9f Binary files /dev/null and b/website/public/img/credential-brokering.png differ diff --git a/website/public/img/credential-injection.png b/website/public/img/credential-injection.png new file mode 100644 index 000000000..7b5fcf5c9 Binary files /dev/null and b/website/public/img/credential-injection.png differ