mirror of
https://github.com/hashicorp/vault.git
synced 2025-11-22 03:01:10 +01:00
3106f26474
* Fix small typo in troubleshooting-acme.mdx * Create changelog/24547.txt * Delete changelog/24547.txt --------- Co-authored-by: Violet Hynes <violet.hynes@hashicorp.com>
202 lines
6.3 KiB
Plaintext
202 lines
6.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'PKI - Secrets Engine: Troubleshooting ACME'
|
|
description: Troubleshoot problems with ACME clients and Vault PKI Secrets Engine's ACME server.
|
|
---
|
|
|
|
# Troubleshoot PKI Secrets Engine and ACME
|
|
|
|
Solve common problems related to ACME client integration with Vault PKI
|
|
Secrets Engine's ACME server.
|
|
|
|
## Error: ACME feature requires local cluster 'path' field configuration to be set
|
|
|
|
If ACME works on some nodes of a Vault Enterprise cluster but not on
|
|
others, it likely means that the cluster address has not been set.
|
|
|
|
### Symptoms
|
|
|
|
When a Vault client reads the ACME config (`/config/acme`) on a
|
|
Performance Secondary nodes or when an ACME client attempts to connect to a
|
|
directory on this node, it will error with:
|
|
|
|
> ACME feature requires local cluster 'path' field configuration to be set
|
|
|
|
### Cause
|
|
|
|
In most cases, cluster path errors mean that the required cluster address is
|
|
not set in your cluster configuration parameter.
|
|
|
|
### Resolution
|
|
|
|
For each Performance Replication cluster, read the value of `/config/cluster`
|
|
and ensure the `path` field is set. When it is missing, update the URL to
|
|
point to this mount's path on a TLS-enabled address for this PR cluster; this
|
|
domain may be a load balanced or a DNS round robin address. For example:
|
|
|
|
```
|
|
$ vault write pki/config/cluster path=https://cluster-b.vault.example.com/v1/pki
|
|
```
|
|
|
|
Once this is done, re-read the ACME configuration and make sure no warnings
|
|
appear:
|
|
|
|
```
|
|
$ vault read pki/config/acme
|
|
```
|
|
|
|
## Error: Unable to register an account with the ACME server
|
|
|
|
### Symptoms
|
|
|
|
When registering a new account without an [External Account Binding
|
|
(EAB)](/vault/api-docs/secret/pki#acme-external-account-bindings), the
|
|
Vault Server rejects the request with a response like:
|
|
|
|
> Unable to register an account with ACME server
|
|
|
|
with further information provided in the debug logs (in the case of
|
|
`certbot`):
|
|
|
|
> Server requires external account binding.
|
|
|
|
or, if the client incorrectly contacted the server, an error like:
|
|
|
|
> The request must include a value for the 'externalAccountBinding' field
|
|
|
|
In either case, a new account needs to be created with an EAB token created
|
|
by Vault.
|
|
|
|
### Cause
|
|
|
|
If a server has been updated to require `eab_policy=always-required` in the
|
|
[ACME configuration](/vault/api-docs/secret/pki#set-acme-configuration),
|
|
new account registration (and reuse of existing accounts will fail).
|
|
|
|
### Resolution
|
|
|
|
Using a Vault token, [fetch a new external account
|
|
binding](/vault/api-docs/secret/pki#get-acme-eab-binding-token) for
|
|
the [desired directory](/vault/api-docs/v1.14.x/secret/pki#acme-directories):
|
|
|
|
```
|
|
$ vault write -f pki/roles/my-role-name/acme/new-eab
|
|
...
|
|
directory roles/my-role-name/acme/directory
|
|
id bc8088d9-3816-5177-ae8e-d8393265f7dd
|
|
key MHcCAQE... additional data elided ...
|
|
...
|
|
```
|
|
|
|
Then pass this new EAB token into the ACME client. For example, with
|
|
`certbot`:
|
|
|
|
```
|
|
$ certbot [... additional parameters ...] \
|
|
--server https://cluster-b.vault.example.com/v1/pki/roles/my-role-name/acme/directory \
|
|
--eab-kid bc8088d9-3816-5177-ae8e-d8393265f7dd \
|
|
--eab-hmac-key MHcCAQE... additional data elided ...
|
|
```
|
|
|
|
Ensure that the ACME directory passed to the ACME client matches that
|
|
fetched from the Vault.
|
|
|
|
## Error: Failed to verify eab
|
|
|
|
### Symptoms
|
|
|
|
When initializing a new account against this Vault server, the ACME client
|
|
might error with a message like:
|
|
|
|
> The client lacks sufficient authorization :: failed to verify eab
|
|
|
|
This is caused by requesting an EAB from a directory not matching the
|
|
one the client used.
|
|
|
|
### Cause
|
|
|
|
If an EAB account token is incorrectly used with the wrong directory, the
|
|
ACME server will reject the request with an error about insufficient
|
|
permissions.
|
|
|
|
### Resolution
|
|
|
|
Ensure the requested EAB token matches the directory. For a given directory
|
|
at `/some/path/acme/directory`, fetch EAB tokens from
|
|
`/some/path/acme/new-eab`. The remaining resolution steps are the same as
|
|
for [debugging account registration
|
|
failures](#debugging-account-registration-failures).
|
|
|
|
## Error: ACME validation failed for `{challenge_id}`
|
|
|
|
### Symptoms
|
|
|
|
When viewing the Vault server logs or attempting to fetch a certificate via
|
|
an ACME client, an error like:
|
|
|
|
> ACME validation failed for a465a798-4400-6c17-6735-e1b38c23de38-tls-alpn-01: ...
|
|
|
|
indicates that the server was unable to validate this challenge accepted
|
|
by the client.
|
|
|
|
### Cause
|
|
|
|
Vault can not verify the server's identity through the client's requested
|
|
[challenge type](/vault/api-docs/secret/pki#acme-challenge-types) (`dns-01`,
|
|
`http-01`, or `tls-alpn-01`). Vault will not issue the certificate requested
|
|
by the client.
|
|
|
|
### Resolution
|
|
|
|
Ensure that DNS is configured correctly from the Vault server's perspective,
|
|
including setting [any custom DNS resolver](/vault/api-docs/secret/pki#dns_resolver).
|
|
|
|
Ensure that any firewalls are set up to allow Vault to talk to the relevant
|
|
systems (the DNS server in the case of `dns-01`, port 80 on the target
|
|
machine for `http-01`, or port 443 on the target machine for `tls-alpn-01`
|
|
challenges).
|
|
|
|
## Error: The client lacks sufficient authorization: account in status: revoked
|
|
|
|
### Symptoms
|
|
|
|
When attempting to renew a certificate, the ACME client reports an error:
|
|
|
|
> The client lacks sufficient authorization: account in status: revoked
|
|
|
|
### Cause
|
|
|
|
If you run a [manual tidy](/vault/api-docs/secret/pki#tidy_acme) or have
|
|
[auto-tidy](/vault/api-docs/secret/pki#configure-automatic-tidy) enabled
|
|
with `tidy_acme=true, Vault will periodically remove stale ACME accounts.
|
|
|
|
Connections from clients using removed accounts will be rejected.
|
|
|
|
### Resolution
|
|
|
|
Refer to the ACME client's documentation for removing cached local
|
|
configuration and setup a new account, specifying any EABs as required.
|
|
|
|
## Get help
|
|
|
|
Please provide the following information when contacting Hashicorp Support
|
|
or filing a GitHub issue to help with our investigation and reproducibility:
|
|
|
|
- ACME client name and version
|
|
- ACME client logs and/or output
|
|
- Vault server **DEBUG** level logs
|
|
|
|
## Tutorial
|
|
|
|
Refer to the [Build Your Own Certificate Authority (CA)](/vault/tutorials/secrets-management/pki-engine)
|
|
guide for a step-by-step tutorial.
|
|
|
|
Have a look at the [PKI Secrets Engine with Managed Keys](/vault/tutorials/enterprise/managed-key-pki)
|
|
for more about how to use externally managed keys with PKI.
|
|
|
|
## API
|
|
|
|
The PKI secrets engine has a full HTTP API. Please see the
|
|
[PKI secrets engine API](/vault/api-docs/secret/pki) for more
|
|
details.
|