Announcing v0.11.0 of step and step-ca

Max Furman

Follow Smallstep

Version 0.11.0 of step and step-ca is now available. You can get it using brew install step (or brew upgrade step) on macOS or grab release artifacts for step and step-ca from GitHub.

The big headline feature for this release is instance identity document support, which makes it super easy to use step to get certificates from step-ca on AWS, GCP, and Azure. This feature is covered in detail in its own blog post. But there are a ton of other small improvements in this release! Here they are.

Helm package for step-ca

If you're using kubernetes, we now have a helm package for step-ca.

Deploy with:

    helm install smallstep/step-certificates

Choose your key types

The step ca certificate subcommand now lets you choose your key type using the --kty, --crv, and --size flags (CLI PR#136). Prior to this release this command only generated ECDSA P-256 keys (which are still the default). We're not going to be comparing key types here, but if you have an opinion this lets you choose a key type to meet your needs.

Perhaps most importantly, this lets you elect to use RSA keys, which are required in some scenarios. For example, you can use this feature along with single sign-on to make certificate issuance self-service for AWS ClientVPN, which requires RSA keys.

    $ step ca certificate mike@example.com mike.crt mike.key --kty RSA

Thank you Jeremy Stott for raising this issue and helping to design and test the solution!

Self-signed X.509 certificates

You can now create self-signed X.509 certificates (as opposed to CA-signed certificates) using step certificate create via the self-signed profile (CLI PR#124):

    $ step certificate create foo.local foo.crt foo.key --profile self-signed --subtle

We decided to gate this feature with the --subtle flag because secure distribution and use of self-signed certificates is tricky.

Thanks James Guthrie for bringing this to our attention and helping design a solution.

Group checks for SSO (OAuth OIDC) certificate provisioning

You can now configure step-ca to only issue certificates to users in particular groups if your OAuth OIDC provider sends a groups claim in identity tokens (which is non-standard, but is supported by Azure, Auth0, and Okta) (CLI PR#83). To do so, simply list the authorized groups in your provisioner configuration:

    "provisioners": [
        ...
        {
            "type": "OIDC",
            "name": "Auth0",
            "clientID": "XXX",
            "clientSecret": "XXX",
            "configurationEndpoint": "https://XXX.auth0.com/.well-known/openid-configuration",
            "groups": ["admin", "ops", "eng"]
        },
        ...
    ]

Note that some providers may require a custom scope to obtain this information. The step ca certificate subcommand doesn't accept arguments to adjust OAuth OIDC scopes. But you can always use step oauth to obtain a token and pass that in to step ca certificate using the --token flag:

    $ export TOKEN=$(step oauth --bare --oidc \
        --client-id XXX --client-secret XXX \
        --provider https://XXX.auth0.com \
        --listen 127.0.0.1:8080 \
        --scope openid --scope groups)
    
    $ step ca certificate mike@example.com mike.crt mike.key \
        --provisioner Auth0 \
        --token $TOKEN
    ✔ Provisioner: Auth0 (OIDC) [client: XXX]
    ✔ CA: https://localhost:8443
    ✔ Certificate: mike.crt
    ✔ Private Key: mike.key

Thanks matteo-s for this contribution.

Email SAN support

We've supported email SANs in certificates issued via single sign-on since v0.9. But you couldn't get a certificate with an email SAN outside that flow. Now you can. We've added general support for email SANs to step ca certificate and step certificate create (CLI PR#131 & CERT PR#93). Just pass an email in as the subject name or via the --san flag and step will do the rest:

    $ step certificate create mike@example.com mike.csr mike.key --csr --no-password --insecure
    Your certificate signing request has been saved in mike.csr.
    Your private key has been saved in mike.key.
    
    $ step ca sign mike.csr mike.crt
    ✔ Provisioner: mike@example.com (JWK) [kid: EVctZyez6yqbimdu8-y80t9uGJQ4oA4rpFqs7392B-I]
    ✔ Please enter the password to decrypt the provisioner key:
    ✔ CA: https://localhost:8443
    ✔ Certificate: mike.crt
    
    $ step certificate inspect mike.crt
    Certificate:
    ...
            Subject: CN=mike@example.com
    ...
                X509v3 Subject Alternative Name:
                    email:mike@example.com

Bundling for step certificate create

The step ca certificate and step ca sign subcommands, which obtain certificates from step-ca, automatically bundle the issuing intermediate certificate with the issued leaf certificate, which is what you typically want. The lower level step certificate create and step certificate sign commands do not. The step certificate bundle subcommand has been available for this purpose, but we've added a new --bundle flag to do this automatically for these two commands, without requiring a separate bundle step (CLI PR#127):

    $ step certificate create root-ca root-ca.crt root-ca.key --profile root-ca
    Please enter the password to encrypt the private key:
    Your certificate has been saved in root-ca.crt.
    Your private key has been saved in root-ca.key.
    
    $ step certificate create intermediate-ca intermediate-ca.crt intermediate-ca.key \
        --profile intermediate-ca --ca ./root-ca.crt --ca-key ./root-ca.key \
        --san inter.smallstep.com --san 1.1.1.1 --san ca.smallstep.com
    Please enter the password to decrypt ./root-ca.key:
    Please enter the password to encrypt the private key:
    Your certificate has been saved in intermediate-ca.crt.
    Your private key has been saved in intermediate-ca.key.
    
    $ step certificate create foo foo.crt foo.key --profile leaf \
        --ca ./intermediate-ca.crt --ca-key ./intermediate-ca.key \
        --bundle
    Please enter the password to decrypt ./intermediate-ca.key:
    Please enter the password to encrypt the private key:
    Your certificate has been saved in foo.crt.
    Your private key has been saved in foo.key.
    
    $ step certificate inspect --bundle --short foo.crt
    X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2695...5994]
      Subject:     foo
      Issuer:      intermediate-ca
      Valid from:  2019-08-30T19:34:04Z
              to:  2019-08-31T19:34:04Z
    X.509v3 Intermediate CA Certificate (ECDSA P-256) [Serial: 2900...0796]
      Subject:     intermediate-ca
                   inter.smallstep.com
                   ca.smallstep.com
                   1.1.1.1
      Issuer:      root-ca
      Valid from:  2019-08-30T19:33:47Z
              to:  2029-08-27T19:33:47Z

Thanks Vikram Khatri for identifying this low hanging fruit and bringing it to our attention.

Custom ports in OAuth callbacks

The step oauth subcommand, used to obtain an OAuth access token or OIDC identity token on the command line, now allows you to specify a port for the callback server to listen on (CLI PR#120). By default, the callback server obtains an available ephemeral port from the operating system. While IdP support for this behavior is clearly required by OAuth, some providers are non-compliant. We opted to add the ability to specify a listen port as a workaround for non-compliant providers:

    $ step oauth --listen 127.0.0.1:8080

Thanks Jibin George for this contribution.

Console mode for SSO (OAuth OIDC) certificate provisioning

When you use an OAuth OIDC provisioner to get a certificate from step-ca, step will automatically open a browser tab for you to complete the OAuth flow. This works great when you run this command locally. But it doesn't work if you're trying to use SSO to get a certificate on a remote machine. The step oauth command has always had the --console flag for this scenario. We've now added --console to step ca certificate and step ca sign (CLI PR#135):

    $ step ca certificate mike@example.com mike.crt mike.key --console
    Use the arrow keys to navigate: ↓ ↑ → ←
    ✔ Provisioner: Google (OIDC) [client: XXX.apps.googleusercontent.com]
    Open a local web browser and visit:
    
    https://accounts.google.com/o/oauth2/v2/auth?client_id=XXX.apps.googleusercontent.com&code_challenge=XXX&code_challenge_method=S256&nonce=XXX&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code&scope=openid+email&state=XXX
    
    Enter verification code: XXX
    
    ✔ CA: https://localhost:8443
    ✔ Certificate: mike.crt
    ✔ Private Key: mike.key

Unreleased stuff you might want to preview

If you're using kubernetes and haven't checked out autocert yet, you should. We're also working on a cert-manager integration for step-ca and an Envoy SDS integration.

That's it, for now...

Issues & PRs always welcome. Or start a discussion and help us build v0.12.0!