A zero trust swiss army knife for working with X509, OAuth, JWT, OATH OTP, etc.
Clone or download
Latest commit e66f6db Dec 11, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github add pull request template Jul 20, 2018
autocomplete Use bash_completion _filedir Jul 28, 2018
cmd/step Move --steppath flag to the command `step path` Nov 21, 2018
command differentiate between output types for --csr Dec 5, 2018
config Add flag to print the steppath. Nov 16, 2018
crypto fix ReadCertPool function Dec 12, 2018
debian Clean changelog Nov 28, 2018
docker forgot to add docker dir Nov 15, 2018
errs add provisioner subcommand under step ca Oct 13, 2018
exec Initial commit Jul 17, 2018
flags Add flag --force on all commands using utils.WriteFile Nov 28, 2018
integration Fix integration tests. Dec 1, 2018
jose Support UI options like templates in password prompts. Nov 30, 2018
make Split Makefile into common and repo specific sections Dec 7, 2018
pkg lost test-file.crt somewhere amidst all the action of porting x509 Jul 27, 2018
token Sort imports. Nov 6, 2018
ui Add simple option to use the simple prompt templates. Dec 1, 2018
usage Make sure all the short help uses the first person Nov 28, 2018
utils Convert overwrite prompt to use the ui package. Dec 1, 2018
.COMPONENT_VERSIONS bump certificates version and update COMPONENT version for brew Dec 11, 2018
.gitignore Merge pull request #22 from APTy/jwks/x5c Aug 22, 2018
.travis.yml add codecov token to travis Nov 3, 2018
CHANGELOG.md update changelog Sep 29, 2018
Gopkg.lock bump smallstep/certificates Dec 12, 2018
Gopkg.toml Do not require schema in ca-url Nov 27, 2018
LICENSE Fix the company name. Jul 31, 2018
Makefile fix makefile dependency ordering Dec 11, 2018
README.md fix install instructions for linux Aug 21, 2018
distribution.md update distribution doc Nov 29, 2018
go.mod Update go mod files. Nov 1, 2018
go.sum Update go mod files. Nov 1, 2018

README.md

Step CLI

step is a zero trust swiss army knife. It’s an easy-to-use and hard-to-misuse utility for building, operating, and automating systems that use zero trust technologies like authenticated encryption (X.509, TLS), single sign-on (OAuth OIDC, SAML), multi-factor authentication (OATH OTP, FIDO U2F), encryption mechanisms (JSON Web Encryption, NaCl), and verifiable claims (JWT, SAML assertions).

For more information and docs see the step website and the blog post announcing step.

Animated terminal showing step in practice

Table of Contents

Installing

These instructions will install an OS specific version of the step binary on your local machine. To build from source see getting started with development below.

Mac OS

Install step via Homebrew:

brew install smallstep/smallstep/step

Test:

step certificate inspect https://smallstep.com

Linux

Download the latest Debian package from releases:

wget https://github.com/smallstep/cli/releases/download/X.Y.Z/step_X.Y.Z_amd64.deb

Install the Debian package:

sudo dpkg -i step_X.Y.Z_amd64.deb

Test:

step certificate inspect https://smallstep.com

Documentation

Documentation can be found in three places:

  1. On the command line with step help xxx where xxx is the subcommand you are interested in. Ex: step help crypto jwk

  2. On the web at https://smallstep.com/docs/cli

  3. In your browser with step help --http :8080 and visiting http://localhost:8080

Examples

X.509 Certificates

Create a root CA, an intermediate, and a leaf X.509 certificate. Bundle the leaf with the intermediate for use with TLS:

$ step certificate create --profile root-ca \
    "Example Root CA" root-ca.crt root-ca.key
$ step certificate create \
    "Example Intermediate CA 1" intermediate-ca.crt intermediate-ca.key \
    --profile intermediate-ca --ca ./root-ca.crt --ca-key ./root-ca.key
$ step certificate create \
    example.com example.com.crt example.com.key \
    --profile leaf --ca ./intermediate-ca.crt --ca-key ./intermediate-ca.key
$ step certificate bundle \
    example.com.crt intermediate-ca.crt example.com-bundle.crt

Extract the expiration date from a certificate (requires jq):

$ step certificate inspect example.com.crt --format json | jq -r .validity.end
$ step certificate inspect https://smallstep.com --format json | jq -r .validity.end

JSON Object Signing & Encryption (JOSE)

Create a JSON Web Key (JWK), add the public key to a keyset, and sign a JSON Web Token (JWT):

$ step crypto jwk create pub.json key.json
$ cat pub.json | step crypto jwk keyset add keys.json
$ JWT=$(step crypto jwt sign \
    --key key.json \
    --iss "issuer@example.com" \
    --aud "audience@example.com" \
    --sub "subject@example.com" \
    --exp $(date -v+15M +"%s"))

Verify your JWT and return the payload:

$ echo $JWT | step crypto jwt verify \
    --jwks keys.json --iss "issuer@example.com" --aud "audience@example.com"

Single Sign-On

Login with Google, get an access token, and use it to make a request to Google's APIs:

curl -H"$(step oauth --header)" https://www.googleapis.com/oauth2/v3/userinfo

Login with Google and obtain an OAuth OIDC identity token for single sign-on:

$ step oauth \
    --provider https://accounts.google.com \
    --client-id 1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com \
    --client-secret udTrOT3gzrO7W9fDPgZQLfYJ \
    --bare --oidc

Obtain and verify a Google-issued OAuth OIDC identity token:

$ step oauth \
    --provider https://accounts.google.com \
    --client-id 1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com \
    --client-secret udTrOT3gzrO7W9fDPgZQLfYJ \
    --bare --oidc \
 | step crypto jwt verify \
   --jwks https://www.googleapis.com/oauth2/v3/certs \
   --iss https://accounts.google.com \
   --aud 1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com

Multi-factor Authentication

Generate a TOTP token and a QR code:

$ step crypto otp generate \
    --issuer smallstep.com --account name@smallstep.com \
    --qr smallstep.png > smallstep.totp

Scan the QR Code using Google Authenticator, Authy or similar software and use it to verify the TOTP token:

$ step crypto otp verify --secret smallstep.totp

Getting Started with Development

These instructions will get you a copy of the project up and running on your local machine for development, testing, and contribution purposes.

Please read the CLI Style Guide before implementing any features or modifying behavior as it contains expectations surrounding how the CLI should behave.

All changes to behavior must be documented in the CHANGELOG.md.

Prerequisites

To get started with local development, you will need three things:

  • Golang installed locally (instructions available here.
  • dep installed locally (instructions available here.
  • A version of make available for usage of the Makefile.
  • The repository checked out in the appropriate location of your $GOPATH.

Ensure you've checked out the repository into the appropriate path inside your $GOPATH. For example, if your $GOPATH is set to ~/go, then you'd check this repository out at ~/go/src/github.com/smallstep/cli. You can learn more about $GOPATH in the documentation.

Installing Dependencies and Bootstrapping

Once you've cloned the repository to the appropriate location, you will now be able to install any other dependencies via the make bootstrap command.

You should only ever need to run this command once, as it will ensure you have the right version of dep and gometalinter installed.

Building step

To build step, simply run make build which will build the cli and place the binary in the bin folder.

Running Tests and Linting

Now that you've installed any dependencies, you can run the tests and lint the code base simply by running make.

Unit Tests

Run the unit tests:

make test

For a more verbose version of the unit tests:

make vtest

Integration Tests

Run the integration tests:

make integration

And coding style tests

These tests apply the following Go linters to verify code style and formatting:

make lint

Adding and Removing Dependencies

To add any dependency to the repository, simply import it into your code and then run dep ensure which will update the Gopkg.lock file. A specific version of a dependency can be specified by adding it to the Gopkg.toml file and running dep ensure.

To remove a dependency, simply remove it from the codebase and any mention of it in the Gopkg.toml file and run dep ensure which will remove it from the vendor folder while updating the Gopkg.lock file.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details