이 시작 가이드에서는 Teleport API Go 클라이언트를 사용하여 Teleport Auth 서비스에 연결합니다.

진행할 단계:

• 간단한 역할 기반 인증 방법을 사용하여 API 사용자 생성
• 해당 사용자의 자격 증명 생성
• Teleport의 API와 상호작용할 Go 클라이언트 생성 및 연결

작동 방식#

Teleport Auth 서비스는 클라이언트 도구가 백엔드 리소스를 관리할 수 있게 해주는 gRPC API를 제공합니다. tctl, Teleport Kubernetes 오퍼레이터, Teleport Terraform 프로바이더는 이 API를 사용하며, API 리소스를 관리하거나 Teleport 감사 이벤트를 구독하는 커스텀 도구를 작성할 수 있습니다.

Teleport API 클라이언트는 TLS 자격 증명을 사용하여 Teleport에 인증합니다. 이 가이드에서는 tsh로 로그인한 후 Auth 서비스가 제공하는 TLS 자격 증명을 로드하는 방법을 보여줍니다.

사전 요구 사항#

• Go [teleport.golang]+ 및 Go 개발 환경 설치

• 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 and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:

     $ TELEPORT_DOMAIN=
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. Follow the instructions for your platform to install tctl and tsh clients:

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.

For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

$ tsh login --proxy= --user=
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

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.

1/3단계. 사용자 생성#

Best practices for production security

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.

팁: API 클라이언트의 커스텀 역할 정의에 대해 자세히 알아보려면 API 권한 부여를 읽으세요.

내장 역할 editor를 가진 사용자 api-admin을 생성합니다:

$ tctl users add api-admin --roles=editor

2/3단계. 클라이언트 자격 증명 생성#

tsh로 새로 생성된 사용자로 로그인합니다.

# tsh 프로파일 생성
$ tsh login --user=api-admin --proxy=tele.example.com

프로파일 자격 증명 로더는 다음 단계에서 현재 프로파일의 자격 증명을 자동으로 가져옵니다.

3/3단계. Go 프로젝트 생성#

새 Go 모듈을 설정하고 client 패키지를 임포트합니다:

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

API 버전: 호환성을 보장하려면 클러스터에서 실행 중인 Teleport의 주요 버전과 일치하는 Teleport API 라이브러리 버전을 사용해야 합니다.

특정 git 태그에 대해 go.mod 파일에 적합한 의사 버전을 찾으려면 teleport 저장소에서 다음 명령을 실행합니다:

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

필요에 따라 Addrs 문자열을 수정하여 main.go 파일을 생성합니다:

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 고객은 <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: %v", resp)
	log.Printf("Server version: %s", resp.ServerVersion)
}

이제 프로그램을 실행하고 클라이언트를 Teleport Auth 서비스에 연결하여 서버 버전을 가져올 수 있습니다.

$ go run main.go

다음 단계#

• pkg.go.dev에 대해 알아보기
• 클라이언트 사용법 알아보기
• 자격 증명 작업 방법 알아보기
• API 및 API 클라이언트에 대한 심층적인 개요는 API 아키텍처를 읽으세요.
• API 클라이언트의 커스텀 역할 정의에 대해 자세히 알아보려면 API 권한 부여를 읽으세요.
• 프로그래밍 방식으로 Teleport API 작업에 대한 자세한 내용은 client pkg.go 참조 문서를 검토하세요.
• API를 최대한 활용하려면 관리 매뉴얼을 숙지하세요.