이 가이드는 하드웨어 기반 개인 키를 사용하여 Teleport 인증을 구성하는 방법을 설명합니다.

작동 방식#

경고 - Enterprise: 하드웨어 키 지원에는 Teleport Enterprise가 필요합니다.

기본적으로 tsh, Teleport Connect 및 기타 Teleport 클라이언트는 사용자의 키와 인증서를 파일 시스템에 직접 저장합니다. 사용자의 파일 시스템이 침해되면 활성 상태인 Teleport 사용자 키와 인증서도 침해됩니다.

SSH 서비스, Kubernetes 서비스, 데이터베이스 서비스 등의 Teleport 서비스로 새 세션을 시작할 때 다중 인증 확인을 요구하도록 세션별 MFA를 구성할 수 있습니다. 그러나 세션별 MFA는 침해된 세션 자격 증명이 tctl로 관리 명령을 실행하는 것과 같은 다른 작업을 수행하는 것을 방지하지 않습니다.

이러한 유형의 공격을 방지하기 위해 Teleport는 하드웨어 기반 개인 키를 지원합니다. 디스크 기반 개인 키와 달리 하드웨어 기반 개인 키는 하드웨어 장치에서 직접 생성되고 저장되며 내보낼 수 없습니다. 하드웨어 기반 개인 키를 사용하면 키가 생성되고 저장된 하드웨어 장치에도 접근할 수 있는 경우에만 로그인 세션이 작동합니다.

또한 tctl edit와 같은 비세션 요청을 포함한 모든 Teleport 요청에 대해 터치를 요구하도록 이 기능을 구성할 수 있습니다. 터치가 요구되면 하드웨어 키 지원은 세션별 MFA보다 더 나은 보안을 제공합니다.

참고 - 터치 캐싱: 과도한 터치 프롬프트를 방지하기 위해 하드웨어 보안 키에 사용자의 터치가 15초 동안 캐시됩니다.

경고 - 호환성: 하드웨어 키 지원은 최고 수준의 보안을 제공합니다. 그러나 모든 서비스가 하드웨어 키와 호환되는 것은 아닙니다.

지원됨:

• Teleport 클라이언트 tsh, tctl 및 Teleport Connect.
• tsh ls, tctl create 등의 표준 Teleport API 요청.
• 서버 접근.
• 에이전트 없는 OpenSSH 서버 접근.
• tsh db connect 대신 tsh proxy db를 사용하는 데이터베이스 접근.
• tsh kube login 대신 tsh proxy kube를 사용하는 Kubernetes 접근.
• 웹 접근 (Teleport 웹 UI).
• 애플리케이션 접근.

지원되지 않음:

• 데스크톱 접근.
• 레거시 OpenSSH 서버 접근

인프라에 접근하기 위해 하드웨어 키가 필요한 경우 하드웨어 키에 접근할 수 없거나 프로토콜이 원시 개인 키만 지원하기 때문에 지원되지 않는 기능도 사용할 수 없습니다.

이러한 비호환성을 해결하려면 중요한 인프라에 접근하는 역할과 같이 필요한 경우에만 하드웨어 키 지원을 활성화하는 것이 좋습니다. 이러한 역할은 사용자가 일반 로그인 세션에서 이러한 문제를 피할 수 있도록 접근 요청으로 필요에 따라 접근할 수 있습니다.

참고: 웹 및 앱 세션은 하드웨어 키에 의해 직접 지원되지 않지만 Auth 서비스와 프록시 서비스에 의해 엄격하게 보호됩니다. 따라서 웹 및 앱 세션은 하드웨어 키 지원을 우회하고 세션별 MFA와 같이 사용자 존재나 확인이 필요할 때 MFA 프롬프트로 대체할 권한을 받습니다.

사전 요구 사항#

• A running Teleport Enterprise 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:

• 시리즈 5+ YubiKey

참고 - PIV 지원: 하드웨어 키 지원을 사용하려면 PIV 호환 하드웨어 키를 사용해야 합니다. 현재 이 기능은 YubiKey 시리즈 5+만 지원 보장됩니다.

• 운영 체제용 스마트 카드 드라이버 설치. Teleport 클라이언트는 스마트 카드 드라이버를 통해 YubiKey에 연결하여 키를 생성하고 암호화 작업을 수행합니다.
  • macOS와 Windows 모두 스마트 카드 드라이버가 포함되어 있습니다.
    • Windows에서 문제가 발생하면 공식 YubiKey Smart Card Minidriver를 사용해 보세요.
  • Linux 배포판에서는 시스템 스마트 카드 서비스(pcsc-lite 패키지에서 제공하는 pcscd)가 설치되어 있고 최신 상태인지 확인합니다.
    • 최대 호환성을 위해 pcsc-lite 버전 2.4.1 이상을 권장합니다. 2.4.1 이상을 사용할 수 없는 경우 일부 배포판 제공 버전이 하드웨어 키 호환성 문제를 일으킬 수 있으므로 최소 버전 1.8.24 이상이 설치되어 있는지 확인합니다.

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/2단계. 하드웨어 키 지원 적용#

하드웨어 키 지원은 기본적으로 필요하지 않습니다.

하드웨어 키 지원에는 세 가지 주요 옵션이 있습니다:

• hardware_key: 사용자 키는 터치/PIN 보호 없이 하드웨어 키에 저장됩니다. 세션 및 모더레이트 세션과 같은 MFA 의존 기능에는 별도의 MFA 확인이 사용됩니다.
• hardware_key_touch: 사용자 키는 터치 보호와 함께 하드웨어 키에 저장됩니다. 각 요청에서 사용자는 하드웨어 키를 터치해야 합니다.
• hardware_key_touch_and_pin: 사용자 키는 터치 및 PIN 보호와 함께 하드웨어 키에 저장됩니다. 각 요청에서 사용자는 하드웨어 키를 터치하고 PIV PIN을 입력해야 합니다.
  • PIV 코드를 설정하지 않은 사용자는 로그인 중에 설정하라는 메시지가 표시됩니다.

다음과 같이 특정 역할에 대해 하드웨어 키 지원을 적용할 수 있습니다:

kind: role
metadata:
  name: admin
spec:
  options:
    require_session_mfa: hardware_key_touch

Teleport 구성을 업데이트하여 클러스터 전체에서 하드웨어 키 지원을 적용할 수도 있습니다:

$ tctl edit cap

spec.require_session_mfa 값을 hardware_key_touch로 설정합니다:

kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  require_session_mfa: hardware_key_touch
  ...
version: v2

편집기를 저장하고 종료하면 tctl이 리소스를 업데이트합니다:

cluster auth preference has been updated

2/2단계. 로그인#

역할이나 클러스터에서 하드웨어 키를 요구하도록 구성한 후 해당 역할을 가지거나 해당 클러스터에 로그인하는 모든 사용자는 모든 Teleport 요청에 하드웨어 키를 사용해야 합니다.

영향을 받는 사용자는 로그인 시 YubiKey를 연결하고 터치하라는 메시지가 표시됩니다. 사용자가 처음 하드웨어 키로 로그인할 때 즉시 다시 로그인해야 할 수 있습니다.

$ tsh login --user=dev --proxy=example.teleport.sh:443
# Enter password for Teleport user dev:
# Unmet private key policy "hardware_key_touch".
# Relogging in with hardware-backed private key.
# Enter password for Teleport user dev:
# Tap your YubiKey
# > Profile URL:        https://example.teleport.sh
#   Logged in as:       dev
#   Cluster:            example.teleport.sh
#   ...

하드웨어 키로 지원되지 않는 기존 세션을 가진 영향을 받는 사용자는 다음 요청 시 다시 로그인하라는 메시지가 표시됩니다. 예:

$ tsh clusters
# Unmet private key policy "hardware_key_touch"
# Relogging in with hardware-backed private key.
# Enter password for Teleport user dev:
# Tap your YubiKey
# Cluster Name        Status Cluster Type Labels Selected
# ------------------- ------ ------------ ------ --------
# example.teleport.sh online root                *

커스텀 PIV 설정#

커스텀 PIV 슬롯#

기본적으로 Teleport 클라이언트는 각 옵션에 다음 PIV 슬롯을 사용합니다:

• hardware_key: 슬롯 9a
• hardware_key_touch: 슬롯 9c
• hardware_key_touch_and_pin: 슬롯 9d
• hardware_key_pin: 슬롯 9e

다른 PIV 애플리케이션을 사용 중인 경우 다른 슬롯을 지정해야 할 수 있습니다. 예를 들어 yubikey-agent는 슬롯 9a를 사용합니다. yubikey-agent 키와 인증서를 덮어쓰지 않으려면 hardware_key 요구 사항이 있는 사용자는 다른 슬롯을 지정해야 합니다.

로그인 시 사용자는 --piv-slot 명령줄 옵션이나 환경 변수를 사용하여 PIV 슬롯을 지정할 수 있습니다. 예:

• tsh login --piv-slot=9c
• TELEPORT_PIV_SLOT=9c tsh login

구성 옵션으로 클러스터 전체에서 PIV 슬롯을 설정할 수도 있습니다:

kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  require_session_mfa: hardware_key
  hardware_key:
    piv_slot: 9c
  ...
version: v2

커스텀 키#

Teleport 클라이언트는 기본 관리 키를 사용하여 지정된 슬롯에 키를 생성합니다.

PIV 키가 다른 관리 키를 사용하는 경우 직접 키를 생성해야 합니다. 이는 YubiKey Manager CLI로 수행할 수 있습니다. 이 명령은 요청을 완료하기 위해 관리 키를 입력하라는 메시지를 표시합니다:

$ ykman piv keys generate -a ECCP256 [slot] --touch-policy=[never|cached|always] --pin-policy=[never|once|always] pub.pem

일부 기능이 작동하려면 슬롯에 인증서도 생성하여 Teleport에서 사용하도록 슬롯을 표시해야 합니다. 이 인증서는 자체 서명될 수 있으며, 아래 예에서는 PIV 슬롯의 키로 서명됩니다. 중요한 세부 사항은 인증서의 주체 필드에 조직 이름으로 "teleport"가 포함되어야 한다는 것입니다.

$ ykman piv certificates generate [slot] -s O=teleport pub.pem

이 명령은 관리 키와 PIV 슬롯 키의 정책에 따라 PIN이나 터치를 요청합니다.

키의 터치 및 PIN 정책이 클러스터 및 역할의 하드웨어 키 요구 사항을 충족하는지 확인하세요.

하드웨어 키 에이전트 - Teleport Connect#

Teleport Connect는 하드웨어 키 에이전트로 작동하여 Teleport 클라이언트를 대신하여 하드웨어 키 요청을 처리할 수 있습니다.

Connect가 실행 중이면 tsh 및 tctl 명령에 대한 터치 및 PIN 프롬프트가 Teleport Connect에 표시됩니다. 이러한 프롬프트는 사용자의 주의를 끌기 위해 전면으로 가져옵니다.

PIN 캐싱#

require_session_mfa: hardware_key_touch_and_pin으로 하드웨어 키 PIN이 적용된 사용자는 각 연결에 대해 PIN을 입력해야 합니다. 기본적으로 이 PIN은 하드웨어 키에 의해 내부적으로 몇 초 동안 캐시되며, 이 메커니즘은 여러 일반적인 사용 사례에는 신뢰할 수 없거나 충분히 오래 지속되지 않습니다:

• Teleport 로컬 프록시를 통한 kubectl 명령, 데이터베이스 쿼리 또는 앱 요청 프록시 (tsh proxy kube|db|app)
• tsh 명령을 일괄 실행하는 자동화 스크립트
• VNet으로 TCP 애플리케이션에 연결
• 일반 Teleport Connect 사용

대신 클러스터 전체 hardware_key.pin_cache_ttl 구성 옵션을 설정하여 Teleport 클라이언트가 설정된 시간 동안 사용자의 PIN을 캐시할 수 있도록 합니다.

$ tctl edit cap

spec.hardware_key.pin_cache_ttl 값을 원하는 PIN 캐시 TTL 기간으로 설정합니다:

kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  hardware_key:
    # pin_cache_ttl은 Teleport 클라이언트가 사용자의 PIV PIN을 캐시하는 기간을 결정합니다.
    # 이 값은 1시간을 초과할 수 없습니다. 0으로 설정하면(기본값) PIN 캐싱이 비활성화됩니다.
    pin_cache_ttl: 1m
  ...
version: v2

편집기를 저장하고 종료하면 tctl이 리소스를 업데이트합니다:

cluster auth preference has been updated

참고 - 하드웨어 키 에이전트: 하드웨어 키 에이전트는 hardware_key.pin_cache_ttl이 설정된 경우 PIN 캐싱을 활용합니다. 즉, Teleport Connect가 실행 중인 상태에서 사용자는 여러 개의 별도 tsh 명령에 걸쳐 PIN을 캐시할 수 있습니다.

문제 해결#

ERROR: private key policy not met#

이 오류는 사용자가 필요한 개인 키 정책을 충족하지 못하는 경우 Auth 서비스와 프록시 서비스에서 반환됩니다. tsh와 Teleport Connect 모두 이러한 오류를 자동으로 감지하고 사용자에게 유효한 하드웨어 기반 개인 키로 다시 로그인하도록 요구합니다.

ERROR: authenticating with management key: auth challenge: smart card error 6982: security status not satisfied#

스마트 카드 인증 챌린지 오류는 잘못된 관리 키가 사용될 때 나타날 수 있습니다.

Teleport 클라이언트는 기본 관리 키로 새 PIV 키를 예상합니다. YubiKey Manager CLI ykman piv reset을 사용하여 기존 PIV 키 및 인증서와 함께 이 키를 재설정할 수 있습니다.

다른 관리 키를 사용하려면 커스텀 PIV 설정 지침을 따르세요.

ERROR: ssh: handshake failed: command failed: transmitting request: an attempt was made to end a non-existent transaction#

때때로 YubiKey와의 PIV 상호작용이 예상치 못한 방식으로 실패할 수 있습니다.

예를 들어 MFA를 위해 YubiKey를 탭한 다음 하드웨어 키 지원을 위해 YubiKey를 탭하면 드물게 오류가 발생할 수 있습니다.

로그인하기 위해 여러 번 탭해야 하는 이유는?#

설정에 따라 YubiKey를 여러 번 탭해야 할 수 있습니다. 각 탭은 안전한 인증을 위해 필요합니다.

예를 들어 cluster_auth_preference에 second_factors: ["webauthn"]가 설정되어 있고 역할에 require_session_mfa: hardware_key_touch가 설정된 경우 처음 로그인 시 다음 출력이 표시됩니다:

$ tsh login --user=dev --proxy=root.example.com:3080

# 인증되지 않은 클라이언트가 "hardware_key_touch"가 사용자 역할에 필요함을
# 추론할 방법이 없으므로 먼저 일반적으로 로그인합니다.

Enter password for Teleport user dev:
Tap any security key
Detected security key tap

# 로그인 결과가 "hardware_key_touch" 오류입니다.

Unmet private key policy "hardware_key_touch".

# 이 시점에서 `tsh`는 오류에서 사용자 역할이 "hardware_key_touch"를 요구한다는 것을
# 추론할 수 있으므로 탭으로 하드웨어 키에 직접 개인 키를 생성하고 로그인 프로세스를 다시 시작합니다.

Relogging in with hardware-backed private key.

# 이번에는 `tsh`가 로그인 요청에서 YubiKey 지원 개인 키를 사용하여
# 사용자 역할의 개인 키 정책을 통과하는 인증서를 얻습니다.

Enter password for Teleport user dev:
Tap any security key
Detected security key tap
Tap your YubiKey
> Profile URL:        https://root.example.com:3080
  Logged in as:       dev
  Cluster:            root.example.com
  ...