Device Trust는 다음 두 가지 단계가 구성되어 있어야 합니다:

• 역할 또는 클러스터 전체 구성을 통해 디바이스 적용 모드가 구성되어 있어야 합니다.
• 신뢰할 수 있는 디바이스가 Teleport에 등록 및 등록되어 있어야 합니다.

이 가이드에서는 기존 사용자 프로필을 업데이트하여 사전 설정된 require-trusted-device 역할을 할당하고, Teleport로 보호된 리소스(테스트 Linux 서버)에 액세스하기 위해 신뢰할 수 있는 디바이스를 Teleport에 등록합니다.

사전 요구 사항#

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

• editor 역할을 가진 사용자.

  $ tsh status
  > Profile URL:      (=clusterDefaults.clusterName=):443
  Logged in as:       (=clusterDefaults.username=)
  Cluster:            (=clusterDefaults.clusterName=)
  Roles:              access, auditor, editor
  Logins:             root, ubuntu, ec2-user
  Kubernetes:         disabled
  Valid until:        2023-08-22 03:30:24 -0400 EDT [valid for 11h52m0s]
  Extensions:         login-ip, permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy
  

• Linux 서버에 대한 액세스 (tsh ssh로 액세스할 수 있는 Linux 서버면 됩니다).

  $ tsh ls
  Node Name        Address        Labels
  ---------------- -------------- --------------------------------------
  (=clusterDefaults.nodeIP=) ⟵ Tunnel
  
  # test connection to (=clusterDefaults.nodeIP=)
  $ tsh ssh root@(=clusterDefaults.nodeIP=)
  root@(=clusterDefaults.nodeIP=):~#
  

위의 사전 요구 사항이 충족되면 다음 단계를 시작하세요.

1/2단계. Device Trust를 적용하도록 사용자 프로필 업데이트#

Device Trust를 적용하려면 사용자에게 Device Trust 모드가 "required"인 역할이 할당되어 있어야 합니다.

이 가이드에서는 사전 설정된 require-trusted-device 역할을 사용하여 현재 사용자 프로필을 업데이트합니다.

사전 설정된 require-trusted-device 역할로 업데이트하기 위해 편집기에서 사용자 리소스를 열어보겠습니다.

$ tctl edit users/(=clusterDefaults.username=)

프로필 편집:

kind: user
metadata:
  id: 1692716146877042322
  name: (=clusterDefaults.username=)
spec:
  created_by:
    time: "2023-08-14T13:42:22.291972449Z"
  expires: "0001-01-01T00:00:00Z"
  roles:
  - access
  - auditor
  - editor
+ - require-trusted-device # add this line
  status:
    is_locked: false
  ...

편집기에서 파일을 저장하고 닫아 사용자를 업데이트하세요.

이제 사용자 프로필이 Device Trust를 적용하도록 업데이트되었으니, 테스트 서버에 다시 액세스해 보세요.

$ tsh logout; tsh login --proxy=(=clusterDefaults.clusterName=) --user=(=clusterDefaults.username=)
$ tsh ssh root@(=clusterDefaults.nodeIP=)
ERROR: access denied to root connecting to (=clusterDefaults.nodeIP=):0

위 단계에서 확인할 수 있듯이, 이전에 액세스 가능했던 <code>[clusterDefaults.nodeIP]</code> SSH 서버에 대한 액세스가 이제 거부됩니다.

2/2단계. 디바이스 등록#

<code>[clusterDefaults.nodeIP]</code> 서버에 다시 액세스하려면 디바이스를 등록해야 합니다.

디바이스 등록은 간단하며, tsh 클라이언트를 사용하여 수행할 수 있습니다:

$ tsh device enroll --current-device
Device "(=devicetrust.asset_tag=)"/macOS registered and enrolled

디바이스 확장이 포함된 업데이트된 인증서를 가져오기 위해 다시 로그인하세요:

$ tsh logout; tsh login --proxy=(=clusterDefaults.clusterName=) --user=(=clusterDefaults.username=)

$ tsh status
> Profile URL:        (=clusterDefaults.clusterName=):443
  Logged in as:       (=clusterDefaults.username=)
  Cluster:            (=clusterDefaults.clusterName=):443
  Roles:              access, auditor, editor
  Logins:             root
  Kubernetes:         enabled
  Valid until:        2023-08-22 04:06:53 -0400 EDT [valid for 12h0m0s]
  Extensions:         login-ip, ... teleport-device-asset-tag, teleport-device-credential-id, teleport-device-id

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

이제 서버(<code>[clusterDefaults.nodeIP]</code>)에 다시 액세스해 봅시다:

$ tsh ssh root@(=clusterDefaults.nodeIP=)
root@(=clusterDefaults.nodeIP=):~#

축하합니다! 신뢰할 수 있는 디바이스를 성공적으로 구성하고 Device Trust 적용으로 보호된 리소스에 액세스했습니다.

문제 해결#

"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.

다음 단계#

• 디바이스 관리
• Device Trust 적용
• Jamf Pro 연동
• Microsoft Intune 연동
• 이 가이드에서 설명한 역할은 Teleport가 Teleport 로컬 사용자 데이터베이스의 값으로 대체하는 internal.logins 트레이트를 사용합니다. Teleport 역할에서 트레이트가 작동하는 방법에 대한 전체 세부 사항은 액세스 제어 참조를 참조하세요.