README

This package is documented using a combination of pkg.go.dev and Teleport Docs.

Reference

Documentation

Overview

Package client provides a gRPC implementation of the Teleport Auth client. This client can be used to programatically interact with a Teleport Auth server.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a gRPC Client that connects to a Teleport Auth server either locally or over ssh through a Teleport web proxy or tunnel proxy.

This client can be used to cover a variety of Teleport use cases, such as programmatically handling access requests, integrating with external tools, or dynamically configuring Teleport.

Example (RoleCRUD)

Below is an example of creating a new Teleport Auth client with Profile credentials, and using that client to create, get, and delete a Role resource object.

Make sure to look at the Getting Started guide before attempting to run this example.

package main

import (
	"context"
	"log"
	"time"

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

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

	// Create a new client in your go file.
	clt, err := client.New(ctx, client.Config{
		Credentials: []client.Credentials{
			client.LoadProfile("", ""),
		},
		// set to true if your Teleport web proxy doesn't have HTTP/TLS certificate
		// configured yet (never use this in production).
		InsecureAddressDiscovery: false,
	})
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	defer clt.Close()

	// Resource Spec structs reflect their Resource's yaml definition.
	roleSpec := types.RoleSpecV4{
		Options: types.RoleOptions{
			MaxSessionTTL: types.Duration(time.Hour),
		},
		Allow: types.RoleConditions{
			Logins: []string{"role1"},
			Rules: []types.Rule{
				types.NewRule(types.KindAccessRequest, []string{types.VerbList, types.VerbRead}),
			},
		},
		Deny: types.RoleConditions{
			NodeLabels: types.Labels{"*": []string{"*"}},
		},
	}

	// There are helper functions for creating Teleport resources.
	role, err := types.NewRole("role1", roleSpec)
	if err != nil {
		log.Fatalf("failed to get role: %v", err)
	}

	// Getters and setters can be used to alter specs.
	role.SetLogins(types.Allow, []string{"root"})

	// Upsert overwrites the resource if it exists. Use this to create/update resources.
	// Equivalent to `tctl create -f role1.yaml`.
	err = clt.UpsertRole(ctx, role)
	if err != nil {
		log.Fatalf("failed to create role: %v", err)
	}

	// Equivalent to `tctl get role/role1`.
	role, err = clt.GetRole(ctx, "role1")
	if err != nil {
		log.Fatalf("failed to get role: %v", err)
	}

	// Equivalent to `tctl rm role/role1`.
	err = clt.DeleteRole(ctx, "role1")
	if err != nil {
		log.Fatalf("failed to delete role: %v", err)
	}
}
Output:

func New

func New(ctx context.Context, cfg Config) (clt *Client, err error)

New creates a new API client with an open connection to a Teleport server.

New will try to open a connection with all combinations of addresses and credentials. The first successful connection to a server will be used, or an aggregated error will be returned if all combinations fail.

cfg.Credentials must be non-empty. One of cfg.Addrs and cfg.Dialer must be non-empty, unless LoadProfile is used to fetch Credentials and load a web proxy dialer.

See the example below for usage.

Example
package main

import (
	"context"
	"log"

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

func main() {
	ctx := context.Background()
	clt, err := client.New(ctx, client.Config{
		// Multiple Addresses can be provided to attempt to
		// connect to the auth server. At least one address
		// must be provided, except when using the ProfileCreds.
		Addrs: []string{
			// The Auth server address can be provided to connect locally.
			"auth.example.com:3025",
			// The tunnel proxy address can be provided
			// to connect to the Auth server over SSH.
			"proxy.example.com:3024",
			// The web proxy address can be provided to automatically
			// find the tunnel proxy address and connect using it.
			"proxy.example.com:3080",
		},
		// Multiple Credentials can be provided to attempt to authenticate
		// the client. At least one Credentials object must be provided.
		Credentials: []client.Credentials{
			client.LoadProfile("", ""),
			client.LoadIdentityFile("identity-path"),
			client.LoadKeyPair("cert.crt", "cert.key", "cert.cas"),
		},
		// set to true if your web proxy doesn't have HTTP/TLS certificate
		// configured yet (never use this in production).
		InsecureAddressDiscovery: false,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer clt.Close()

	clt.Ping(ctx)
}
Output:

func (*Client) AcquireSemaphore

func (c *Client) AcquireSemaphore(ctx context.Context, params types.AcquireSemaphoreRequest) (*types.SemaphoreLease, error)

AcquireSemaphore acquires lease with requested resources from semaphore.

func (*Client) AddMFADevice

func (*Client) CancelSemaphoreLease

func (c *Client) CancelSemaphoreLease(ctx context.Context, lease types.SemaphoreLease) error

CancelSemaphoreLease cancels semaphore lease early.

func (*Client) Close

func (c *Client) Close() error

Close closes the Client connection to the auth server.

func (*Client) Config

func (c *Client) Config() *tls.Config

Config returns the tls.Config the client connected with.

func (*Client) CreateAccessRequest

func (c *Client) CreateAccessRequest(ctx context.Context, req types.AccessRequest) error

CreateAccessRequest registers a new access request with the auth server.

func (*Client) CreateAppSession

func (c *Client) CreateAppSession(ctx context.Context, req types.CreateAppSessionRequest) (types.WebSession, error)

CreateAppSession creates an application web session. Application web sessions represent a browser session the client holds.

func (*Client) CreateAuditStream

func (c *Client) CreateAuditStream(ctx context.Context, sessionID string) (events.Stream, error)

CreateAuditStream creates new audit stream.

func (*Client) CreateResetPasswordToken

func (c *Client) CreateResetPasswordToken(ctx context.Context, req *proto.CreateResetPasswordTokenRequest) (types.ResetPasswordToken, error)

CreateResetPasswordToken creates reset password token.

func (*Client) CreateUser

func (c *Client) CreateUser(ctx context.Context, user types.User) error

CreateUser creates a new user from the specified descriptor.

func (*Client) DeleteAccessRequest

func (c *Client) DeleteAccessRequest(ctx context.Context, reqID string) error

DeleteAccessRequest deletes an access request.

func (*Client) DeleteAllAppServers

func (c *Client) DeleteAllAppServers(ctx context.Context, namespace string) error

DeleteAllAppServers removes all application servers.

func (*Client) DeleteAllAppSessions

func (c *Client) DeleteAllAppSessions(ctx context.Context) error

DeleteAllAppSessions removes all application web sessions.

func (*Client) DeleteAllDatabaseServers

func (c *Client) DeleteAllDatabaseServers(ctx context.Context, namespace string) error

DeleteAllDatabaseServers removes all registered database proxy servers.

func (*Client) DeleteAllKubeServices

func (c *Client) DeleteAllKubeServices(ctx context.Context) error

DeleteAllKubeServices deletes all registered kubernetes services.

func (*Client) DeleteAllNodes

func (c *Client) DeleteAllNodes(ctx context.Context, namespace string) error

DeleteAllNodes deletes all nodes in a given namespace.

func (*Client) DeleteAppServer

func (c *Client) DeleteAppServer(ctx context.Context, namespace string, name string) error

DeleteAppServer removes an application server.

func (*Client) DeleteAppSession

func (c *Client) DeleteAppSession(ctx context.Context, req types.DeleteAppSessionRequest) error

DeleteAppSession removes an application web session.

func (*Client) DeleteClusterAuditConfig

func (c *Client) DeleteClusterAuditConfig(ctx context.Context) error

DeleteClusterAuditConfig not implemented: can only be called locally.

func (*Client) DeleteClusterNetworkingConfig

func (c *Client) DeleteClusterNetworkingConfig(ctx context.Context) error

DeleteClusterNetworkingConfig not implemented: can only be called locally.

func (*Client) DeleteDatabaseServer

func (c *Client) DeleteDatabaseServer(ctx context.Context, namespace, hostID, name string) error

DeleteDatabaseServer removes the specified database proxy server.

func (*Client) DeleteGithubConnector

func (c *Client) DeleteGithubConnector(ctx context.Context, name string) error

DeleteGithubConnector deletes a Github connector by name.

func (*Client) DeleteKubeService

func (c *Client) DeleteKubeService(ctx context.Context, name string) error

DeleteKubeService deletes a named kubernetes service.

func (*Client) DeleteMFADevice

func (*Client) DeleteNode

func (c *Client) DeleteNode(ctx context.Context, namespace, name string) error

DeleteNode deletes a node by name and namespace.

func (*Client) DeleteOIDCConnector

func (c *Client) DeleteOIDCConnector(ctx context.Context, name string) error

DeleteOIDCConnector deletes an OIDC connector by name.

func (*Client) DeleteRole

func (c *Client) DeleteRole(ctx context.Context, name string) error

DeleteRole deletes role by name

func (*Client) DeleteSAMLConnector

func (c *Client) DeleteSAMLConnector(ctx context.Context, name string) error

DeleteSAMLConnector deletes a SAML connector by name.

func (*Client) DeleteSemaphore

func (c *Client) DeleteSemaphore(ctx context.Context, filter types.SemaphoreFilter) error

DeleteSemaphore deletes a semaphore matching the supplied filter.

func (*Client) DeleteSessionRecordingConfig

func (c *Client) DeleteSessionRecordingConfig(ctx context.Context) error

DeleteSessionRecordingConfig not implemented: can only be called locally.

func (*Client) DeleteToken

func (c *Client) DeleteToken(ctx context.Context, name string) error

DeleteToken deletes a provision token by name.

func (*Client) DeleteTrustedCluster

func (c *Client) DeleteTrustedCluster(ctx context.Context, name string) error

DeleteTrustedCluster deletes a Trusted Cluster by name.

func (*Client) DeleteUser

func (c *Client) DeleteUser(ctx context.Context, user string) error

DeleteUser deletes a user by name.

func (*Client) Dialer

func (c *Client) Dialer() ContextDialer

Dialer returns the ContextDialer the client connected with.

func (*Client) EmitAuditEvent

func (c *Client) EmitAuditEvent(ctx context.Context, event events.AuditEvent) error

EmitAuditEvent sends an auditable event to the auth server.

func (*Client) GenerateAppToken

func (c *Client) GenerateAppToken(ctx context.Context, req types.GenerateAppTokenRequest) (string, error)

GenerateAppToken creates a JWT token with application access.

func (*Client) GenerateDatabaseCert

func (c *Client) GenerateDatabaseCert(ctx context.Context, req *proto.DatabaseCertRequest) (*proto.DatabaseCertResponse, error)

GenerateDatabaseCert generates client certificate used by a database service to authenticate with the database instance.

func (*Client) GenerateUserCerts

func (c *Client) GenerateUserCerts(ctx context.Context, req proto.UserCertsRequest) (*proto.Certs, error)

GenerateUserCerts takes the public key in the OpenSSH `authorized_keys` plain text format, signs it using User Certificate Authority signing key and returns the resulting certificates.

func (*Client) GenerateUserSingleUseCerts

func (c *Client) GenerateUserSingleUseCerts(ctx context.Context) (proto.AuthService_GenerateUserSingleUseCertsClient, error)

func (*Client) GetAccessCapabilities

func (c *Client) GetAccessCapabilities(ctx context.Context, req types.AccessCapabilitiesRequest) (*types.AccessCapabilities, error)

GetAccessCapabilities requests the access capabilities of a user.

func (*Client) GetAccessRequests

func (c *Client) GetAccessRequests(ctx context.Context, filter types.AccessRequestFilter) ([]types.AccessRequest, error)

GetAccessRequests retrieves a list of all access requests matching the provided filter.

func (*Client) GetAppServers

func (c *Client) GetAppServers(ctx context.Context, namespace string) ([]types.Server, error)

GetAppServers gets all application servers.

func (*Client) GetAppSession

func (c *Client) GetAppSession(ctx context.Context, req types.GetAppSessionRequest) (types.WebSession, error)

GetAppSession gets an application web session.

func (*Client) GetAppSessions

func (c *Client) GetAppSessions(ctx context.Context) ([]types.WebSession, error)

GetAppSessions gets all application web sessions.

func (*Client) GetClusterAuditConfig

func (c *Client) GetClusterAuditConfig(ctx context.Context) (types.ClusterAuditConfig, error)

GetClusterAuditConfig gets cluster audit configuration.

func (*Client) GetClusterNetworkingConfig

func (c *Client) GetClusterNetworkingConfig(ctx context.Context) (types.ClusterNetworkingConfig, error)

GetClusterNetworkingConfig gets cluster networking configuration.

func (*Client) GetConnection

func (c *Client) GetConnection() *grpc.ClientConn

GetConnection returns GRPC connection.

func (*Client) GetDatabaseServers

func (c *Client) GetDatabaseServers(ctx context.Context, namespace string) ([]types.DatabaseServer, error)

GetDatabaseServers returns all registered database proxy servers.

func (*Client) GetGithubConnector

func (c *Client) GetGithubConnector(ctx context.Context, name string, withSecrets bool) (types.GithubConnector, error)

GetGithubConnector returns a Github connector by name.

func (*Client) GetGithubConnectors

func (c *Client) GetGithubConnectors(ctx context.Context, withSecrets bool) ([]types.GithubConnector, error)

GetGithubConnectors returns a list of Github connectors.

func (*Client) GetKubeServices

func (c *Client) GetKubeServices(ctx context.Context) ([]types.Server, error)

GetKubeServices returns the list of kubernetes services registered in the cluster.

func (*Client) GetMFADevices

func (*Client) GetNode

func (c *Client) GetNode(ctx context.Context, namespace, name string) (types.Server, error)

GetNode returns a node by name and namespace.

func (*Client) GetNodes

func (c *Client) GetNodes(ctx context.Context, namespace string) ([]types.Server, error)

GetNodes returns a list of nodes by namespace. Nodes that the user doesn't have access to are filtered out.

func (*Client) GetOIDCConnector

func (c *Client) GetOIDCConnector(ctx context.Context, name string, withSecrets bool) (types.OIDCConnector, error)

GetOIDCConnector returns an OIDC connector by name.

func (*Client) GetOIDCConnectors

func (c *Client) GetOIDCConnectors(ctx context.Context, withSecrets bool) ([]types.OIDCConnector, error)

GetOIDCConnectors returns a list of OIDC connectors.

func (*Client) GetPluginData

func (c *Client) GetPluginData(ctx context.Context, filter types.PluginDataFilter) ([]types.PluginData, error)

GetPluginData loads all plugin data matching the supplied filter.

func (*Client) GetResetPasswordToken

func (c *Client) GetResetPasswordToken(ctx context.Context, tokenID string) (types.ResetPasswordToken, error)

GetResetPasswordToken returns a ResetPasswordToken for the specified tokenID.

func (*Client) GetRole

func (c *Client) GetRole(ctx context.Context, name string) (types.Role, error)

GetRole returns role by name

func (*Client) GetRoles

func (c *Client) GetRoles(ctx context.Context) ([]types.Role, error)

GetRoles returns a list of roles

func (*Client) GetSAMLConnector

func (c *Client) GetSAMLConnector(ctx context.Context, name string, withSecrets bool) (types.SAMLConnector, error)

GetSAMLConnector returns a SAML connector by name.

func (*Client) GetSAMLConnectors

func (c *Client) GetSAMLConnectors(ctx context.Context, withSecrets bool) ([]types.SAMLConnector, error)

GetSAMLConnectors returns a list of SAML connectors.

func (*Client) GetSemaphores

func (c *Client) GetSemaphores(ctx context.Context, filter types.SemaphoreFilter) ([]types.Semaphore, error)

GetSemaphores returns a list of all semaphores matching the supplied filter.

func (*Client) GetSessionRecordingConfig

func (c *Client) GetSessionRecordingConfig(ctx context.Context) (types.SessionRecordingConfig, error)

GetSessionRecordingConfig gets session recording configuration.

func (*Client) GetToken

func (c *Client) GetToken(ctx context.Context, name string) (types.ProvisionToken, error)

GetToken returns a provision token by name.

func (*Client) GetTokens

func (c *Client) GetTokens(ctx context.Context) ([]types.ProvisionToken, error)

GetTokens returns a list of active provision tokens for nodes and users.

func (*Client) GetTrustedCluster

func (c *Client) GetTrustedCluster(ctx context.Context, name string) (types.TrustedCluster, error)

GetTrustedCluster returns a Trusted Cluster by name.

func (*Client) GetTrustedClusters

func (c *Client) GetTrustedClusters(ctx context.Context) ([]types.TrustedCluster, error)

GetTrustedClusters returns a list of Trusted Clusters.

func (*Client) GetUser

func (c *Client) GetUser(name string, withSecrets bool) (types.User, error)

GetUser returns a list of usernames registered in the system. withSecrets controls whether authentication details are returned.

func (*Client) GetUsers

func (c *Client) GetUsers(withSecrets bool) ([]types.User, error)

GetUsers returns a list of users. withSecrets controls whether authentication details are returned.

func (*Client) GetWebSession

func (c *Client) GetWebSession(ctx context.Context, req types.GetWebSessionRequest) (types.WebSession, error)

GetWebSession returns the web session for the specified request. Implements ReadAccessPoint

func (*Client) GetWebToken

func (c *Client) GetWebToken(ctx context.Context, req types.GetWebTokenRequest) (types.WebToken, error)

GetWebToken returns the web token for the specified request. Implements ReadAccessPoint

func (*Client) IsMFARequired

func (*Client) KeepAliveSemaphoreLease

func (c *Client) KeepAliveSemaphoreLease(ctx context.Context, lease types.SemaphoreLease) error

KeepAliveSemaphoreLease updates semaphore lease.

func (*Client) NewKeepAliver

func (c *Client) NewKeepAliver(ctx context.Context) (types.KeepAliver, error)

NewKeepAliver returns a new instance of keep aliver. It is the caller's responsibility to invoke Close on the returned value to release the keepAliver resources.

func (*Client) NewWatcher

func (c *Client) NewWatcher(ctx context.Context, watch types.Watch) (types.Watcher, error)

NewWatcher returns a new streamWatcher

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) (proto.PingResponse, error)

Ping gets basic info about the auth server.

func (*Client) ResetAuthPreference

func (c *Client) ResetAuthPreference(ctx context.Context) error

ResetAuthPreference resets cluster auth preference to defaults.

func (*Client) ResetClusterNetworkingConfig

func (c *Client) ResetClusterNetworkingConfig(ctx context.Context) error

ResetClusterNetworkingConfig resets cluster networking configuration to defaults.

func (*Client) ResetSessionRecordingConfig

func (c *Client) ResetSessionRecordingConfig(ctx context.Context) error

ResetSessionRecordingConfig resets session recording configuration to defaults.

func (*Client) ResumeAuditStream

func (c *Client) ResumeAuditStream(ctx context.Context, sessionID, uploadID string) (events.Stream, error)

ResumeAuditStream resumes existing audit stream.

func (*Client) RotateResetPasswordTokenSecrets

func (c *Client) RotateResetPasswordTokenSecrets(ctx context.Context, tokenID string) (types.ResetPasswordTokenSecrets, error)

RotateResetPasswordTokenSecrets rotates secrets for a given tokenID. It gets called every time a user fetches 2nd-factor secrets during registration attempt. This ensures that an attacker that gains the ResetPasswordToken link can not view it, extract the OTP key from the QR code, then allow the user to signup with the same OTP token.

func (*Client) SearchEvents

func (c *Client) SearchEvents(ctx context.Context, fromUTC, toUTC time.Time, namespace string, eventTypes []string, limit int, startKey string) ([]events.AuditEvent, string, error)

SearchEvents allows searching for events with a full pagination support.

func (*Client) SearchSessionEvents

func (c *Client) SearchSessionEvents(ctx context.Context, fromUTC time.Time, toUTC time.Time, limit int, startKey string) ([]events.AuditEvent, string, error)

SearchSessionEvents allows searching for session events with a full pagination support.

func (*Client) SetAccessRequestState

func (c *Client) SetAccessRequestState(ctx context.Context, params types.AccessRequestUpdate) error

SetAccessRequestState updates the state of an existing access request.

func (*Client) SetClusterAuditConfig

func (c *Client) SetClusterAuditConfig(ctx context.Context, auditConfig types.ClusterAuditConfig) error

SetClusterAuditConfig sets cluster audit configuration.

func (*Client) SetClusterNetworkingConfig

func (c *Client) SetClusterNetworkingConfig(ctx context.Context, netConfig types.ClusterNetworkingConfig) error

SetClusterNetworkingConfig sets cluster networking configuration.

func (*Client) SetSessionRecordingConfig

func (c *Client) SetSessionRecordingConfig(ctx context.Context, recConfig types.SessionRecordingConfig) error

SetSessionRecordingConfig sets session recording configuration.

func (*Client) SignDatabaseCSR

func (c *Client) SignDatabaseCSR(ctx context.Context, req *proto.DatabaseCSRRequest) (*proto.DatabaseCSRResponse, error)

SignDatabaseCSR generates a client certificate used by proxy when talking to a remote database service.

func (*Client) SubmitAccessReview

func (c *Client) SubmitAccessReview(ctx context.Context, params types.AccessReviewSubmission) (types.AccessRequest, error)

SubmitAccessReview applies a review to a request and returns the post-application state.

func (*Client) UpdatePluginData

func (c *Client) UpdatePluginData(ctx context.Context, params types.PluginDataUpdateParams) error

UpdatePluginData updates a per-resource PluginData entry.

func (*Client) UpdateRemoteCluster

func (c *Client) UpdateRemoteCluster(ctx context.Context, rc types.RemoteCluster) error

UpdateRemoteCluster updates remote cluster from the specified value.

func (*Client) UpdateUser

func (c *Client) UpdateUser(ctx context.Context, user types.User) error

UpdateUser updates an existing user in a backend.

func (*Client) UpsertAppServer

func (c *Client) UpsertAppServer(ctx context.Context, server types.Server) (*types.KeepAlive, error)

UpsertAppServer adds an application server.

func (*Client) UpsertDatabaseServer

func (c *Client) UpsertDatabaseServer(ctx context.Context, server types.DatabaseServer) (*types.KeepAlive, error)

UpsertDatabaseServer registers a new database proxy server.

func (*Client) UpsertGithubConnector

func (c *Client) UpsertGithubConnector(ctx context.Context, connector types.GithubConnector) error

UpsertGithubConnector creates or updates a Github connector.

func (*Client) UpsertKubeService

func (c *Client) UpsertKubeService(ctx context.Context, s types.Server) error

UpsertKubeService is used by kubernetes services to report their presence to other auth servers in form of hearbeat expiring after ttl period.

func (*Client) UpsertNode

func (c *Client) UpsertNode(ctx context.Context, node types.Server) (*types.KeepAlive, error)

UpsertNode is used by SSH servers to report their presence to the auth servers in form of heartbeat expiring after ttl period.

func (*Client) UpsertOIDCConnector

func (c *Client) UpsertOIDCConnector(ctx context.Context, oidcConnector types.OIDCConnector) error

UpsertOIDCConnector creates or updates an OIDC connector.

func (*Client) UpsertRole

func (c *Client) UpsertRole(ctx context.Context, role types.Role) error

UpsertRole creates or updates role

func (*Client) UpsertSAMLConnector

func (c *Client) UpsertSAMLConnector(ctx context.Context, connector types.SAMLConnector) error

UpsertSAMLConnector creates or updates a SAML connector.

func (*Client) UpsertToken

func (c *Client) UpsertToken(ctx context.Context, token types.ProvisionToken) error

UpsertToken creates or updates a provision token.

func (*Client) UpsertTrustedCluster

func (c *Client) UpsertTrustedCluster(ctx context.Context, trusedCluster types.TrustedCluster) (types.TrustedCluster, error)

UpsertTrustedCluster creates or updates a Trusted Cluster.

func (*Client) WebSessions

func (c *Client) WebSessions() types.WebSessionInterface

WebSessions returns the web sessions controller

func (*Client) WebTokens

func (c *Client) WebTokens() types.WebTokenInterface

WebTokens returns the web tokens controller

func (*Client) WithCallOptions

func (c *Client) WithCallOptions(opts ...grpc.CallOption) *Client

WithCallOptions returns a copy of the client with the given call options set. This function should be used for chaining - client.WithCallOptions().Ping()

type Config

type Config struct {
	// Addrs is a list of teleport auth/proxy server addresses to dial.
	Addrs []string
	// Credentials are a list of credentials to use when attempting
	// to connect to the server.
	Credentials []Credentials
	// Dialer is a custom dialer used to dial a server. If set, Dialer
	// takes precedence over all other connection options.
	Dialer ContextDialer
	// DialOpts define options for dialing the client connection.
	DialOpts []grpc.DialOption
	// DialInBackground specifies to dial the connection in the background
	// rather than blocking until the connection is up. A predefined Dialer
	// or an auth server address must be provided.
	DialInBackground bool
	// DialTimeout defines how long to attempt dialing before timing out.
	DialTimeout time.Duration
	// KeepAlivePeriod defines period between keep alives.
	KeepAlivePeriod time.Duration
	// KeepAliveCount specifies the amount of missed keep alives
	// to wait for before declaring the connection as broken.
	KeepAliveCount int
	// The web proxy uses a self-signed TLS certificate by default, which
	// requires this field to be set. If the web proxy was provided with
	// signed TLS certificates, this field should not be set.
	InsecureAddressDiscovery bool
}

Config contains configuration of the client

func (*Config) CheckAndSetDefaults

func (c *Config) CheckAndSetDefaults() error

CheckAndSetDefaults checks and sets default config values.

type ContextDialer

type ContextDialer interface {
	// DialContext is a function that dials the specified address
	DialContext(ctx context.Context, network, addr string) (net.Conn, error)
}

ContextDialer represents network dialer interface that uses context

func NewDirectDialer

func NewDirectDialer(keepAlivePeriod, dialTimeout time.Duration) ContextDialer

NewDirectDialer makes a new dialer to connect directly to an Auth server.

func NewProxyDialer

func NewProxyDialer(ssh ssh.ClientConfig, keepAlivePeriod, dialTimeout time.Duration, discoveryAddr string, insecure bool) ContextDialer

NewProxyDialer makes a dialer to connect to an Auth server through the SSH reverse tunnel on the proxy. The dialer will ping the web client to discover the tunnel proxy address on each dial.

type ContextDialerFunc

type ContextDialerFunc func(ctx context.Context, network, addr string) (net.Conn, error)

ContextDialerFunc is a function wrapper that implements the ContextDialer interface.

func (ContextDialerFunc) DialContext

func (f ContextDialerFunc) DialContext(ctx context.Context, network, addr string) (net.Conn, error)

DialContext is a function that dials to the specified address

type Credentials

type Credentials interface {
	// Dialer is used to create a dialer used to connect to the Auth server.
	Dialer(cfg Config) (ContextDialer, error)
	// TLSConfig returns TLS configuration used to authenticate the client.
	TLSConfig() (*tls.Config, error)
	// SSHClientConfig returns SSH configuration used to connect to the
	// Auth server through a reverse tunnel.
	SSHClientConfig() (*ssh.ClientConfig, error)
}

Credentials are used to authenticate the API auth client. Some Credentials also provide other functionality, such as automatic address discovery and ssh connectivity.

See the examples below for an example of each loader.

Example (LoadIdentity)

Generate identity file with tsh or tctl.

$ tsh login --user=api-user --out=identity-file-path
$ tctl auth sign --user=api-user --out=identity-file-path

Load credentials from the specified identity file.

package main

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

func main() {
	client.LoadIdentityFile("identity-file-path")
}
Output:

Example (LoadKeyPair)

Generate certificate key pair with tctl.

$ tctl auth sign --format=tls --user=api-user --out=path/to/certs

Load credentials from the specified certificate files.

package main

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

func main() {
	client.LoadKeyPair(
		"path/to/certs.crt",
		"path/to/certs.key",
		"path/to/certs.cas",
	)
}
Output:

Example (LoadProfile)

Generate tsh profile with tsh.

$ tsh login --user=api-user

Load credentials from the default directory and current profile, or specify the directory and profile.

package main

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

func main() {
	client.LoadProfile("", "")
	client.LoadProfile("profile-directory", "api-user")
}
Output:

func LoadIdentityFile

func LoadIdentityFile(path string) Credentials

LoadIdentityFile is used to load Credentials from an identity file on disk.

Identity Credentials can be used to connect to an auth server directly or through a reverse tunnel.

A new identity file can be generated with tsh or tctl.

$ tsh login --user=api-user --out=identity-file-path
$ tctl auth sign --user=api-user --out=identity-file-path

The identity file's time to live can be specified with --ttl.

See the example below for usage.

Example

Load credentials from the specified identity file.

package main

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

func main() {
	client.LoadIdentityFile("identity-file-path")
}
Output:

func LoadKeyPair

func LoadKeyPair(certFile, keyFile, caFile string) Credentials

LoadKeyPair is used to load Credentials from a certicate keypair on disk.

KeyPair Credentials can only be used to connect directly to a Teleport Auth server.

New KeyPair files can be generated with tsh or tctl.

$ tctl auth sign --format=tls --user=api-user --out=path/to/certs

The certificates' time to live can be specified with --ttl.

See the example below for usage.

Example

Load credentials from the specified certificate files.

package main

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

func main() {
	client.LoadKeyPair(
		"path/to/certs.crt",
		"path/to/certs.key",
		"path/to/certs.cas",
	)
}
Output:

func LoadProfile

func LoadProfile(dir, name string) Credentials

LoadProfile is used to load Credentials from a tsh profile on disk.

dir is the profile directory. It will defaults to "~/.tsh".

name is the profile name. It will default to the currently active tsh profile.

Profile Credentials can be used to connect to an auth server directly or through a reverse tunnel.

Profile Credentials will automatically attempt to find your reverse tunnel address and make a connection through it.

A new profile can be generated with tsh.

$ tsh login --user=api-user
Example

Load credentials from the default directory and current profile, or specify the directory and profile.

package main

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

func main() {
	client.LoadProfile("", "")
	client.LoadProfile("profile-directory", "api-user")
}
Output:

func LoadTLS

func LoadTLS(tlsConfig *tls.Config) Credentials

LoadTLS is used to load Credentials directly from a *tls.Config.

TLS creds can only be used to connect directly to a Teleport Auth server.

Directories

Path Synopsis
Package proto holds the protobuff api specification for Teleport Auth servers and clients
Package proto holds the protobuff api specification for Teleport Auth servers and clients
Package webclient provides a client for the Teleport Proxy API endpoints.
Package webclient provides a client for the Teleport Proxy API endpoints.