TLS certificate auth method (API)

warning

Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround. See the deprecation FAQ for more information.

This is the API documentation for the OpenBao TLS Certificate authentication method. For general information about the usage and operation of the TLS Certificate method, please see the OpenBao TLS Certificate method documentation.

This documentation assumes the TLS Certificate method is mounted at the /auth/cert path in OpenBao. 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.

Method	Path
`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 individual allowed_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 of oid:value. Expects the extension value to be some type of ASN1 encoded string. All conditions must be met. Supports globbing on value.
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.
display_name (string: "") - The display_name to set on tokens issued when authenticating against this CA certificate. If not set, defaults to the name of the role.

token_ttl (integer: 0 or string: "") - The incremental lifetime for generated tokens. This current value of this will be referenced at renewal time.
token_max_ttl (integer: 0 or string: "") - The maximum lifetime for generated tokens. This current value of this will be referenced at renewal time.
token_policies (array: [] or comma-delimited string: "") - List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.
policies (array: [] or comma-delimited string: "") - DEPRECATED: Please use the token_policies parameter instead. List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.

token_bound_cidrs (array: [] or comma-delimited string: "") - List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate successfully, and ties the resulting token to these blocks as well.
token_strictly_bind_ip (bool: false) - If set, the token will be restricted to the source IP address making the initial login request. This conflicts with token_bound_cidrs.
token_explicit_max_ttl (integer: 0 or string: "") - If set, will encode an explicit max TTL onto the token. This is a hard cap even if token_ttl and token_max_ttl would otherwise allow a renewal.
token_no_default_policy (bool: false) - If set, the default policy will not be set on generated tokens; otherwise it will be added to the policies set in token_policies.
token_num_uses (integer: 0) - The maximum number of times a generated token may be used (within its lifetime); 0 means unlimited. If you require the token to have the ability to create child tokens, you will need to set this value to 0.
token_period (integer: 0 or string: "") - The maximum allowed period value when a periodic token is requested from this role.
token_type (string: "") - The type of token that should be generated. Can be service, batch, or default to use the mount's tuned default (which unless changed will be service tokens). For token store roles, there are two additional possibilities: default-service and default-batch which specify the type to return unless the client requests a different type at generation time.

Sample payload

{
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
  "display_name": "test",
  "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --cacert openbao-ca.pem \
    --data @payload.json
    https://127.0.0.1:8200/v1/auth/cert/certs/test-ca

Read CA certificate role

Gets information associated with the named role.

Method	Path
`GET`	`/auth/cert/certs/:name`

Parameters

name (string: <required>) - The name of the certificate role.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --cacert openbao-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/certs/test-ca

Sample response

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
    "display_name": "test",
    "policies": "",
    "allowed_names": "",
    "required_extensions": "",
    "ttl": 2764800,
    "max_ttl": 2764800,
    "period": 0
  },
  "warnings": null,
  "auth": null
}

List certificate roles

Lists configured certificate names.

Method	Path
`LIST`	`/auth/cert/certs`

Parameters

after (string: "") - Optional entry to begin listing after for pagination; not required to exist.
limit (int: 0) - Optional number of entries to return; defaults to all entries.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    --cacert openbao-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/certs

Sample response

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": ["cert1", "cert2"]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

Delete certificate role

Deletes the named role and CA cert from the method mount.

Method	Path
`DELETE`	`/auth/cert/certs/:name`

Parameters

name (string: <required>) - The name of the certificate role.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    --cacert openbao-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/certs/cert1

List CRLs

Lists configured certificate revocation lists.

Method	Path
`LIST`	`/auth/cert/crls`

Parameters

after (string: "") - Optional entry to begin listing after for pagination; not required to exist.
limit (int: 0) - Optional number of entries to return; defaults to all entries.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    --cacert openbao-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/crls

Sample response

{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": ["crl1", "crl2"]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

Create CRL

Sets a named CRL.

Method	Path
`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

{
  "crl": "-----BEGIN X509 CRL-----\n...\n-----END X509 CRL-----"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --cacert openbao-ca.pem \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/cert/crls/custom-crl

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.

Method	Path
`GET`	`/auth/cert/crls/:name`

Parameters

name (string: <required>) - The name of the CRL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --cacert openbao-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/crls/custom-crl

Sample response

{
  "auth": null,
  "data": {
    "serials": {
      "13": {}
    }
  },
  "lease_duration": 0,
  "lease_id": "",
  "renewable": false,
  "warnings": null
}

Delete CRL

Deletes the named CRL from the auth method mount.

Method	Path
`DELETE`	`/auth/cert/crls/:name`

Parameters

name (string: <required>) - The name of the CRL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    --cacert openbao-ca.pem \
    https://127.0.0.1:8200/v1/auth/cert/crls/cert1

Configure TLS certificate method

Configuration options for the method.

Method	Path
`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 to allowed_metadata_extensions will be stored in the alias
ocsp_cache_size (int: 100) - The size of the OCSP response LRU cache. Note that this cache is used for all configured certificates.

Sample payload

{
  "disable_binding": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --cacert openbao-ca.pem \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/cert/certs/cert1

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)

Method	Path
`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

{
  "name": "cert1"
}

Sample request

warning

NOTE The --cacert value used here is for the OpenBao TLS Listener CA certificate, not the CA that issued the client authentication certificate. This can be omitted if the CA used to issue the OpenBao server certificate is trusted by the local system executing this command.

$ curl \
    --request POST \
    --cacert openbao-ca.pem \
    --cert cert.pem \
    --key key.pem \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/cert/login

Sample response

{
  "auth": {
    "client_token": "cf95f87d-f95b-47ff-b1f5-ba7bff850425",
    "policies": ["web", "stage"],
    "lease_duration": 3600,
    "renewable": true
  }
}

Create CA certificate role​

Parameters​

Sample payload​

Sample request​

Read CA certificate role​

Parameters​

Sample request​

Sample response​

List certificate roles​

Parameters​

Sample request​

Sample response​

Delete certificate role​

Parameters​

Sample request​

List CRLs​

Parameters​

Sample request​

Sample response​

Create CRL​

Parameters​

Sample payload​

Sample request​

Read CRL​

Parameters​

Sample request​

Sample response​

Delete CRL​

Parameters​

Sample request​

Configure TLS certificate method​

Parameters​

Sample payload​

Sample request​

Login with TLS certificate method​

Parameters​

Sample payload​

Sample request​

Sample response​

Create CA certificate role

Parameters

Sample payload

Sample request

Read CA certificate role

Parameters

Sample request

Sample response

List certificate roles

Parameters

Sample request

Sample response

Delete certificate role

Parameters

Sample request

List CRLs

Parameters

Sample request

Sample response

Create CRL

Parameters

Sample payload

Sample request

Read CRL

Parameters

Sample request

Sample response

Delete CRL

Parameters

Sample request

Configure TLS certificate method

Parameters

Sample payload

Sample request

Login with TLS certificate method

Parameters

Sample payload

Sample request

Sample response