9de0dbaef9
Add note about X.509 SHA-1 deprecation to relevant plugins Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
373 lines
10 KiB
Plaintext
373 lines
10 KiB
Plaintext
---
|
|
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](/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. Supports globbing on
|
|
`value`.
|
|
- `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
|
|
```
|
|
|
|
## Create CRL
|
|
|
|
Sets a named CRL.
|
|
|
|
| Method | Path |
|
|
| :----- | :---------------------- |
|
|
| `POST` | `/auth/cert/crls/:name` |
|
|
|
|
### Parameters
|
|
|
|
- `name` `(string: <required>)` - The name of the CRL.
|
|
- `crl` `(string: <required>)` - The PEM format CRL.
|
|
|
|
### 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.
|
|
|
|
### 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/certs/cert1
|
|
```
|
|
|
|
## 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
|
|
}
|
|
}
|
|
```
|