Teleport의 SSH 서비스는 로그인 시 로컬 Unix 사용자를 자동으로 생성하도록 구성할 수 있습니다.

이를 통해 조직의 각 구성원을 위해 사용자를 수동으로 생성하지 않아도 되며 특정 호스트의 권한에 대한 더 세분화된 제어를 제공합니다. Teleport가 생성한 호스트 사용자는 임시적이며 SSH 세션 종료 시 삭제됩니다.

이 가이드에서는 다음을 진행합니다:

• SSH 세션 중에 이루어지는 자동 호스트 사용자 생성과, SSH 세션과 무관하게 이루어지는 정적 호스트 사용자 생성 중 하나를 선택합니다.
• 선택한 호스트 사용자 생성 모드를 활성화하도록 Teleport 역할을 구성합니다.
• 자동 호스트 사용자 생성의 경우, 생성된 호스트 사용자를 지원하도록 대상 서버를 구성합니다.
• 정적 호스트 사용자 생성의 경우, 생성된 호스트 사용자를 구성하는 동적 Teleport 리소스를 적용합니다.
• Teleport로 보호되는 서버에서 호스트 사용자 생성을 테스트합니다.

사전 요구 사항#

• 실행 중인 Teleport 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

• tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 

• Teleport에 등록된 실행 중인 Linux 서버. 서버를 Teleport 클러스터에 추가하는 방법은 시작하기 가이드를 참조하세요. 이 가이드의 지침에 익숙해지기 전까지는 데모 환경에서 실행 중인 서버를 등록하는 것을 권장합니다.
• Teleport SSH 서비스가 임시 사용자를 생성하기 위해 다음 명령을 실행해야 하므로, 이 유틸리티들이 PATH에서 사용 가능해야 합니다:
  • useradd
  • userdel
  • usermod
  • groupadd
  • getent
  • visudo

Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음, 현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.

예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의 도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여 다음 명령을 실행합니다:

$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

cluster에 연결하여 tctl status 명령을 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 이후의 tctl 명령을 실행할 수 있습니다. 자체 Teleport cluster를 호스팅하는 경우, 전체 권한을 얻기 위해 Teleport Auth Service를 호스팅하는 컴퓨터에서 tctl 명령을 실행할 수도 있습니다.

자동 호스트 사용자#

이 섹션에서는 Teleport 사용자가 SSH 세션을 시작할 때 로컬 사용자를 생성하도록 Teleport를 구성합니다.

1단계/4. RBAC 구성#

Teleport 사용자가 SSH 서비스 인스턴스에 접근하면, Teleport는 해당 인스턴스와 일치하는 사용자의 각 역할을 확인합니다. 인스턴스와 일치하는 역할이 하나라도 있지만 create_host_user_mode를 설정하지 않은 경우, 자동 사용자 생성은 비활성화됩니다. 서버와 일치하지 않는 역할은 확인되지 않습니다.

호스트 사용자 생성을 활성화하려면 다음을 진행합니다:

• 호스트 사용자 생성을 활성화하는 Teleport 역할과 매칭할 수 있도록 서버에 라벨을 지정합니다.
• 추가한 라벨이 있는 서버에 대해 호스트 사용자 생성을 활성화하는 역할을 생성합니다.
• 이 가이드의 목적을 위해, 방금 생성한 역할만 가진 Teleport 사용자를 생성합니다.

서버에 라벨 지정#

1. 이 가이드를 시작하기 전에 Teleport로 등록한 서버에 접근하여, 기본적으로 /etc/teleport.yaml인 Teleport 구성 파일을 엽니다.

2. 구성 파일에 다음 변경 사항을 적용합니다:

     labels:
   +   app: "nginx"
   

3. 서버에서 Teleport를 재시작합니다.

Teleport 역할 정의#

다음 역할 사양은 사용자가 일치하는 모든 서버에서 nginxrestarter로 로그인할 수 있도록 허용합니다. auto-users.yaml이라는 파일에 이 내용을 추가하세요:

kind: role
version: v5
metadata:
  name: auto-users
spec:
  options:
    # Allow automatic creation of users.
    create_host_user_mode: keep
    create_host_user_default_shell: /bin/bash
  allow:
    logins: [ "nginxrestarter" ]
    # List of host groups the created user will be added to. Any that don't already exist are created.
    host_groups: [ubuntu, nginx, other]
    # List of entries to include in a temporary sudoers file created in /etc/sudoers.d
    host_sudoers: [
       # This line will allow the `nginxrestarter` user to run
       # `systemctl restart nginx.service` as
       # root without requiring a password.
       # The sudoers entries will be prefixed with `nginxrestarter` in this case.
       # sudoers file reference documentation: https://www.sudo.ws/docs/man/1.8.17/sudoers.man/
       "ALL = (root) NOPASSWD: /usr/bin/systemctl restart nginx.service"
    ]
    node_labels:
      "app": "nginx"

create_host_user_mode 필드는 값이 keep일 때 호스트 사용자 생성을 활성화합니다. auto-users 역할을 가진 사용자가 app:nginx 라벨과 일치하는 서버에 로그인하면, Teleport SSH 서비스는 호스트 사용자를 생성하고, host_groups에 나열된 그룹에 추가하며, host_sudoers 필드에 지정된 sudoer 권한을 부여합니다. 이 경우, 새 사용자는 root로 Nginx 서비스를 재시작할 수 있는 권한을 받습니다. Teleport 16.4.0 이상에서는 생성된 사용자의 기본 셸을 create_host_user_default_shell로 구성할 수 있습니다. 그렇지 않으면 호스트의 기본 셸이 사용됩니다.

kind: role
version: v5
metadata:
  name: auto-users
spec:
  options:
    create_host_user_mode: keep
  deny:
    host_sudoers: [
       "*" # ensure that users in this role never have sudoers files created on matching Nodes
       "ALL=(ALL) NOPASSWD: ALL" # host_sudoers entries matching this are filtered out
    ]
    node_labels:
      "app": "nginx"

# teleport.yaml
teleport:
  nodename: node
ssh_service:
  enabled: true
  # Disable automatic host user creation on this Node, regardless of role permissions.
  disable_create_host_user: true

역할을 생성합니다:

$ tctl create -f auto-users.yaml
# role 'auto-users' has been created

Teleport 사용자 생성#

1. 다음 명령을 실행하여 auto-users 역할을 가진 Teleport 사용자를 생성합니다:

   $ tctl users add demo-user --roles=auto-users --logins=nginxrestarter
   

2. 터미널에 표시되는 안내에 따라 Teleport Web UI를 방문하여 사용자를 생성합니다.

2단계/4. [선택 사항] 생성된 사용자의 UID 및 GID 구성#

사용자가 host_user_uid 및 host_user_gid 트레이트를 지정한 경우, 호스트 사용자가 생성될 때 UID 및 GID가 해당 값으로 설정됩니다.

이러한 값은 tctl을 통해 사용자를 생성하거나 업데이트할 때 수동으로 설정하거나, 동일한 이름의 SSO 속성을 통해 설정할 수 있습니다.

지정된 GID를 가진 그룹이 아직 존재하지 않는 경우, 생성되는 사용자와 동일한 로그인 이름으로 그룹이 생성됩니다.

kind: user
metadata:
  name: demo-user
spec:
  ...
  traits:
    logins:
    - nginxrestarter
    host_user_gid:
    # gid and uid values must be quoted.
    - "1234"
    host_user_uid:
    - "5678"

host_user_uid 트레이트가 없는 Teleport 사용자의 경우, Teleport 17.3부터는 모든 Teleport SSH 인스턴스에서 자동으로 생성되는 호스트 사용자에 대해, 주어진 사용자 이름마다 동일한 UID를 할당하도록 클러스터를 구성할 수 있습니다.

다음 명령을 사용하여 클러스터 인증 설정(preference)을 편집합니다:

$ tctl edit cluster_auth_preference

편집기에서 cluster_auth_preference에 다음과 유사한 stable_unix_user_config 필드가 포함되어 있는지 확인합니다:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  # ...
  stable_unix_user_config:
    enabled: true
    first_uid: 90000
    last_uid: 95000

first_uid와 last_uid 사이(양쪽 포함)의 UID 범위는 Teleport가 새 사용자에게 UID를 할당하는 데 사용되며, 서버 전체에서 다른 서비스나 워크로드가 이미 사용 중인 UID 범위와 겹치지 않도록 해야 합니다. Linux에서 UID 할당은 다양할 수 있지만, systemd documentation for "Users, Groups, UIDs and GIDs on systemd Systems"에 나열된 사용 가능한 범위 중 하나를 사용하는 것을 권장합니다.

활성화되면, 사용자 트레이트로 다른 UID가 지정되지 않은 경우 모든 Teleport SSH 인스턴스(17.3 이상 버전)는 자동으로 새 호스트 사용자를 생성할 때 컨트롤 플레인에서 제공한 UID를 사용합니다.

다음 명령으로 할당된 UID 목록을 확인할 수 있습니다:

$ tctl stable-unix-users ls

3단계/4. Linux 서버에서 sudoers 구성#

Teleport 호스트 사용자 생성은 새 사용자를 위해 sudoers.d 디렉터리를 활용합니다. CentOS 빌드의 경우, sudoers 파일에 다음 줄이 있는지 확인하세요. 다른 Linux 배포판에서는 무시하세요:

#includedir /etc/sudoers.d

sudoers 파일에서 # 기호는 일반적으로 주석을 나타내는 데 사용됩니다. 그러나 이 맥락에서 #includedir는 지시문이며 주석이 아닙니다.

Debian 기반 시스템에서는 유사한 목적을 수행하는 @includedir /etc/sudoers.d를 사용할 수 있습니다. 운영 체제에 맞는 올바른 지시문을 사용해야 합니다.

4단계/4 호스트 사용자 생성 테스트#

tsh를 통해 원격 노드에 연결하고 호스트 사용자 생성이 활성화된 경우, Teleport SSH 서비스는 호스트에 사용자를 자동으로 생성합니다:

$ tsh login
$ tsh ssh nginxrestarter@develnode
$ grep "nginxrestarter" /etc/passwd
# nginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash
$ grep "other" /etc/group
# other:x:1002:nginxrestarter
$ exit
$ tsh ssh admin@develnode # checking the user was deleted after logout
$ grep "nginxrestarter" /etc/passwd
$ echo $?
# 1

위 사용자가 로그인하면, nginxrestarter 사용자와 아직 존재하지 않는 모든 그룹이 호스트에 생성됩니다. nginxrestarter 사용자는 host_groups 필드에 지정된 대로 ubuntu, nginx, other 그룹에 추가됩니다.

정적 호스트 사용자#

이 섹션에서는 SSH 세션과 무관하게 로컬 사용자를 생성하도록 Teleport를 구성합니다. 정적 호스트 사용자를 사용하려면 Auth 서버, SSH 서비스, tctl에서 Teleport 버전 16.3.0 이상이 필요합니다.

1단계/3. RBAC 구성#

서버에 라벨 지정#

1. 이 가이드를 시작하기 전에 Teleport로 등록한 서버에 접근하여, 기본적으로 /etc/teleport.yaml인 Teleport 구성 파일을 엽니다.

2. 구성 파일에 다음 변경 사항을 적용합니다:

     labels:
   +   app: "nginx"
   

3. 서버에서 Teleport를 재시작합니다.

Teleport 역할 정의#

다음 역할 사양은 사용자가 일치하는 모든 서버에서 nginxrestarter로 로그인할 수 있도록 허용합니다. auto-users.yaml이라는 파일에 이 내용을 추가하세요:

kind: role
version: v5
metadata:
  name: auto-users
spec:
  allow:
    logins: ["nginxrestarter"]
    node_labels:
      "app": "nginx"

역할을 생성합니다:

$ tctl create -f auto-users.yaml
# role 'auto-users' has been created

Teleport 사용자 생성#

1. 다음 명령을 실행하여 auto-users 역할을 가진 Teleport 사용자를 생성합니다:

   $ tctl users add demo-user --roles=auto-users --logins=nginxrestarter
   

2. 터미널에 표시되는 안내에 따라 Teleport Web UI를 방문하여 사용자를 생성합니다.

2단계/3. 정적 호스트 사용자 생성#

nginxrestarter.yaml이라는 파일에 다음 내용을 추가하세요:

kind: static_host_user
metadata:
  name: nginxrestarter
spec:
  matchers:
    # Use either node_labels or node_labels_expression to select which servers
    # to create the host user on. Only one is required.
    - node_labels:
      - name: app
        values: ["nginx"]
      node_labels_expression: 'labels["app"] == "nginx"'
      # List of host groups the created user will be added to. Any that don't already exist are created.
      groups: [ubuntu, nginx, other]
      # List of entries to include in a temporary sudoers file created in /etc/sudoers.d
      sudoers: [
        # This line will allow the `nginxrestarter` user to run
        # `systemctl restart nginx.service` as
        # root without requiring a password.
        # The sudoers entries will be prefixed with `nginxrestarter` in this case.
        # sudoers file reference documentation: https://www.sudo.ws/docs/man/1.8.17/sudoers.man/
        "ALL = (root) NOPASSWD: /usr/bin/systemctl restart nginx.service"
      ]
      # UID of the host user. Optional.
      # uid: 1234
      # GID of the host user. Optional.
      # gid: 1234
      # Default shell for the created user. Optional.
      # default_shell: /bin/bash
      # Whether or not static host user provisioning should automatically take ownership of existing users
      # created outside of Teleport. Optional.
      # take_ownership_if_user_exists: true

    # Add additional matchers if needed to configure nginxrestarter differently
    # on different servers.
    # - node_labels:
      # ...

정적 호스트 사용자 리소스의 이름은 생성할 사용자의 로그인과 일치해야 합니다. 서버는 하나의 정의된 매처(matcher)가 충족되는 경우에만 사용자를 프로비저닝합니다. 단일 정적 호스트 사용자 리소스에 대해 여러 개의 매치가 있거나, 사용자가 이미 존재하고 take_ownership_if_user_exists가 true로 설정되지 않은 경우, 서버는 사용자 프로비저닝을 거부합니다.

정적 호스트 사용자를 생성합니다:

$ tctl create -f nginxrestarter.yaml
# static_host_user 'nginxrestarter' has been created

3단계/3. 테스트#

tsh를 통해 원격 노드에 연결하여 호스트 사용자가 생성되었는지 확인합니다:

$ tsh login
$ tsh ssh nginxrestarter@develnode
$ grep "nginxrestarter" /etc/passwd
# nginxrestarter:x:1001:1003::/home/nginxrestarter:/bin/bash
$ grep "other" /etc/group
# other:x:1002:nginxrestarter

내부 동작 원리#

Teleport SSH 서비스는 호스트에 새 사용자를 생성하기 위해 useradd를 실행하며, useradd 바이너리를 찾을 수 없는 경우 오류를 반환합니다. useradd 명령은 Teleport 사용자의 역할에 지정된 그룹에 사용자를 추가하며, Teleport는 별도로 새 호스트 사용자의 이름으로 새 홈 디렉터리를 생성합니다.

SSH 서비스는 사용자를 추가할 때 useradd --no-create-home --home-dir <home> <username> --groups <groups> --uid <uid> --gid <gid>를 실행하며, 다른 모든 옵션은 시스템 기본값을 사용합니다. 예를 들어, 사용자는 호스트의 기본 로그인 셸과 연결되며, 이는 /etc/default/useradd에서 SHELL 필드를 설정하여 지정할 수 있습니다. 기본 동작에 대한 전체 설명은 시스템의 useradd 매뉴얼을 참조하세요.

Teleport SSH 서비스는 또한 /etc/sudoers.d에 파일을 생성하며, 이 파일에는 host_sudoers의 내용이 한 줄에 하나씩, 로그인한 사용자의 사용자 이름을 각 항목 앞에 붙여 작성됩니다.

이후 세션은 평소대로 진행됩니다. SSH 세션이 종료되면, 사용자와 홈 디렉터리는 머신에 그대로 유지됩니다. 역할 정의에서 create_host_user_mode를 insecure-drop으로 설정하여 자동 호스트 사용자를 제거할 수도 있습니다. 그러나 사용자 ID가 시스템에서 재사용될 가능성이 있어 여러 보안 위험이 발생할 수 있으므로, 특별한 필요가 있고 그 영향을 이해하고 있는 경우가 아니라면 keep 모드를 사용하는 것을 권장합니다.

세션이 진행 중인 동안 Teleport SSH 인스턴스가 재시작되면, 다음 Teleport 재시작 시 사용자가 정리됩니다.

관리되지 않는 사용자 마이그레이션#

이전 버전 Teleport의 keep 모드 사용자#

v14.3.24, v15.4.16, v16.1.8 이전에 create_host_user_mode: keep으로 생성된 자동 호스트 사용자는 이후 버전의 Teleport에서 관리되지 않습니다. 다음 세션에서 이러한 사용자를 자동으로 마이그레이션하려면, 역할의 host_groups에 teleport-keep을 추가하면 됩니다. 호스트 사용자는 마이그레이션하려는 호스트에서 직접 teleport-keep 그룹에 추가하여 수동으로도 마이그레이션할 수 있습니다.

정적 호스트 사용자#

기본적으로 정적 호스트 사용자 프로비저닝은 Teleport 외부에서 생성된 기존 사용자의 소유권을 가져오지 않습니다. Teleport가 정적 호스트 사용자와 충돌하는 관리되지 않는 사용자의 소유권을 자동으로 가져오도록 구성하려면, 정적 호스트 사용자 리소스에서 take_ownership_if_user_exists 플래그를 true로 설정하면 됩니다. 이렇게 하면 기존 사용자가 Teleport의 관리 하에 들어오고 해당 사용자에게 할당된 그룹이 재정의됩니다. teleport-keep 사용자를 마이그레이션하는 것과 마찬가지로, 호스트에서 직접 teleport-static 그룹에 사용자를 추가하여 수동으로 마이그레이션하는 것도 가능합니다.

다음 단계#

• 데이터베이스 접근에 대한 자동 사용자 프로비저닝을 구성합니다.
• 데스크톱 접근에 대한 자동 사용자 프로비저닝을 구성합니다.
• Terraform을 사용하여 자동 사용자 프로비저닝을 구성합니다. Terraform 공급자(provider)를 사용할 때 일부 값이 이 가이드에서 설명한 것과 다를 수 있다는 점에 유의하세요.