Teleport Getting Started: Secure Access Setup Guide (2026)

Getting started overview

Teleport provides a unified access plane for managing and auditing access to infrastructure, including SSH servers, Kubernetes clusters, databases, web applications, and Windows desktops Teleport documentation overview. This guide details the process of initiating a Teleport deployment, obtaining necessary credentials, and performing a basic authenticated operation to confirm successful setup.

The core process involves:

1. Deploying the Teleport Auth Service and Proxy Service.
2. Creating user accounts and roles.
3. Configuring a resource (e.g., an SSH server) to be accessible via Teleport.
4. Establishing an authenticated connection to that resource.

For those starting with Teleport, the Teleport getting started guide recommends beginning with the open-source Community Edition for evaluation and non-production environments. Commercial versions offer additional features such as enterprise identity integrations and advanced auditing capabilities Teleport pricing tiers.

Installation options

Teleport can be deployed in various configurations:

• Self-hosted: Deploying Teleport components on your own infrastructure, typically using Docker, Kubernetes, or direct binary installation Teleport installation instructions. This offers full control over the environment.
• Cloud-hosted (Teleport Cloud): A managed service where Teleport Cloud hosts and manages the Auth and Proxy services, reducing operational overhead Teleport Cloud documentation.

For this getting started guide, we will focus on the initial setup steps common to both self-hosted and cloud deployments, emphasizing credential management and the first authenticated request.

Create an account and get keys

Regardless of the deployment model, establishing user accounts and obtaining authentication credentials are prerequisites for interacting with Teleport. Teleport uses short-lived X.509 certificates issued by its Auth Service for authentication, rather than long-lived API keys or passwords for infrastructure access Teleport authentication architecture. This enhances security by reducing the risk associated with compromised static credentials.

Teleport Cloud signup

1. Navigate to the Teleport Cloud signup page.
2. Provide the required information to create an account. This typically involves an email address and setting a password for the Teleport Cloud portal.
3. Once your account is created, you will be directed to your Teleport Cloud dashboard. From here, you can invite users and configure your cluster.
4. To log in to your Teleport cluster using the tsh client (Teleport's command-line tool), you will use identity provider credentials (e.g., GitHub, Google, Okta) configured during the initial setup Teleport Cloud getting started guide.

Self-hosted setup

For a self-hosted Teleport cluster, the process involves installing the Teleport daemon (teleport) and configuring its services. This example assumes a basic Linux installation.

1. Install Teleport: Download and install the Teleport package. For Debian/Ubuntu, this might look like:

   curl https://apt.releases.teleport.dev/teleport-install.sh | bash
   sudo apt install teleport
   

   For other operating systems, refer to the Teleport installation guide.

2. Initialize Teleport: Generate an initial configuration file.

   sudo teleport configure --output /etc/teleport.yaml
   

3. Start Teleport: Enable and start the Teleport service.

   sudo systemctl enable teleport
   sudo systemctl start teleport
   

4. Create the first user: Use tctl (Teleport Control Tool) to create an initial user with administrative privileges. This user will authenticate via a local password.

   sudo tctl users add <username> --roles=editor,access --logins=root,ubuntu
   

   You will be prompted to set a password for this user. This user can then log in via tsh login.

5. Log in with tsh: Authenticate your tsh client with the Teleport cluster.

   tsh login --proxy=<your-teleport-cluster-address> --user=<username>
   

   This command will prompt for your password and then issue a short-lived certificate to your local machine, allowing subsequent commands to be authenticated.

Your first request

Once authenticated with tsh login, your local client has a valid, short-lived certificate. You can now access resources that your Teleport user role permits. We will demonstrate accessing an SSH server managed by Teleport.

Prerequisites for first request

• A running Teleport cluster (self-hosted or Teleport Cloud).
• Your tsh client is authenticated to the cluster.
• At least one SSH server configured as a Teleport Node, or an application accessible via Teleport. For an SSH server, this involves installing the Teleport daemon on the server and configuring it to join your Teleport cluster Teleport SSH documentation.

Accessing an SSH server via Teleport

1. List available SSH nodes: Use tsh ls to see all SSH servers registered with your Teleport cluster.

   tsh ls
   

   This command will display a list of nodes, including their hostnames and labels.

   $ tsh ls
   -- Cluster: <your-teleport-cluster-address> --
   
   Node Name              Address            Labels
   ---------              -------            ------
   my-app-server-1        192.168.1.100:22   env=dev,app=web
   my-database-server     192.168.1.101:22   env=prod,app=db
   

2. Connect to an SSH node: Use tsh ssh to establish an SSH connection. You need to specify the login user (e.g., root, ubuntu, or a user allowed by your role) and the node's name or address.

   tsh ssh <login-user>@<node-name-or-address>
   

   Example:

   tsh ssh ubuntu@my-app-server-1
   

   If successful, you will be dropped into an SSH shell on the target server, authenticated by your Teleport-issued certificate. All sessions are recorded and audited by the Teleport Auth Service, providing a comprehensive audit trail Teleport audit logging documentation.

First Request Quick Reference

Common next steps

After successfully establishing your first connection, consider these common next steps to expand your Teleport deployment:

• Integrate Identity Providers (IdP): Connect Teleport to your existing identity management systems such as Okta, Auth0, Google Workspace, or GitHub for centralized user management and single sign-on (SSO) Teleport SSO integration. This reduces manual user provisioning and enhances security by leveraging established identity sources.

• Add More Resources: Extend Teleport's reach to other infrastructure components:

  • Kubernetes: Provide secure access to Kubernetes clusters Teleport Kubernetes access.
  • Databases: Secure connections to PostgreSQL, MySQL, MongoDB, and other databases Teleport database access.
  • Applications: Grant access to internal web applications Teleport application access.
  • Desktops: Manage access to Windows Desktops via RDP Teleport desktop access.

• Configure Roles and RBAC: Define granular Role-Based Access Control (RBAC) policies to specify which users can access which resources and with what permissions Teleport RBAC documentation. This is crucial for implementing the principle of least privilege.

• Set Up Audit Logging and Session Recording: Review and configure audit logging to ensure all access events are captured. Enable session recording for critical infrastructure to review interactive sessions Teleport audit logging. This is vital for compliance and incident response.

• Explore Teleport APIs and SDKs: For programmatic interaction, explore the Teleport API and available SDKs (Go, Python, Node.js) to automate tasks or integrate Teleport with other systems Teleport API reference. For example, you might use the API to manage users, roles, or resources dynamically. The Google API Client Library for Python provides a general example of how such libraries facilitate interaction with APIs.

Troubleshooting the first call

Encountering issues during the initial setup is common. Here are some troubleshooting steps for your first Teleport call:

• tsh login issues:

  • Proxy address: Ensure the --proxy address is correct and accessible from your client machine. It should point to your Teleport Proxy Service.
  • User credentials: Double-check the username and password (for local users) or ensure your IdP authentication flow completes successfully.
  • Certificate expiry: Teleport certificates are short-lived. If you've been authenticated for a while, your certificate might have expired. Run tsh login again to renew it.

• tsh ssh connection failures:

  • Node visibility: Use tsh ls to confirm the target SSH node is visible to your Teleport cluster and that its name/address is correct.
  • Teleport agent on node: Verify that the Teleport agent (teleport service) is running on the target SSH server and is successfully registered with your Teleport cluster. Check its logs (e.g., sudo journalctl -u teleport).
  • Firewall rules: Ensure that necessary ports (typically 3025 for SSH, 3023 for proxy) are open between your client, the Teleport Proxy, and the target SSH node.
  • User permissions: Check your Teleport role configuration to ensure your user has permission to access the target node and can log in as the specified user (e.g., ubuntu). Review the Teleport RBAC documentation for role definitions.
  • Time synchronization: Teleport relies on synchronized clocks for certificate validation. Ensure that the clocks on your client, the Teleport cluster, and the target node are synchronized (e.g., using NTP). Inaccurate time can lead to certificate validation failures, as detailed in general RFC 5280 on X.509 certificates.

• Teleport cluster logs: Always refer to the logs of your Teleport Auth and Proxy services for detailed error messages. These logs provide insights into authentication failures, connection issues, and role-related problems Teleport troubleshooting guide.