헤드리스 인증(Headless Authentication)은 필요한 메커니즘으로 직접 인증할 수 없는 머신에서 Teleport로 안전하게 인증하는 방법을 제공합니다.

예를 들어:

• 원격 개발 박스에서 WebAuthn 또는 SSO MFA로 인증
• WebAuthn 호환 브라우저 없이 머신에서 WebAuthn으로 인증
• SSO 공급자가 지원하지 않는 브라우저에서 SSO MFA로 인증

참고 - 헤드리스 인증 지원: 헤드리스 인증은 다음 tsh 명령만 지원합니다:

• tsh ls
• tsh ssh
• tsh scp
• tsh proxy kube

향후 헤드리스 인증은 다른 tsh 명령으로 확장될 예정입니다.

작동 방식#

헤드리스 인증 흐름에서 원격 머신의 사용자는 tsh 명령을 실행할 때 헤드리스 인증을 요청합니다. tsh는 Teleport 프록시 서비스의 API 경로 /webapi/login/headless에 요청을 보내고, Teleport 프록시 서비스는 Teleport Auth 서비스에 요청을 보내 헤드리스 인증 요청을 백엔드에 저장합니다. 그런 다음 tsh는 요청 ID를 가져와 사용자의 터미널에 ID가 포함된 URL을 출력합니다. 사용자는 브라우저에서 URL에 접근하여 Teleport Auth 서비스와의 MFA 흐름을 완료합니다.

Teleport Auth 서비스가 사용자를 인증하면 tsh는 메모리에 새 개인 키를 생성하고 사용자 인증서를 얻기 위해서만 공개 키를 공유합니다. 그런 다음 tsh는 유출 영향을 줄이기 위해 1분 TTL로 메모리에 사용자 인증서를 보유합니다.

사전 요구 사항#

• WebAuthn 또는 SSO MFA가 구성된 Teleport 클러스터.
• 헤드리스 인증 활동을 위한 머신에는 Linux, macOS 또는 Windows tsh 바이너리가 설치되어 있어야 합니다.
• 헤드리스 인증 요청을 승인하는 데 사용되는 머신에는 WebAuthn 지원이 있는 웹 브라우저 또는 tsh 바이너리가 설치되어 있어야 합니다.
• 선택 사항: 원활한 헤드리스 인증 승인을 위한 Teleport Connect.

1/3단계. 구성#

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

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

$ tctl create -f cap.yaml
# cluster auth preference has been updated

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factors: ["webauthn"]
  webauthn:
    rp_id: example.com
  headless: false # 헤드리스 인증 비활성화

$ tctl create -f cap.yaml
# cluster auth preference has been updated

2/3단계. 헤드리스 인증 시작#

--headless 플래그로 헤드리스 tsh 명령을 실행합니다. 이는 헤드리스 인증을 시작하여 URL과 tsh 명령을 출력합니다.

$ tsh ls --headless --proxy=proxy.example.com --user=alice
# Complete headless authentication in your local web browser:
#
# https://proxy.example.com:3080/web/headless/86172f78-af7c-5935-a7c1-ed06b94f17dc
#
# or execute this command in your local terminal:
#
# tsh headless approve --user=alice --proxy=proxy.example.com 86172f78-af7c-5935-a7c1-ed06b94f17dc

3/3단계. 헤드리스 인증 승인#

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

표준 로그인 세션과 달리 헤드리스 세션은 단일 tsh 요청의 수명 동안만 사용 가능합니다. 즉, 각 tsh --headless 명령마다 헤드리스 인증 흐름을 거쳐야 합니다:

예제: SSH 서버 목록 조회#

$ tsh ls --headless --proxy=proxy.example.com --user=alice
# Complete headless authentication in your local web browser:
#
# https://proxy.example.com:3080/web/headless/86172f78-af7c-5935-a7c1-ed06b94f17dc
#
# or execute this command in your local terminal:
#
# tsh headless approve --user=alice --proxy=proxy.example.com 86172f78-af7c-5935-a7c1-ed06b94f17dc
# # 사용자가 링크를 통해 승인
# Node Name Address        Labels
# --------- -------------- -----------
# server01  127.0.0.1:3022 arch=x86_64

예제: SSH 세션 시작#

$ tsh ssh --headless --proxy=proxy.example.com --user=alice alice@server01
# Complete headless authentication in your local web browser:
#
# https://proxy.example.com:3080/web/headless/864cccd9-2425-46d9-a9f2-636387e66ebf
#
# or execute this command in your local terminal:
#
# tsh headless approve --user=alice --proxy=proxy.example.com 864cccd9-2425-46d9-a9f2-636387e66ebf
# # 사용자가 링크를 통해 승인하면 SSH 터미널이 시작됩니다
alice@server01 $

참고: Teleport 사용자, --user 매개변수는 헤드리스 인증 활동을 요청하는 Teleport 사용자입니다. --user 매개변수나 환경 변수가 설정되지 않으면 머신 터미널의 OS 사용자가 사용됩니다.

tsh ssh 명령의 로그인 사용자 이름 --login 매개변수 또는 login@hostname은 SSH 세션을 여는 사용자입니다. SSH 세션에 로그인 사용자 이름이 설정되지 않으면 OS 터미널 사용자 이름이 사용됩니다. Teleport 사용자는 해당 서버의 로그인 사용자에 대한 접근 권한이 있어야 하며, 그렇지 않으면 접근 거부 메시지가 표시됩니다. 사용자는 헤드리스 인증 활동이 승인된 후에도 로컬 터미널에서 실행하는 것과 동일한 접근 권한이 부여되거나 거부되므로 접근 거부 메시지를 받을 수 있습니다.

예제: Kubernetes#

$ tsh proxy kube --headless --proxy=proxy.example.com --user=alice example-cluster
Complete headless authentication in your local web browser:
# https://proxy.example.com:3080/web/headless/7f7e1369-e45b-5b7b-bb17-84360873acaf
#
# or execute this command in your local terminal:
#
# tsh headless approve --user=alice --proxy=proxy.example.com 7f7e1369-e45b-5b7b-bb17-84360873acaf
# # 사용자가 링크를 통해 승인하면 로컬 프록시가 생성됩니다:

Preparing the following Teleport Kubernetes clusters:
Teleport Cluster Name Kube Cluster Name
--------------------- -----------------
teleport-cluster             example-cluster

Started local proxy for Kubernetes on 127.0.0.1:1234 in the background
and kubectl is set up to work with it. Try issuing a command, for example "kubectl get namespaces"

$ kubectl get pods
NAMESPACE        NAME                                READY   STATUS    RESTARTS      AGE
teleport-agent   teleport-agent-0                    1/1     Running   0             2d12h

선택 사항: Teleport Connect#

Teleport Connect를 사용하여 헤드리스 인증 로그인을 승인할 수도 있습니다. Teleport Connect는 헤드리스 인증 로그인 시도를 자동으로 감지하고 요청을 승인하거나 취소할 수 있게 해줍니다.

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

문제 해결#

"WARN: Failed to lock system memory for headless login: ..."#

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

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

"operation not permitted" 또는 "cannot allocate memory"#

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

"memory locking is not supported on non-linux operating systems"#

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

mlock 비활성화#

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