Getting Started
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.19+ and Go development environment.
- Set up Teleport through one of our getting started guides. You can also begin a free trial of Teleport Cloud.
Step 1/3. Create a user
When running Teleport in production, we recommend that you follow the practices below to avoid security incidents. These practices may differ from the examples used in this guide, which are intended for demo environments:
- 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" (PoLP). Don't give users
permissive roles when giving them more restrictive roles will do instead.
For example, assign users the built-in
access,editor
roles. - When joining a Teleport resource service (e.g., the Database Service or
Application Service) to a cluster, save the invitation token to a file.
Otherwise, the token will be visible when examining the
teleport
command that started the agent, e.g., via thehistory
command on a compromised system.
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-demogo mod init client-demogo get github.com/gravitational/teleport/api/client
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
- Learn about pkg.go.dev
- Learn how to use the client
- Learn how to work with credentials
- Read about Teleport API architecture for an in-depth overview of the API and API clients.
- Read API authorization to learn more about defining custom roles for your API client.
- Review the
client
pkg.go reference documentation for more information about working with the Teleport API programmatically. - Familiarize yourself with the admin manual to make the best use of the API.