Teleport Approver Workflow

Read-only access

This process is typically grants read-only access. Refer to the change management process if read/write access is required.

This workflow outlines the process to review Teleport access requests. It applies to all forms of read-only access facilitated by Teleport, including the Rails console and database access.

Prerequisites

• You are a people manager in the Engineering or Security departments, or have otherwise been granted a Teleport approver role.
• Teleport access via Okta (see getting access).
• (optional) tsh is installed (see installation instructions).

Who can approve access requests?

Access during a production incident

If urgent access is required during a production incident, ping @sre-oncall for approval (only during production incidents).

Requests are generally reviewed by the requester’s direct manager. If their manager is unavailable, the request may be forwarded to the #eng-managers channel for review by any available engineering manager.

Environment	Access type	Approvers
Non-prod	Read-only	N/A - approval not required
Non-prod	Read/write	N/A - governed by the change management process
Prod	Read-only	People managers in the Engineering or Security departments
Prod	Rake	People managers in the Monetization group (Fulfillment and Growth)
Prod	Read/write	N/A - governed by the change management process

Process

Security compliance requirement

Help GitLab remain secure and compliant by carefully following this process. Failure to do so may lead to an incomplete audit trail, which could result in negative findings during a compliance audit. Thank you for your assistance.

If you have any questions please reach out in #security_help.

This process is typically initiated when a requester tags you in the #teleport-requests channel, or asks you directly to approve an access request.

1. Log into Teleport via Okta SSO at https://production.teleport.gitlab.net.
2. In the left-hand sidebar, navigate to Identity Governance > Access Requests. Alternatively, you may click the link in #teleport-requests to jump directly to the request.
3. Identify the requester’s pending access request and click View.
4. Follow the review checklist below to determine whether the request meets security & compliance requirements.
5. If each checklist requirement is met, select Approve short-term access, otherwise select Reject request. You may optionally provide a short message with your reasoning
6. Click Submit Review.
7. The Slack bot in the #teleport-requests channel will automatically notify the requester.

Review checklist

Tip

You do not need to verify the requester’s identity. All access requests are authenticated via Okta and restricted to GitLab team members.

• The reason field contains a permanent link (usually to a GitLab issue)
• The issue linked in the reason field explains why the access request is required at this point in time
• The issue linked in the reason field explains what the requester intends to use the access for
• As an approver, use your judgement to determine whether the roles or resources being requested are appropriate and align with the the issue linked in the reason field.

(Optional) CLI workflow

Approvals can be done entirely through the web interface, but there are times when it may be desirable to do them from the CLI.

tsh login --proxy=production.teleport.gitlab.net # Log into Teleport
tsh request ls                                   # List pending access requests
tsh request show <request_id>                    # Show the details of a request
tsh request review <request_id>                  # Review a request

Next Steps

• Access requests are temporary and expire after 12 hours, but may be used across multiple sessions. They may be renewed before or after expiration using the same request process.
• Read about access requests in Teleport’s docs.

Support

• For help with Teleport or the approval process, ask in #security_help.
• To report a Teleport bug, open an issue with Infrastructure Security.

Troubleshooting

Credentials expired

If you see the following errors:

ERROR: your credentials have expired, please login using tsh login

ERROR: lstat /private/var/lib/teleport: no such file or directory

It’s likely that you need to log in or re-authenticate with:

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

User Issues

Many user issues can be corrected by removing their local ~/.tsh directory. It will be re-created on next login. These problems usually show up if the user has previously connected to an instance which has been rebuilt and has new CA certificates.

There are also times when restarting the Teleport service has resolved user issues. Read about that in the teleport_admin runbook.