Scaling Privileged Access for Modern Infrastructure: Real-World Insights
Apr 25
Virtual
Register Today
Support
LOG IN
Teleport logoTry For Free
Contact SalesTry for Free
Support
LOG IN
Fork me on GitHub

Teleport

API Getting Started Guide

Version 15.x

In this getting started guide we will use the Teleport API Go client to connect to a Teleport Auth Service.

Here are the steps we'll walkthrough:

  • Create an API user using a simple role-based authentication method.
  • Generate credentials for that user.
  • Create and connect a Go client to interact with Teleport's API.

Prerequisites

  • Install Go 1.21+ and Go development environment.

  • A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool version >= 15.2.2.

    On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example: 
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status
    Cluster  teleport.example.com
    Version  15.2.2
    CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/3. Create a user

When running Teleport in production, you should adhere to the following best practices to avoid security incidents:

  • Avoid using sudo in production environments unless it's necessary.
  • Create new, non-root, users and use test instances for experimenting with Teleport.
  • Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443).
  • Follow the principle of least privilege. Don't give users permissive roles when more a restrictive role will do. For example, don't assign users the built-in access,editor roles, which give them permissions to access and edit all cluster resources. Instead, define roles with the minimum required permissions for each user and configure access requests to provide temporary elevated permissions.
  • When you enroll Teleport resources—for example, new databases or applications—you should save the invitation token to a file. If you enter the token directly on the command line, a malicious user could view it by running the history command on a compromised system.

You should note that these practices aren't necessarily reflected in the examples used in documentation. Examples in the documentation are primarily intended for demonstration and for development environments.

Tip

Read API authorization to learn more about defining custom roles for your API client.

Create a user api-admin with the built-in role editor:

Run this directly on your Auth Server unless you are using Teleport Cloud
Add a user and login via the Proxy Service
sudo tctl users add api-admin --roles=editor

Step 2/3. Generate client credentials

Log in as the newly created user with tsh.

generate tsh profile
tsh login --user=api-admin --proxy=tele.example.com

The Profile Credentials loader will automatically retrieve Credentials from the current profile in the next step.

Step 3/3. Create a Go project

Set up a new Go module and import the client package:

mkdir client-demo && cd client-demo
go mod init client-demo
go get github.com/gravitational/teleport/api/client
API Version

To ensure compatibility, you should use a version of Teleport's API library that matches the major version of Teleport running in your cluster.

To find the pseudoversion appropriate for a go.mod file for a specific git tag, run the following command from the teleport repository:

go list -f '{{.Version}}' -m "github.com/gravitational/teleport/api@$(git rev-parse v12.1.0)"
v0.0.0-20230307032901-49a6de744a3a

Create a file called main.go, modifying the Addrs strings as needed:

package main

import (
	"context"
	"log"

	"github.com/gravitational/teleport/api/client"
)

func main() {
	ctx := context.Background()

	clt, err := client.New(ctx, client.Config{
		Addrs: []string{
			// Teleport Cloud customers should use <tenantname>.teleport.sh
			"tele.example.com:443",
			"tele.example.com:3025",
			"tele.example.com:3024",
			"tele.example.com:3080",
 		},
		Credentials: []client.Credentials{
			client.LoadProfile("", ""),
		},
	})

	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}

	defer clt.Close()
	resp, err := clt.Ping(ctx)
	if err != nil {
		log.Fatalf("failed to ping server: %v", err)
	}

	log.Printf("Example success!")
	log.Printf("Example server response: %s", resp)
	log.Printf("Server version: %s", resp.ServerVersion)
}

Now you can run the program and connect the client to the Teleport Auth Server to fetch the server version.

go run main.go

Next steps