이 가이드는 신뢰할 수 있는 디바이스 등록, 디바이스 등록 토큰 만들기, 신뢰할 수 있는 디바이스 제거와 같은 Device Trust 관리 작업 수행 방법을 안내합니다.

전제 조건#

• 실행 중인 Teleport Enterprise 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

• tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

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

  2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 

• macOS 디바이스를 등록하려면 다음이 필요합니다:

  • 서명 및 공증된 tsh 바이너리. macOS tsh 설치 프로그램 다운로드.

• Windows 디바이스를 등록하려면 다음이 필요합니다:

  • TPM 2.0을 갖춘 디바이스.
  • 관리자 권한을 가진 사용자. 이는 등록 중에만 필요합니다.
  • tsh 클라이언트. Windows tsh 설치 프로그램 다운로드.

• Linux 디바이스를 등록하려면 다음이 필요합니다:

  • TPM 2.0을 갖춘 디바이스.

  • /dev/tpmrm0 디바이스를 사용할 권한을 가진 사용자(일반적으로 사용자에게 tss 그룹을 할당하여 처리).

  • tsh 클라이언트. Linux용 tsh 설치.

    WSL 사용자는 대신 Windows 바이너리를 사용해야 합니다. Windows tsh 설치 프로그램 다운로드.

• Web UI 세션을 인증하려면 Teleport Connect가 필요합니다

• Teleport 배포로의 올바른 최종 사용자 IP 전파: X-Forwarded-For 헤더(L7 로드 밸런서) 또는 PROXY 프로토콜(L4 로드 밸런서)

신뢰할 수 있는 디바이스 등록#

tctl 도구는 디바이스 인벤토리를 관리하는 데 사용됩니다. 디바이스 관리자는 디바이스를 관리하고 새 디바이스를 인벤토리에 추가하며 더 이상 사용하지 않는 디바이스를 제거할 책임이 있습니다.

$ tsh device enroll --current-device

디바이스를 등록하기 전에 먼저 디바이스를 등록해야 합니다. 디바이스를 등록하려면 먼저 시리얼 번호를 확인해야 합니다.

tsh로 디바이스 시리얼 번호 조회(등록하려는 디바이스에서 실행해야 합니다):

$ tsh device asset-tag
(=devicetrust.asset_tag=)

$ tsh device asset-tag
(=devicetrust.asset_tag=)

[devicetrust.asset_tag]" description="등록할 시리얼 번호"/>를 등록하려는 디바이스의 시리얼 번호로 교체하고 macos를 운영 체제로 교체합니다. tctl devices add 명령을 실행합니다:

$ tctl devices add --os='macos' --asset-tag='(=devicetrust.asset_tag=)'
Device (=devicetrust.asset_tag=)/macos added to the inventory

tctl을 사용하여 디바이스가 등록되었는지 확인합니다:

$ tctl devices ls
Asset Tag    OS    Source Enroll Status Owner Device ID
------------ ----- ------ ------------- ----- ------------------------------------
(=devicetrust.asset_tag=) macOS        not enrolled        (=devicetrust.device_id=)

디바이스 등록 토큰 만들기#

등록된 디바이스는 등록 절차를 거친 후 신뢰할 수 있는 디바이스가 됩니다. 디바이스를 등록하려면 디바이스 등록 토큰이 필요합니다. 토큰은 디바이스 관리자가 만들어 등록을 수행하는 사람에게 비공개로(예: 회사 채팅을 통해) 전송됩니다.

등록 토큰을 만들려면 아래 명령을 실행합니다. --asset-tag는 등록하려는 디바이스의 시리얼 번호입니다:

$ tctl devices enroll --asset-tag="(=devicetrust.asset_tag=)"
Run the command below on device "(=devicetrust.asset_tag=)" to enroll it:
tsh device enroll --token=(=devicetrust.enroll_token=)

신뢰할 수 있는 디바이스 등록#

등록 절차를 수행하려면 위에서 지정한 디바이스를 사용하여 tctl devices enroll이 출력한 명령을 입력합니다:

$ tsh device enroll --token=(=devicetrust.enroll_token=)
Device "(=devicetrust.asset_tag=)"/macOS enrolled

$ tsh logout
$ tsh login --proxy=(=clusterDefaults.clusterName=) --user=(=clusterDefaults.username=) # fetch new certificates
Enter password for Teleport user (=clusterDefaults.username=):
Tap any security key
Detected security key tap
> Profile URL:        (=clusterDefaults.clusterName=):443
  Logged in as:       (=clusterDefaults.username=)
  Cluster:            (=clusterDefaults.clusterName=)
  Roles:              access, editor
  Logins:             (=clusterDefaults.username=)
  Kubernetes:         enabled
  Valid until:        2023-06-23 02:47:05 -0300 -03 [valid for 12h0m0s]
  Extensions:         teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id

teleport-device-* 확장의 존재는 디바이스가 성공적으로 등록되고 인증되었음을 나타냅니다. 위의 디바이스는 이제 신뢰할 수 있는 디바이스입니다.

자동 등록#

많은 사용자에게 등록 토큰을 배포하는 것은 어려울 수 있습니다. 이를 해결하기 위해 Teleport는 자동 등록을 지원합니다. 활성화되면 자동 등록은 다음 Teleport(tsh) 로그인 시 사용자의 디바이스를 자동으로 등록합니다.

자동 등록이 작동하려면 다음 조건이 충족되어야 합니다:

• 디바이스가 등록되어 있어야 합니다. 등록은 수동으로 수행되거나 MDM 통합을 사용하여 수행될 수 있습니다.
• 클러스터 설정에서 자동 등록이 활성화되어 있어야 합니다.

클러스터 설정에서 자동 등록을 활성화합니다. 다음 명령을 사용하여 동적 구성 리소스를 수정합니다:

$ tctl edit cluster_auth_preference

다음과 같이 변경합니다:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  # ...
  device_trust:
    mode: "required"
+   auto_enroll: true

편집기를 저장하고 닫아 변경 사항을 적용합니다.

활성화되면 Teleport에 디바이스가 등록된 사용자는 다음 로그인 시 Teleport에 디바이스가 등록됩니다.

$ tsh logout
All users logged out.
$ tsh login --proxy=(=clusterDefaults.clusterName=) --user=(=clusterDefaults.username=)
Enter password for Teleport user (=clusterDefaults.username=):
Tap any security key
Detected security key tap
> Profile URL:        (=clusterDefaults.clusterName=):443
  Logged in as:       (=clusterDefaults.username=)
  Cluster:            (=clusterDefaults.clusterName=)
  Roles:              access, editor
  Logins:             (=clusterDefaults.username=)
  Kubernetes:         enabled
  Valid until:        2023-06-23 02:47:05 -0300 -03 [valid for 12h0m0s]
  Extensions:         teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id

teleport-device-* 확장의 존재는 디바이스가 성공적으로 등록되고 인증되었음을 나타냅니다.

신뢰할 수 있는 디바이스 제거#

더 이상 사용하지 않는 디바이스는 tctl devices rm --device-id= 또는 tctl devices rm --asset-tag=을 사용하여 제거할 수 있습니다.

먼저 삭제할 디바이스를 찾습니다:

$ tctl devices ls
Asset Tag    OS    Source Enroll Status Owner Device ID
------------ ----- ------ ------------- ----- ------------------------------------
C00AA0AAAA0A macOS        enrolled      alice c9cbb327-68a8-497e-b820-6a4b2bf58269

이제 asset-tag 또는 device id를 사용하여 디바이스를 삭제합니다:

# Delete using asset tag:
$ tctl devices rm --asset-tag=C00AA0AAAA0A
Device "C00AA0AAAA0A" removed

# Delete using device id:
$ tctl devices rm --device-id=c9cbb327-68a8-497e-b820-6a4b2bf58269
Device "c9cbb327-68a8-497e-b820-6a4b2bf58269" removed

TPM EKCert CA 허용 목록 구성#

이 조언은 Windows 및 Linux와 같이 TPM을 사용하는 플랫폼의 Device Trust에만 적용됩니다.

일부 TPM에는 제조업체의 CA(인증 기관)가 서명한 EKCert라고 하는 인증서가 포함되어 있습니다. 이 인증서를 통해 제3자(예: Teleport 클러스터)는 통신하고 있는 TPM이 합법적임을 알 수 있습니다. 이를 통해 관리자가 등록 전에 디바이스가 변조되지 않았음을 확인해야 하는 부담이 크게 줄어듭니다.

기본적으로 Teleport 클러스터는 EKCert를 검증하지 않습니다. 모든 TPM에 EKCert가 포함되어 있지 않고 제조업체의 CA에 대한 지식 없이는 EKCert를 검증할 수 없기 때문입니다. 이 검증은 ekcert_allowed_cas라는 Teleport 구성 필드를 포함하여 활성화됩니다.

구성되면 필드에 지정된 CA가 서명한 EKCert가 있는 TPM을 포함하는 디바이스만 등록할 수 있습니다. 이전에 등록된 디바이스는 영향을 받지 않습니다.

ekcert_allowed_cas를 구성하려면 먼저 디바이스에 포함된 TPM 제조업체로부터 PEM 형식의 CA 인증서를 얻어야 합니다. 이 단계는 제조업체마다 다릅니다.

PEM 형식의 CA 인증서를 얻은 후 다음 명령을 사용하여 동적 구성 리소스를 수정합니다:

$ tctl edit cluster_auth_preference

다음과 같이 변경합니다:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  ...
  device_trust:
    mode: "required" # add this line
+    ekcert_allowed_cas:
+      # The CA is configured inline within the resource:
+      - |
+        -----BEGIN CERTIFICATE-----
+        --snip--
+        -----END CERTIFICATE-----

편집기를 저장하고 닫아 변경 사항을 적용합니다.

문제 해결#

tsh device enroll 실행 시 "binary missing signature or entitlements"#

신뢰할 수 있는 디바이스를 등록하고 사용하려면 서명 및 노터라이즈된 tsh 바이너리가 필요합니다. 이 문제를 해결하려면 macOS tsh 설치 프로그램을 다운로드하세요.

신뢰할 수 있는 디바이스 사용 시 "unauthorized device" 오류#

신뢰할 수 있는 디바이스는 Teleport가 이를 인식하기 전에 먼저 등록(register)과 enrollment 과정을 거쳐야 합니다. 등록 및 enrollment 단계를 따르고, enrollment가 완료된 후 반드시 tsh logout과 tsh login을 수행하세요.

Linux에서 "Failed to open the TPM device"#

Linux 사용자는 TPM 디바이스인 /dev/tpmrm0에 대한 읽기 및 쓰기 권한이 필요합니다. 이러한 권한이 없으면 tsh는 대부분의 작업에서 sudo 프롬프트를 요구하게 됩니다.

가장 간단한 해결 방법은 사용 중인 배포판에 tss 그룹이 포함되어 있는지 확인하고 이를 OS 사용자에게 할당하는 것입니다. 이것이 불가능하거나 다른 해결책을 찾고 있다면, TPM2 Software Stack에서 제공하는 것과 유사한 udev 규칙을 생성하는 것을 권장합니다.

자동 enrollment이 작동하지 않음#

자동 enrollment 절차는 그 자동화된 특성상 일반 enrollment보다 더 엄격합니다. 추가적인 자동 enrollment 검사에는 다음이 포함됩니다:

1. MDM 서비스에서 유래한 데이터 등 디바이스 프로필 데이터를 실제 디바이스와 대조하여 검증
2. 디바이스가 다른 사용자에 의해 enroll되지 않았는지 검증(자동 enroll은 이미 enroll된 디바이스를 가져올 수 없습니다)

감사 로그에서 단서를 확인하세요: 실패한 "Device Enroll Token Created" 이벤트를 찾아 세부 정보의 "message" 필드를 살펴보세요.

(1)이 문제라고 의심된다면, 실제 디바이스를 해당 인벤토리 정의와 비교하세요(실제 디바이스에서 실행한 tsh device collect와 tctl get device/<asset_tag>). 디바이스 프로필을 조정하거나, 수동 enrollment을 수행하거나, 다음 MDM 동기화를 기다리면 문제가 해결될 수 있습니다.

(2)가 의심된다면, tctl edit device/<asset_tag>로 디바이스의 "enroll_status" 필드를 "not_enrolled"로 변경하여 디바이스를 unenroll할 수 있습니다.

App access와 "access to this app requires a trusted device"#

아래의 Web UI 문제 해결 섹션의 안내를 따르세요(Teleport v16 이상).

또는 App Access 지원에서 설명하는 tsh 명령 중 하나를 사용할 수 있습니다. 예를 들어 myapp라는 앱의 경우 tsh proxy app myapp -p 8888을 실행한 다음, 브라우저에서 http://localhost:8888을 여세요.

이미 tsh proxy app을 실행 중이거나 tsh app login으로 획득한 인증서를 사용하고 있다면, 디바이스가 등록되지 않았거나 enroll되지 않았을 가능성이 높습니다. 이 경우 위의 unauthorized device 섹션의 조언을 따르세요.

Desktop access와 "access to this app requires a trusted device"#

아래의 Web UI 문제 해결 섹션의 안내를 따르세요.

Web UI에서 신뢰할 수 있는 디바이스 인증에 실패함#

Web UI는 로그인 시 Teleport Connect를 사용하여 디바이스를 인증하려고 시도합니다. 로그인 직후 디바이스 인증을 요청받지 못했다면 아래 단계를 따르세요:

1. 디바이스가 등록 및 enroll되었는지 확인하세요
2. Teleport Connect를 설치하세요. Linux에서는 DEB 또는 RPM 패키지를 사용하세요(tarball은 사용자 지정 URL 핸들러를 등록하지 않습니다).
3. Teleport Connect가 Web에서 접근하려는 것과 동일한 리소스에 접근할 수 있는지 확인하세요
4. 클러스터 관리자에게 Device Trust가 활성화되어 있는지 문의하세요(클러스터 모드 "optional" 이상)

위 단계를 완료한 후 Web UI에서 로그아웃했다가 다시 로그인해 보세요. 오류가 지속되면 감사 로그에서 실패한 "device authenticated" 또는 "device web" 이벤트를 확인하고 이벤트 내의 실패 세부 정보를 살펴보세요.

"device web authentication IP mismatch" 오류#

감사 로그의 "IP mismatch" 오류는 디바이스 웹 인증 절차에서 수행하는 IP 검사가 실패했음을 나타냅니다. 이 경우 최종 사용자의 IP가 Teleport 배포에 올바르게 전파되지 않았을 가능성이 높습니다.

• L7 로드 밸런서: X-Forwarded-For 헤더를 전파하는지 확인하세요
• L4 로드 밸런서: PROXY protocol을 활성화하세요

웹 UI에서 Device Trust 인가 상태 확인#

웹 UI에서 Device Trust 사용이 성공적으로 인가되면, 사용자는 화면 오른쪽 상단의 로그인된 사용자 이름 옆에 녹색 방패 아이콘을 보게 됩니다. 또한 사용자 이름을 클릭하여 사용자 메뉴를 표시하면 해당 세션이 Device Trust로 인가되었음을 나타냅니다.

사용자가 웹 UI에서 Device Trust 사용을 인가받지 못했지만 클러스터 전역 구성 또는 할당된 역할이 신뢰할 수 있는 디바이스 사용을 요구하는 경우, 사용자는 화면 오른쪽 상단의 로그인된 사용자 이름 옆에 노란색 경고 방패를 보게 됩니다. 또한 사용자 이름을 클릭하여 사용자 메뉴를 표시하면 해당 세션이 Device Trust로 인가되지 않았으며 사용자의 접근이 제한됨을 나타냅니다.

테마	Device Trust로 인가된 세션	Device Trust로 인가되지 않은 세션
라이트
다크

다음 단계#

• Device Trust 강제
• Jamf Pro 통합
• Microsoft Intune 통합