TLS certificate auth method (API)
This is the API documentation for the Vault TLS Certificate authentication method. For general information about the usage and operation of the TLS Certificate method, please see the Vault TLS Certificate method documentation.
This documentation assumes the TLS Certificate method is mounted at the /auth/cert
path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly.
Create CA certificate role
Sets a CA cert and associated parameters in a role name.
POST
/auth/cert/certs/:name
Parameters
name
(string: <required>)
- The name of the certificate role.certificate
(string: <required>)
- The PEM-format CA certificate.allowed_names
(string: "")
- DEPRECATED: Please use the individualallowed_X_sans
parameters instead. Constrain the Common and Alternative Names in the client certificate with a globbed pattern. Value is a comma-separated list of patterns. Authentication requires at least one Name matching at least one pattern. If not set, defaults to allowing all names.allowed_common_names
(string: "" or array: [])
- Constrain the Common Names in the client certificate with a globbed pattern. Value is a comma-separated list of patterns. Authentication requires at least one Name matching at least one pattern. If not set, defaults to allowing all names.allowed_dns_sans
(string: "" or array: [])
- Constrain the Alternative Names in the client certificate with a globbed pattern. Value is a comma-separated list of patterns. Authentication requires at least one DNS matching at least one pattern. If not set, defaults to allowing all dns.allowed_email_sans
(string: "" or array: [])
- Constrain the Alternative Names in the client certificate with a globbed pattern. Value is a comma-separated list of patterns. Authentication requires at least one Email matching at least one pattern. If not set, defaults to allowing all emails.allowed_uri_sans
(string: "" or array: [])
- Constrain the Alternative Names in the client certificate with a globbed pattern. Value is a comma-separated list of URI patterns. Authentication requires at least one URI matching at least one pattern. If not set, defaults to allowing all URIs.allowed_organizational_units
(string: "" or array: [])
- Constrain the Organizational Units (OU) in the client certificate with a globbed pattern. Value is a comma-separated list of OU patterns. Authentication requires at least one OU matching at least one pattern. If not set, defaults to allowing all OUs.required_extensions
(string: "" or array: [])
- Require specific Custom Extension OIDs to exist and match the pattern. Value is a comma separated string or array ofoid:value
. Expects the extension value to be some type of ASN1 encoded string. All conditions must be met. To match on the hex-encoded value of the extension, including non-string extensions, use the formathex:<oid>:<value>
.Supports globbing onvalue
.allowed_metadata_extensions
(array:[])
- A comma separated string or array of oid extensions. Upon successful authentication, these extensions will be added as metadata if they are present in the certificate. The metadata key will be the string consisting of the oid numbers separated by a dash (-) instead of a dot (.) to allow usage in ACL templates.ocsp_enabled
(bool: false)
- If enabled, validate certificates' revocation status using OCSP.ocsp_ca_certificates
(string: "")
Any additional CA certificates needed to verify OCSP responses. Provided as base64 encoded PEM data.ocsp_servers_override
(array: [])
: A comma-separated list of OCSP server addresses. If unset, the OCSP server is determined from the AuthorityInformationAccess extension on the certificate being inspected.ocsp_fail_open
(bool: false)
- If true and an OCSP response cannot be fetched or is of an unknown status, the login will proceed as if the certificate has not been revoked.ocsp_query_all_servers
(bool: false)
- If set to true, rather than accepting the first successful OCSP response, query all servers and consider the certificate valid only if all servers agree.~> Note: When using Vault's PKI engine with Performance Replication clusters as the OCSP provider, and without
unified_crls=true
set on the source mount or when using cluster-local OCSP resolvers, we recommend enabling this option.display_name
(string: "")
- Thedisplay_name
to set on tokens issued when authenticating against this CA certificate. If not set, defaults to the name of the role.
@include 'tokenfields.mdx'
Sample payload
Sample request
Read CA certificate role
Gets information associated with the named role.
GET
/auth/cert/certs/:name
Parameters
name
(string: <required>)
- The name of the certificate role.
Sample request
Sample response
List certificate roles
Lists configured certificate names.
LIST
/auth/cert/certs
Sample request
Sample response
Delete certificate role
Deletes the named role and CA cert from the method mount.
DELETE
/auth/cert/certs/:name
Parameters
name
(string: <required>)
- The name of the certificate role.
Sample request
List CRLs
Lists configured certificate revocation lists.
LIST
/auth/cert/crls
Sample request
Sample response
Create CRL
Sets a named CRL.
POST
/auth/cert/crls/:name
Parameters
name
(string: <required>)
- The name of the CRL.crl
(string: "")
- The PEM format CRL.url
(string: "")
- The URL of a CRL distribution point.
Note: Either 'crl' or 'url' parameters must be provided, if both are provided, 'crl' is used.
Sample payload
Sample request
Read CRL
Gets information associated with the named CRL (currently, the serial numbers contained within). As the serials can be integers up to an arbitrary size, these are returned as strings.
GET
/auth/cert/crls/:name
Parameters
name
(string: <required>)
- The name of the CRL.
Sample request
Sample response
Delete CRL
Deletes the named CRL from the auth method mount.
DELETE
/auth/cert/crls/:name
Parameters
name
(string: <required>)
- The name of the CRL.
Sample request
Configure TLS certificate method
Configuration options for the method.
POST
/auth/cert/config
Parameters
disable_binding
(boolean: false)
- If set, during renewal, skips the matching of presented client identity with the client identity used during login.enable_identity_alias_metadata
(boolean: false)
- If set, metadata of the certificate including the metadata corresponding toallowed_metadata_extensions
will be stored in the aliasocsp_cache_size
(int: 100)
- The size of the OCSP response LRU cache. Note that this cache is used for all configured certificates.
Sample payload
Sample request
Login with TLS certificate method
Log in and fetch a token. If there is a valid chain to a CA configured in the method and all role constraints are matched, a token will be issued. If the certificate has DNS SANs in it, each of those will be verified. If Common Name is required to be verified, then it should be a fully qualified DNS domain name and must be duplicated as a DNS SAN (see https://tools.ietf.org/html/rfc6125#section-2.3)
POST
/auth/cert/login
Parameters
name
(string: "")
- Authenticate against only the named certificate role, returning its policy list if successful. If not set, defaults to trying all certificate roles and returning any one that matches.
Sample payload
Sample request
~> NOTE The --cacert
value used here is for the Vault TLS Listener CA certificate, not the CA that issued the client authentication certificate. This can be omitted if the CA used to issue the Vault server certificate is trusted by the local system executing this command.
Sample response
Last updated