Tutorials, examples, integrations and workflows

[tashian]

Aside from our official tutorials and blog posts, there have been many community-contributed tutorials, examples, integrations and workflows that use the step toolchain. Here's a few we know about. As these are community contributions, they are not supported by Smallstep. Use them at your own risk.

General tutorials

• Blog post about running a PKI using step-ca and Docker (9/2021)
• Praqma/smallstep-ca-demo: Demo showing how to provide a behind-the-firewall Certificate Authority for CI/CD environments (related blog post)
• To automate TLS certificates in Docker containers using ACME, see smallstep/docker-tls, and the accompanying blog post
• Root rotation tutorial for step-ca by @darsh12
• Nitrokey HSM 2 powered PKI with step-ca by @seism0saurus

Plugins for step

• step-kmsproxy-plugin:
  Provides an HSM/KMS-backed authenticating proxy for mTLS services. Thanks to
  @andsens for creating and maintaining this plugin!

Integrations with other OSS projects

• isodude/step-ca-oidc-hydra: a Docker Compose project that integrates step-ca's OIDC provisioner with Hydra, an API-only OAuth 2.0 and OpenID Connect provider.
• joaopedrolourencoaffonso/python_smallstep peer-to-peer registration authority. A python API that uses Quart, Telethon and step-ca to provide a simple Registration Authority for P2P. See this discussion for more details.
• Using Gitea with step-ca SSH certificates
• NGINX with step-ca certificates: A Docker Compose project that runs a step-ca container, an Nginx container, and a container that creates and renews the Nginx server certificate.
• Securing Istio and Kubernetes With a Private Certificate Authority
• smallstep/mongo-tls: Complete setups for MongoDB single-node TLS, cluster TLS, and X.509 user authentication, using step-ca. See the accompanying blog series.
• Win Acme: Here's a discussion thread on configuration and integration
• quickvm/smallstep-systemd-units, contributed by Joe Doss, contains two things: A template for systemd-based boostrapping, enrollment, and renewal of certificates, and an example automation for Hashicorp Vault server certificates
• 802.1X identity certificates for macOS devices, via step-ca's SCEP server — this tutorial bridges FreeRADIUS + Google Workspace LDAP + MicroMDM + step-ca
• step-by-step + Bitwarden + Vaultwarden + Traefik in-depth tutorial by Yassine Zouggari

Configuration Management

• Basic Puppet example shows how to instrument services with TLS via Puppet manifests
• Custom GitHub Action that sets up step CLI
• Puppet example by Robert Waffen on GitHub: https://github.com/rand0mcode/puppet-step_ca
• SaltStack formula by darix on GitHub: https://github.com/darix/step-ca-formula
• SaltStack example by Ross Crawford-d'Heureuse on GitHub: https://github.com/rosscdh/smallstep_ca-formula
• Ansible collection by Max Hösel on GitHub: https://github.com/maxhoesel/ansible-collection-smallstep
• Ansible collection focused on SSH CAs: https://github.com/smallstep/certificates/tree/master/examples/ansible
• Edd Miles wrote a blog showing how to automate SSH host certificates using Puppet. Also explores adding TLS certificate automation for TrueNAS Scale, Forejo/Gitea, Opnsense, and QNAP devices.

Integrations with programming languages

Go

• Go client example: A client that can interact with the step-ca API
• Bootstrap server: Example server and client code that gets a certificate from step-ca (JWK provisioner) and uses mutual TLS authentication with its clients. The server does its own internal certificate renewal with the CA.
• go-grpc-example: ACME and non-ACME (static PEM) versions of a gRPC server that uses server-side TLS

Python

• smallstep/clients contains a Python client for step-ca certificate signing

Node.js

• smallstep/clients contains a Node.js client for step-ca certificate signing

CA configuration and PKI architectures

• The Federated roots example allows you to run multiple federated autonomous CAs within a PKI that includes multiple root CAs
• The Custom validity periods example shows how to configure provisioners with different minimum, default, and maximum certificate validity durations.
• rjfmachado/step-ca-azure is a deployment of step-ca on Azure. It leverages Azure Key Vault, Azure MySQL, and Managed Identities.

Webhook apps

• Smallstep's webhook example server for step-ca, written in Go
• A sample webhook server by @maraino to allow requests with an ACME device-attest-01 flow in step-ca.
• step-posture-connector is designed to assist step-ca with posture information during an ACME device attestation process. Created by Jedda Wignall— see Jedda's related blog post about Apple Managed Device Attestation

Demos

• smallstep/step-ssh-example demonstrates the use of SSH certificates for hosts and users. Requires Vagrant.
• smallstep/step-aws-emojivoto is an example microservice application that uses mutual TLS between microservices. It employs step-sds, Envoy (for TLS termination), and AWS as a host

Utilities

• Get an identity token from Okta without a web browser: https://gist.github.com/mmalone/2405891649a18d5468fa23f6908261a3
• Command-line SCIM directory management (create, delete, lookup): https://gist.github.com/mmalone/5c60d4b3fb507233c40de83f7c751553
• Get row counts from the Badger database used by step-ca: https://gist.github.com/dopey/8e9206073e2cb052b6f633c0b7d4d8df
• Export data from the step-ca Badger database with step-badger
• Convert step-ca certificate data in PostgreSQL into JSON with stepundb

If you've created a tutorial, blog post, repo, or Gist that shows off how you're using our stuff, please add it in the comments!

[krnbr]

Using Smallstep to secure the AWS API gateway using MTLS, here is the link:-

https://dev.to/aws-builders/aws-api-gateway-mtls-authentication-with-smallstep-pulumi-2o65

[krnbr]

Traefik and Smallstep integration

https://neuw.medium.com/smallstep-and-traefik-architecture-60233533d05a?source=friends_link&sk=fc6dce7fc4ce1c40e0481f17209b1b6b

https://neuw.medium.com/setup-traefik-acme-using-smallstep-f7986302a12c?source=friends_link&sk=10e5ccc066c89d7b220d8f94657e7689

[damhau]

I'm working on a self hosted GUI to manage step ca with feature like list/sign/revoke certificate.

I've have a few question, are you ok with this ? And shall I share it here ?

[tashian]

I'd suggest joining our Discord: https://u.step.sm/discord

[seism0saurus]

I did a walkthrough for a Nitrokey HSM 2 powered PKI with step-ca at the Open Security Conference 24. Maybe it is helpful for some readers: https://seism0saurus.de/posts/private-acme-ca-hsm/

[maraino]

Love it, you can also use step-kms-plugin to create the root and intermediate keys:

step kms create "pkcs11:module-path=/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so;token=smallstep;id=1000;object=root?pin-value=password
step kms create "pkcs11:module-path=/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so;token=smallstep;id=1010;object=intermediate?pin-value=password

And create the root and intermediate certificates:

export KMS="pkcs11:module-path=/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so;token=smallstep?pin-value=password"
step certificate create --profile root-ca --kms $KMS --key "pkcs11:object=root" \
     'My Root CA' root_ca.crt
step certificate create --profile intermediate-ca \
     --kms $KMS --key "pkcs11:object=intermediate" \
     --ca-kms $KMS --ca-key "pkcs11:object=root" \
     'My Intermediate CA' intermeidate_ca.crt

That would create a basic root and intermediate ca, but you can customize it using a template.

[maraino]

If you are using p11-kit and it is properly configured, you can get rid of the module-path argument to the URIs are simpler, and there are also 3 ways to ask for a pin:

pkcs11:module-path=token=smallstep;id=1000;object=root?pin-value=password
pkcs11:module-path=token=smallstep;id=1000;object=root?pin-source=/path/to/pin.txt
pkcs11:module-path=token=smallstep;id=1000;object=root?pin-prompt

The last one is in the last version of step-kms-plugin.

[sdgathman]

Using acme-tiny https://github.com/diafygi/acme-tiny/ with step-ca ACME provisioner.
Invoke as
acme-tiny --account-key private/account.key --csr csr/mysite.csr --acme-dir /var/www/challenges/ --ca https://ca.internal:9000/acme/MYCA > certs/mysite.crt

This assumes the internal CA is already trusted to connect to ca.internal and DNS configured to resolve the internal TLD.

This will be integrated with the Fedora acme-tiny package system glue.

[darsh12]

I could not find a good guide on how to rotate root ca, so wrote a small guide on how I was able to achieve that
https://unhackable.lol/rotate-root-with-step-ca-small-step/

[maraino]

Hi @darsh12, I'd like to see the guide that you wrote, but I get a 502 from cloudflare.

[darsh12]

Hey, @maraino was just updating the site. It should be back up in 5 min.

[darsh12]

@maraino, it is now online.

[tashian]

thanks @darsh12 I've added your tutorial to the post. :)

[themushum]

Very concisely, I was directed to Step-Ca after days on end working with OpenSSl to achieve self-signed certificates for my internal only Unraid server. There is no Unraid Community version of Step-Ca, but I was able to successfully get the Step-Ca docker working through the Docker hub.

There appears to be some step associated with it to install Step CLI. I won't blame anyone for ignoring my request for guidance on that part, either directly or some resource that is more clear for a newbie than the Section START step-ca (where it is discussed). I feel Step-ca maybe the solution to the problem. I would appreciate even knowing if this is not the case. :-)

[sdgathman]

I was able to do everything with openssl CLI. Step-cli knows about step-ca, but I haven't run into anything that openssl can't do (to provide step-ca with everything it needs). Could be more automated with some scripting.

[netops2devops]

Hey folks,

I wanted to share an ExternalCAS implementation that I recently developed for our org mostly out of necessity. Due to constraints imposed by security policy and legacy DNS mgmt infrastructure, we are unable to use LetsEncrypt directly.

While we use InCommon/Sectigo as our primary CA, it is my understanding that this plugin is generic enough to work with any CA which supports external account binding. It most definitely works with InCommon that I can confirm. I am using step-ca as a standalone ACME server running in RA mode. Once step-ca validates the client has solved ACME challenge, it uses EAB credentials to get a signed certificate from the external CA.

https://github.com/esnet/acme-proxy

If folks could provide some feedback or happen to spot something obvious which doesn't seem right, please do share.

Thanks for developing & maintaining this open source project. It really is a swiss army knife for all things PKI 😀