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
• step and step-ca don't have active revocation (CRL & OCSP) support yet, but you can manually manage a CRL. This gist and this blogpost give an example. (Also, we have some official docs for simple active revocation. See Production Considerations)

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

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.