step ca token

NAME

step ca token – generate an OTT granting access to the CA

USAGE

step ca token subject [–kid=kid] [–issuer=issuer] [–ca-url=uri] [–root=file] [–not-before=time|duration] [–not-after=time|duration] [–password-file=file] [–output-file=file] [–key=path] [–san=SAN] [–offline] [–revoke]

DESCRIPTION

step ca token command generates a one-time token granting access to the certificates authority.

POSITIONAL ARGUMENTS

subject
The Common Name, DNS Name, or IP address that will be set by the certificate authority. When there are no additional Subject Alternative Names configured (via the –san flag), the subject will be added as the only element of the ‘sans’ claim on the token.

OPTIONS

–kid=kid
The provisioner kid to use.
–issuer=name
The provisioner name to use.
–ca-url=URI
URI of the targeted Step Certificate Authority.
–root=file
The path to the PEM file used as the root certificate authority.
–not-before=time|duration
The time|duration set in the NotBefore (nbf) property of the token. If a time is used it is expected to be in RFC 3339 format. If a duration is used, it is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.
–not-after=time|duration
The time|duration set in the Expiration (exp) property of the token. If a time is used it is expected to be in RFC 3339 format. If a duration is used, it is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.
–san=value
Add DNS or IP Address Subjective Alternative Names (SANs) that the token is authorized to request. A certificate signing request using this token must match the complete set of subjective alternative names in the token 1:1. Use the ‘–san’ flag multiple times to configure multiple SANs.
–key=path
The private key path used to sign the JWT. This is usually downloaded from the certificate authority.
–password-file=file
The path to the file containing the password to decrypt the one-time token generating key.
–output-file=file
The destination file of the generated one-time token.
–offline=--ca-config
Creates a token without contacting the certificate authority. Offline mode requires the flags --ca-config or --kid, --issuer, --key, --ca-url, and --root.
–revoke=value
Create a token for authorizing ‘Revoke’ requests. The audience will be invalid for any other API request.
–ca-config=path
The path to the certificate authority configuration file. Defaults to $STEPPATH/config/ca.json
-f=value, –force=value
Force the overwrite of files without asking.

EXAMPLES

Most of the following examples assumes that –ca-url and –root are set using environment variables or the default configuration file in $STEPPATH/config/defaults.json.

Get a new token for a DNS. Because there are no Subject Alternative Names configured (via the ‘–san’ flag), the ‘sans’ claim of the token will have a default value of [‘internal.example.com’]:

$ step ca token internal.example.com

Get a new token for a ‘Revoke’ request:

$ step ca token --revoke 146103349666685108195655980390445292315

Get a new token for an IP address. Because there are no Subject Alternative Names configured (via the ‘–san’ flag), the ‘sans’ claim of the token will have a default value of [‘192.168.10.10’]:

$ step ca token 192.168.10.10

Get a new token with custom Subject Alternative Names. The value of the ‘sans’ claim of the token will be [‘1.1.1.1’, ‘hello.example.com’] - ‘foobar’ will not be in the ‘sans’ claim unless explicitly configured via the ‘–sans’ flag:

$ step ca token foobar --san 1.1.1.1 --san hello.example.com

Get a new token that expires in 30 minutes:

$ step ca token --not-after 30m internal.example.com

Get a new token that becomes valid in 30 minutes and expires 5 minutes after that:

$ step ca token --not-before 30m --not-after 35m internal.example.com

Get a new token signed with the given private key, the public key must be configured in the certificate authority:

$ step ca token internal.smallstep.com --key token.key

Get a new token for a specific provisioner kid, ca-url and root:

$ step ca token internal.example.com \
    --kid 4vn46fbZT68Uxfs9LBwHkTvrjEvxQqx-W8nnE-qDjts \
    --ca-url https://ca.example.com \
    --root /path/to/root_ca.crt

Get a new token using the simple offline mode, requires the configuration files, certificates, and keys created with step ca init:

$ step ca token internal.example.com --offline

Get a new token using the offline mode with all the parameters:

$ step ca token internal.example.com \
    --offline \
    --kid 4vn46fbZT68Uxfs9LBwHkTvrjEvxQqx-W8nnE-qDjts \
    --issuer you@example.com \
    --key provisioner.key \
    --ca-url https://ca.example.com \
    --root /path/to/root_ca.crt

Get a new token for a ‘Revoke’ request:

$ step ca token --revoke 146103349666685108195655980390445292315

Get a new token in offline mode for a ‘Revoke’ request:

$ step ca token --offline --revoke 146103349666685108195655980390445292315