Fork me on GitHub
Teleport

API Getting Started Guide

Getting Started

In this getting started guide we will use the Teleport API Go client to connect to a Teleport Node configured as an Auth server.

Here are the steps we'll walkthrough:

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

Prerequisites

Step 1/3. Create a user

Tip

The examples below may include the use of the sudo keyword, token UUIDs, and users with admin privileges to make following each step easier when creating resources from scratch.

Generally:

  1. We discourage using sudo in production environments unless it's needed.
  2. We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
  3. We encourage adherence to the Principle of Least Privilege (PoLP) and Zero Admin best practices. Don't give users the admin role when giving them the more restrictive access,editor roles will do instead.
  4. Saving tokens into a file rather than sharing tokens directly as strings.

Learn more about Teleport Role-Based Access Control best practices.

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 admin:

Run this directly on your auth server

Add user and login via web proxy

sudo tctl users add api-admin --roles=admin

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

Create a file main.go with the following command, modifying the Addrs strings as needed:

cat > main.go << 'EOF'
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{
            "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)
}
EOF

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

Have a suggestion or can’t find something?
IMPROVE THE DOCS