SSH secrets engine (API)
This is the API documentation for the Vault SSH secrets engine. For general information about the usage and operation of the SSH secrets engine, please see the SSH documentation.
This documentation assumes the SSH secrets engine is enabled at the /ssh
path
in Vault. Since it is possible to enable secrets engines at any location, please
update your API calls accordingly.
Create/Update role
This endpoint creates or updates a named role.
Method | Path |
---|---|
POST | /ssh/roles/:name |
Parameters
name
(string: <required>)
– Specifies the name of the role to create. This is part of the request URL.default_user
(string: "")
– Specifies the default username for which a credential will be generated. When the endpointcreds/
is used without a username, this value will be used as default username. Its recommended to create individual roles for each username to ensure absolute isolation between usernames. This is required for OTP type roles.When
default_user_template
is set totrue
, this field can contain an identity template with any prefix or suffix, likessh-{{identity.entity.id}}-user
.For the CA type, if you wish this to be a valid principal, it must also be in
allowed_users
.default_user_template
(bool: false)
- If set,default_users
can be specified using identity template values. A non-templated user is also permitted.cidr_list
(string: "")
– Specifies a comma separated list of CIDR blocks for which the role is applicable for. It is possible that a same set of CIDR blocks are part of multiple roles. This is a required parameter, unless the role is registered under the/config/zeroaddress
endpoint. Note: [Not applicable for CA type]exclude_cidr_list
(string: "")
– Specifies a comma-separated list of CIDR blocks. IP addresses belonging to these blocks are not accepted by the role. This is particularly useful when big CIDR blocks are being used by the role and certain parts need to be kept out. Note: [Not applicable for CA type]port
(int: 22)
– Specifies the port number for SSH connection. Port number does not play any role in OTP generation. For theotp
secrets engine type, this is just a way to inform the client about the port number to use. The port number will be returned to the client by Vault along with the OTP.key_type
(string: <required>)
– Specifies the type of credentials generated by this role. This can be eitherotp
orca
.allowed_users
(string: "")
– If this option is not specified, or if it is*
, the client can request a credential for any valid user at the remote host, including the admin user. To only allow an explicit list of users, set this parameter using a comma-separated username list to enforce it. When this parameter is set, the credentials are created only fordefault_user
and usernames listed. Setting this option will enable all the users with access this role to fetch credentials for all other usernames in this list. Whenallowed_users_template
is set totrue
, this field can contain an identity template with any prefix or suffix, likessh-{{identity.entity.id}}-user
. Use with caution. N.B.: if the type isca
, an empty list does not allow any user; instead you must use*
to enable this behavior.allowed_users_template
(bool: false)
- If set,allowed_users
can be specified using identity template policies. Non-templated users are also permitted.allowed_domains
(string: "")
– A comma-separated list of domains for which a client can request a host certificate. If this option is explicitly set to"*"
, then credentials can be created for any domain. See alsoallow_bare_domains
andallow_subdomains
.allowed_domains_template
(bool: false)
- If set,allowed_domains
can be specified using identity template policies. Non-templated domains are also permitted.ttl
(string: "")
– Specifies the Time To Live value provided as a string duration with time suffix. Hour is the largest suffix. If not set, uses the system default value or the value ofmax_ttl
, whichever is shorter.max_ttl
(string: "")
– Specifies the maximum Time To Live provided as a string duration with time suffix. Hour is the largest suffix. If not set, defaults to the system maximum lease TTL.allowed_critical_options
(string: "")
– Specifies a comma-separated list of critical options that certificates can have when signed. To allow any critical options, set this to an empty string. Will default to allowing any critical options.allowed_extensions
(string: "")
– Specifies a comma-separated list of extensions that certificates can have when signed. To allow a user to specify any extension, set this to"*"
. If not set, users will not be allowed to specify extensions and will get the extensions specified withindefault_extensions
. For the list of extensions, take a look at the sshd manual'sAUTHORIZED_KEYS FILE FORMAT
section. You should add apermit-
before the name of extension to allow it.default_critical_options
(map<string|string>: "")
– Specifies a map of critical options certificates should have if none are provided when signing. This field takes in key value pairs in JSON format. Note that these are not restricted byallowed_critical_options
. Defaults to none.default_extensions
(map<string|string>: "")
– Specifies a map of extensions certificates should have if none are provided when signing. This field takes in key value pairs in JSON format. Note that these are not restricted byallowed_extensions
. Defaults to none.default_extensions_template
(bool: false)
- If set,default_extensions
can be specified using identity template values. A non-templated user is also permitted.allow_user_certificates
(bool: false)
– Specifies if certificates are allowed to be signed for use as a 'user'.allow_host_certificates
(bool: false)
– Specifies if certificates are allowed to be signed for use as a 'host'.allow_bare_domains
(bool: false)
– Specifies if host certificates that are requested are allowed to use the base domains listed inallowed_domains
, e.g. "example.com". This is a separate option as in some cases this can be considered a security threat.allow_subdomains
(bool: false)
– Specifies if host certificates that are requested are allowed to be subdomains of those listed inallowed_domains
, e.g. if "example.com" is part ofallowed_domains
, this allows "foo.example.com".allow_user_key_ids
(bool: false)
– Specifies if users can override the key ID for a signed certificate with the "key_id" field. When false, the key ID will always be the token display name. The key ID is logged by the SSH server and can be useful for auditing.key_id_format
(string: "")
– When supplied, this value specifies a custom format for the key id of a signed certificate. The following variables are available for use: '{{token_display_name}}' - The display name of the token used to make the request. '{{role_name}}' - The name of the role signing the request. '{{public_key_hash}}' - A SHA256 checksum of the public key that is being signed. e.g. "custom-keyid-{{token_display_name}}"allowed_user_key_lengths
(map<string|(int|[]int|string)>: "")
– Specifies a map of ssh key types and their expected sizes which are allowed to be signed by the CA type. To specify multiple sizes, either use a comma-separated list or an array of allowed key widths. We support both OpenSSH-style key identifiers and short names (rsa
,ecdsa
,dsa
, ored25519
) as keys. For example, a valid policy to allow common RSA and ECDSA key lengths might be:Note that when an algorithm identifier uniquely specifies a key length (such as with
ecdsa-sha2-nistp256
ored25519
), the value of the length is ignored (and can be zero).Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used:
ed25519
.algorithm_signer
(string: "default")
- Algorithm to sign keys with. Valid values aressh-rsa
,rsa-sha2-256
,rsa-sha2-512
, ordefault
. This value may also be left blank to use the signer's default algorithm, and must be left blank or have valuedefault
for CA key types other than RSA.Note: The value of
default
may change over time as vulnerabilities in algorithms are discovered. The present value for RSA keys is equivalent torsa-sha2-256
.Warning: The
algorithm_signer
valuessh-rsa
uses the SHA-1 hash algorithm. This algorithm is now considered insecure and is not supported by current OpenSSH versions. As a result, Vault has made the new defaultrsa-sha2-256
for RSA CA keys. It is strongly encouraged for all users to migrate torsa-sha2-256
ordefault
if the role was created with an explicitalgorithm_signer=rsa-sha
parameter or has been migrated to such.not_before_duration
(duration: "30s")
– Specifies the duration by which to backdate theValidAfter
property. Uses duration format strings.
Sample payload
Sample request
Read role
This endpoint queries a named role.
Method | Path |
---|---|
GET | /ssh/roles/:name |
Parameters
name
(string: <required>)
– Specifies the name of the role to read. This is part of the request URL.
Sample request
Sample response
For an OTP role:
For a CA role:
List roles
This endpoint returns a list of available roles. Only the role names are returned, not any values.
Method | Path |
---|---|
LIST | /ssh/roles |
Sample request
Sample response
Delete role
This endpoint deletes a named role.
Method | Path |
---|---|
DELETE | /ssh/roles/:name |
Parameters
name
(string: <required>)
– Specifies the name of the role to delete. This is part of the request URL.
Sample request
List Zero-Address roles
This endpoint returns the list of configured zero-address roles.
Method | Path |
---|---|
GET | /ssh/config/zeroaddress |
Sample request
Sample response
Configure Zero-Address roles
This endpoint configures zero-address roles.
Method | Path |
---|---|
POST | /ssh/config/zeroaddress |
Parameters
roles
(string: <required>)
– Specifies a string containing comma separated list of role names which allows credentials to be requested for any IP address. CIDR blocks previously registered under these roles will be ignored.
Sample payload
Sample request
Delete Zero-Address role
This endpoint deletes the zero-address roles configuration.
Method | Path |
---|---|
DELETE | /ssh/config/zeroaddress |
Sample request
Generate SSH credentials
This endpoint creates credentials for a specific username and IP with the parameters defined in the given role.
Method | Path |
---|---|
POST | /ssh/creds/:name |
Parameters
name
(string: <required>)
– Specifies the name of the role to create credentials against. This is part of the request URL.username
(string: "")
– Specifies the username on the remote host.ip
(string: <required>)
– Specifies the IP of the remote host.
Sample payload
Sample request
Sample response
For an OTP role:
List roles by IP
This endpoint lists all of the roles with which the given IP is associated.
Method | Path |
---|---|
POST | /ssh/lookup |
Parameters
ip
(string: <required>)
– Specifies the IP of the remote host.
Sample payload
Sample request
Sample response
An array of roles as a secret structure.
Verify SSH OTP
This endpoint verifies if the given OTP is valid. This is an unauthenticated endpoint.
Method | Path |
---|---|
POST | /ssh/verify |
Parameters
otp
(string: <required>)
– Specifies the One-Time-Key that needs to be validated.
Sample payload
Sample request
Sample response
Submit CA information
This endpoint allows submitting the CA information for the secrets engine via an SSH key pair. If you have already set a certificate and key, they will be overridden.
Method | Path | |
---|---|---|
POST | /ssh/config/ca | 200/204 application/json |
Parameters
private_key
(string: "")
– Specifies the private key part the SSH CA key pair; required ifgenerate_signing_key
is false.public_key
(string: "")
– Specifies the public key part of the SSH CA key pair; required ifgenerate_signing_key
is false.generate_signing_key
(bool: true)
– Specifies if Vault should generate the signing key pair internally. Iftrue
, an RSA key pair is generated, and the generated public key is returned so you can add it to your configuration. Iffalse
, then you must provideprivate_key
andpublic_key
, but these can be of any valid signing key type.key_type
(string: ssh-rsa)
- Specifies the desired key type for the generated SSH CA key whengenerate_signing_key
is set totrue
. Valid values are OpenSSH key type identifiers (ssh-rsa
,ecdsa-sha2-nistp256
,ecdsa-sha2-nistp384
,ecdsa-sha2-nistp521
, orssh-ed25519
) or an algorithm (rsa
,ec
, ored25519
).Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used:
ed25519
.key_bits
(int: 0)
- Specifies the desired key bits for the generated SSH CA key whengenerate_signing_key
is set totrue
. This is only used for variable length keys (such asssh-rsa
, where the value ofkey_bits
specifies the size of the RSA key pair to generate; with the default0
value resulting in a 4096-bit key) or when theec
algorithm is specified inkey_type
(where the value ofkey_bits
identifies which NIST P-curve to use;256
,384
, or521
, with the default0
value resulting in a NIST P-256 key).
Sample payload
Sample request
Sample response
This will return a 204
response if generate_signing_key
was unset or false.
This will return a 200
response if generate_signing_key
was true:
Delete CA information
This endpoint deletes the CA information for the backend via an SSH key pair.
Method | Path |
---|---|
DELETE | /ssh/config/ca |
Sample request
Read public key (Unauthenticated)
This endpoint returns the configured/generated public key. This is an unauthenticated endpoint.
Note: this is a raw response endpoint without JSON encoding; use
vault read -format=raw
or an external tool (e.g., curl
) to fetch this
value.
Method | Path | Content-Type |
---|---|---|
GET | /ssh/public_key | 200 text/plain |
Sample request
Sample response
Read public key (Authenticated)
This endpoint reads the configured/generated public key.
Method | Path |
---|---|
GET | /ssh/config/ca |
Sample request
Sample response
Sign SSH key
This endpoint signs an SSH public key based on the supplied parameters and
subject to the restrictions of the role named in the path. Both create
and
update
policy capabilities are needed to sign and update SSH keys. If only
create
capability is granted, and a SSH key does not exist, it will be created
using the default parameters already configured. If only update
capability is
available and a SSH key does not exist, an error will be returned and SSH keys
must exist already before may be updated.
It is similar to the endpoint /ssh/issue/:name
. Instead of issuing new
SSH credentials, this returns a certificate for the given SSH public key.
The issued certificate uses the defaults specified in the role named in this endpoint. Where not restricted by the parameters of this role, the parameters of the issued certificate can be further customized in this API call.
Note: The issued certificate is returned but not stored by Vault. If you do not save it from the response, request it again by repeating this request.
Method | Path |
---|---|
POST | /ssh/sign/:name |
Parameters
name
(string: <required>)
– Specifies the name of the role to sign. This is part of the request URL.public_key
(string: <required>)
– Specifies the SSH public key that should be signed.ttl
(string: "")
– Specifies the Requested Time To Live. Cannot be greater than the role'smax_ttl
value. If not provided, the role'sttl
value will be used. Note that the role values default to system values if not explicitly set.valid_principals
(string: "")
– Specifies valid principals, either usernames or hostnames, that the certificate should be signed for.cert_type
(string: "user")
– Specifies the type of certificate to be created; either "user" or "host".key_id
(string: "")
– Specifies the key id that the created certificate should have. If not specified, the display name of the token will be used.critical_options
(map<string|string>: "")
– Specifies a map of the critical options that the certificate should be signed for. Defaults to none.extensions
(map<string|string>: "")
– Specifies a map of the extensions that the certificate should be signed for. Defaults to none.
Sample payload
Sample request
Sample response
Generate certificate and key
This endpoint issues a new set of SSH credentials (private key and certificate).
It is similar to the endpoint /ssh/sign/:name
: Instead of signing an existing
SSH public key, it generates and issues new SSH credentials (key and certificate).
The issued certificate uses the defaults specified in the role named in this endpoint. Where not restricted by the parameters of this role, the parameters of the issued certificate can be further customized in this API call.
Note: The issued credentials are returned but not stored by Vault. If you do not save them from the response, issue new credentials by using this request again. This endpoint is available with Vault version 1.12+.
Method | Path |
---|---|
POST | /ssh/issue/:name |
Parameters
name
(string: <required>)
– Specifies the name of the role to create the certificate against. This is part of the request URL.key_type
(string: "rsa")
– Specifies the desired key type; must bersa
,ed25519
orec
.key_bits
(int: 0)
– Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); withkey_type=rsa
, allowed values are: 2048 (default), 3072, or 4096; withkey_type=ec
, allowed values are: 256 (default), 384, or 521; ignored withkey_type=ed25519
.ttl
(string: "")
– Specifies the Requested Time To Live. Cannot be greater than the role'smax_ttl
value. If not provided, the role'sttl
value will be used. Note that the role values default to system values if not explicitly set.valid_principals
(string: "")
– Specifies valid principals, either usernames or hostnames, that the certificate should be signed for.cert_type
(string: "user")
– Specifies the type of certificate to be created; either "user" or "host".key_id
(string: "")
– Specifies the key id that the created certificate should have. If not specified, the display name of the token will be used.critical_options
(map<string|string>: "")
– Specifies a map of the critical options that the certificate should be signed for. Defaults to none.extensions
(map<string|string>: "")
– Specifies a map of the extensions that the certificate should be signed for. Defaults to none.
Sample payload
Sample request
Sample response
Tidy host keys
This endpoint removes all existing host keys from Vault, if any are present. These keys were used with the Dynamic Keys functionality, which were removed from this engine.
Note: This does not clean up any pending dynamic key leases and will not
remove these keys from systems with authorized hosts entries created by
Vault. That must be done manually by an operator, potentially before the
removal of these host keys if they are necessary to access these
systems.
For a more effective cleanup process, it is suggest to stay on Vault 1.12,
manually revoke all dynamic key leases, wait for this to finish, and then
upgrade to Vault 1.13+.
Method | Path |
---|---|
DELETE | /ssh/tidy/dynamic-keys |
Sample request
Sample response