이 가이드에서는 인프라를 코드로(IaC)를 통해 사용자를 생성하고 역할을 부여하는 방법을 설명합니다. Teleport는 코드에서 동적으로 리소스를 생성하는 세 가지 방법을 지원합니다:

• Kubernetes에서 Teleport 리소스를 관리할 수 있는 Teleport Kubernetes Operator
• Terraform을 통해 Teleport 리소스를 관리할 수 있는 Teleport Terraform Provider
• 로컬 컴퓨터 또는 CI 환경에서 Teleport 리소스를 관리할 수 있는 tctl CLI

작동 방식#

Teleport에서 사용자와 역할은 Teleport Auth Service에서 관리하는 백엔드 리소스입니다. Teleport Auth Service는 사용자 및 역할을 포함한 백엔드 리소스를 생성, 삭제 또는 수정할 수 있는 gRPC API를 노출합니다. Teleport Kubernetes Operator와 Terraform 공급자, 그리고 tctl 명령줄 도구는 Teleport Auth Service에 인증하고 gRPC API와 상호작용하여 Teleport 사용자와 역할을 관리할 수 있습니다.

사전 요구사항#

이 가이드를 따르려면 다음이 필요합니다:

tctl의 경우:

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

Kubernetes Operator의 경우:

다음 중 하나를 따라 실행 중인 운영자가 있어야 합니다:

• teleport-cluster Helm 차트에서 운영자 활성화 가이드.
• 독립형 운영자 설정 가이드.

또한 운영자를 배포한 네임스페이스를 설정해야 합니다. 이 네임스페이스는 CustomResource를 배포할 네임스페이스입니다:

# for operators deployed with the `teleport-cluster` Helm chart
$ export OPERATOR_NAMESPACE="teleport-cluster"

# for standalone operators
$ export OPERATOR_NAMESPACE="teleport-iac"

Terraform의 경우:

Terraform 공급자 가이드를 따라 기능적인 Teleport Terraform 공급자를 설정합니다.

1단계/4단계: 매니페스트 작성#

이 단계에서는 Teleport에서 원하는 리소스를 설명하는 텍스트 파일을 작성합니다. 이러한 파일을 매니페스트(manifests)라고 하며, 사용할 IaC 도구에 따라 구문이 달라집니다.

이러한 매니페스트는 일반적으로 git과 같은 공유 버전 관리 시스템에 버전 관리됩니다. 이를 통해 모든 변경 사항을 추적하고, Teleport에서 리소스를 변경하기 전에 표준 코드 검토 절차를 따르며, 필요한 경우 Teleport 인스턴스를 빠르게 재배포할 수 있습니다.

역할 매니페스트 작성#

2개의 역할을 생성합니다:

• manager: 사용자 및 역할 목록 조회, 감사 이벤트 및 세션 내용 검토 허용.
• engineer: 개발 및 스테이징 서버에 대한 접근 허용.

tctl 사용:

다음 roles.yaml 파일을 생성합니다:

kind: role
version: v7
metadata:
  name: manager
spec:
  allow:
    rules:
      - resources: ['user', 'role']
        verbs: ['list','read']
      - resources: ['session', 'event']
        verbs: ['list', 'read']
---
kind: role
version: v7
metadata:
  name: engineer
spec:
  allow:
    logins: ['root', 'ubuntu', '{{internal.logins}}']
    node_labels:
      'env': ['test', 'staging']

Kubernetes Operator 사용:

다음 roles.yaml 파일을 생성합니다:

apiVersion: resources.teleport.dev/v1
kind: TeleportRoleV7
metadata:
  name: manager
spec:
  allow:
    rules:
      - resources: ['user', 'role']
        verbs: ['list','read']
      - resources: ['session', 'event']
        verbs: ['list', 'read']
---
apiVersion: resources.teleport.dev/v1
kind: TeleportRoleV7
metadata:
  name: engineer
spec:
  allow:
    logins: ['root', 'ubuntu', '{{internal.logins}}']
    node_labels:
      'env': ['test', 'staging']

참고: Kubernetes는 모든 사용자 정의 리소스 이름이 RFC 1123을 따르도록 유효성을 검사합니다. RFC 1123에는 호스트 이름에 대한 사양이 포함되어 있습니다. 이를 위해 운영자가 제어하는 Teleport 리소스의 metadata.name 필드는 소문자 영숫자, - 또는 .로 구성되어야 하며 영숫자 문자로 시작하고 끝나야 합니다.

Terraform 사용:

다음 roles.tf 파일을 생성합니다:

resource "teleport_role" "manager" {
  version = "v7"
  metadata = {
    name = "manager"
  }

  spec = {
    allow = {
      rules = [
        {
          resources = ["user", "role"]
          verbs     = ["list", "read"]
        },
        {
          resources = ["session", "event"]
          verbs     = ["list", "read"]
        }
      ]
    }
  }
}

resource "teleport_role" "engineer" {
  version = "v7"
  metadata = {
    name = "engineer"
  }

  spec = {
    allow = {
      logins = ["root", "ubuntu", "{{internal.logins}}"]
      node_labels = {
        env = ["test", "staging"]
      }
    }
  }
}

사용자 매니페스트 작성#

2명의 사용자를 생성합니다:

• Bob, engineer 역할을 가진 엔지니어.
• Alice, manager와 engineer 역할을 모두 가진 엔지니어링 매니저.

참고: 매니페스트에서 생성된 사용자는 외부 SAML/OIDC/GitHub 아이덴티티 공급자(IdP)에서 오는 사용자와 달리 로컬 사용자입니다.

자세한 내용은 사용자 유형 참조를 참조하세요.

tctl 사용:

다음 내용으로 users.yaml 파일을 생성합니다:

kind: user
version: v2
metadata:
  name: alice
spec:
  roles: ['manager', 'engineer']
---
kind: user
version: v2
metadata:
  name: bob
spec:
  roles: ['engineer']

Kubernetes Operator 사용:

다음 내용으로 users.yaml 파일을 생성합니다:

apiVersion: resources.teleport.dev/v2
kind: TeleportUser
metadata:
  name: alice
spec:
  roles: ['manager', 'engineer']
---
apiVersion: resources.teleport.dev/v2
kind: TeleportUser
metadata:
  name: bob
spec:
  roles: ['engineer']

참고: Kubernetes는 모든 사용자 정의 리소스 이름이 RFC 1123을 따르도록 유효성을 검사합니다. RFC 1123에는 호스트 이름에 대한 사양이 포함되어 있습니다. 이를 위해 운영자가 제어하는 Teleport 리소스의 metadata.name 필드는 소문자 영숫자, - 또는 .로 구성되어야 하며 영숫자 문자로 시작하고 끝나야 합니다.

Terraform 사용:

다음 내용으로 users.tf 파일을 생성합니다:

resource "teleport_user" "alice" {
  version = "v2"
  metadata = {
    name        = "alice"
  }

  spec = {
    # referencing to the teleport_role resource name instead of using plain
    # strings tells Terraform that the user depends on the role. Thanks to this,
    # Terraform will create the role first and won't let you remove the role
    # if it is still assigned to a user (which is illegal in Teleport).
    roles = [
      teleport_role.manager.metadata.name,
      teleport_role.engineer.metadata.name,
    ]
  }
}

resource "teleport_user" "bob" {
  version = "v2"
  metadata = {
    name        = "bob"
  }

  spec = {
    roles = [teleport_role.engineer.metadata.name]
  }
}

2단계/4단계: 모든 매니페스트 적용#

tctl 사용:

$ tctl create -f roles.yaml
role 'manager' has been created
role 'engineer' has been created

$ tctl create -f users.yaml
user "alice" has been created
user "bob" has been created

참고: 사용자 리소스는 역할에 의존하므로, 존재하지 않는 역할을 가진 사용자는 유효하지 않고 Teleport에서 거부될 수 있으므로 사용자 전에 역할을 생성해야 합니다.

Kubernetes Operator 사용:

$ kubectl apply -n "$OPERATOR_NAMESPACE" -f roles.yaml
teleportrolev7.resources.teleport.dev/manager created
teleportrolev7.resources.teleport.dev/engineer created

$ kubectl apply -n "$OPERATOR_NAMESPACE" -f users.yaml
teleportuser.resources.teleport.dev/alice created
teleportuser.resources.teleport.dev/bob created

생성된 Kubernetes 리소스를 나열합니다:

$ kubectl get teleportrolev7 -n "$OPERATOR_NAMESPACE"
# NAME       AGE
# engineer   10m
# manager    10m

$ kubectl get teleportusers -n "$OPERATOR_NAMESPACE"
# NAME     AGE
# alice    10m
# bob      10m

Terraform 사용:

$ terraform plan
[...]
Plan: 4 to add, 0 to change, 0 to destroy.

$ terraform apply
teleport_role.engineer: Creating...
teleport_role.manager: Creating...
teleport_role.engineer: Creation complete after 0s [id=engineer]
teleport_role.manager: Creation complete after 0s [id=manager]
teleport_user.bob: Creating...
teleport_user.alice: Creating...
teleport_user.bob: Creation complete after 0s [id=bob]
teleport_user.alice: Creation complete after 0s [id=alice]

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

3단계/4단계: 사용자가 생성되었는지 확인#

IaC 도구가 실행된 후, 사용자가 올바르게 생성되고 올바른 역할이 부여되었는지 확인합니다.

UI를 통해:

UI 접근 권한이 있는 경우 Teleport 클러스터 Web UI에 연결하여 "Users" 탭을 선택합니다.

두 명의 새 사용자 alice와 bob이 표시됩니다.

CLI를 통해:

$ tctl users ls
User                          Roles
----------------------------- -------------------------
@teleport-access-approval-bot @teleport-access-approver
alice                         manager,engineer
bob                           engineer
bot-operator                  bot-operator

# alternatively you can inspect the users details by doing
$ tctl get user/alice
kind: user
metadata:
  id: 1704849160091933780
  labels:
    teleport.dev/origin: kubernetes
  name: alice
spec:
  created_by:
    time: "2024-01-10T01:12:40.088581806Z"
    user:
      name: bot-operator
  expires: "0001-01-01T00:00:00Z"
  roles:
  - manager
  - engineer
  status:
    is_locked: false
    lock_expires: "0001-01-01T00:00:00Z"
    locked_time: "0001-01-01T00:00:00Z"
    recovery_attempt_lock_expires: "0001-01-01T00:00:00Z"
version: v2

4단계/4단계: 비밀번호 재설정 링크 생성#

이 시점에서 Teleport에 로컬 사용자가 생성되었습니다. 그러나 비밀번호나 추가 인증 요소를 지정하지 않았습니다. 사용자가 Teleport 등록을 완료하고 Teleport에 로그인할 수 있도록 비밀번호 재설정 링크를 발행해야 합니다.

사용자 재설정 링크에는 일회용 만료 토큰이 포함되어 있습니다. 이 때문에 다른 Teleport 리소스와 동일한 선언적 접근 방식을 따를 수 없으며 매니페스트를 통해 생성할 수 없습니다. 사용자 생성 후 한 번 이러한 토큰을 생성하고 최종 사용자에게 비밀번호/MFA를 등록하도록 안전하게 전송해야 합니다.

옵션 1: CLI를 통한 재설정#

tctl을 통해 사용자 비밀번호를 수동으로 재설정할 수 있습니다:

$ tctl users reset alice
User "alice" has been reset. Share this URL with the user to complete password reset, link is valid for 8h:
https://teleport.example.com:443/web/reset/05b420fdc784597cbbb1d2ba65697cd8

NOTE: Make sure teleport.example.com:443 points at a Teleport proxy which users can access.

옵션 2: 사용자 재설정 자동화#

재설정 링크를 사용자에게 안전하게 전송하는 방법이 있다면 조직의 특정 요구에 맞는 자동화를 구축할 수 있습니다. 예를 들어:

$ tctl users reset alice --format=json | \
    jq '"Sending an email to " + .spec.user +" that contains the link: " + .spec.url'

jq 명령을 안전한 채널로 실제로 링크를 전송하는 것으로 바꿔야 합니다. 이 채널은 조직에 따라 달라집니다. 보통 직접 메시지나 이메일입니다.

Terraform 사용자를 위한 팁:

local-exec 프로비저너를 사용하여 Terraform 리소스 생성 시 사용자 정의 스크립트를 트리거할 수 있습니다.

resource "teleport_user" "bob" {
  version = v2
  metadata = {
    name = "bob"
  }

  spec = {
    roles = [teleport_role.engineer.metadata.name]
  }

  # on user creation, trigger a reset flow and send the link via
  provisioner "local-exec" {
    command = "tctl users reset alice --format=json | jq '\"Sending an email to \" + .spec.user +\" that contains the link: \" + .spec.url'"
  }
}

다음 단계#

• manager 역할을 가진 사용자가 접근 목록(Access Lists)을 통해 engineer 중 일부에게 프로덕션 서버 접근 권한을 부여할 수 있도록 허용합니다. 매니저는 부여된 접근을 주기적으로 정당화하고 검토해야 합니다. 기능에 대한 개요는 접근 목록 문서를 참조하고, 단계별 IaC AccessList 설정은 접근 목록 IaC 가이드를 참조하세요.
• engineer 역할을 가진 사용자가 프로덕션에 대한 임시 접근을 요청하고 manager 역할을 가진 사용자가 요청을 검증할 수 있도록 허용합니다. 접근 요청 문서를 참조하세요.
• 사용자 리소스 및 역할 리소스의 참조에서 지원되는 모든 필드를 확인할 수 있습니다.