Teleport SSO Authentication Flow on Headless Servers

How do you log into a Teleport Cluster, using the tsh client, on a headless server when an authentication connector (Github, Okta, SAML, etc) is used?

A browser is not available to perform the authentication flow between the Teleport Cluster, the identity provider, and the tsh client.

You have several options… Here are a few:

  1. If you are connecting to a remote machine, from a local machine which does have the capability to run a browser, you can simply forward your local ssh-agent from your local machine to the remote machine. To accomplish this, run tsh -A. Teleport will forward your local ssh-agent to the remote server, permitting you to move between remote Teleport Nodes using the ssh-agent credentials. On the remote machine, run ssh-add -l to review the certificates.

  2. Run tsh login --bind-addr (or the TELEPORT_LOGIN_BIND_ADDR environment variable). If you have network access to the remote machine, from your local machine’s browser, use the URL that the tsh client outputs to screen to complete the authentication flow. Alternatively, configure an SSH tunnel to access the authentication handler listening on 127.0.0.1:<port> (See tsh output for URL).

  3. You can configure a local user within Teleport to bypass your identity platform. From the Teleport Auth server, run tctl users add to create a local user. Follow the directions on the screen to set the password for the user. To log into this user, and bypass your authentication connector, run tsh login --proxy=xxx --auth=local. Teleport will ask for the username, password, and 2FA via the terminal.

  4. You can export a long lived static certificate, then use this for authentication. tsh login --identity=static_creds.pem
    Details here: https://gravitational.com/teleport/docs/user-manual/#ssh-certificates-for-automation

Quick tip: For all Teleport command line tools, you can add the --help flag to get more information about the available options. tsh login --help provides all of the supported flags for the login command.

1 Like