mirror of https://github.com/hashicorp/boundary
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
162 lines
9.2 KiB
162 lines
9.2 KiB
---
|
|
layout: docs
|
|
page_title: Credential library resource
|
|
description: >-
|
|
Learn about using the credential library resource to provide credentials from a credential store. Understand the credential library attributes you can configure.
|
|
---
|
|
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
|
|
# Credential libraries
|
|
|
|
A credential library is a resource that provides [credentials][] of the same type and same access level from a single [credential store][].
|
|
|
|
## Attributes
|
|
|
|
A credential library has the following configurable attributes:
|
|
|
|
- `name` - (optional) If you set this attribute, the `name` must be unique within the credential library's parent credential store.
|
|
|
|
- `description` - (optional) A user-defined description of the credential library for identification purposes.
|
|
|
|
### Vault generic credential library attributes
|
|
|
|
The generic Vault credential library has the following additional attributes:
|
|
|
|
- `vault-path` - (required) The path in Vault to request credentials from.
|
|
|
|
- `credential-type` - (optional) The type of credential this library issues. The default value is `unspecified`.
|
|
|
|
- `credential-mapping-override` - (optional) If set, this value overrides the field attributes in the credential that is retrieved from Vault.
|
|
|
|
- `vault-http-method` - (optional) The HTTP method the library uses when it requests credentials from Vault.
|
|
Can be either `GET` or `POST`.
|
|
The default value is `GET`.
|
|
|
|
- `vault-http-request-body` - (optional) The body of the HTTP request the library sends to Vault when it requests credentials.
|
|
Only valid if `http_method` is set to `POST`.
|
|
|
|
### Vault SSH certificate credential library attributes
|
|
|
|
<EnterpriseAlert product="boundary">This feature requires <a href="https://www.hashicorp.com/products/boundary">HCP Boundary or Boundary Enterprise</a></EnterpriseAlert>
|
|
|
|
You can configure SSH credential injection using [Vault's SSH secrets engine](/vault/docs/secrets/ssh) to create the SSH certificate credentials.
|
|
SSH certificate-based authentication extends key-based authentication using digital signatures.
|
|
Your users' authenticity is determined by a certificate signed by a trusted certificate authority (CA).
|
|
You can configure Vault's SSH secrets engine to act as the CA.
|
|
|
|
SSH certificates let you specify how long they are valid for, who can gain access to a target host, how users can log in, and what commands can be used on the target machine.
|
|
Unlike SSH key pairs, SSH certificates are short-lived and self-destructive.
|
|
|
|
A Vault SSH certificate credential library has the following additional attributes:
|
|
|
|
<Note>
|
|
|
|
The certificate is issued for the entire session, so if the `ttl` value is shorter than the target's `session_max_seconds` value, later connections may fail.
|
|
To prevent failures, you should ensure that the `ttl` value is equal to or longer than the target's `session_max_seconds`.
|
|
Alternatively, you could set the `session_connection_limit` to `1` for any targets that use the credential library.
|
|
|
|
</Note>
|
|
|
|
- `vault-path` - (required) The path in Vault to request credentials from.
|
|
|
|
- `username` - (required) The username to use with the SSH certificate.
|
|
You can create a template for this value using [Vault credential library parameter templating](#vault-generic-credential-library-parameter-templating).
|
|
|
|
- `key_type` - (optional) The type of key to use for the generated SSH private key.
|
|
The key type is either `ed25519`, `ecdsa`, or `rsa`.
|
|
The default key type is `ed25519`.
|
|
|
|
- `key_bits` - (optional) The number of bits used to generate the SSH private key.
|
|
The number of bits depends on the `key_type` value you select:
|
|
- For an `ed25519` key type, you should not set the `key_bits` value.
|
|
- For an `ecdsa` key type, you can select either `256`, `384`, or `521`.
|
|
- For an `rsa` key type, you can select either `2048`, `3072`, or `4096`.
|
|
|
|
- `ttl` - (optional) The SSH certificate's time-to-live (TTL).
|
|
|
|
- `key_id` - (optional) The key ID for the created SSH certificate. You can create a template for this value using [Vault credential library parameter templating](#vault-certificates-library-parameter-templating).
|
|
|
|
- `critical_options` - (optional) Any critical options that the certificate should be signed for.
|
|
For more information, refer to the [list of critical options](https://github.com/openssh/openssh-portable/blob/5f93c4836527d9fda05de8944a1c7b4a205080c7/PROTOCOL.certkeys#L221-L269) supported by OpenSSH.
|
|
|
|
- `extensions` - (optional) Any extensions that the certificate should be signed for.
|
|
For more information, refer to the [list of extensions](https://github.com/openssh/openssh-portable/blob/5f93c4836527d9fda05de8944a1c7b4a205080c7/PROTOCOL.certkeys#L270-L319) supported by OpenSSH.
|
|
Note that the `permit-pty` value should be set for an interactive shell to function properly.
|
|
|
|
- `additional_valid_principals` - (optional) Valid Principals that the certificate should be signed for in addition to the provided username.
|
|
For more information, refer to OpenSSH's ["valid principals" definition](https://github.com/openssh/openssh-portable/blob/5f93c4836527d9fda05de8944a1c7b4a205080c7/PROTOCOL.certkeys#L176-L181) as well as Vault's documentation for the [SSH secrets engine](https://developer.hashicorp.com/vault/api-docs/secret/ssh#valid_principals).
|
|
Note that all SSH certificates issued by a Vault SSH certificate credential library use the `SSH_CERT_TYPE_USER` certificate type mentioned in the OpenSSH definition link.
|
|
|
|
### Vault parameter templating
|
|
|
|
Sometimes it can be useful to provide information about a Boundary user or account when making a call to Vault. For example, this can allow picking the correct role when asking for database credentials (if roles are separated per-user), or providing a value to encode in an X.509 certificate generated by Vault. You can template user and account information into either the path in Vault, the `POST` request body, or both.
|
|
|
|
#### Vault generic credential library parameter templating
|
|
|
|
The following Vault template parameters are supported in Boundary's Vault generic credential library.
|
|
Note that account values are tied to the account associated with the token used to make the call:
|
|
|
|
- `{{.User.Id}}` - The user's ID.
|
|
- `{{.User.Name}}` - The user's name from the user resource.
|
|
- `{{.User.FullName}}` - The user's name from the account corresponding to the primary auth method in the user's scope.
|
|
This value may not be populated, or it may be different from the account name used in the template.
|
|
- `{{.User.Email}}` - The user's email address from the account corresponding to the primary auth method in the user's scope.
|
|
This value may not be populated, or it may be different from the account name used in the template.
|
|
- `{{.Account.Id}}` - The account's ID.
|
|
- `{{.Account.Name}}` - The name of the account from the account resource.
|
|
- `{{.Account.LoginName}}` - The account's login name, if a login name is used by that type of account.
|
|
- `{{.Account.Subject}}` - The account's subject, if a subject is used by that type of account.
|
|
- `{{.Account.Email}}` - The account's email, if email is used by that type of account.
|
|
|
|
#### Vault certificates library parameter templating
|
|
|
|
The following Vault template parameters are supported in Boundary's Vault certificate library.
|
|
Note that account values are tied to the account associated with the token used to make the call:
|
|
|
|
- `{{.User.Name}}` - The user's name from the user resource.
|
|
- `{{.Account.Id}}` - The account's ID.
|
|
|
|
#### Useful templating functions:
|
|
|
|
The `truncateFrom` function strips the rest of a string after a specified
|
|
substring. This function is useful for pulling a user or account name from an
|
|
email address. The following example turns `foo@example.com` into `foo`:
|
|
|
|
`{{truncateFrom .Account.Email "@"}}`
|
|
|
|
The example above uses the account email, but it could be any other parameter.
|
|
|
|
The `coalesce` function chooses the first non-empty value out of the list. This
|
|
is useful when using account names/login names since only one may be populated:
|
|
|
|
`{{coalesce .Account.Name .Account.LoginName}}`
|
|
|
|
## Tutorial
|
|
|
|
Refer to the [SSH certificate injection with HCP Boundary](/boundary/tutorials/credential-management/hcp-certificate-injection) tutorial to learn how to configure credential injection with SSH certificates using Vault.
|
|
|
|
## Referenced by
|
|
|
|
- [Credential][]
|
|
- [Credential store][]
|
|
- [Target][]
|
|
|
|
[credential store]: /boundary/docs/domain-model/credential-stores
|
|
[credential stores]: /boundary/docs/domain-model/credential-stores
|
|
[credential]: /boundary/docs/domain-model/credentials
|
|
[credentials]: /boundary/docs/domain-model/credentials
|
|
[project]: /boundary/docs/domain-model/scopes#projects
|
|
[projects]: /boundary/docs/domain-model/scopes#projects
|
|
[target]: /boundary/docs/domain-model/targets
|
|
[targets]: /boundary/docs/domain-model/targets
|
|
|
|
## Service API docs
|
|
|
|
The following services are relevant to this resource:
|
|
|
|
- [Credential library service](/boundary/api-docs/credential-library-service)
|