디바이스 모드 "required"로 보호된 리소스는 사용자의 신원을 확인하고 필요한 역할을 적용하는 것 외에도 신뢰할 수 있는 디바이스의 사용을 강제합니다. 또한, 신뢰할 수 있는 디바이스를 사용하는 사용자는 디바이스 정보가 포함된 감사 기록을 남깁니다.

Device Trust 적용은 device_trust_mode 인증 설정으로 표현되는 다음 세 가지 작동 모드로 구성할 수 있습니다:

• off - Device Trust를 비활성화합니다. 디바이스 인증이 수행되지 않으며 디바이스 인식 감사 로그가 없습니다.
• optional - 디바이스 인증 및 디바이스 인식 감사를 활성화하지만, 리소스에 액세스하기 위해 신뢰할 수 있는 디바이스를 요구하지 않습니다.
• required - 디바이스 인증 및 디바이스 인식 감사를 활성화합니다. 또한 모든 SSH, 데이터베이스 및 Kubernetes 연결에 신뢰할 수 있는 디바이스를 요구합니다.
• required-for-humans - 디바이스 인증 및 디바이스 인식 감사를 활성화합니다. 또한 인간 사용자에 한해 모든 SSH, 데이터베이스 및 Kubernetes 연결에 신뢰할 수 있는 디바이스를 요구합니다(봇은 제외됨).

사전 요구 사항#

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

이 가이드는 앱이나 데스크톱에 대해 신뢰할 수 있는 디바이스 사용을 적용하지 않는 사전 설정된 require-trusted-device 역할을 사용합니다. 해당 지침은 각 섹션을 참조하세요.

역할 기반 신뢰할 수 있는 디바이스 적용#

역할 기반 구성은 역할 수준에서 신뢰할 수 있는 디바이스 액세스를 적용합니다. spec.options.device_trust_mode 옵션으로 구성할 수 있으며 allow 규칙의 리소스에 적용됩니다. require_session_mfa와 유사하게 작동합니다.

사용자가 Teleport로 데이터베이스, Kubernetes 클러스터 및 서버에 액세스할 때 특정 역할에 대해 인증된 디바이스 검사를 적용하려면 device_trust_mode 필드를 "required" 또는 "required-for-humans"로 설정하여 역할을 업데이트하세요. 다음 예시는 사전 설정된 require-trusted-device 역할을 업데이트합니다:

kind: role
version: v7
metadata:
  name: require-trusted-device
spec:
  options:
    device_trust_mode: "required"
  allow:
    db_labels:
      '*': '*'
    db_names:
    - '*'
    db_users:
    - '*'
    kubernetes_groups:
    - '{{internal.kubernetes_groups}}'
    - system:masters
    - developers
    - viewers
    kubernetes_labels:
      '*': '*'
    logins:
    - '{{internal.logins}}'
    node_labels:
      '*': '*'

역할 업데이트:

$ tctl create -f device-enforcement.yaml

클러스터 전체 신뢰할 수 있는 디바이스 적용#

클러스터 전체 구성은 클러스터 수준에서 신뢰할 수 있는 디바이스 액세스를 적용합니다. Enterprise 클러스터는 기본적으로 optional 모드로 실행됩니다. 모드를 required로 변경하면 모든 SSH, 데이터베이스 및 Kubernetes 액세스에 신뢰할 수 있는 디바이스가 요구됩니다.

디바이스 모드 required를 활성화하려면 다음과 같이 구성을 업데이트하세요:

다음 명령어를 사용하여 클러스터 인증 기본 설정을 편집하세요:

$ tctl edit cluster_auth_preference

다음 변경 사항을 적용하세요:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factors: ["webauthn"]
  webauthn:
    rp_id: (=clusterDefaults.clusterName=)
  device_trust:
+   mode: "required" # add this line

편집기를 저장하고 닫아 변경 사항을 적용하세요.

구성이 업데이트되면 신뢰할 수 있는 디바이스 없이 SSH, 데이터베이스 및 Kubernetes에 액세스하는 것이 금지됩니다. 예를 들어, 신뢰할 수 있는 디바이스 없이 SSH 액세스를 시도하면 다음 오류가 발생합니다:

$ tsh ssh (=clusterDefaults.nodeIP=)
ERROR: ssh: rejected: administratively prohibited (unauthorized device)

웹 애플리케이션 지원#

Teleport 앱 서비스는 역할 기반 적용을 통해 Device Trust를 적용할 수 있습니다.

웹 UI(Teleport v16 이상)를 사용하여 Device Trust로 보호된 앱에 액세스하려면 디바이스가 등록 및 등록되어 있는지 확인하고, Teleport Connect를 설치한 후 로그인 중 표시되는 지침을 따르세요.

또는 tsh proxy app이나 tsh app login에서 발급한 인증서를 사용할 수 있습니다.

예를 들어, 모든 env:production 앱에 Device Trust를 적용하려면 아래 역할을 require-trusted-device-apps.yaml로 저장하세요:

kind: role
version: v7
metadata:
  name: require-trusted-device-apps
spec:
  options:
    device_trust_mode: "required"
  allow:
    app_labels:
      env: production

역할을 생성하고 사용자에게 할당하세요:

$ tctl create require-trusted-device-apps.yaml
$ tctl edit users/alice

kind: user
metadata:
  name: alice
  # (...)
spec:
  roles:
  - access
  - editor
+ - require-trusted-device-apps
  # (...)
version: v2

이제 alice 사용자는 신뢰할 수 있는 디바이스를 사용해서만 env:production 앱에 액세스할 수 있습니다.

데스크톱 지원#

Teleport 데스크톱 서비스는 역할 기반 적용을 통해 Device Trust를 적용할 수 있습니다.

Device Trust로 보호된 데스크톱에 액세스하려면 디바이스가 등록 및 등록되어 있는지 확인하고, Teleport Connect를 설치한 후 로그인 중 표시되는 지침을 따르세요.

예를 들어, 모든 env:production 데스크톱에 Device Trust를 적용하려면 아래 역할을 require-trusted-device-desktops.yaml로 저장하세요:

kind: role
version: v7
metadata:
  name: require-trusted-device-desktops
spec:
  options:
    device_trust_mode: "required"
  allow:
    windows_desktop_labels:
      env: "production"
    windows_desktop_logins: ["Administrator", "alice"]

역할을 생성하고 사용자에게 할당하세요:

$ tctl create require-trusted-device-desktops.yaml
$ tctl edit users/alice

kind: user
metadata:
  name: alice
  # (...)
spec:
  roles:
  - access
  - editor
+ - require-trusted-device-desktops
  # (...)
version: v2

이제 alice 사용자는 신뢰할 수 있는 디바이스를 사용해서만 env:production 데스크톱에 액세스할 수 있습니다.

디바이스 잠금#

세션 및 신원 잠금과 유사하게, 디바이스를 tctl lock을 사용하여 잠글 수 있습니다.

잠금은 잠긴 디바이스에서 발생하는 인증서 발급 및 진행 중이거나 향후의 액세스를 차단합니다. 디바이스 잠금은 Device Trust가 활성화되어 있고 디바이스가 Teleport에 등록된 경우에만 작동합니다.

잠글 디바이스 ID 찾기:

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

디바이스 잠금:

$ tctl lock --device=(=devicetrust.device_id=) --ttl=12h
Created a lock with name "5444970a-39a0-4814-968d-e58b4a8fa686".

이제 해당 디바이스의 사용자가 예를 들어 SSH 서버에 액세스하려고 하면 Teleport가 액세스를 거부합니다:

$ tsh ssh (=clusterDefaults.nodeIP=)
ERROR: ssh: rejected: administratively prohibited (lock targeting Device:"(=devicetrust.device_id=)" is in force)

문제 해결#

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

다음 단계#

• 디바이스 관리
• Jamf Pro 연동
• Microsoft Intune 연동