Getting Access to Teleport

Teleport is the Unified Access Plane used at GitLab for audited, on-demand access to infrastructure resources including servers, databases, and Rails consoles.

Prerequisites

Okta access

Before you can use Teleport, you must be assigned the Teleport app in Okta. This is typically part of your role’s baseline group assignment during onboarding.

If your onboarding is complete and you still do not see the Teleport app listed in Okta, open an access request and follow the appropriate approval process.

Okta login unsuccessful

Attempting to log in to Teleport directly from the Okta dashboard may fail with a “Login Unsuccessful” message. This is expected and does not necessarily mean you need to open an access request.

Click “Please attempt to log in again”, then click “Okta” under “Sign in to Teleport”.

Install tsh

The Teleport CLI client tsh must be installed on your local machine. Official packages for macOS and Linux are available on Teleport’s website (select CLI Client Tools from the drop down menu).

On macOS Teleport may also be installed via Homebrew:

brew install teleport

Tip

The syntax and options for tsh ssh are very similar to the standard ssh command. See this guide for more information.

Logging In

Note

production.teleport.gitlab.net provides access to all GitLab environments, including production, staging, preprod and more.

Command line interface (tsh)

Once you have the Teleport app assigned in Okta, log in with tsh:

tsh login --proxy=production.teleport.gitlab.net

This opens Okta in a browser window for authentication. After authenticating, your local tsh session is valid and you can connect to resources.

Tip

The --proxy=production.teleport.gitlab.net flag must be provided the first time you use tsh, after which it will be remembered and it does not need to be provided again.

Web UI

Teleport has a web interface which you can access at https://production.teleport.gitlab.net. The web interface may be used as an alternative to the CLI for most tasks, including SSH access, database console access, making access requests, approving access requests and more.

Teleport Connect (optional alternative to tsh)

Teleport Connect is a native app that provides the same access as tsh in a graphical interface. Official packages for macOS and Linux are available on Teleport’s website (select Desktop App: Teleport Connect from the drop down menu).

On macOS Teleport Connect may also be installed via Homebrew:

brew install teleport-connect

Role-based access

Teleport uses Role-Based Access Control (RBAC). Your Okta group membership determines which Teleport roles you are assigned. Some roles are granted by default (such as read-only non-prod access); others (such as production access) require an explicit access request.

Access granted via a request is temporary (12 hours). It may be renewed before or after expiration by following the same process.

Refer to the guides in Next steps for details on how to make an access request.

Next steps

You can use Teleport to:

• Access the Rails console
• Access a database
• Access a host via SSH
• Approve an access request (if you’ve been granted an approver role)

Support

If you have any issues using Teleport or the approval process, ask the Infrastructure Security team in the #security_help Slack channel.

To report a bug or problem with Teleport, open an issue with Infrastructure Security.

Troubleshooting

Error: failed to add one or more keys to the agent

If you see:

ERROR: failed to add one or more keys to the agent.
agent: failure, agent: failure

This is caused by your ssh-agent configuration. Set TELEPORT_ADD_KEYS_TO_AGENT=no in your environment to work around it. You can persist this in your ~/.bashrc or ~/.zshrc, or prefix individual commands:

TELEPORT_ADD_KEYS_TO_AGENT=no tsh login

There is an open upstream issue tracking this.

Debug

If you have issues connecting, use the --debug flag for verbose output:

tsh --debug login --proxy=production.teleport.gitlab.net