DOCSEARCHbyAlgolia
Submit Docs

step-ca Documentation

repository·master·Indexed 27 days ago

https://github.com/smallstep/certificates

An online certificate authority (CA) for automated, secure certificate management in DevOps workflows. It supports HTTPS, SSH, and ACME protocols, serving as a private ACMEv2 server and the server-side counterpart to the step CLI. Key features include support for multiple database backends (Badger, BoltDB, Postgres, MySQL), various authorization methods (OAuth/OIDC, JWK, SCEP), and a Go client API for certificate signing, renewal, and revocation.

Tokens
5.5K
Snippets
5
Records
45
Agent score
92%

What's inside step-ca

  1. Overview of step-ca

    master

    step-ca is an online certificate authority designed for secure, automated certificate management in DevOps environments. It serves as the server-side counterpart to the step CLI tool.

    Key Capabilities:

    • HTTPS/TLS Certificates: Issue certificates for browsers (RFC5280 compliant), VMs, containers, APIs, and Kubernetes pods.
    • SSH Certificates: Issue certificates for users (via SSO identity tokens) and hosts (via cloud instance identity documents).
    • ACME Server: Acts as a private ACMEv2 server to automate certificate issuance for any compatible client.
    • Automation: Supports various authorization methods including ACME, OAuth/OIDC, Cloud Instance Identity, JWK tokens, and SCEP.

  3. Use step-ca as a private ACME server

    master

    step-ca can function as a private ACMEv2 (RFC8555) server, allowing you to automate certificate issuance using standard ACME clients.

    Supported ACME Challenge Types:

    • http-01: Requires placing a token at a well-known URL.
    • dns-01: Requires adding a TXT record to your DNS.
    • tls-alpn-01: Requires responding to the challenge at the TLS layer.

    Compatible Clients:

    • CLI Tools: certbot, acme.sh, win-acme, step CLI.
    • Web Servers: Caddy, Traefik, Apache, nginx.
    • Programmatic Libraries: lego (Go), acme module (Python/Certbot), acme-client (Node.js).

  4. Manage PKI with the step CLI

    master

    The step CLI integrates with step-ca to perform various PKI management tasks. Common operations include:

    • Authenticate and Obtain: Use any supported provisioner to get a certificate.
    • Root Management: Securely distribute root certificates and bootstrap PKI relying parties.
    • Lifecycle Management: Renew and revoke certificates issued by step-ca.
    • Client Setup: Install root certificates on machines and browsers to establish trust.
    • Inspection: Inspect and lint certificates.
    • Key Generation: Generate key pairs locally so private keys are never transmitted over the network.

  6. Configure ACME ports for testing

    master

    To use custom ports for ACME challenges (HTTP-01 or TLS-ALPN-01), you must use the --insecure flag. This is typically used for testing purposes.

    • Use --acme-http-port <port> for HTTP-01 challenges.
    • Use --acme-tls-port <port> for TLS-ALPN-01 challenges.

  7. Run the step-ca server

    master

    The step-ca command runs the Step Online Certificate Authority (Step CA) using a provided configuration file. This command typically runs indefinitely and is used to serve certificates to clients.

    Usage

    step-ca [config] [**--context**=<name>] [**--password-file**=<file>] [**--ssh-host-password-file**=<file>] [**--ssh-user-password-file**=<file>] [**--issuer-password-file**=<file>] [**--resolver**=<addr>]

    Arguments

    • <config>: The path to the configuration file (e.g., ca.json) that defines the operation of the Step CA. This file is usually generated during step ca init.

  8. Onboard step-ca using the onboarding guide

    master

    The onboard command configures and runs step-ca by following the Smallstep onboarding guide. This process automates the generation of root and intermediate certificates, provisioners, and the CA configuration.

    Usage

    1. Open https://smallstep.com/onboarding in your browser.
    2. Obtain the token provided by the guide.
    3. Run the command with the token:
    step-ca onboard <token>

    Environment Variables

    If you are using a local development environment instead of the production onboarding service, set the STEP_CA_ONBOARDING_URL environment variable:

    export STEP_CA_ONBOARDING_URL=http://localhost:3002/onboarding/

    Process Details

    • Configuration: The command fetches configuration (Name, DNS, Address) from the onboarding URL.
    • Security: A random 32-character ASCII password is generated for the CA.
    • PKI Generation: It generates a root certificate, an intermediate certificate, and an admin provisioner.
    • Files: Configuration and certificate files are written to disk automatically.
    • Startup: Once initialized, step-ca starts running immediately. You must return to your browser to complete the guide.

  9. Enable step-ca profiling with STEP_PROF_ADDR

    master

    You can enable the Go pprof profiler for the step-ca server by setting the STEP_PROF_ADDR environment variable. This starts a separate HTTP server on the specified address to allow for performance profiling.

    Example:

    export STEP_PROF_ADDR=:6060
step-ca $STEPPATH/config/ca.json

  10. Enable a linked CA with a token

    master

    If your authority is configured with a LinkedDeployment type, you must provide a token to enable the linked CA. You can provide this via the --token flag or the STEP_CA_TOKEN environment variable.

    To obtain a token:

    1. Contact Smallstep to create a Certificate Manager account.
    2. Add a new authority and select "Link a step-ca instance".
    3. Follow the browser instructions to start step-ca using the --token flag.