헤드리스 WebAuthn은 WebAuthn 장치에 접근할 수 없는 머신에서 WebAuthn을 통해 인증하는 안전한 방법을 제공합니다. 이를 통해 WebAuthn과 호환되지 않는 환경에서 일반적으로 사용할 수 없는 WebAuthn 기능을 사용할 수 있습니다. 예를 들어:

• 원격 개발 박스에서 WebAuthn으로 Teleport에 로그인
• 원격 개발 박스에서 세션별 MFA로 Teleport SSH 서비스에 연결
• 세션별 MFA로 한 Teleport SSH 서비스에서 다른 서비스로 tsh scp 수행
• WebAuthn 호환 브라우저가 없는 머신에서 Teleport에 로그인

전제 조건

• WebAuthn이 구성된 Teleport 클러스터. 두 번째 요소: WebAuthn 가이드를 참조하세요.
• YubiKey와 같은 WebAuthn 하드웨어 장치.
• 헤드리스 WebAuthn 활동을 위한 머신에 Linux, macOS 또는 Windows tsh 바이너리 설치.
• 헤드리스 WebAuthn 요청을 승인하는 데 사용할 머신에 WebAuthn 지원이 있는 웹 브라우저 또는 tsh 바이너리 설치.
• 선택 사항: 매끄러운 헤드리스 WebAuthn 승인을 위한 Teleport Connect v13.3.1 이상.

1단계/3. 구성

WebAuthn이 가능한 Teleport 클러스터는 추가 구성 없이 자동으로 헤드리스 WebAuthn이 가능합니다.

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factor: "on"
  webauthn:
    rp_id: example.com
  connector_name: headless # 기본적으로 헤드리스

tctl create -f cap.yaml
클러스터 인증 선호도가 업데이트되었습니다

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factor: "on"
  webauthn:
    rp_id: example.com
  headless: false # 헤드리스 WebAuthn 비활성화

tctl create -f cap.yaml
클러스터 인증 선호도가 업데이트되었습니다

2단계/3. 헤드리스 WebAuthn 시작

--headless 플래그를 사용하여 헤드리스 tsh 명령을 실행하세요. 그러면 헤드리스 인증이 시작되며 URL과 tsh 명령이 출력됩니다.

tsh ls --headless --proxy=proxy.example.com --user=alice
로컬 웹 브라우저에서 헤드리스 인증을 완료하세요:
https://proxy.example.com:3080/web/headless/86172f78-af7c-5935-a7c1-ed06b94f17dc
또는 로컬 터미널에서 이 명령을 실행하세요:
tsh headless approve --user=alice --proxy=proxy.example.com 86172f78-af7c-5935-a7c1-ed06b94f17dc

3단계/3. 헤드리스 WebAuthn 승인

헤드리스 인증을 승인하려면 로컬 웹 브라우저에서 tsh에 의해 출력된 URL을 클릭하거나 복사하여 붙여넣으세요. WebAuthn 확인으로 로그인을 승인하라는 메시지가 표시됩니다. 승인되면, 초기 tsh --headless <command>가 로컬로 로그인한 것처럼 계속 진행됩니다.

표준 로그인 세션과 달리, 헤드리스 세션은 단일 tsh 요청의 수명 동안만 사용할 수 있습니다. 즉, 각 tsh --headless 명령에 대해 헤드리스 WebAuthn 흐름을 다시 거쳐야 합니다:

예: SSH 서버 나열

tsh ls --headless --proxy=proxy.example.com --user=alice
로컬 웹 브라우저에서 헤드리스 인증을 완료하세요:
https://proxy.example.com:3080/web/headless/86172f78-af7c-5935-a7c1-ed06b94f17dc
또는 로컬 터미널에서 이 명령을 실행하세요:
tsh headless approve --user=alice --proxy=proxy.example.com 86172f78-af7c-5935-a7c1-ed06b94f17dc
# 사용자가 링크를 통해 승인
노드 이름 주소       라벨
--------- ---------- -----------
server01  127.0.0.1:3022 arch=x86_64

예: SSH 세션 시작

tsh ssh --headless --proxy=proxy.example.com --user=alice alice@server01
로컬 웹 브라우저에서 헤드리스 인증을 완료하세요:
https://proxy.example.com:3080/web/headless/864cccd9-2425-46d9-a9f2-636387e66ebf
또는 로컬 터미널에서 이 명령을 실행하세요:
tsh headless approve --user=alice --proxy=proxy.example.com 864cccd9-2425-46d9-a9f2-636387e66ebf
# 사용자가 링크를 통해 승인하고 SSH 터미널 시작
alice@server01 $

선택 사항: Teleport Connect

Teleport Connect v13.3.1 이상으로 헤드리스 WebAuthn 로그인 승인을 수행할 수 있습니다. Teleport Connect는 헤드리스 WebAuthn 로그인 시도를 자동으로 감지하고 요청을 승인하거나 취소할 수 있도록 합니다.

승인 프로세스를 완료하기 위해 MFA 키를 탭하라는 메시지가 표시됩니다.

문제 해결

"WARN: 헤드리스 로그인에 대한 시스템 메모리 잠금을 실패했습니다: ..."

헤드리스 WebAuthn을 사용할 때 tsh는 개인 키와 인증서 데이터를 디스크(~/.tsh)에 쓰지 않습니다. 대신, tsh는 요청 기간 동안 이러한 비밀을 메모리에 보관합니다. 또한, 프로세스 메모리를 잠가 다른 사용자에 의해 비밀이 도난당하는 것을 방지하려고 합니다.

발생할 수 있는 특정 경고 메시지와 해결 방법은 다음과 같습니다:

"허용되지 않은 작업" 또는 "메모리 할당 불가"

프로세스 메모리를 잠그려면 OS 사용자가 필요한 메모리 양을 잠글 수 있는 권한이 있어야 합니다. ulimit -l을 사용하여 OS 사용자의 현재 제한을 확인하세요. 필요한 메모리 양은 시스템마다 다를 수 있으므로 ulimit -l unlimited로 제한을 무제한으로 업데이트하거나 /etc/security/limits.conf에 <os_username> hard memlock unlimited 줄을 추가하는 것이 좋습니다.

"비-Linux 운영 체제에서는 메모리 잠금이 지원되지 않음"

mlockall 시스템 호출은 Linux 운영 체제에서만 지원됩니다. 즉, 다른 운영 체제에서는 항상 메모리 잠금 시도가 실패하고 경고 메시지가 출력됩니다. 공유 머신에서 최고의 보안 수준을 위해서는 헤드리스 WebAuthn을 Linux 머신에서만 사용하는 것을 권장합니다.

mlock 비활성화

위의 솔루션이 환경에서 실행 가능하지 않은 경우, --mlock 플래그 또는 TELEPORT_MLOCK_MODE 환경 변수를 off 또는 best_effort로 설정하여 메모리 잠금 요구 사항을 비활성화할 수 있습니다. 이는 공유 시스템에서 메모리 스왑 공격이 가능한 프로덕션 환경에서는 권장되지 않습니다.