Configuring step-ca Provisioners

Provisioners are methods of using the CA to get certificates for humans or machines. They offer different modes of authorization for the CA. In this section we'll discuss the different provisioners, their target use cases, and how to add, remove, and configure them.

When choosing a provisioner for your use case, you can narrow your options by starting from the types of identifiers you need on a certificate.

Besides the identifier types described above, step-ca also integrates with and supports Wire messenger application identities. The configuration for this is described in ACME for Wire messenger clients.

You can also narrow your provisioner options based on trust dependencies. Trust dependencies are third parties you can leverage to bootstrap trust within your PKI.

Every provisioner has a slightly different scope of authorization. Below is a table detailing the authorization capabilities of each provisioner.

For an example of how to interpret this table, let's take the JWK provisioner. The JWK provisioner is capable of signing, renewing, and revoking X.509 certificates, as well signing user and host SSH certificates. A JWK provisioner cannot renew or rekey SSH certificates.

An SSHPOP provisioner can revoke and rekey SSH certificates and renew SSH host certificates. An SSHPOP provisioner cannot sign, renew, or revoke X.509 certificates, and it cannot sign SSH user and host certificates or renew SSH user certificates.

It's important to understand the capabilities and limitations when selecting a provisioner for a given workload.

Use the step ca provisioner command group to add, remove, or modify provisioner configurations. Run these commands directly on your CA machine. They need to modify the $(step path)/config/ca.json configuration file.

Some provisioner options override global defaults for your CA. For a list of global options, see the configuration guide section for the authority configuration block.

A remote provisioner management API can be enabled in step-ca. It is disabled by default. With remote provisioner management, the CA's provisioner configuration is stored in the database instead of ca.json. (The global CA configuration remains in ca.json.)

This feature can be useful if you have multiple CA administrators, run several load-balanced step-ca instances, or if you want to manage your provisioners remotely (eg. with Infrastructure as Code (IaC) tools; see below).

See Remote Provisioner Management for more.

Common provisioner operations include:

Unless you are using remote provisioner management, you must send a SIGHUP signal, or restart the step-ca process, for changes to your provisioner configuration to take effect.

Use step ca provisioner add to add a provisioner:

See the command reference for complete documentation and examples.

Use step ca provisioner remove to remove provisioners:

You can also edit the ca.json configuration file and remove the entire block containing the provisioner you'd like to remove.

To get a list of all of your current provisioners, use step ca provisioner list or the /provisioners endpoint on your CA.

Use step ca provisioner update to update provisioner configurations:

In this example we've modified the minumum, maximum, and default durations for TLS certificates generated by this provisioner.

Provisioner configuration can be used to affect X.509 and SSH certificate lifetimes, extensions, and templates. There are some provisioner-specific options, which are covered by the documentation for each provisioner type, below.

This feature is disabled by default.

When remote provisioner management is enabled, your provisioner configuration is stored in the database, rather than in ca.json. Provisioner configuration is managed by running step ca provisioner commands locally or remotely. These commands require you to sign in as an Admin user.

To enable remote provisioner management on a new CA, pass --remote-management to step ca init. This will:

To migrate your ca.json provisioners to the database, and to enable remote provisioner management on an existing CA:

With remote provisioner management,
"Admins" can remotely manage provisioners.
"Super Admins" are Admins that can also manage the list of Admins for the CA using step ca admin.

To perform CA administrative operations, you sign into that provisioner as an Admin.

As a Super Admin, lets create an Admin user linked to the Admin JWK provisioner:

Output:

An Admin (or a Super Admin) is a combination of a username (a subject name) and a provisioner. There are no passwords associated with administrators. An administrator is just a subject name and a provisioner name.

The default Super Admin username is step, and the default admin provisioner is called Admin JWK.

You can authenticate as an administrator via the authentication scheme of the provisioner. For example, for the default JWK provisioner, running administrative commands in step will prompt for the provisioner password.

Tip: Single Sign-On can be used for Admin users. To enable SSO CA administration, first add an OIDC provisioner linked to your identity provider. Then, add an Admin user associated with that provisioner, using your email address as the Admin's subject name.

The Admin and Super Admin privileges are not scoped to a provisioner: Admins can modify any provisioner configurations. Super Admins are Admins that can also modify Admins, regardless of provisioner.

You're all set. 🎉

You can use the step ca provisioner commands, from any client, to modify your CA's provisioner configuration.

If you want to manage provisioners remotely using a script or an Infrastructure as Code (IaC) tool, you will need an administrative certificate and key.

An administrative certificate must meet the following criteria:

To create an admin certificate, run:

Output:

With that certificate, you can use it as follows:

If the admin.crt represents a Super Admin, the same flags can also be used to manage Admins:

JSON Web Key (JWK) is the default CA provisioner type, and the step ca certificate client tries to use it by default. With a JWK provisioner, a Certificate Signing Request (CSR) is sent to the CA along with a short-lived JSON Web Token (JWT) which authenticates the request.

The JWK provisioner can be useful for custom integrations. JWTs are easy to generate programmatically, without using step. We have written a few example clients for demonstration purposes.

Here's an example JWT used by step-ca:

The JWT subject (sub) specifies a subject Common Name for the issued certificate. The sha and sans claims are non-standard: they specify the root CA certificate fingerprint in SHA256 and any subject alternative name(s) that are authorized for inclusion in the issued certificate.

The JWT is designed to be generated in one context, then passed into the context where it will be used (eg. a container or pod). Meanwhile, sensitive private key material can remain in the context where it is generated. Therefore, by default, the JWT is not bound to the CSR, which may not yet exist when the token is created. The JWT is instead bound to the expected SANs, subject common name, and the CA's root fingerprint. See Issue a Certificate Using A Single-Use CA Token for an example.

Optionally, a confirmation claim (cnf) can be added (as defined in RFC 7800 § 3.4 to bind the JWT to a CSR. See smallstep/certificates#1637 for details.

Add a JWK provisioner:

In the ca.json configuration file, a complete JWK provisioner example looks like:

We can use step crypto jwe decrypt to see the private key encrypted with the password asdf:

The encrypted private key stored in the JWK provisioner configuration and published to the public /provisioners endpoint is provided for client convenience. It is not required for step-ca to operate. To remove this key:

Sometimes it's useful to issue certificates to people. So step-ca supports single sign-on with identity providers (IdPs) like Google, Okta, Microsoft Entra ID, Keycloak, or any other provider that supports OAuth's OpenID Connect extension.

OpenID Connect is an extension to OAuth 2.0 that adds an identity layer. Providers that support OIDC can issue identity tokens ("ID tokens") to OAuth clients. These are JSON Web Tokens (JWTs) containing user identity information (eg. full name, username, email address). Like certificates, OIDC tokens have a validity period and are cryptographically signed by a trust authority (the OAuth provider).

Here's an example OIDC identity token issued by Google:

The OIDC provisioner in step-ca can be configured to trust and accept an OAuth provider's ID tokens for authentication. By default, the issued certificate will use the subject (sub) claim from the identity token as its subject. The value of the token's email claim is also included as an email SAN in the certificate.

Fig. 3: Diagram of how step works with individuals using a single sign-on provisioner

From the user's perspective, when requesting a certificate, step detects the OIDC provisioner and initiates the OAuth login flow automatically:

When creating an OAuth app, there isn't much to configure on the IdP. Most providers will ask you to specify a Redirect URI, where the ID token will be delivered at the end of the OAuth flow. Since step starts its own local web server to receive the token, use http://127.0.0.1 as the Redirect URI.

One of the most common providers, and the one used in the following example, is Google Identity.

Add a Google provisioner:

Example ca.json provisioner configuration for a Google provisioner:

For OpenID Connect, by default, step opens a web browser to run the Authorization Code flow with PKCE.

Sometimes it's helpful to use OAuth in an input-constrained environment where no web browser is available. The Device Authorization Grant flow (aka "Device Flow") is an OAuth 2.0 extension designed for this scenario. The step client supports the Device Authorization Grant flow.

To use the Device Authorization Grant flow for input-constrained devices, run:

or

With the X5C provisioner, a client can authenticate a certificate request using an existing X.509 certificate from a different CA. It allows clients to use a different PKI to bootstrap trust. Configure this provisioner with a root CA certificate, and any certificate that chains up to that root can be used in a certificate request.

The X5C provisioner uses X5C tokens for authentication. An X5C token is a JWT, signed by the certificate private key, with an x5c header that contains the certificate bundle.

If you would like any certificate signed by step-ca to become a provisioner (have the ability to request new certificates with any name), you can create an X5C provisioner using the root certificate used by step-ca, like so:

Or, you can configure the X5C provisioner with an outside root, granting provisioner capabilities to a completely separate PKI.

Below is an example of an X5C provisioner in the ca.json:

This is an experimental feature.

If you have a Nebula overlay network, you can create a Nebula provisioner and configure it with your Nebula root CA certificate. Clients can then use their Nebula client certificate and private key to request an X.509 or SSH host certificate from step-ca. The Nebula certificate they use for authentication must be issued by the Nebula root CA configured in the provisioner.

The Nebula client certificate is used for authorization, too: The client is allowed to request an X.509 or SSH host certificate with the name or any of the ips appearing on the Nebula client certificate.

To be clear, Nebula certificates can contain a single name and a list of ips. The name field is often a DNS hostname, but it could be an email, IP, or URI. And ips contains a list of CIDR blocks. In step-ca, the Nebula provisioner will authorize certificate subjects or SANs that include the name, plus IPs in any of the CIDR blocks in ips on the Nebula certificate.

To get started, create a Nebula provisioner:

Now you can get an X509 certificate with the Nebula provisioner, using a Nebula client certificate. Here's an example using the DNS name host3.example.com, and two IPs:

An SSHPOP provisioner allows a client to renew, revoke, or rekey an SSH certificate using that certificate for authentication with the CA. The renew and rekey methods can only be used on SSH host certificates.

An SSHPOP provisioner is configured with the user and host root ssh certificates from the ca.json. The SSHPOP provisioner can only authenticate SSHPOP tokens generated using SSH certificates created by step-ca.

An SSHPOP token is a JWT, signed by the certificate private key, with an sshpop header that contains the SSH certificate.

When configured with the --ssh option (step ca init --ssh), the CA will contain a default SSHPOP provisioner named sshpop.

Add an SSHPOP provisioner:

An example SSHPOP provisioner in the ca.json:

The ACME Protocol can authenticate Certificate Signing Requests (CSRs) in a way that enables automation.

ACME clients must answer challenges presented by the ACME server to prove to the CA that they control the identifiers listed in the CSR. ACME supports four different types of challenges: http-01, dns-01, tls-alpn-01, and device-attest-01. These are designed for operability in different environments. See ACME Basics for a description of each challenge type and their tradeoffs.

In a typical setup, an ACME server might issue server certificates via the http-01, dns-01, tls-alpn-01 challenge types, and client certificates via the device-attest-01 challenge type.

The ACME provisioner in step-ca supports issuing X.509 certificates using IP, hostname, and device identifiers.

Add an ACME provisioner:

This will add an ACME server to step-ca. ACME clients are commonly configured with an ACME directory URL. If your CA is hosted at ca.internal, and you run the above command, your ACME server directory URL will be https://ca.internal/acme/acme-example/directory.

To configure popular ACME clients to use step-ca, see our tutorial on the subject.

Here's an example of an ACME provisioner configuration in ca.json:

See ACME Basics for more guidance on configuring and using the ACME protocol with step-ca.

The device-attest-01 challenge supports device attestations from iOS, iPadOS, tvOS, and YubiKeys. An attestation certificate is used to satisfy the ACME challenge. The CSR may include a device ID in a permanentIdentifier SAN (RFC 4043), depending on the application.

This challenge type is not enabled by default and must be explicitly enabled.

The device-attest-01 challenge response uses a variant of the WebAuthn attestation statement format adapted for ACME. The variations are specified in IETF draft-acme-device-attest.

step-ca supports device attestation statements in tpm, apple, and step formats.

To add a device-attest-01 provisioner for use with Managed Device Attestation on Apple devices, run:

In your Apple MDM profile, you will need:

To add a device-attest-01 provisioner for YubiKey devices, run:

To get a client certificate for a hardware-bound private key on your YubiKey:

While step-ca supports the tpm attestation format of ACME device-attest-01, an end-to-end TPM-bound client certificate flow is not available at this time.

A device needs to provide an attestation certificate in its response to an ACME device-attest-01 challenge. Apple has an online attestation authority service for this. Yubico offers attestation certificates on their devices.

But we have not seen a public or open source attestation authority that can issue attestation certificates for TPMs. TPMs also have privacy constraints and a wide range of use case-specific validation requirements that complexify attestation flows.

For a description of how a TPM-based attestation flow might work, if implemented, see TPMs + ACME: Better Together

The wire-oidc-01 and wire-dpop-01 challenges enable step-ca to issue certificates to Wire messenger clients. Wire clients make use of a user and a device identity, both of which are challenged and verified, after which the identities are combined into a single X.509 certificate.

Here's an example of an ACME provisioner with Wire support enabled in $(step path)/config/ca.json:

The SCEP provisioner can sign and renew certificates using the SCEP protocol (RFC8894). SCEP is very popular for use in network equipment and mobile device management (MDM). It runs over HTTP using POSTed binary data or base64-encoded GET parameters, using CMS (PKCS#7) and CSR (PKCS#10) data formats. A (shared) secret authenticates clients to the CA.

Your CA must use an RSA intermediate CA, even if your client supports ECDSA. The RSA intermediate is used to decrypt the contents of the SCEP pkcsPKIEnvelope containing the certificate request. This operation cannot be performed using an ECDSA key.

Because step ca init creates an ECDSA chain by default, you will need to convert your CA to use an RSA CA chain before using the SCEP provisioner.

In this example, we will add a SCEP provisioner using challenge secret secret1234 and AES-256-CBC as the encryption algorithm:

The shared challenge should be a value that you will distribute to your SCEP clients.

Here's an example of a SCEP provisioner in $(step path)/config/ca.json:

If you don't want to rely on a single, static secret, you can configure a SCEPCHALLENGE webhook instead. When a SCEP client requests a certificate, the webhook server will receive a request with the scepChallenge and scepTransactionID properties from the SCEP request. The webhook server can then decide if the request is allowed or not.

By default SCEP will only be served via HTTPS. Most SCEP clients use HTTP, so you will most likely need your CA to listen using HTTP too, which it does not do by default. Enable this by filling in the "insecureAddress" property to your top-level CA configuration:

Finally, restart step-ca. Your SCEP provisioner is now available at the endpoint http://ca.example.com:8080/scep/scepca.

A K8sSA provisioner allows a client to request a certificate from the server using a Kubernetes Service Account Token.

As of the time when this provisioner was coded, the Kubernetes Service Account API for retrieving the token from a running instance was still in beta. Therefore, our K8sSA provisioner must be configured with the public key that will be used to validate K8sSA tokens.

K8sSA tokens are very minimal. There is no place for SANs, or other details that a user may want validated in a CSR. It is essentially a bearer token. Therefore, at this time a K8sSA token can be used to sign a CSR with any SANs. Said differently, the K8sSA provisioner does little to no validation on the CSR before signing it. You should only configure and use this provisioner if you know what you are doing. If a malicious user obtains the private key they will be able to create certificates with any SANs and Subject.

Add a K8sSA provsioner:

An example of a K8sSA provisioner in the ca.json:

step-ca can be configured to use instance identity documents (IIDs) to authorize certificate signing requests from cloud VMs running on AWS, GCP, or Azure. IIDs are signed JSON tokens, created when the instance is launched, and made available via the instance metadata API.

Here's the contents of an example IID from AWS:

Fig. 2: Diagram of how step works with a cloud service as the provisioner

Once you’ve configured step-ca to accept IIDs for authentication, step will detect the provisioner type, obtain an IID token from your cloud provider's metadata API, and use it to obtain a certificate from step-ca.

From the CA's perspective, an IID is a single-use token. A host can only get one certificate, ever, per IID. A host can then renew its certificate using step ca renew. If the certificate ever expires, the host will need to use a different provisioner to issue a new one.

While IIDs simplify the integration of step-ca, the approach comes with risks.

Unfortunately, an IID usually doesn't contain enough information to authenticate a host certificate. For example, while an IID may contain the private or public IP for the host, it will not contain all of the DNS names and IP addresses that you may want on the certificate.

Because of this, step-ca's cloud provisioners use the Trust on First Use (TOFU) security model, allowing any instance to get a certificate with any names (SANs) on it.

This allows for a "cryptographic perimeter": If a host presents a certificate that was signed by your CA using a cloud provisioner, and the CA is configured to verify the instance's account, project, or tenant ID in the IID, you can have some confidence that the request came from your infrastructure (not someone else's), but you cannot assume that the names on the certificate are authentic.

Because of this, every host in your infrastructure must be trusted.

Here are some things you can do to mitigate risk when using IIDs:

There are a lot of details to get right to make this model secure, many of which are environment-dependent and beyond the scope of this document.

The AWS provisioner allows granting a certificate to an Amazon EC2 instance using the Instance Identity Documents

The step CLI will generate a custom JWT token containing the instance identity document and its signature and the CA will grant a certificate after validating it.

Find your AWS account ID to restrict access to our VMs:

On the host running step-ca add an AWS provisioner to your configuration by running:

In the ca.json, an AWS provisioner looks like:

The GCP provisioner grants certificates to Google Compute Engine instance using its identity token. The CA will validate the JWT and grant a certificate.

On the host running step-ca, add an GCP provisioner to your configuration by running:

In the ca.json, a GCP provisioner looks like:

The Azure provisioner grants certificates to Microsoft Azure instances using the managed identities tokens. The CA will validate the JWT and grant a certificate.

On the host running step-ca, add an Azure provisioner to your configuration by running:

In the ca.json, an Azure provisioner looks like: