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

전제 조건#

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

• To enroll a macOS device, you need:

  • A signed and notarized tsh binary. Download the macOS tsh installer.

• To enroll a Windows device, you need:

  • A device with TPM 2.0.
  • A user with administrator privileges. This is only required during enrollment.
  • The tsh client. Download the Windows tsh installer.

• To enroll a Linux device, you need:

  • A device with TPM 2.0.

  • A user with permissions to use the /dev/tpmrm0 device (typically done by assigning the tss group to the user).

  • The tsh client. Install tsh for Linux.

    WSL users should use the Windows binary instead. Download the Windows tsh installer.

• To authenticate a Web UI session you need Teleport Connect

• Correct end-user IP propagation to your Teleport deployment: X-Forwarded-For header (L7 load balancer) or PROXY protocol (L4 load balancer)

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

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="등록할 시리얼 번호"/>를 등록하려는 디바이스의 시리얼 번호로 교체하고 를 운영 체제로 교체합니다. tctl devices add 명령을 실행합니다:

$ tctl devices add --os='' --asset-tag=''
Device /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-----

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

문제 해결#

"binary missing signature or entitlements" on tsh device enroll#

A signed and notarized tsh binary is necessary to enroll and use a a trusted device. Download the macOS tsh installer to fix the problem.

"unauthorized device" errors using a trusted device#

A trusted device needs to be registered and enrolled before it is recognized by Teleport as such. Follow the registration and enrollment steps and make sure to tsh logout and tsh login after enrollment is done.

"Failed to open the TPM device" on Linux#

Linux users need permissions to read and write from the TPM device, /dev/tpmrm0. Without such permissions tsh would need sudo prompts for most operations.

The simplest way to solve this is to check if your distro ships with the tss group and assign it to your OS user. If that is not possible, or you are looking for a different solution, we recommend creating udev rules similar to the ones shipped by the TPM2 Software Stack.

Auto enrollment not working#

Auto-enrollment ceremonies, due to their automated nature, are stricter than regular enrollment. Additional auto-enrollment checks include:

1. Verifying device profile data, such as data originated from an MDM service, against the actual device
2. Verifying that the device is not enrolled by another user (auto-enroll cannot take devices that are already enrolled)

Check you audit log for clues: look for failed "Device Enroll Token Created" events and see the "message" field in the details.

If you suspect (1) is the issue, compare the actual device against its inventory definition (tsh device collect executed in the actual device vs tctl get device/<asset_tag>). Tweaking the device profile, manual enrollment or waiting for the next MDM sync may solve the issue.

If you suspect (2), you can unenroll the device using tctl edit device/<asset_tag> and changing the "enroll_status" field to "not_enrolled".

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

Follow the instructions in the Web UI troubleshooting section below (Teleport v16 or later).

Alternatively, you may use one of the tsh commands described by App Access support. For example, for an app called myapp, run tsh proxy app myapp -p 8888, then open http://localhost:8888 in your browser.

If you are already running tsh proxy app, or using the certificates acquired from tsh app login, then it's likely your device isn't registered or enrolled. In this case, follow the advice from the unauthorized device section above.

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

Follow the instructions in the Web UI troubleshooting section below.

Web UI fails to authenticate trusted device#

The Web UI attempts to authenticate your device using Teleport Connect during login. If you are not asked to authenticate your device immediately after login, follow the steps below:

1. Make sure your device is registered and enrolled
2. Install Teleport Connect. Use the DEB or RPM packages on Linux (the tarball doesn't register the custom URL handler).
3. Make sure Teleport Connect can access the same resource you are trying to access on the Web
4. Ask your cluster administrator if Device Trust is enabled (cluster mode "optional" or higher)

After the steps above are done try logging out from the Web UI and logging in again. If the error persists, check your audit log for failed "device authenticated" or "device web" events and look for failure details within the events.

"device web authentication IP mismatch" errors#

"IP mismatch" errors in audit logs indicate that the IP checks performed by the device web authentication ceremony failed. In this case it's likely that end-user IPs are not propagated correctly to your Teleport deployment.

• L7 load balancer: make sure it propagates the X-Forwarded-For header
• L4 load balancer: enable PROXY protocol

Checking Device Trust authorization status in the web UI#

When successfully authorized to use Device Trust in the web UI, the user will see a green shield icon next to the logged-in username at the top right of the screen. Additionally, clicking on the username to show the user menu will indicate that the session is authorized with Device Trust.

If the user is not authorized to use Device Trust in the web UI, but either the cluster-wide configuration or their assigned role(s) require the use of a trusted device, the user will see a yellow warning shield next to the logged-in username at the top right of the screen. Additionally, clicking on the username to show the user menu will indicate that the session is not authorized with Device Trust, so the user's access is restricted.

Theme	Session authorized with Device Trust	Session not authorized with Device Trust
Light
Dark

다음 단계#

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