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

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

- `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 credential library 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.

The following Vault template parameters are supported in Boundary.
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.

Additionally, there are a couple of useful 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)
