Webhooks let you enrich X.509 or SSH certificates with data requested from an external endpoint.
The CA fetches key/value pairs from a configured webhook when a CSR is being processed,
and the webhook data is passed along to the provisioner's certificate template.
Attach webhooks to provisioners via the step ca provisioner webhook command group.
We've created an example webhook server.
You can use it to try out webhooks locally,
or as the basis of your own custom webhook integration.
Initialize a new Certificate Authority with remote management enabled.
step ca init --remote-management --context webhooks
The webhook server must include "allow": true in the response body,
or step-ca will refuse to sign the certificate request.
The step-ca template engine augments the template data with the data object in the response body.
For example, a webhook server could send the following JSON response:
A template on the provisioner will then be able to reference the response under the path .Webhooks.webhook_name.
If the webhook was named people, the role in the webhook response could be accessed in a template under the field .Webhooks.people.role.
All requests will use the POST method to send a JSON body to the webhook server containing a timestamp field.
Additional data will vary based on the type of the certificate being signed.
The webhooks server example repository contains examples in Go of parsing webhook request bodies for both X.509 and SSH certificate requests.
You can use webhooks to enrich device certificates issued via an ACME device-attest-01 challenge.
When used with the ACME provisioner
and the ACME device-attest-01 challenge,
the request body will also contain the verified device ID in the attestationData.permanentIdentifier field.
Your webhook server must authenticate each request from the CA.
To achieve this, the CA sends a signature of its payload in the webhook request header,
and the webhook server must confirm this signature.
The signature also tells the webhook server which webhook is currently being executed.
In addition the the signature header, you can optionally enable two other authentication schemes:
Authorization Header The CA can send a bearer token or username and password in an Authentication header.
Mutual TLS The webhook server can require and verify the connection using mutual TLS. The CA will provide a client certificate when requested.
Every webhook has a unique secret that will be displayed when the webhook is created
via step ca provisioner webhook add.
step-ca will include a signature of the payload in the X-Smallstep-Signature header.
The webhook ID will also be included in the X-Smallstep-Webhook-ID header
to help associate the correct signing secret with the webhook request.
Webhook servers must compute an HMAC with the SHA256 hash function,
using the webhook signing secret as the key and the request body as the message.
See the webhook server example repository for an example of verifying the signature.
Authorization Header (optional)
For an additional layer of security, step-ca may be configured to send
either a bearer token
or a username:password in the Authorization header.
To use a bearer token, run:
step ca provisioner webhook update my_provisioner my_webhook --bearer-token abc123xyz
Or, to use basic authentication, run:
step ca provisioner webhook update my_provisioner my_webhook --basic-auth-username user --basic-auth-password-file pass.txt
Mutual TLS (optional)
You can also use mutual TLS to authenticate step-ca as a client of your webhook server.
By default, step-ca will send the CA's self-generated leaf certificate
when asked for a client certificate as part of the TLS handshake.
To enable mutual TLS,
configure your webhook server to request and verify a client certificate
that chains up to your root CA certificate.