Configuring step-ca Templates

People use private CAs for all sorts of things, in many different contexts: web apps, mobile apps, code signing, cloud VM instances, SSH, IoT devices, etc. So step-ca must be flexible enough to handle a wide variety of flows.

X.509 and SSH certificate templates open up these possibilities. With certificate templates, you can do things like:

Certificate templates are JSON documents that describe the most important properties in the final certificate or certificate request. They are Go text/template files. Sprig functions are available inside the templates. A few custom functions for ASN.1 encoding and time formatting are also available.

There are default X.509 and SSH templates hardcoded into step-ca.

In addition to the time formatting functions offered by Sprig, step-ca has added some additional convenience functions for X.509 and SSH templates:

How you add templates to step-ca depends on whether you have enabled remote provisioner management.

Remote provisioner management is disabled by default.

Within the provisioner configuration block of $STEPPATH/config/ca.json, certificate templates can be set under the property "options". The following snippet shows a provisioner with custom X.509 and SSH templates:

You can use step ca provisioner update to read a template file which will then be stored in the database for use by step-ca. For example:

See step ca provisioner update for more options.

X.509 templates can be used in two places:

Here's what the default X.509 leaf certificate template looks like:

The fields available in an X.509 template map to X.509 v3 certificate fields. See the complete list of fields supported in step-ca templates.

Here are some common variables available in X.509 certificate templates:

You can also import values from the "templateData" object in your provisioner's configuration block.

This is section is for advanced use cases that require custom extensions or special encodings of data inside certificates. Most users are best served by step-ca's higher-level template functions.

The templating system in step-ca includes a few functions for encoding ASN.1 values.

ASN.1 (Abstract Syntax Notation 1) is a standard from the 1980s that define the data structures and format of an X.509 certificate. X.509 certificates are encoded using ASN.1, then serialized into binary using DER (Distinguished Encoding Rules) before being (optionally) PEM-encoded with Base64.

Use these functions to populate custom certificate OID extensions:

When applied to template variables, these functions enable dynamic OID extensions:

Let's walk through one line of this template:

To render this line of the template:

Encodes a string into an ASN.1 value.

A data type can be supplied as a prefix, and ASN.1 Printable is the default data type:

This function supports the data types described here:

For more details on ASN.1 types and their meanings, see ASN.1 Types.

asn1Marshal simplifies the encoding of Go variables into ASN.1. For example, if you want to encode the Not After value in an X5C authorization certificate, without converting it to a string first, asn1Marshal .AuthorizationCrt.NotAfter will do the trick.

asn1Marshal imitates Go's asn1.MarshalWithParams function.

The second parameter is the ASN.1 data type. It will use Go's default transformation if no data type is supplied.

Creates an ASN.1 SEQUENCE of values.

Creates an ASN.1 SET of values.

step-ca also supports SSH certificate templates. Here is step-ca's default SSH certificate template:

The OpenSSH certificate protocol spec defines SSH certificate fields and the available Critical Options and Extensions. Third parties can also add custom extensions. See the complete list of fields supported by step-ca SSH template.

Here are the most relevant parameters available in SSH certificate template:

You can also import parameter values from your provisioner's configuration block.

The most common type of certificate you'll want to create is a leaf (or end-entity) certificate; this is the type of certificate that your servers or clients will use.

The default leaf certificate template is:

We will explain what each block does, but first, let's look at what a rendered template might look like. Imagine that you run the following command to create a certificate that has jane@doe.com as an email SAN.

The rendered template (from which the X.509 certificate will be generated and signed) is:

Going back to the template above, we can see that the template has blocks delimited by {{ and }}. These are called actions - actions are data evaluations or control structures. The ones in the default template are:

Finally we also set the extended key usage serverAuth and clientAuth so the certificate can be used in a server application or in a client for mTLS.

An intermediate certificate is a certificate that can be used to sign another certificate, and it has itself been signed by another intermediate certificate or by a root certificate.

The default template for an intermediate certificate is:

This template is most commonly used when initializing a CA.

The keyUsage certSign allows a certificate to sign other certificates. crlSign allows a certificate to sign Certificate Revocation Lists or CRLs.

In basicConstraints we say that this certificate is a CA, and the path length constraint, maxPathLen, is maximum number of non-self-issued intermediate certificates that may follow this certificate in a valid certification path. An intermediate with a maxPathLen set to 0 won't be able to sign another intermediate certificate. To be precise, it can sign it, but the new intermediate won't be trusted by clients, so it won't be useful.

Knowing this we can also guess that the intermediate certificate's issuer had at least a maxPathLen of 1. So if you want to use an intermediate certificate that can sign other intermediates, make sure to set more permissive maxPathLen in the root and intermediate certificate used.

The command step certificate create with the --profile intermediate-ca flag uses the template above, but if you want to create an intermediate with a custom template you can run:

A root certificate is a self-signed certificate used to sign other certificates. The default root certificate template is:

Here we are specifying that the issuer is equivalent to the subject, and the maxPathLen is set to 1, so it can sign intermediate certificates with maxPathLen set to 0. If you want to allow intermediates to sign other intermediates, you need to set the maxPathLen to at least 2. It's also possible to not limit the number of intermediates that can follow this certificate if we set maxPathLen to -1, and then create intermediates that set a specific limit, i.e. 0 for those that can sign only leaf certificates and 1 for those that can sign at most one downstream intermediate certificate.

The command step certificate create with the --profile root-ca flag uses the above template. To create a custom root certificate, you can run:

In the previous section, we learned how to create and use the basic templates, but we've just scratched the surface of what's possible. With templates, you can customize and parameterize every aspect of an X.509 or SSH certificate.

Below, we'll walk through a few advanced templating examples.

Let's start with one of the shortest templates:

This template produces a signed certificate that contains all the information present in the certificate request (with a few caveats). All SANs and extensions present in the certificate request will be in the final certificate.

The only modifications that a signed certificate might have (over a CSR), would be in the certificate subject on step-ca if a template is provided in the ca.json, and it will set the Subject Alternative Name extension to critical if the subject is empty.

In step-ca, X.509 templates can also be parameterized with variables that will be provided by step at certificate creation time. A common use case for variables is when you receive a CSR from another team, or a CSR embedded in hardware, and you need to define a SAN for it.

For example, below is an X.509 template that accepts the user variable dnsName but falls back to the default leaf template if it's not present:

You can then use step to sign a CSR like so:

Both flags, --set <name=value> and --set-file <path> are available in step ca certificate and step ca sign. If you need to pass more than one variable, you can use --set multiple times or use a JSON file with multiple properties.

It's worth mentioning the while we used "dnsNames" instead of "sans" in the example above, both can be used. "dnsNames" is an array of strings (or just one string if only one is required), while "sans" is an array of objects like:

The variable .SANs is generated by the provisioners with the values of the trusted names.

Besides "dnsNames", you can also use "emailAddresses", "ipAddresses", and "uris".

Name constraints are useful in intermediate certificates when you want to limit the validity of certificates that an intermediate can sign. If we want to only allow DNS name like *.example.com we can generate an intermediate with the template:

Given a root certificate and a key, you can generate the intermediate with:

Besides "permittedDNSDomains", the "nameConstraints" property accepts all the following properties:

Remember that in certificate templates, if an array only has one member, you can write it as a string:

SANs, key usages, extended key usages, basic constraints, and name constraints, are all extensions in an X.509 certificate. Templates provide an easy way for assigning extensions without the need of using the actual extension bytes.

The same thing is also possible with top-level certificate template properties like:

But if you need to create your own extension, or use an unsupported one, you can also write a custom extension like:

The crux here is that the value of the extension is the Base64 encoding of the actual bytes that go into that extension, so if you are encoding a structure in your extension using the ASN.1 encoding, you will have to put the Base64 version of the encoded bytes.

One interesting use case for certificate templates is the signing of OpenVPN certificates. These certificates require specific key usages not available in the default templates.

This is a template you can use in a provisioner signing OpenVPN client certificates:

And the following template can be used for a provisioner signing OpenVPN server certificates:

A full configuration of step-ca and OpenVPN is available in our blog post "Announcing X.509 Certificate Flexibility"

With GitHub Enterprise Cloud or GitHub Enterprise Server, you can configure GitHub to use SSH certificates. Specifically, GitHub will trust an SSH Certificate Authority for your team. But, to get it to work, you have to generate custom SSH certificates for your users using a login@github.com extension, where the value of the extension is their GitHub Username. This custom extension value authenticates your users to GitHub Enterprise. Which is great: The same certificates that let you SSH into your servers now also let you push code.

Here's an SSH template that supports the GitHub custom SSH certificate extension:

To use this template, you'd need to add a ghu ("GitHub Username") custom claim to the token that you send the CA to authenticate your certificate request.

If you use an OIDC provisioner with this template, you can configure your identity provider to serve a custom claim labeled ghu in your ID token. Our blog post "Clever Uses of SSH Certificate Templates" has more details on this option.

The JWK and Cloud provisioners also use tokens. Here's an example of a Bash test script that decrypts your JWK provisioner key, and uses it to sign a token that step-ca will accept for an SSH certificate:

Here's the script used in concert with the GitHub SSH template above:

In production, you would not want to hand out your JWK provisioner password. But you could create a token server that interoperates with step-ca and injects secure values into the token.

Let's say your organization has shared group accounts on your hosts (eg. "dba" or "devops"). You'd want to be able to issue people in those groups a certificate that contains their user principals ("carl", "carl@smallstep.com"), plus principals for any group accounts they need access to.

Let's use the OIDC ID token to inject additional principals into an SSH user certificate.

First, configure a custom groups claim with your identity provider, and add the claim to the payload of the ID token. In this example, we're assuming the groups claim contains a space-separated list of possible group accounts.

Then, use the following template to merge the group accounts with the user's own principals (derived from the email claim):

This is a good example of the use of Sprig functions in templates.

Finally, test out your flow with step ssh login, and use step ssh inspect to check the principals of the certificate you're issued by the CA.

To delve deeper into certificate templates and all the options, the best source of information is the code docs for the go.step.sm/crypto/x509util package:

More information and more examples are available in the blog posts "Announcing X.509 Certificate Flexibility" and "Clever Uses of SSH Certificate Templates".