step ssh login

Name

step ssh login -- adds a SSH certificate into the authentication agent

Usage

step ssh login [<identity>]
[--token=<token>] [--provisioner=<name>] [--provisioner-password-file=<file>]
[--principal=<string>] [--not-before=<time|duration>] [--not-after=<time|duration>]
[--kty=<key-type>] [--curve=<curve>] [--size=<size>] [--comment=<comment>]
[--set=<key=value>] [--set-file=<file>] [--console] [--force] [--insecure]
[--offline] [--ca-config=<file>]
[--ca-url=<uri>] [--root=<file>] [--context=<name>]

Description

step ssh login generates a new SSH key pair and send a request to step certificates to sign a user certificate. This certificate will be automatically added to the SSH agent.

With a certificate servers may trust only the CA key and verify its signature on a certificate rather than trusting many user keys.

Positional arguments

identity The certificate identity. If no principals are passed we will use the identity as a principal, if it has the format abc@def then the principal will be abc.

Options

--token=token The one-time token used to authenticate with the CA in order to create the certificate.

--add-user Create a user provisioner certificate used to create a new user.

--principal=value, -n=value Add the specified principal (username) to the certificate request. This flag can be used multiple times. However, it cannot be used in conjunction with '--token' when requesting certificates from OIDC, JWK, and X5C provisioners, or from any provisioner with 'disableCustomSANs' set to 'true'. These provisioners will use the contents of the token to determine the principals.

--identity=value The certificate identity. It is usually passed as a positional argument, but a flag exists so it can be configured in $STEPPATH/config/defaults.json.

--provisioner=name, --issuer=name The provisioner name to use.

--provisioner-password-file=file, --password-file=file The path to the file containing the password to decrypt the one-time token generating key.

--not-before=time|duration The time|duration when the certificate validity period starts. 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 when the certificate validity period ends. 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".

--set=key=value The key=value pair with template data variables. Use the --set flag multiple times to add multiple variables.

--set-file=file The JSON file with the template data variables.

--console Complete the flow while remaining inside the terminal.

-f, --force Force the overwrite of files without asking.

--offline Creates a certificate without contacting the certificate authority. Offline mode uses the configuration, certificates, and keys created with step ca init, but can accept a different configuration file using --ca-config flag.

--ca-config=file The certificate authority configuration file. Defaults to $(step path)/config/ca.json

--ca-url=URI URI of the targeted Step Certificate Authority.

--root=file The path to the PEM file used as the root certificate authority.

--context=name The context name to apply for the given command.

--comment=value The comment used when adding the certificate to an agent. Defaults to the subject if not provided.

--kty=kty The kty to build the certificate upon. If unset, default is EC.

kty is a case-sensitive string and must be one of:

  • EC: Create an elliptic curve keypair

  • OKP: Create an octet key pair (for "Ed25519" curve)

  • RSA: Create an RSA keypair

--crv=curve, --curve=curve The elliptic curve to use for EC and OKP key types. Corresponds to the "crv" JWK parameter. Valid curves are defined in JWA [RFC7518]. If unset, default is P-256 for EC keys and Ed25519 for OKP keys.

curve is a case-sensitive string and must be one of:

  • P-256: NIST P-256 Curve

  • P-384: NIST P-384 Curve

  • P-521: NIST P-521 Curve

  • Ed25519: Ed25519 Curve

--size=size The size (in bits) of the key for RSA and oct key types. RSA keys require a minimum key size of 2048 bits. If unset, default is 2048 bits for RSA keys and 128 bits for oct keys.

--insecure

Examples

Request a new SSH certificate and add it to the agent:

$ step ssh login bob

Request a new SSH certificate using an OIDC provisioner:

$ step ssh login

Request a new SSH certificate valid only for 1h:

$ step ssh login --not-after 1h alice

Request a new SSH certificate with multiple principals:

$ step ssh login --principal admin --principal bob bob@smallstep.com

Request a new SSH certificate and set a custom comment in the agent

$ step ssh login --comment my-custom-comment bob@smallstep.com

Request a new SSH certificate with an EC key and P-521 curve:

$  step ssh certificate --kty EC --curve "P-521" mariano@work id_ecdsa

Request a new SSH certificate with an Octet Key Pair and Ed25519 curve:

$  step ssh certificate --kty OKP --curve Ed25519 mariano@work id_ed25519