이 가이드는 Bound Keypair 클라이언트를 관리하는 사용자가 봇 또는 에이전트의 수명 주기 동안 수행해야 할 수 있는 다양한 작업을 설명합니다.

추가 복구 시도 허용#

standard 복구 모드를 사용하는 경우, 설정된 횟수의 복구 시도만 가능합니다. 한도에 도달하면 한도가 증가될 때까지 더 이상 복구 시도를 할 수 없습니다.

이 한도를 늘리고 만료된 클라이언트가 다시 참여할 수 있도록 하려면 tctl edit를 사용하여 토큰을 편집하세요:

$ tctl edit token/example-token

spec.bound_keypair.recovery.limit 필드를 찾아 원하는 만큼 한도를 증가시키세요. 원하는 임계값을 자유롭게 선택할 수 있습니다. 예를 들어 다음 사용 사례를 고려하세요:

• 각 참여 시도마다 인간의 개입이 필요한 경우 이 값을 1씩 증가시킬 수 있습니다. 이 단일 복구 시도는 즉시 소비되므로 향후 복구에는 다시 인간의 개입이 필요하며, 다운타임이 발생할 수 있습니다.

  이 방법은 다운타임이 발생할 가능성이 있지만, 각 복구 시 인간이 클라이언트의 상태를 확인하도록 보장합니다.

• 각 복구마다 인간의 개입을 원하지만 다운타임을 피하고 싶다면 이 값을 2씩 증가시킬 수 있습니다. 첫 번째 시도는 즉시 소비되지만, 클라이언트는 향후 자동 사용을 위한 하나의 복구 시도를 보유하게 됩니다.

  인간 사용자가 정기적으로 복구 횟수와 클라이언트를 감사하여 복구 시도가 항상 가능하고 호스트가 예상대로 작동하는지 확인할 수 있습니다.

• 더 큰 값은 인간 개입 사이의 시간을 늘립니다. 자동 클라이언트 복구에 대한 허용 범위를 원하는 대로 선택할 수 있습니다.

또한 무제한 자동 복구 시도를 허용하고 싶다면 relaxed 복구 모드에 대한 아래 항목을 참조하세요.

복구 한도는 항상 복구 카운터(status.bound_keypair.recovery_count 필드)에 상대적입니다. 한도를 줄이거나 0으로 설정하는 것은 유효하지만, 그렇게 하면 한도가 다시 증가될 때까지 향후 복구 시도가 방지될 수 있습니다.

또한 참여 상태 검증이 여전히 필요하며, 동일한 키 쌍과 토큰의 동시 사용을 방지한다는 점을 참고하세요. 즉, 복구 한도를 늘리더라도 여러 클라이언트가 참여할 수는 없습니다.

무제한 복구 시도 허용#

무제한 복구 시도를 허용하려면 spec.bound_keypair.recovery.mode 필드를 relaxed로 설정해야 합니다. 이를 위해 tctl edit를 사용하여 토큰을 편집하세요:

$ tctl edit token/example-token

spec.bound_keypair.recovery.mode 필드를 찾거나 생성하고 값을 relaxed로 설정하세요. 파일을 저장하고 편집기를 종료하여 토큰을 업데이트하세요.

복구 모드가 relaxed로 설정되면 limit 필드는 무시되고 status.bound_keypair.recovery_count 필드는 설정된 한도를 초과하여 증가할 수 있습니다. 나중에 모드를 다시 standard로 변경하는 경우, recovery_count의 현재 값을 수용하도록 limit를 늘리지 않으면 향후 복구 시도가 실패한다는 점에 유의하세요.

relaxed 모드를 사용하는 경우에도 참여 상태 검증이 여전히 필요하며 동일한 키 쌍과 토큰의 동시 사용이 방지됩니다. 사용 사례에 이것이 필요한 경우 참여 상태 검증 비활성화를 할 수 있지만, 그렇게 하면 토큰의 보안에 영향을 미칩니다.

키 쌍 교체 요청#

키 쌍 교체를 요청하려면 .spec.bound_keypair.rotate_after 필드에 타임스탬프를 설정하세요. 해당 타임스탬프가 경과한 후 다음 인증 시도에서 봇이 자동으로 키 쌍을 교체합니다.

이 프로세스를 간소화하기 위해 tctl bound-keypair rotate 도우미를 사용할 수 있습니다:

$ tctl bound-keypair rotate token-name

이 명령은 타임스탬프를 현재 시간으로 설정합니다. 봇은 기본적으로 20분마다만 재인증하므로 요청이 처리되기까지 다소 시간이 걸릴 수 있습니다. 토큰의 .status.bound_keypair.last_rotated_at 필드를 확인하여 교체 상태를 모니터링할 수 있습니다.

조기 교체를 강제하고 싶고 봇 호스트에 접근할 수 있다면 tbot 프로세스를 다시 시작하거나 pkill -usr1 tbot으로 신호를 보내 조기 교체를 요청할 수 있습니다.

이전 10개의 키 쌍은 클러스터 롤백 시 사용을 위해 클라이언트에 보존됩니다; 추가 정보는 클러스터 롤백 섹션을 참조하세요.

bound_keypair 클라이언트 잠금#

bound_keypair 참여 방법을 사용하여 참여한 클라이언트(봇 또는 에이전트)를 잠그는 가장 간단한 방법은 참여 토큰 잠금 대상을 사용하는 것입니다:

$ tctl lock --join-token=token-name

bound keypair 토큰은 단일 클라이언트와 연결되어 있으므로, 이는 클라이언트를 효과적으로 잠그게 됩니다. 잠금이 제거될 때까지 재인증, 복구, Teleport API 상호작용 또는 자격 증명 사용이 불가능합니다.

봇 전용 잠금 참고 사항#

봇이 충분히 오랫동안 잠겨 있으면 - 봇은 기본적으로 1시간의 인증서 TTL을 가집니다 - 인증서가 만료됩니다. 이 잠금을 제거하고 봇을 복원하려는 경우, 추가 복구 시도를 수용하기 위해 복구 한도(.spec.bound_keypair.recovery.limit)를 늘려야 할 수도 있습니다.

다른 잠금 대상도 사용할 수 있지만 권장되지는 않습니다:

• 봇 인스턴스 (tctl lock --bot-instance-id ...): 봇의 단일 인스턴스만 잠급니다. 복구 한도가 허용하는 경우 자동 복구 프로세스가 재참여를 시도하고, 성공하면 새로운 봇 인스턴스 ID를 생성한다는 점에 유의하세요.
• 봇 이름 (tctl lock --user bot-<name>): 동일한 봇/사용자를 사용하는 모든 봇을 잠급니다. 이는 지나치게 광범위할 수 있으며 이 봇 사용자 하에 실행 중인 다른 인스턴스도 잠글 수 있습니다.

고유 ID로 에이전트 잠금#

봇과 마찬가지로 에이전트는 고유 ID를 가집니다. 다음 명령을 실행하여 고유 ID를 확인하세요:

$ tctl inventory ls

목록에서 원하는 호스트를 찾아 "Server ID" 열에서 ID를 복사하세요. 그런 다음 해당 ID에 대한 잠금을 생성하세요:

$ tctl lock --server-id=1234abcd-1234-5678-abcd-1234abcd5678

잠긴 bound_keypair 클라이언트 복구#

bound_keypair 참여 방법으로 참여한 봇 또는 에이전트는 다음을 포함한 다양한 조건에서 자동으로 잠길 수 있습니다:

• 참여 상태 검증을 올바르게 완료하지 못한 경우
• 유효하지 않은 세대 카운터가 있는 인증서로 연결하는 경우 (봇에만 해당)
• 클러스터 관리자에 의해 수동으로 잠긴 경우

잠긴 클라이언트를 복구하려면 먼저 클라이언트의 내부 스토리지가 손상되지 않았는지 확인하세요. 봇의 경우 storage 디렉터리(일반적으로 /var/lib/teleport/bot), 에이전트의 경우 데이터 디렉터리(/var/lib/teleport)를 확인하세요. 이러한 잠금 조건은 동일한 인증서와 개인 키 복사본을 사용하여 두 명 이상의 클라이언트가 참여하려고 시도하는 경우 트리거되도록 설계되어 있습니다. 이는 잘못된 구성이나 공격자가 봇의 자격 증명을 복사하여 발생할 수 있으므로, 이상적으로는 봇 잠금을 해제하기 전에 후자를 배제해야 합니다.

다음으로, 클라이언트를 대상으로 하는 잠금의 이름(UUID)을 확인하세요:

$ tctl get lock
kind: lock
metadata:
  name: 372af058-76d1-4e64-93da-3b04d7d03ac2
spec:
  target:
    user: bot-example
version: v2
---
kind: lock
metadata:
  name: 791d0b1d-01b4-4752-8a99-9b2908aebfae
spec:
  target:
    bot_instance_id: e7d494ae-a0ff-4d12-b935-de5e2025f667
version: v2
---
kind: lock
metadata:
  name: a69fdbb2-8e53-406a-b453-48b2cda6991d
spec:
  target:
    join_token: example-token-name
version: v2
---
kind: lock
metadata:
  name: 7a892628-97a6-4038-be36-d4739bf78109
spec:
  target:
    server_id: 3d8b0237-f2e0-4add-aec1-7f293278b35e
version: v2

위에 표시된 다양한 잠금 및 잠금 대상에 유의하세요. 봇은 다음 잠금 유형 중 하나로 대상이 될 수 있습니다:

• Teleport 사용자 이름 (bot-example)
• 봇 인스턴스 ID (UUID)
• 참여 토큰 이름

에이전트의 경우 다른 잠금 집합이 생성될 수 있습니다:

• 참여 토큰 이름
• 서버 ID (수동으로만)

Bound Keypair Joining을 사용하는 클라이언트에 대해 자동으로 생성된 잠금은 일반적으로 join_token 대상을 사용하지만, 이러한 값 중 하나를 대상으로 하는 잠금이 수동으로 생성될 수도 있습니다.

잠금에는 잠금이 생성된 이유에 대한 세부 정보가 포함된 메시지 필드가 있을 수 있습니다.

잠금 이름을 확인한 후 tctl rm을 사용하여 각 잠금을 제거하세요:

$ tctl rm lock/372af058-76d1-4e64-93da-3b04d7d03ac2

다음으로 참여 상태를 재설정해야 합니다. tctl edit를 사용하여 토큰의 복구 모드를 insecure로 설정하되, 현재 값(standard 또는 relaxed)을 메모해 두세요:

$ tctl edit token/example-token

.spec.bound_keypair.recovery.mode 필드를 insecure로 변경하고, 저장한 후 편집기를 종료하세요.

이제 클라이언트가 다시 참여할 수 있습니다. 충분한 시간이 주어지면 자체적으로 재시도하지만, 호스트에 접근할 수 있다면 다음 명령으로 재시작할 수 있습니다:

• 봇의 경우: systemctl restart tbot
• 에이전트의 경우: systemctl restart teleport

이제 클라이언트가 성공적으로 참여할 수 있어야 합니다. Teleport 웹 UI에서 새 감사 이벤트를 확인하거나 복구 카운터가 증가할 때까지 기다려서 진행 상황을 모니터링할 수 있습니다:

$ tctl get token/example-token --format=json | jq '.[].status.bound_keypair.recovery_count'

클라이언트가 성공적으로 참여한 후 tctl edit를 사용하여 복구 모드를 이전 값으로 재설정하세요:

$ tctl edit token/example-token

클라이언트의 자격 증명이 손상되었을 가능성이 있다면, 키 쌍 교체 요청도 하고 싶을 수 있으며, 호스트가 적절히 보안되어 있는지 확인하기 위한 다른 조치도 취해야 합니다.

참여 상태 검증 비활성화#

의도적으로 참여 상태 검증을 비활성화하는 것이 유용한 경우가 있습니다. 예를 들어 다음과 함께 사용할 수 있습니다:

• 명시적인 위임 참여 방법 없이 CI/CD 공급자.
• 각 참여 후 업데이트된 참여 상태 문서를 저장할 수 없는 불변 스토리지를 가진 노드.

계속하기 전에, 참여 상태 검증을 비활성화하면 Teleport가 동일한 bound keypair 토큰을 사용하여 여러 클라이언트가 참여하는지 감지할 수 없게 된다는 점에 유의하세요. 즉, 공격자가 개인 키를 복사하면 무기한으로 참여할 수 있습니다. 키 쌍을 보호하고, 봇의 경우 Teleport의 RBAC 시스템을 사용하여 봇 ID에서의 접근을 제한하는 것이 중요합니다.

준비가 되면 tctl edit를 사용하여 Bound Keypair 토큰을 수정하세요:

$ tctl edit token/example-token

spec.bound_keypair.recovery.mode 필드를 찾거나 추가하고 insecure로 설정하세요. 저장하고 편집기를 종료하여 토큰을 업데이트하세요.

모드를 insecure로 설정하면 recovery.limit가 무시되어 토큰의 무제한 재사용이 허용되고, 참여 상태 검증이 비활성화되어 동시 또는 무상태 재사용이 허용됩니다.

클러스터 롤백 후 복구#

어떤 이유로든 Teleport 클러스터가 롤백되면, 참여 클라이언트가 참여 상태 검증에 실패할 수 있습니다. 로컬 참여 상태 문서가 Teleport에 현재(또는 이전에) 알려진 값과 일치하지 않을 수 있기 때문입니다.

가장 간단한 해결 방법은 클러스터 복원 후 첫 번째 참여 시도를 위해 모든 bound keypair 토큰을 일시적으로 insecure 복구 모드로 설정하는 것입니다. 한 번 참여하면 다시 유효한 참여 상태를 갖게 되므로 복구 모드를 이전 값으로 복원할 수 있습니다.

복구 모드를 변경하려면 tctl edit를 사용하여 토큰 리소스를 수정하세요:

$ tctl edit token/example-token

spec.bound_keypair.recovery.mode 필드를 찾아 값을 "insecure"로 설정하세요. 각 bound keypair 토큰에 대해 이 과정을 반복하세요. 모든 bound keypair 클라이언트가 재인증할 때까지 기다린 후 이 과정을 반복하여 복구 모드를 이전 값으로 복원하세요.

Teleport 클러스터의 스냅샷과 복원 사이에 키 쌍이 교체된 경우, 클라이언트는 이전 10개의 키 쌍만 기록을 유지합니다. 이는 복원된 Teleport 클러스터가 예상하는 키 쌍이 클라이언트 측 기록에서 교체되었거나, 클라이언트 측 기록이 손실되거나 삭제된 경우 서버 측 복구가 불가능할 수 있음을 의미합니다.

정적 키 수동 교체#

정적 키는 클라이언트가 임의의(잠재적으로 원격) 키 저장소에서 키를 업데이트할 수 없기 때문에 자동 키 교체를 방지합니다. 그러나 환경이나 비밀 저장소가 API를 통해 비밀을 업데이트할 수 있다면 교체를 자동화하는 것이 여전히 가능할 수 있습니다.

이를 자동화하는 데 필요한 구체적인 단계는 환경에 따라 다르지만 일반적인 단계는 다음과 같습니다:

1. tbot 클라이언트를 사용하여 임의의 노드에서 새 키 쌍을 생성하세요:

   $ tbot keypair create --proxy-server example.teleport.sh:443 --static --format json
   

2. jq 또는 다른 JSON 파서와 같은 원하는 도구를 사용하여 .public_key 및 .private_key 값을 파싱하세요.

3. .public_key 필드의 값을 사용하여 새 공개 키를 신뢰하도록 Teleport의 토큰을 교체하세요:

   $ cat my-token.yaml
   version: v2
   kind: token
   metadata:
     name: my-token
   spec:
     bot_name: example-bot
     bound_keypair:
       onboarding:
         initial_public_key: <insert .public_key value here>
       recovery:
         mode: insecure
     join_method: bound_keypair
     roles:
     - Bot
   $ tctl create -f my-token.yaml
   

4. 새 개인 키를 키 저장소에 삽입하세요. 이는 사용 중인 키 저장소 또는 공급자에 따라 다릅니다.

   • 환경 변수를 통해 개인 키를 전달하는 경우, 값을 직접 복사하세요.
   • 파일을 통해 개인 키를 전달하는 경우, 먼저 base64로 인코딩된 개인 키를 디코딩하세요:

     $ tbot keypair create --proxy-server example.teleport.sh:443 --static --format json | jq -r .private_key | base64 -d
     

     ...그리고 결과를 필요에 따라 저장하세요.

5. 향후 작업은 이제 새 키 쌍을 사용해야 합니다.

정적 키를 자주 교체하면 insecure 복구의 보안 트레이드오프를 완화하는 데 도움이 됩니다. 정적 키에 대한 자세한 정보는 개념 페이지를 참조하세요.

Teleport 에이전트를 위한 Bound Keypair 참여의 제한 사항#

Teleport v18.8부터 bound_keypair 참여 방법은 머신 및 워크로드 아이덴티티 봇뿐만 아니라 표준 에이전트 유형도 지원합니다.

에이전트에 대한 Bound Keypair 참여의 이점은 더 제한적이므로 대부분의 사용자는 여전히 전통적인 token 참여 방법을 선호할 것입니다:

• 에이전트는 궁극적으로 여전히 장기 인증서를 발급받으며 제한된 상황, 즉 클러스터 CA 교체 또는 기존 에이전트에 새 시스템 역할이 추가되는 경우에만 이러한 아이덴티티를 갱신합니다.
• 대부분의 에이전트는 단 한 번만 참여하므로 Bound Keypair의 참여 상태 검증은 사실상 사용되지 않습니다.
• 키 쌍 교체는 참여 시에만 이루어질 수 있으므로, 에이전트는 역할 변경과 같은 특정 조건에서만 키 쌍 교체 요청을 처리합니다.
• 에이전트 아이덴티티는 다른 Teleport 리소스에 대한 접근 권한이 없으므로, Bound Keypair 참여가 제공하는 추가 보호 기능을 활용하거나 혜택을 받지 못합니다.
• Bound Keypair 참여 방법은 token 참여보다 더 복잡하며 잠재적인 새로운 실패 모드를 도입합니다.
• 에이전트는 등록 비밀(Bound Keypair의 기본 모드) 또는 정적 키 파일을 통해서만 참여할 수 있습니다. 비정적 사전 등록 키는 현재 지원되지 않습니다.

그럼에도 불구하고 특정 상황에서는 에이전트에 Bound Keypair를 고려할 수 있습니다:

• 엄격하게 단일 사용인 표준 token 유형 토큰의 대안을 원하는 경우.

  Bound Keypair 토큰(및 등록 비밀)은 단일 호스트(봇 또는 에이전트)와 엄격하게 쌍으로 연결되므로, 사용자에게 bound keypair 토큰과 등록 비밀을 제공하면 단일 노드만 참여할 수 있습니다.

• 참여 프로세스에 공유 비밀이 없기를 원하는 경우. Bound Keypair의 정적 키를 사용하면 대상 노드 자체에서 키 쌍을 생성할 수 있습니다. 공개 키만 시스템 외부로 나가며 비밀이나 개인 키 자료는 절대로 호스트를 떠날 필요가 없습니다.

Bound Keypair 참여를 사용하여 에이전트를 참여시키려면 다음 가이드를 참조하세요:

• Bound Keypair를 사용한 에이전트 참여
• Bound Keypair 정적 키를 사용한 에이전트 참여