CyberCoveLLC/threshold
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update credentials docs for 0.12.0 (#2871)

Browse Source 
* docs: Update credentials docs for 0.12.0

* Update website/content/docs/concepts/domain-model/credential-libraries.mdx

Co-authored-by: Timothy Messier <tim.messier@gmail.com>

* docs: updates from review

* docs: fix capitalizationi

---------

Co-authored-by: Timothy Messier <tim.messier@gmail.com>
This commit is contained in:
Dan HeathandTimothy Messier authored and GitHub committed 2023-02-03 16:25:08 -05:00
1 parent 80774077d6
commit 51f2876265
2 files changed
+86 -32
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

website/content/docs/concepts/domain-model/credential-libraries.mdx
+61 -22
View File
@@ -7,39 +7,78 @@ description: |-
# Credential Libraries
A credential library is a resource
that provides [credentials][]
of the same type and same access level
from a single [credential store][].
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 set, the `name` must be unique within the credential library's parent
[credential store][].
- `name` - (optional) If you set this attribute, the `name` must be unique within the credential library's parent [credential store][].
- `description` - (optional)
- `description` - (optional) A user-defined description of the credential library for identification purposes.
### Vault Credential Library Attributes
### Vault generic credential library attributes
A Vault credential library has the following additional attributes:
The generic Vault credential library has the following additional attributes:
- `path` - (required)
The path in Vault to request credentials from.
- `path` - (required) The path in Vault to request credentials from.
- `http_method` - (optional: defaults to `GET`)
The HTTP method the library uses when requesting credentials from Vault.
Can be either `GET` or `POST`.
- `http_method` - (optional) The HTTP method the library uses when requesting credentials from Vault.
Can be either `GET` or `POST`.
The default value is `GET`.
- `http_request_body` - (optional)
The body of the HTTP request the library sends to Vault when requesting credentials.
Only valid if `http_method` is set to `POST`.
- `http_request_body` - (optional) The body of the HTTP request the library sends to Vault when requesting credentials.
Only valid if `http_method` is set to `POST`.
### Vault Credential Library Parameter Templating
### Vault SSH certificate credential library attributes
In some cases 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. As of Boundary 0.11.1, you can template user and account information into either the path in Vault, the `POST` request body, or both.
As of Boundary 0.12.0, 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>
- `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.
### 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. As of Boundary 0.11.1, 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:
@@ -64,7 +103,7 @@ The following example turns `foo@example.com` into `foo`:
The example above uses the account email, but it could be any other parameter.
## Referenced By
## Referenced by
- [Credential][]
- [Credential Store][]
@@ -79,7 +118,7 @@ The example above uses the account email, but it could be any other parameter.
[target]: /boundary/docs/concepts/domain-model/targets
[targets]: /boundary/docs/concepts/domain-model/targets
## Service API Docs
## Service API docs
The following services are relevant to this resource:
website/content/docs/concepts/domain-model/credentials.mdx
+25 -10
View File
@@ -7,18 +7,19 @@ description: |-
# Credentials
A credential is a data structure containing one or more secrets
that binds an identity to a set of permissions or capabilities
on a [host][] for a [session][].
A credential is a data structure containing one or more secrets that binds an identity to a set of permissions or capabilities on a [host][] for a [session][].
## Attributes
## Credential types
## Credential Types
Optionally, credentials can be typed to indicate compliance with a specific format.
The following credential types are supported in Boundary:
Optionally, credentials can be typed to indicate compliance with a specific
format.
- [Username password](#username-password)
- [SSH private key](#ssh-private-key)
- [SSH certificate](#ssh-certificate)
- [JSON](#json)
### Username Password
### Username password
`username_password` credentials contain the following fields:
@@ -26,7 +27,7 @@ format.
- `password` - The password field associated with the credential.
### SSH Private Key
### SSH private key
`ssh_private_key` credentials contain the following fields:
@@ -34,7 +35,21 @@ format.
- `private_key` - The private key field associated with the credential.
## Referenced By
### SSH certificate
`ssh_certificate` credentials contain the following fields:
- `username` - The username field associated with the credential.
- `ssh_certificate` - The SSH certificate associated with the credential.
### JSON
As of Boundary 0.11.0, you can provide credentials using a JSON blob.
There is no required structure for the JSON blob, other than it must be a key value map.
JSON credentials are only brokered to users that connect to machines.
## Referenced by
- [Credential Store][]
- [Credential Library][]