1--- 2layout: docs 3page_title: TLS Certificates - Auth Methods 4description: >- 5 The "cert" auth method allows users to authenticate with Vault using TLS 6 client certificates. 7--- 8 9# TLS Certificates Auth Method 10 11The `cert` auth method allows authentication using SSL/TLS client certificates 12which are either signed by a CA or self-signed. 13 14The trusted certificates and CAs are configured directly to the auth method 15using the `certs/` path. This method cannot read trusted certificates from an 16external source. 17 18CA certificates are associated with a role; role names and CRL names are normalized to 19lower-case. 20 21Please note that to use this auth method, `tls_disable` must be false in the Vault 22configuration. This is because the certificates are sent through TLS communication itself. 23 24## Revocation Checking 25 26Since Vault 0.4, the method supports revocation checking. 27 28An authorised user can submit PEM-formatted CRLs identified by a given name; 29these can be updated or deleted at will. (Note: Vault **does not** fetch CRLs; 30the CRLs themselves and any updates must be pushed into Vault when desired, 31such as via a `cron` job that fetches them from the source and pushes them into 32Vault.) 33 34When there are CRLs present, at the time of client authentication: 35 36- If the client presents any chain where no certificate in the chain matches a 37 revoked serial number, authentication is allowed 38 39- If there is no chain presented by the client without a revoked serial number, 40 authentication is denied 41 42This method provides good security while also allowing for flexibility. For 43instance, if an intermediate CA is going to be retired, a client can be 44configured with two certificate chains: one that contains the initial 45intermediate CA in the path, and the other that contains the replacement. When 46the initial intermediate CA is revoked, the chain containing the replacement 47will still allow the client to successfully authenticate. 48 49**N.B.**: Matching is performed by _serial number only_. For most CAs, 50including Vault's `pki` method, multiple CRLs can successfully be used as 51serial numbers are globally unique. However, since RFCs only specify that 52serial numbers must be unique per-CA, some CAs issue serial numbers in-order, 53which may cause clashes if attempting to use CRLs from two such CAs in the same 54mount of the method. The workaround here is to mount multiple copies of the 55`cert` method, configure each with one CA/CRL, and have clients connect to the 56appropriate mount. 57 58In addition, since the method does not fetch the CRLs itself, the CRL's 59designated time to next update is not considered. If a CRL is no longer in use, 60it is up to the administrator to remove it from the method. 61 62## Authentication 63 64### Via the CLI 65 66The below authenticates against the `web` cert role by presenting a certificate 67(`cert.pem`) and key (`key.pem`) signed by the CA associated with the `web` cert 68role. Note that the name `web` ties to the configuration example below writing 69to a path of `auth/cert/certs/web`. If a certificate role name is not specified, 70the auth method will try to authenticate against all trusted certificates. 71 72~> **NOTE** The `-ca-cert` value used here is for the Vault TLS Listener CA 73certificate, not the CA that issued the client authentication certificate. This 74can be omitted if the CA used to issue the Vault server certificate is trusted 75by the local system executing this command. 76 77```shell-session 78$ vault login \ 79 -method=cert \ 80 -ca-cert=vault-ca.pem \ 81 -client-cert=cert.pem \ 82 -client-key=key.pem \ 83 name=web 84``` 85 86### Via the API 87 88The endpoint for the login is `/login`. The client simply connects with their 89TLS certificate and when the login endpoint is hit, the auth method will 90determine if there is a matching trusted certificate to authenticate the client. 91Optionally, you may specify a single certificate role to authenticate against. 92 93~> **NOTE** The `--cacert` value used here is for the Vault TLS Listener CA 94certificate, not the CA that issued the client authentication certificate. This 95can be omitted if the CA used to issue the Vault server certificate is trusted 96by the local system executing this command. 97 98```shell-session 99$ curl \ 100 --request POST \ 101 --cacert vault-ca.pem \ 102 --cert cert.pem \ 103 --key key.pem \ 104 --data '{"name": "web"}' \ 105 https://127.0.0.1:8200/v1/auth/cert/login 106``` 107 108## Configuration 109 110Auth methods must be configured in advance before users or machines can 111authenticate. These steps are usually completed by an operator or configuration 112management tool. 113 1141. Enable the certificate auth method: 115 116 ```text 117 $ vault auth enable cert 118 ``` 119 1201. Configure it with trusted certificates that are allowed to authenticate: 121 122 ```text 123 $ vault write auth/cert/certs/web \ 124 display_name=web \ 125 policies=web,prod \ 126 certificate=@web-cert.pem \ 127 ttl=3600 128 ``` 129 130 This creates a new trusted certificate "web" with same display name and the 131 "web" and "prod" policies. The certificate (public key) used to verify 132 clients is given by the "web-cert.pem" file. Lastly, an optional `ttl` value 133 can be provided in seconds to limit the lease duration. 134 135## API 136 137The TLS Certificate auth method has a full HTTP API. Please see the 138[TLS Certificate API](/api/auth/cert) for more details. 139