Smallstep Step-CA

Smallstep Step-CA Integration

Integrate Smallstep Step-CA with SSL-CLM to:

Issue certificates
Renew certificates
Revoke certificates
Sync certificate inventory
Use secure JWK-based authentication (One-Time Tokens)

Step-CA integrates directly via its REST API. No agent is required — the platform communicates with the CA from the backend.

Architecture

SSL-CLM Platform (Backend)
│
│  (HTTPS + JWK-signed One-Time Tokens)
▼
Smallstep Step-CA (REST API)
│
▼
Internal Certificate Authority

Prerequisites

Smallstep Step-CA installed and running
A JWK provisioner configured for SSL-CLM
Network access from the SSL-CLM platform to the Step-CA API
The provisioner private key (JWK format)

Step 1 — Install Step CLI

Install the Smallstep CLI on your CA server:

https://smallstep.com/docs/step-cli/installation

Verify:

step version

Step 2 — Initialize Step-CA

If you don’t already have a running Step-CA:

step ca init \
  --name "Internal CA" \
  --dns step-ca.internal.corp \
  --address :9000 \
  --provisioner admin@company.com \
  --password-file step-ca-password.txt

Start the CA:

step-ca $(step path)/config/ca.json

The API will be available at:

https://step-ca.internal.corp:9000

Step 3 — Create a JWK Provisioner for SSL-CLM

Create a dedicated provisioner for the SSL-CLM platform (separate from any admin provisioner):

# Generate EC P-256 key pair
step crypto jwk create clm-pub.json clm-priv.json \
  --kty EC \
  --crv P-256 \
  --no-password \
  --insecure

# Add provisioner to Step-CA
step ca provisioner add clm@company.com \
  --type JWK \
  --public-key clm-pub.json

Verify it’s registered:

step ca provisioner list

Step 4 — Get the Private Key for SSL-CLM

View the provisioner private key:

cat clm-priv.json

Output (example):

{
  "kty": "EC",
  "crv": "P-256",
  "kid": "pA46iGmXmpipV4HmqlvozxPde7VNavSdLZmiaEa5iyA",
  "x": "...",
  "y": "...",
  "d": "..."
}

You will paste this into the SSL-CLM CA configuration. The platform stores it encrypted in the vault.

Step 5 — Add the Certificate Authority in SSL-CLM

Navigate to Infrastructure → Certificate Authorities
Click + Add CA
Select Smallstep CA from the type cards
Fill in the configuration:

Connection:

Field	Description	Example
Name	Friendly display name	`Smallstep Internal CA`
CA Base URL	Step-CA API base URL	`https://step-ca.internal.corp:9000`
API Path	API version path (usually `/1.0`)	`/1.0`

Authentication:

Field	Description	Example
Provisioner Name	JWK provisioner name (iss claim)	`clm@company.com`
Provisioner Key ID	JWK key ID (kid header) — optional, auto-extracted from JWK	`pA46iGmX...`
Provisioner Private Key (JWK)	Full JWK private key JSON (stored encrypted in vault)	`{"kty":"EC","crv":"P-256",...}`

Advanced:

Field	Description	Example
OTT TTL (seconds)	One-Time Token time-to-live	`300` (default)
Discovery Interval	Hours between inventory syncs	`24`

Click Save

The platform stores the JWK private key securely in the vault. It generates short-lived One-Time Tokens (OTTs) at runtime for each operation — the key itself is never exposed.

Step 6 — Issue a Certificate

Navigate to Certificates → + New Certificate
Select Issue from CA
Choose the Smallstep CA
Enter Common Name and SANs
Click Submit

Flow:

Platform generates a CSR
Platform signs an OTT using the provisioner JWK (valid for 5 minutes)
Platform calls Step-CA’s /sign endpoint with the CSR + OTT
Step-CA validates the OTT and issues the certificate
Certificate is stored in inventory

Step 7 — Revoke a Certificate

When revocation is requested:

Platform signs an OTT for the revocation operation
Platform calls Step-CA’s revoke endpoint
Certificate status updated to REVOKED

How OTT Authentication Works

SSL-CLM uses One-Time Tokens (OTTs) for every operation with Step-CA:

1. Platform loads the provisioner JWK private key from vault
2. Platform creates a JWT with:
   - iss: provisioner name (e.g., "clm@company.com")
   - sub: certificate CN being requested
   - aud: Step-CA API URL
   - exp: current time + TTL (300s)
   - jti: unique token ID
3. JWT is signed with the provisioner's private key
4. JWT is sent to Step-CA as the authorization token
5. Step-CA validates the JWT against the provisioner's public key
6. Operation is executed
7. JWT cannot be reused (one-time)

This means no long-lived credentials are transmitted — each request gets a fresh, short-lived token.

Security Model

Principle	Implementation
No stored passwords	Authentication via cryptographic key signing (JWK)
Short-lived tokens	OTTs expire in 5 minutes and are single-use
Key in vault	Provisioner private key stored encrypted, never in config files
Separate provisioners	Use a dedicated provisioner for SSL-CLM, separate from admin CLI
EC P-256	Recommended key type for provisioners

Troubleshooting

Issue	Possible Cause	Resolution
”Unauthorized” error	Wrong provisioner name or kid mismatch	Verify provisioner name matches exactly; check kid in the JWK
”Connection refused”	Step-CA not running or wrong port	Confirm Step-CA is running; verify base URL and port
”Provisioner not found”	Provisioner not registered in Step-CA	Run `step ca provisioner list` to verify
Certificate not issued	OTT expired (clock skew)	Ensure platform server clock is synced (NTP)
TLS handshake failure	Platform doesn’t trust Step-CA’s certificate	Add Step-CA’s root cert as trusted, or disable strict verification

Operational Best Practices

Use a dedicated provisioner (clm@company.com) — don’t share with the admin CLI
Use EC P-256 keys (fast, secure, small tokens)
Set OTT TTL to 300 seconds (5 min) — long enough for network latency, short enough for security
Enable scheduled inventory refresh (24h) to keep the platform in sync with Step-CA
Rotate provisioner keys periodically — generate a new key pair, update in SSL-CLM, remove the old one from Step-CA
Back up the Step-CA PKI directory ($(step path))