Smallstep

https://smallstep.com/docs/tutorials/
Admin
Smallstep is an automated certificate management and PKI platform that secures network access,...
Tokens:98,073
Snippets:728
Trust Score:9.4
Update:4 days ago
Show doc for...
Tokens:
Raw
### Python: Install dependencies and start server

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Install the acme and pem packages, then start the Python HTTPS server. The server uses the ACME client to obtain a certificate.

```bash
pip install acme
pip install pem
python https.py
```

--------------------------------

### Run the Python example server

Source: https://smallstep.com/docs/tutorials/user-authentication

Starts the Python mTLS server.

```bash
python server.py
```

--------------------------------

### Node.js: Install dependencies and start server

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Install the node-acme-client package and start the Node.js ACME server. The server uses the ACME client to obtain a certificate and serve HTTPS.

```bash
npm install node-acme-client
node acme.js
```

--------------------------------

### Start step-ca server

Source: https://smallstep.com/docs/tutorials/ssh-certificate-login

Command to start the step-ca server with the example configuration, requiring passwords for intermediate CA, SSH host, and SSH user keys.

```bash
$ export STEPPATH=pwd/step
$ step-ca step/config/ca.json
Please enter the password to decrypt step/secrets/intermediate_ca_key: password
Please enter the password to decrypt step/secrets/ssh_host_key: password
Please enter the password to decrypt step/secrets/ssh_user_key: password
2019/09/11 22:59:01 Serving HTTPS on :443 ...
```

--------------------------------

### Apache: Start and verify with curl

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Start Apache and verify the HTTPS setup using curl with the root CA certificate. The expected output is 'Hello TLS'.

```bash
$ curl --cacert $(step path)/certs/root_ca.crt https://foo.internal

Hello TLS
```

--------------------------------

### Start step-ca server

Source: https://smallstep.com/docs/tutorials/docker-tls-certificate-authority

Starts the CA server, exposing the HTTPS API on port 9000.

```bash
docker run -d -p 9000:9000 -v step:/home/step smallstep/step-ca
```

--------------------------------

### Start Vagrant VM for SSH certificate login

Source: https://smallstep.com/docs/tutorials/ssh-certificate-login

Run `vagrant up` inside the step-ssh-example repo to start the testhost VM. The output shows the VM booting and provisioning, including instructions to add the host CA key to known_hosts and an /etc/hosts entry.

```bash
$ vagrant up
Bringing machine 'testhost' up with 'virtualbox' provider...
==> testhost: Importing base box 'ubuntu/bionic64'...
    [...]
==> testhost: Preparing network interfaces based on configuration...
    testhost: Adapter 1: nat
    testhost: Adapter 2: hostonly
==> testhost: Forwarding ports...
    testhost: 22 (guest) => 2222 (host) (adapter 1)
==> testhost: Running 'pre-boot' VM customizations...
==> testhost: Booting VM...
==> testhost: Waiting for machine to boot. This may take a few minutes...
    testhost: SSH address: 127.0.0.1:2222
    testhost: SSH username: vagrant
    testhost: SSH auth method: private key
    testhost: VirtualBox Version: 6.0
    [...]
==> testhost: Setting hostname...
==> testhost: Configuring and enabling network interfaces...
==> testhost: Mounting shared folders...
    testhost: /keys => /Users/sourishkrout/dev/src/smallstep/code/src/github.com/smallstep/step-examples/ssh-example/keys
    testhost: /vagrant => /Users/sourishkrout/dev/src/smallstep/code/src/github.com/smallstep/step-examples/ssh-example
==> testhost: Running provisioner: shell...
    testhost: Running: inline script
    testhost: Add following line to your local hosts ~/.ssh/known_hosts file to accept host certs
    testhost: @cert-authority * ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBJJM+jkIdieQvdPb8DwnfnJudEc9PgVBqLDWHKgvqoIiMXhuIyGstQ9ULOBMdJkqxMjkRTFZp1iFvIk+iU6hwTA=
    testhost: Add a /etc/hosts file entry testhost to resolve to 192.168.0.101
    testhost: Check out README.md to learn how to grab user ssh certs to log into testhost

```

--------------------------------

### Start Caddy with sudo

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Command to start Caddy and serve HTTPS. Caddy automatically renews certificates after ⅔ of the validity period.

```bash
$ sudo caddy start
```

--------------------------------

### Start Keycloak containers

Source: https://smallstep.com/docs/tutorials/keycloak-oidc-provisioner

Starts the Keycloak and MySQL containers. Requires Docker Compose version 3+.

```bash
$ docker-compose up
```

--------------------------------

### Start HTTP server and check NGINX with curl

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Commands to start a simple HTTP server and verify NGINX is serving HTTPS with the step-ca root certificate.

```bash
$ echo "Hello TLS!" > index.html

$ python -m SimpleHTTPServer 8000 &

$ curl https://foo.internal --cacert $(step path)/certs/root_ca.crt

Hello TLS!
```

--------------------------------

### Clone the certificates repository and navigate to basic-federation folder

Source: https://smallstep.com/docs/tutorials/pki-trust-model-federation

Clones the Smallstep certificates repository and changes into the basic-federation example folder. The output shows the cloning progress and the resulting directory.

```bash
$ git clone https://github.com/smallstep/certificates.git
Cloning into 'certificates'...
remote: Enumerating objects: 16, done.
remote: Counting objects: 100% (16/16), done.
remote: Compressing objects: 100% (15/15), done.
remote: Total 8355 (delta 3), reused 5 (delta 0), pack-reused 8339
Receiving objects: 100% (8355/8355), 34.92 MiB | 11.05 MiB/s, done.
Resolving deltas: 100% (5727/5727), done.
$ cd ./certificates/examples/basic-federation
```

--------------------------------

### Traefik v1: Start Traefik with root CA certificate

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Start Traefik v1 with the LEGO_CA_CERTIFICATES environment variable set to the path of the root CA certificate, so Traefik trusts your step-ca.

```bash
LEGO_CA_CERTIFICATES=$(step path)/certs/root_ca.crt traefik
```

--------------------------------

### Linux Smallstep agent post-install script

Source: https://smallstep.com/docs/tutorials/connect-fleet-dm-to-smallstep

Use this post-install script when adding the Linux agent package in Fleet to configure the agent and start the service.

```bash
#!/bin/bash
```

--------------------------------

### Fleet GitOps Directory Structure

Source: https://smallstep.com/docs/tutorials/connect-fleet-dm-to-smallstep

Example directory layout for a Fleet GitOps repository.

```text
fleet-gitops/
├── default.yml
├── teams/
│   └── team.yml
└── lib/
    ├── fleet-<connection-id>.mobileconfig
    └── smallstep-agent-setup.sh
```

--------------------------------

### Start Cloud CA with federated configuration

Source: https://smallstep.com/docs/tutorials/pki-trust-model-federation

Starts the Cloud CA using the federated configuration file. Prompts for the intermediate CA key password (password) and serves HTTPS on port 1443.

```bash
$ step-ca ./pki/cloud/config/ca.federated.json
Please enter the password to decrypt intermediate_ca_key: password
2019/01/22 13:38:52 Serving HTTPS on :1443 ...
```

--------------------------------

### Install step-ca root certificate with step certificate install

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Use this command to add the step-ca root certificate to your system's default trust store. This is a global operation that makes certificates issued by your CA trusted everywhere, including web browsers. It is a helper command provided by step.

```bash
step certificate install
```

--------------------------------

### Go: Obtain client certificate with step ca

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Get a client certificate from step-ca using an OAuth/OIDC provisioner. The output shows the provisioner and certificate details.

```bash
$ step ca certificate mike@example.com mike.crt mike.key

✔ Provisioner: Google (OIDC) [client: <redacted>.apps.googleusercontent.com]
✔ CA: https://ca.internal
✔ Certificate: mike.crt
✔ Private Key: mike.key
```

--------------------------------

### Initialize a Smallstep PKI with step ca init

Source: https://smallstep.com/docs/tutorials/ssh-certificate-login

Run this command to create a new PKI. The output shows the generated root and intermediate certificates, SSH keys, and configuration files.

```bash
step ca init
```

--------------------------------

### Linux Chrome Policy File Example with Specific URL

Source: https://smallstep.com/docs/tutorials/browser-certificate-setup-guide

This snippet shows an example of the Chrome policy file with a specific URL and team slug. Replace the example values with your own.

```json
{
    "AutoSelectCertificateForUrls": ["{\"pattern\":\"https://example.id.smallstep.com\",\"filter\":{\"ISSUER\":{\"CN\":\"Smallstep example Accounts Intermediate CA\"}}}"]
}
```

--------------------------------

### Initialize PKI bootstrapping

Source: https://smallstep.com/docs/tutorials/docker-tls-certificate-authority

Runs the initialization command to set up the CA configuration, keys, and database within the Docker volume.

```bash
docker run -it -v step:/home/step smallstep/step-ca step ca init
```

```text
✔ What would you like to name your new PKI? (e.g. Smallstep): Smallstep
✔ What DNS names or IP addresses would you like to add to your new CA? (e.g. ca.smallstep.com[,1.1.1.1,etc.]): localhost
✔ What address will your new CA listen at? (e.g. :443): :9000
✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): admin@smallstep.com
✔ What do you want your password to be? [leave empty and we'll generate one]:

Generating root certificate...
all done!

Generating intermediate certificate...
all done!

✔ Root certificate: /home/step/certs/root_ca.crt
✔ Root private key: /home/step/secrets/root_ca_key
✔ Root fingerprint: 86a278f34e58c7ab04313aff0e8e5114f1d1da955ecb20412b3d32cc2267ddcd
✔ Intermediate certificate: /home/step/certs/intermediate_ca.crt
✔ Intermediate private key: /home/step/secrets/intermediate_ca_key
✔ Database folder: /home/step/db
✔ Default configuration: /home/step/config/defaults.json
✔ Certificate Authority configuration: /home/step/config/ca.json

Your PKI is ready to go. To generate certificates for individual services see 'step help ca'.
```

--------------------------------

### Traefik v2: Bootstrap CA and install root certificate in Docker

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Run these commands inside a Docker container to bootstrap step-ca and install the root CA certificate into the container's trust store. The --install flag installs the root certificate, and update-ca-certificates updates the system trust store.

```bash
$ step ca bootstrap --ca-url "${CA_URL}" --fingerprint "${CA_FINGERPRINT}" --install --force
$ update-ca-certificates
```

--------------------------------

### Start step-ca server with generated configuration

Source: https://smallstep.com/docs/tutorials/ssh-certificate-login

Launch the step-ca server using the configuration generated by step ca init. You will be prompted for the passwords to decrypt the intermediate and SSH host/user keys.

```bash
$ step-ca $(step path)/config/ca.json
Please enter the password to decrypt /tmp/mystep/secrets/intermediate_ca_key:
Please enter the password to decrypt /tmp/mystep/secrets/ssh_host_key:
Please enter the password to decrypt /tmp/mystep/secrets/ssh_user_key:
2019/09/11 23:34:13 Serving HTTPS on :443 ...
```

--------------------------------

### Install cert-manager

Source: https://smallstep.com/docs/tutorials/kubernetes-acme-ca

Installs cert-manager v1.12.0 into the Kubernetes cluster using kubectl apply. This is required before configuring the ACME issuer.

```bash
$ kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.12.0/cert-manager.yaml

```

--------------------------------

### Initialize step-ca with SSH support

Source: https://smallstep.com/docs/tutorials/ssh-certificate-login

Command to initialize a new PKI with both X509 and SSH certificate authorities, showing the interactive prompts and output.

```bash
$ export STEPPATH=/tmp/mystep
$ step ca init --ssh
✔ What would you like to name your new PKI? (e.g. Smallstep): Smallstep
✔ What DNS names or IP addresses would you like to add to your new CA? (e.g. ca.smallstep.com[,1.1.1.1,etc.]): localhost
✔ What address will your new CA listen at? (e.g. :443): :443
✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): admin
✔ What do you want your password to be? [leave empty and we will generate one]:

Generating root certificate...
all done!

Generating intermediate certificate...

Generating user and host SSH certificate signing keys...
all done!
```

--------------------------------

### Install Certificate Policy Configuration

Source: https://smallstep.com/docs/tutorials/connect-jumpcloud-to-smallstep

Configures the Install Certificate policy in JumpCloud for the Root and Intermediate certificates, with the Intermediate certificate placed in the Root store as a legacy requirement.

```text
Certificate
```

--------------------------------

### Run demo server with Cloud CA certificate

Source: https://smallstep.com/docs/tutorials/pki-trust-model-federation

Runs the demo server using a certificate from the Cloud CA. It uses the step SDK to obtain X.509 certificates, automatically renew them, and fetch a trusted roots bundle. The server reports which root certificates it will use to authenticate client certificates.

```bash
$ go run server/main.go $(step ca token --ca-url https://localhost:1443 --root ./pki/cloud/certs/root_ca.crt 127.0.0.1)
✔ Key ID: EE1ZiqkMaxsUdpz8SCSkRBzwK9TWUoidQnMnJ8Eryn8 (sebastian@smallstep.com)
✔ Please enter the password to decrypt the provisioner key: password
Server is using federated root certificates
Accepting certs anchored in CN=Smallstep Public Cloud Root CA
Accepting certs anchored in CN=Smallstep Kubernetes Root CA
Listening on :8443 ...
```

--------------------------------

### Start Kubernetes CA with federated configuration

Source: https://smallstep.com/docs/tutorials/pki-trust-model-federation

Starts the Kubernetes CA using the federated configuration file. Prompts for the intermediate CA key password (password) and serves HTTPS on port 2443.

```bash
$ step-ca ./pki/kubernetes/config/ca.federated.json
Please enter the password to decrypt intermediate_ca_key: password
2019/01/22 13:39:44 Serving HTTPS on :2443 ...
```

--------------------------------

### Run demo client with Kubernetes CA certificate

Source: https://smallstep.com/docs/tutorials/pki-trust-model-federation

Runs the demo client using a certificate from the Kubernetes CA. It uses the step SDK to mutually authenticate connections to servers, automatically handling certificate bootstrapping, renewal, and fetching a bundle of trusted roots. The client sends HTTP requests to the demo server periodically.

```bash
$ go run client/main.go $(step ca token sdk_client --ca-url https://localhost:2443 --root ./pki/kubernetes/certs/root_ca.crt)
✔ Key ID: S5gYgpeqcIAgc1Zr4myZXpgJ_Ao4ryS6F6wqg9o8RYo (sebastian@smallstep.com)
✔ Please enter the password to decrypt the provisioner key: password
Server responded: Hello sdk_client (cert issued by 'Smallstep Kubernetes Root CA') at 2019-01-23 00:51:38.576648 +0000 UTC
```

--------------------------------

### Bootstrap CA on VM

Source: https://smallstep.com/docs/tutorials/cloud-vm-certificate

Bootstraps a VM to trust and connect to the step-ca server.

```bash
$ step ca bootstrap --ca-url https://ca.local --fingerprint f501ed49263c1369bd490a85660ddd4388d4175e0337100a11d4e82eae496499
```

--------------------------------

### Apply configuration using fleetctl gitops

Source: https://smallstep.com/docs/tutorials/connect-fleet-dm-to-smallstep

Apply your Fleet configuration files using the fleetctl gitops command.

```bash
fleetctl gitops -f default.yml -f teams/team.yml
```

--------------------------------

### Get certificate with IID

Source: https://smallstep.com/docs/tutorials/cloud-vm-certificate

Requests a certificate using IID-based authentication with the specified provisioner.

```bash
$ step ca certificate foo.local foo.crt foo.key --provisioner "AWS IID Provisioner"
```

--------------------------------

### Connect with OpenConnect using GlobalProtect protocol

Source: https://smallstep.com/docs/tutorials/vpn-setup-guide-globalprotect

Run as root to read the key file, use the TPM, and create the tunnel interface. Requires OpenConnect with TPMv2 support and a hardware TPM at /dev/tpmrm0.

```bash
sudo openconnect --protocol=gp \
  -c /var/lib/step-agent/certificates/globalprotect/service.crt \
  -k /var/lib/step-agent/certificates/globalprotect/service.key \
  <portal-fqdn>
```

--------------------------------

### Get root certificate fingerprint

Source: https://smallstep.com/docs/tutorials/cloud-vm-certificate

Finds the fingerprint of the root certificate used by step-ca.

```bash
$ step certificate fingerprint $(step path)/certs/root_ca.crt
```

--------------------------------

### Import existing PKI files

Source: https://smallstep.com/docs/tutorials/intermediate-ca-new-ca

Moves existing root and intermediate certificates and keys into the step-ca configuration directory.

```bash
$ mv root.crt $(step path)/certs/root_ca.crt
$ mv intermediate.crt $(step path)/certs/intermediate_ca.crt
$ mv intermediate_ca_key $(step path)/secrets/intermediate_ca_key
```

--------------------------------

### Apache VirtualHost configuration with certbot

Source: https://smallstep.com/docs/tutorials/acme-protocol-acme-clients

Example Apache configuration using certificates issued by step-ca through certbot.

```apache
<VirtualHost *:443>
  ServerName foo.internal
  DocumentRoot /home/mmalone/www
  SSLEngine on
  SSLCertificateFile /etc/letsencrypt/live/foo.internal/fullchain.pem
  SSLCertificateKeyFile /etc/letsencrypt/live/foo.internal/privkey.pem
</VirtualHost>
```
Tokens:
Raw