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

You need the Teleport CLI client tsh installed on your local machine. Official packages for macOS and Linux are available on Teleport’s website.

Tip

On macOS Teleport can 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.

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”.

Logging In

Command line interface

Once you have the Teleport app assigned in Okta, log in using 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 interface

There is one Teleport instance available at https://production.teleport.gitlab.net. You can also use the Teleport Web UI as an alternative to the CLI.

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; others (such as read/write 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.

Making an access request

Requesting access via the CLI

Access requests may alternatively made via Teleport’s CLI. Refer to Access the Rails console or Access a database for details.

When an access request is required, the general workflow is:

1. Login to the Teleport web UI at https://production.teleport.gitlab.net.

2. Navigate to the Access Requests page under Identity Governance on the left sidebar.

3. Submit an access request for the role or resources you need.

   Important

   The Reason field must contain a permanent link to a GitLab issue (or similar) outlining why you need access, or your request will be rejected (see Teleport Approver Workflow).

4. Ask an Engineering or Security manager to review the request.

5. Once approved, log in with tsh using the request ID to assume the role.

   # The request ID is returned in Step 1
   tsh login --request-id=<request-id>

If necessary, refer to Teleport’s documentation for more information.

Next Steps

You can use Teleport to:

• Access the Rails console
• Access a database
• Access a host via SSH

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