diff --git a/website/content/docs/concepts/credential-management.mdx b/website/content/docs/concepts/credential-management.mdx index 71dcce2ab0..aa27958b8b 100644 --- a/website/content/docs/concepts/credential-management.mdx +++ b/website/content/docs/concepts/credential-management.mdx @@ -12,6 +12,8 @@ After they connect to the machine, they may also require another set of credenti 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. diff --git a/website/content/docs/configuration/credential-management/configure-credential-brokering.mdx b/website/content/docs/configuration/credential-management/configure-credential-brokering.mdx new file mode 100644 index 0000000000..d589cb6d8c --- /dev/null +++ b/website/content/docs/configuration/credential-management/configure-credential-brokering.mdx @@ -0,0 +1,69 @@ +--- +layout: docs +page_title: Configure targets with credential brokering +description: |- + Configure credential brokering workflows so that Boundary centrally manages credentials and returns them to users when they successfully connect to a target. +--- + +# Configure targets with credential brokering + +The following section provides steps to configure your targets with credential brokering. +When you use credential brokering, Boundary returns credentials to the user when they successfully connect to a target. + +## Requirements + +- You must have an existing target available. +- You must have configured either a static credential store or a Vault credential store: + + - To configure a static credential store, refer to [Create static credential stores](/boundary/docs/configuration/credential-management/static-cred-boundary). + - To configure a Vault credential store and credential library, refer to [Create Vault credential stores](/boundary/docs/configuration/credential-management/static-cred-vault). + +- You must have a static credential saved in your static credential store or Vault credential store. The credential must correspond to the target you want to authenticate to. + +## Configuration + +Complete the following steps to configure credential brokering for a target: + + + + +1. Log in to Boundary. +1. Select **Orgs** on the navigation pane. +1. Select your desired org. +1. Select the project where your target resides. +1. Click **Targets** on the navigation pane. +1. Click on the target you want to configure for credential brokering. +1. Click on the **Brokered Credential** tab. +1. Click **Managed** and select **Add Brokered Credential** in the pull down menu. +1. Do one of the following: + - **If you are using a static credential store**: Select the credential that corresponds to your target and click **Add Brokered Credentials**. + - **If you are using a Vault credential store**: Select the credential library that corresponds to your target and click **Add Brokered Credentials**. + + + + +1. Log into Boundary. + + ```shell-session + $ boundary authenticate + Please enter the login name (it will be hidden): + Please enter the password (it will be hidden): + ``` +1. Add brokered credentials to target. + + ```shell-session + $ boundary targets add-credential-sources \ + -id ttcp_vO60a7TwpI \ + -application-credential-source csvlt_Xqa6V6QwfM + ``` + + + + If you are using a static credential store, `brokered-credential-source` refers to the ID of a **credential** in the static credential store. + + If you are using a Vault credential store, `brokered-credential-source` refers to the ID of a **credential library** in the Vault credential store. + + + + + \ No newline at end of file diff --git a/website/content/docs/configuration/credential-management/configure-credential-injection.mdx b/website/content/docs/configuration/credential-management/configure-credential-injection.mdx new file mode 100644 index 0000000000..b1cf39fd82 --- /dev/null +++ b/website/content/docs/configuration/credential-management/configure-credential-injection.mdx @@ -0,0 +1,73 @@ +--- +layout: docs +page_title: Configure targets with credential injection +description: |- + Configure credential injection so Boundary provides users with a passwordless experience when connecting to targets. Availabile exclusively for Enterprise users. +--- + +# Configure targets with credential injection + +This feature requires HCP Boundary or Boundary Enterprise + +The following section provides steps to configure your targets with credential injection. +Credential injection provides end users with a passwordless experience when they connect to targets. + +## Requirements + +- This feature requires either HCP Boundary or Boundary Enterprise +- You must have an existing target available. +- You must have configured either a static credential store or a Vault credential store: + + - To configure a static credential store, refer to [Create static credential stores](/boundary/docs/configuration/credential-management/static-cred-boundary). + - To configure a Vault credential store and credential library, refer to [Create Vault credential stores](/boundary/docs/configuration/credential-management/static-cred-vault). + +- You must have a static credential saved in your static credential store or Vault credential store. The credential must correspond to the target to which you want to authenticate. + +## Configuration + +Complete the following steps to configure targets with credential injection: + + + + +1. Log in to Boundary. +1. Select **Orgs** on the navigation pane. +1. Select your desired org. +1. Select the project where your target resides. +1. Click **Targets** on the navigation pane. +1. Click on your target you want to configure for credential injection. +1. Click on the **Injected Application Credential** tab. +1. Click **Managed** and select **Add Injected Application Credential** in the pull down menu. +1. Do one of the following: + - **If you are using a static credential store**: Select the credential that corresponds to your target and click **Add Injected Application Credential**. + - **If you are using a Vault credential store**: Select the credential library that corresponds to your target and click **Add Injected Application Credential**. + + + + +1. Log into Boundary. + + ```shell-session + $ boundary authenticate + Please enter the login name (it will be hidden): + Please enter the password (it will be hidden): + ``` + +1. Add credential injection to target. + + ```shell-session + $ boundary targets add-credential-sources \ + -id ttcp_vO60a7TwpI \ + -injected-application-credential-source csvlt_Xqa6V6QwfM + ``` + + + + If you are using a static credential store, `brokered-credential-source` refers to the ID of a **credential** in the static credential store. + + If you are using a Vault credential store, `brokered-credential-source` refers to the ID of a **credential library** in the Vault credential store. + + + + + \ No newline at end of file diff --git a/website/content/docs/configuration/credential-management/index.mdx b/website/content/docs/configuration/credential-management/index.mdx new file mode 100644 index 0000000000..54392c1189 --- /dev/null +++ b/website/content/docs/configuration/credential-management/index.mdx @@ -0,0 +1,41 @@ +--- +layout: docs +page_title: Configure credentials with Boundary +description: |- + Credential stores let you store and manage credentials in Boundary. Learn about configuring user workflows with credential management or credential injection. +--- + +# Overview + +When users connect to a target machine, they typically need a set of credentials for authentication. Rather than requiring users to securely store and manage credentials for every target resource, Boundary centralizes credential management to enhance security. + +## Credential stores + +Boundary supports credential management using [credential stores](/boundary/docs/concepts/domain-model/credential-stores), which are resources that store credentials for various targets. + +There are two types of credential stores: + +1. Static credential store +1. Vault credential store + +Static credential stores are built into Boundary and only store static credentials like username and password, or keypairs. Vault credential stores point to a HashiCorp Vault instance, which provides additional capabilities like generating short-lived dynamic credentials. + +Boundary can retrieve credentials from the credential stores and present them back to the user when they connect to targets. This workflow is referred to as **credential brokering**. Boundary can also inject credentials directly into the session on behalf of the user. This workflow is referred to as **credential injection**. + + +## End user workflows + +End users can experience three workflows when they connect to a target. In the first workflow, when an end user connects to a target, Boundary initiates the session, but the end user must know the credentials to authenticate into the session. This workflow is available for testing purposes, but it is not recommended because it places the burden on the users to securely store and manage credentials. + +The second workflow uses a feature called credential brokering, where credentials are retrieved from a credentials store and returned back to the end user. The end user then enters the credentials into the session when prompted by the target. This workflow is more secure than the first workflow since credentials are centrally managed through Boundary. For more information, see the [credential brokering](/boundary/docs/concepts/credential-management#credential-brokering) concepts page. + +The third workflow uses a featured called credential injection, where credentials are retrieved from a credential store and injected directly into the session on behalf of the end user. This workflow is the most secure because credentials are not exposed to the end user, reducing the chances of a leaked credential. This workflow is also more streamlined as the user goes through a passwordless experience. For more information, see the [credential injection](/boundary/docs/concepts/credential-management#credential-injection) concepts page. + +## Next steps + +The following pages provide steps to configure static credentials using both a static credential store and a Vault credential store. You can also configure targets for either credential brokering or credential injection workflows. + +- [Create a static credential store](/boundary/docs/configuration/credential-management/static-cred-boundary) +- [Create a Vault credential store](/boundary/docs/configuration/credential-management/static-cred-vault) +- [Configure targets with credential brokering](/boundary/docs/configuration/credential-management/configure-credential-brokering) +- [Configure targets with credential injection](/boundary/docs/configuration/credential-management/configure-credential-injection) \ No newline at end of file diff --git a/website/content/docs/configuration/credential-management/static-cred-boundary.mdx b/website/content/docs/configuration/credential-management/static-cred-boundary.mdx new file mode 100644 index 0000000000..3f3c719235 --- /dev/null +++ b/website/content/docs/configuration/credential-management/static-cred-boundary.mdx @@ -0,0 +1,110 @@ +--- +layout: docs +page_title: Manage static credentials with Boundary +description: |- + Create a static credential store to manage static credentials in Boundary. Credential stores let you configure targets for credential brokering or injection. +--- + +# Create a static credential store + +You can manage credentials in Boundary using [credential stores](/boundary/docs/concepts/domain-model/credential-stores), which are resources that store credentials for various targets. +Static credential stores are built into Boundary and only store static credentials like username and password or keypairs. + +## Requirements + +Ensure that you have an [Org scope and a project scope](/boundary/docs/commands/scopes/create) created in your Boundary instance. + +## Configuration + +Complete the following steps to create a static credential store: + + + + +1. Log in to Boundary +1. Select **Orgs** on the navigation pane. +1. Select your desired org. +1. Select the project to which your static credential store should belong. +1. Select **Credential Stores** on the navigation pane. +1. Select **New Credential Store**. +1. Provide a name for your credential store and select type **Static**. +1. Click **Save**. You now have a static credential store where you can store static credentials. +1. (Optional) If you have a static credential, you can add it into the static credential store. Static credential types can be a username and password, username and private key, or JSON blob. + + a. In your static credential store, click on the **Credentials** tab. + + b. Click **Manage**, and then select **New Credential** from the pull down menu. + + c. Complete the following fields to add static credentials to your static credential store: + - Name (optional) - The name is optional, but if you enter a name, it must be unique. + - Description (optional) - An optional description of the credential for identification purposes. + - Type - The type of static credential you want to add. Select between username and password, username and keypair, or a JSON blob. + - Credential data - Depending on the credential type selected, enter the credential data. + + d. Click **Save**. + + + + +1. Log into Boundary. + + ```shell-session + $ boundary authenticate + Please enter the login name (it will be hidden): + Please enter the password (it will be hidden): + ``` + +1. Create a credential store and provide a name and project ID. + + ```shell-session + $ boundary credential-stores create static \ + -scope-id p_VHAKTCEKcU \ + -name "my-static-credential-store" + ``` + +1. (Optional) If you have a static credential, you can add it into the static credential store using one of the following commands, based on the type of credential. Static credential types can be a username and password, username and keypair, or JSON blob. + + - For username and password credentials: + + ```shell-session + $ boundary credentials create username-password \ + -name "test-credentials" \ + -credential-store-id csst_O8utI0b3XC \ + -username \ + -password env:// + ``` + + To prevent credentials from being logged in the terminal, you must place passwords in an environment variable or file, and pass them to the `-password` option using the `env://` or `file://` syntax. + + - For username and private key credentials: + + ```shell-session + $ boundary credentials create ssh-private-key \ + -credential-store-id csst_O8utI0b3XC \ + -username \ + -private-key file:// + ``` + + To prevent credentials from being logged in the terminal, you must place SSH private keys in an environment variable or file, and pass them to the `-private-key` option using the `env://` or `file://` syntax. + + - For JSON blob credentials: + + ```shell-session + $ boundary credentials create json \ + -credential-store-id csst_O8utI0b3XC \ + -object file:// + ``` + + To prevent credentials from being logged in the terminal, you must place the JSON map value in a file, and pass it to the `-object` option using the `file://` syntax. + + + + +## Next steps + +Once you have created a credential store, you can configure targets for credential brokering or credential injection. +When you use credential brokering, Boundary centrally manages credentials and returns them to the user when they attempt to connect to a target. +Credential injection requires HCP Boundary or Boundary Enterprise, and it provides end users with a passwordless experience when they connect to targets. + +- [Configure a target for credential brokering](/boundary/docs/configuration/credential-management/configure-credential-brokering) +- [Configure a target for credential injection](/boundary/docs/configuration/credential-management/configure-credential-brokering) \ No newline at end of file diff --git a/website/content/docs/configuration/credential-management/static-cred-vault.mdx b/website/content/docs/configuration/credential-management/static-cred-vault.mdx new file mode 100644 index 0000000000..ab4101f9a7 --- /dev/null +++ b/website/content/docs/configuration/credential-management/static-cred-vault.mdx @@ -0,0 +1,105 @@ +--- +layout: docs +page_title: Manage static credentials with Vault +description: |- + Create a Vault credential store to manage credentials in Boundary. Credential stores let you configure targets for credential brokering or credential injection. +--- + +# Create a Vault credential store + +You can manage credentials in Boundary using [credential stores](/boundary/docs/concepts/domain-model/credential-stores), which are resources that store credentials for various targets. +Vault credential stores point to a HashiCorp Vault instance, which provides capabilities like generating short-lived dynamic credentials. + +## Requirements + +- You must have a Vault instance available with an address or URL that is reachable from your Boundary instance. This will be used to connect Boundary to Vault. +- You must have static credentials stored in Vault’s key/value secrets engine. Examples of static credential types include username and password or username and SSH private key. +- You must have a Vault token for Boundary to authenticate and access your static credentials. + +## Configuration + +Complete the following steps to create a Vault credential store: + + + + +1. Log in to Boundary. +1. Select **Orgs** on the navigation pane. +1. Select your desired org. +1. Select the project to which your static credential store should belong. +1. Select **Credential Stores** on the navigation pane. +1. Select **New Credential Store**. +1. Provide a name for your credential store and select type **Vault**. +1. Complete the fields related to your Vault instance: + - **Address** - The address of your Vault instance. + - **Worker Filter** (optional) - If your Vault instance does not have a publicly accessible address and instead is proxied through a Boundary worker, enter the worker filter. This should be a boolean expression. Refer to the examples in the [Worker tags](/boundary/docs/concepts/filtering/worker-tags) documentation. + - **Token** - Token provided by Vault that provides access to the static credentials within your Vault instance. + - **Namespace** (optional) - Vault namespace. Requires Vault Enterprise. + - **TLS Server Name** (optional) - Name to use as the SNI host if you connect to Vault via TLS. + - **Client Certificate** (optional) - A PEM-encoded client certificate to use for TLS authentication to the Vault server. + - **Client Certificate key** (optional) - A PEM-encoded private key that matches the client certificate from client certificate. + - **CA Certificate** (optional) - A PEM-encoded CA certificate to verify the Vault server's TLS certificate. + +1. Click **Save**. You now have a static credential store where you can store static credentials. +1. In your newly created Vault credential store, click on the **Credential Libraries** tab. +1. Click **Manage**, and then select **New Credential Library** in the pull down menu. +1. Complete the fields related to the static credentials stored in your Vault instance: + - **Name** (optional) - The name is optional, but if you enter a name, it must be unique within the parent credential store. + - **Type** - Select **Generic Secrets**. + - **Vault Path** - Enter the path for the location of your static credentials stored in Vault. Boundary uses this field to locate the static credentials inside Vault. + - **Credential Type** - Select the appropriate credential type that matches the static credential stored in Vault. + - **HTTP Method** - Select **GET**. +1. Click **Save**. + + + + +1. Log into Boundary. + + ```shell-session + $ boundary authenticate + Please enter the login name (it will be hidden): + Please enter the password (it will be hidden): + ``` + +1. Create a credential store and provide a name and project ID. + + ```shell-session + $ boundary credential-stores create vault \ + -scope-id p_VHAKTCEKcU \ + -name "vault-cred-store-test" + ``` + +1. Create a credential library using one of the following commands, based on the type of credential. + + - For username and password credentials: + + ```shell-session + $ boundary credential-libraries create vault-generic \ + -name "vault-cred-lib-test" \ + -credential-store-id csvlt_Xqa6V6QwfM \ + -credential-type username_password \ + -vault-path "path/to/vault/credentials" + ``` + + - For username and private key credentials: + + ```shell-session + $ boundary credential-libraries create vault-generic \ + -name "vault-cred-lib-test" \ + -credential-store-id csvlt_Xqa6V6QwfM \ + -credential-type ssh_private_key \ + -vault-path "path/to/vault/credentials" + ``` + + + + +## Next steps + +Once you have created a credential store, you can configure targets for credential brokering or credential injection. +When you use credential brokering, Boundary centrally manages credentials and returns them to the user when they attempt to connect to a target. +Credential injection requires HCP Boundary or Boundary Enterprise, and it provides end users with a passwordless experience when they connect to targets. + +- [Configure a target for credential brokering](/boundary/docs/configuration/credential-management/configure-credential-brokering) +- [Configure a target for credential injection](/boundary/docs/configuration/credential-management/configure-credential-brokering) \ No newline at end of file diff --git a/website/content/docs/integrations/vault/index.mdx b/website/content/docs/integrations/vault/index.mdx index dfb1e9b606..7b4c0fd289 100644 --- a/website/content/docs/integrations/vault/index.mdx +++ b/website/content/docs/integrations/vault/index.mdx @@ -22,6 +22,12 @@ Timely access to resources creates improvements in workflow efficiency by removi ## Credential management +To configure credential brokering or credential injection with static credentials on Vault, please see [Manage static credentials with Vault](/boundary/docs/configuration/credential-management/static-cred-vault). + + +# Credentials +Vault can work with Boundary to be a credential [store](https://developer.hashicorp.com/boundary/docs/concepts/domain-model/credential-stores) and [library](https://developer.hashicorp.com/boundary/docs/concepts/domain-model/credential-libraries), which allows for credentials to be stored in Vault and used by Boundary. There are two configuration options: + Within Boundary, you can configure Vault as a [credential store](/boundary/docs/concepts/domain-model/credential-stores) and [credential library](/boundary/docs/concepts/domain-model/credential-libraries). There are two configuration options: diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 20c01f0968..79dcf4d963 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -481,6 +481,36 @@ } ] }, + { + "title": "Credential management", + "routes": [ + { + "title": "Overview", + "path": "configuration/credential-management" + }, + { + "title": "Create a static credential store", + "path": "configuration/credential-management/static-cred-boundary" + }, + { + "title": "Create a Vault credential store", + "path": "configuration/credential-management/static-cred-vault" + }, + { + "title": "Configure targets with credential brokering", + "path": "configuration/credential-management/configure-credential-brokering" + }, + { + "title": "Configure targets with credential injection", + "path": "configuration/credential-management/configure-credential-injection", + "badge": { + "text": "HCP/ENT", + "type": "outlined", + "color": "neutral" + } + } + ] + }, { "title": "Session recordings", "badge": {