vault/website/content/api-docs/auth/cert.mdx

---
layout: api
page_title: TLS Certificate - Auth Methods - HTTP API
description: |-
  This is the API documentation for the Vault TLS Certificate authentication
  method.
---

# TLS certificate auth method (API)

@include 'x509-sha1-deprecation.mdx'

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](/vault/docs/auth/cert).

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.

| 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](https://github.com/ryanuber/go-glob/blob/master/README.md#example). 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](https://github.com/ryanuber/go-glob/blob/master/README.md#example). 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](https://github.com/ryanuber/go-glob/blob/master/README.md#example). 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](https://github.com/ryanuber/go-glob/blob/master/README.md#example). 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](https://github.com/ryanuber/go-glob/blob/master/README.md#example). 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](https://github.com/ryanuber/go-glob/blob/master/README.md#example). 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. To match on the hex-encoded
  value of the extension, including non-string extensions, use the format
  `hex:<oid>:<value>`.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 OCSP responder 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_this_update_max_age` `(integer:0 or string: "")` - If greater than 0, specifies
  the maximum age of an OCSP thisUpdate field. This avoids accepting old responses
  without a nextUpdate field.
- `ocsp_max_retries` `(integer: 4)` - The number of retries attempted before giving
  up on an OCSP request. 0 will disable retries
- `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: "")` - The `display_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

```json
{
  "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

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --cacert vault-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

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

### Sample response

```json
{
  "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` |

### Sample request

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

### Sample response

```json
{
  "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

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    --cacert vault-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` |

### Sample request

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

### Sample response

```json
{
  "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

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

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --cacert vault-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

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

### Sample response

```json
{
  "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

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    --cacert vault-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.
- `role_cache_size` `(int: 200)` - The size of the role cache.  Use `-1` to disable
  role caching.

### Sample payload

```json
{
  "disable_binding": true
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --cacert vault-ca.pem \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/cert/config
```

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

| 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

```json
{
  "name": "cert1"
}
```

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

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

### Sample response

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