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.

Overview

Authorization Scope by Provisioner

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.

Managing Provisioners

Common provisioner operations include:

Add a provisioner

See step ca provisioner add --help for documentation and examples on adding provisioners.

We strongly recommend using the step ca provisioner add [...] utility to generate provisioners in your ca.json configuration. We often encode fields differently in the JSON than you might expect. And you can always modify the JSON configuration manually after using the utility.

Remove a provisioner

See step ca provisioner remove --help for documentation and examples on removing provisioners.

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

List all provisioners

To get a list of all of your current provisioners, run the following command in your terminal:

Modify a provisioner

Modify a provisioner by directly modifying the ca.json configuration.

The following diff is an example of modifications in ca.json that add few configuration options to a provisioner:

In this example we've modified the min, max, and default duration for TLS certificates generated by this provisioner.

Provisioner configuration can be used to affect X.509 and SSH certificate lifetimes, extensions, and any other attribute belonging to the certificate. See the Modifiers section for more details.

Modifiers

Claims

Each provisioner can define an optional claims attribute. The settings in this attribute override any settings in the global claims attribute in the authority configuration.

Example claims:

X.509 CA properties

SSH CA properties

Options

Each provisioner can define an optional options attribute. This attribute allows an operator to set templates that will be applied to all X.509 or SSH certificates generated using the provisioner.

Learn more about configuring X.509 and SSH templates here.

JWK

JWK is the default provisioner type. It uses public-key cryptography to sign and validate a JSON Web Token (JWT).

The step CLI tool will create a JWK provisioner when step ca init is used, and it also contains commands to add (step ca provisioner add) and remove (step ca provisioner remove) JWK provisioners.

Example

Add a JWK provisioner:

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

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

If the ca.json does not contain the encryptedKey attribute, the private key must be provided using the --key flag when using the step ca [token | certificate | sign] utilities.

OAuth/OIDC Single Sign-on

Sometimes it's useful to issue certificates to people. So step-ca supports single sign-on with identity providers (IdPs) like Google, Okta, Azure Active Directory, 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:

Configuring your identity provider (IdP)

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.

Example: Google Identity

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:

Notes

Further reading

X5C - X.509 Certificate

An X5C provisioner allows a client to get an x509 or SSH certificate using an existing X509 certificate that is trusted by the provisioner.

An X5C provisioner is configured with a root certificate, supplied by the user, at the time the provisioner is created. The X5C provisioner can authenticate X5C tokens.

What's an X5C token? It's a JWT, signed by the certificate private key, with an x5c header that contains the chain.

Example

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:

SSHPOP - SSH Certificate

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.json will contain a default SSHPOP provisioner named sshpop.

Example

Add an SSHPOP provisioner:

An example SSHPOP provisioner in the ca.json:

ACME

An ACME provisioner allows a client to request a certificate from the server using the ACME Protocol. This provisioner supports issuing X.509 certificates with IP or hostname identifiers. It supports the http-01, dns-01, and tls-alpn-01 ACME challenge types, All authentication of the CSR is managed by the ACME protocol.

Example

Add an ACME provisioner:

An example of an ACME provisioner in the ca.json:

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

SCEP

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.

Requirements

Your CA must use an RSA intermediate CA, even if your client supports ECDSA. We use the RSA intermediate to encrypt/decrypt data, and you cannot do that with 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.

Configuration

The step ca provisioner command group does not yet support SCEP. Configure a new SCEP provisioner by adding the following to the provisioners section of $(step path)/config/ca.json:

Change the "challenge" password to a value that you will distribute to your clients.

Most SCEP clients use HTTP. So, you will most likely need your CA to listen using HTTP, 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://your.ca.hostname:8080/scep/scepca.

K8sSA - Kubernetes Service Account

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.

Example

Add a K8sSA provsioner:

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

Cloud Provisioners

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.

Security Risks and Limitations

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.

Mitigating the risk of IIDs

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.

AWS

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.

Example

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:

GCP

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

Example

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

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

Azure

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

Example

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

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