디렉터리 공유는 보안을 손상시키지 않고 로컬 머신과 원격 데스크톱 간에 파일을 이동하고 해당 파일에 변경 사항을 적용하기 쉽게 만드는 Teleport 기능입니다.

이 가이드에서는 연결된 Windows 데스크톱에서 디렉터리를 공유하고, 해당 디렉터리의 파일을 편집한 다음, 디렉터리 공유를 비활성화하도록 Teleport 역할을 구성합니다.

작동 방식#

원격 데스크톱 세션 중에 로컬 워크스테이션의 폴더를 원격 데스크톱과 공유하도록 선택할 수 있습니다. 세션 기간 동안 원격 데스크톱이나 워크스테이션의 폴더 변경 사항이 두 머신에 모두 반영됩니다.

공유 디렉터리를 사용하면 원격 Windows 데스크톱에서 로그 파일을 다운로드하거나, 구성 파일을 편집하거나, 다른 파일 조작을 편리하게 수행할 수 있습니다. 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 데스크톱 서비스. 아직 데스크톱 접근을 구성하지 않았다면, 이 가이드를 시작하기 전에 데스크톱 접근 시작하기를 먼저 읽어보세요.

• 로컬 머신에 Teleport Connect 앱 또는 브라우저. 브라우저는 Teleport가 디렉터리 공유에 사용하는 File System Access API를 지원해야 합니다. Google Chrome, Brave, Microsoft Edge와 같은 Chromium 기반 브라우저의 최신 버전을 지원합니다.

  Brave 사용자는 brave://flags/#file-system-access-api로 이동하여 "Enable"을 선택하면 File System Access API를 활성화할 수 있습니다.

  전체 호환성 표는 Mozilla Developer Network 문서에서 확인할 수 있습니다.

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 명령을 실행할 수도 있습니다.

Step 1/4. 디렉터리 공유하기#

디렉터리를 공유하려면 Teleport Web UI 또는 Teleport Connect를 열고 데스크톱을 찾은 다음 'Connect'를 클릭하여 세션을 시작합니다.

세션이 시작되면 화면 오른쪽 상단의 점 3개 메뉴를 클릭하고 "Share Directory"를 클릭합니다.

공유할 수 있는 디렉터리의 제한 사항#

공유 금지 디렉터리 (Web UI 전용)#

보안상의 이유로, 웹 브라우저의 파일시스템 접근 API는 "Desktop", "Documents"와 같이 일반적으로 사용되는 사용자 디렉터리의 표준 위치는 물론, 운영체제 자체에서 더 일반적으로 사용되는 중요 디렉터리를 포함하여 특정 디렉터리를 공유하지 못하도록 금지합니다.

차단된 사용자 디렉터리의 전체 목록은 File System Access 사양을 참조하세요.

이러한 차단된 사용자 디렉터리 내부의 하위 디렉터리는 여전히 공유할 수 있습니다.

긴 디렉터리 이름#

테스트 결과, 모든 경로 세그먼트를 포함한 이름이 640자 이상인 디렉터리를 공유하면 디렉터리 공유에서 예기치 않은 오류가 발생하는 것으로 확인되었습니다.

디렉터리를 공유한 후에는#

브라우저를 사용하여 디렉터리를 공유하는 경우, 변경 사항을 적용할 수 있도록 권한을 부여하라는 메시지가 표시됩니다. 디렉터리 공유를 활성화하려면 이 메시지를 수락해야 합니다.

권한을 부여하면 원격 데스크톱의 파일 탐색기에 새 디렉터리가 표시됩니다. 이 디렉터리는 로컬 머신의 디렉터리와 이름이 같지만, 이름 뒤에 "on teleport"가 추가됩니다.

한 번에 하나의 디렉터리만 공유할 수 있습니다.

Step 2/4. 디렉터리의 파일 편집하기#

로컬 머신과 원격 데스크톱 간에 파일과 파일 수정 사항을 쉽게 공유할 수 있습니다.

원격 측에서 편집하기#

원격 측의 공유 디렉터리에서 파일을 생성, 편집 또는 삭제하면 이러한 변경 사항이 로컬 머신의 디렉터리에 적용됩니다.

원격 측에서 파일을 공유 디렉터리로 이동하면 해당 파일이 로컬 측에도 나타납니다. 그리고 원격 측에서 디렉터리 밖으로 파일을 이동하면 원격 데스크톱이 해당 파일을 복사하여 공유 디렉터리 내에 유지합니다.

또한 공유 디렉터리 내의 한 하위 디렉터리에서 파일을 복사하여 다른 하위 디렉터리에 붙여넣을 수 있으며, 로컬 측에도 변경 사항이 반영됩니다.

로컬 측에서 편집하기#

로컬 머신의 공유 디렉터리에서 파일을 생성, 편집, 삭제할 수 있으며, 하위 디렉터리 간에 파일을 이동할 수도 있습니다.

로컬에서 변경한 사항을 원격 측에서 확인하려면 원격 디렉터리를 새로 고침하거나 다시 열어야 하며, 또는 로컬에서 변경한 개별 파일을 다시 열어야 합니다. 이렇게 하면 원격 데스크톱이 로컬 머신에서 디렉터리의 현재 상태를 요청합니다.

파일 크기 제한#

공유 디렉터리로 대용량 파일을 이동하는 성능은 네트워크 상태에 따라 달라지며, 파일 편집 성능은 파일 편집에 사용하는 프로그램에 따라 달라집니다.

공유 디렉터리 내 파일에는 크기 제한이 없지만, 네트워크 대역폭과 시스템 리소스에 미치는 영향을 줄이기 위해 32MB 이하의 파일을 조작하는 것을 권장합니다.

Step 3/4. 연결 해제#

디렉터리 공유를 중단하려면 원격 데스크톱 세션을 종료합니다. 데스크톱 세션 화면 오른쪽 상단의 점 3개 메뉴로 이동하여 "Disconnect"를 클릭합니다.

다음에 원격 데스크톱에서 세션을 시작할 때는 디렉터리가 더 이상 공유되지 않습니다. 해당 콘텐츠에 접근하려면 디렉터리를 다시 공유해야 합니다.

Step 4/4. 디렉터리 공유 비활성화#

Teleport Auth 서비스는 데스크톱 세션을 시작하는 사용자의 역할을 기반으로 원격 데스크톱에서 디렉터리 공유에 대한 접근 권한을 부여합니다.

Teleport 역할은 기본적으로 디렉터리 공유를 활성화합니다. 사용자의 Teleport 역할 중 하나가 디렉터리 공유를 비활성화하면, 해당 사용자에 대해 디렉터리 공유가 비활성화됩니다.

Teleport 사용자에 대해 디렉터리 공유를 비활성화하려면 role.yaml이라는 파일에 다음과 유사한 역할을 정의합니다.

kind: role
version: v5
metadata:
  name: "no-sharing"
spec:
  options:
    desktop_directory_sharing: false

역할을 생성합니다.

$ tctl create -f role.yaml

인증 공급자에 맞는 적절한 명령을 실행하여 no-sharing 역할을 your Teleport user에게 할당하십시오:

Local User

1. 로컬 사용자의 역할을 쉼표로 구분된 목록으로 가져옵니다:

   $ ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')
   

2. 로컬 사용자를 편집하여 새 역할을 추가합니다:

   $ tctl users update $(tsh status -f json | jq -r '.active.username') \
     --set-roles "${ROLES?},no-sharing"
   

3. Teleport 클러스터에서 로그아웃한 다음 다시 로그인하여 새 역할을 적용합니다.

GitHub

1. 텍스트 편집기에서 github 인증 커넥터를 엽니다:

   $ tctl edit github/github
   

2. github 커넥터를 편집하여 teams_to_roles 섹션에 no-sharing을 추가합니다.

   이 역할에 매핑해야 할 팀은 조직의 역할 기반 액세스 제어(RBAC)를 어떻게 설계했는지에 따라 달라집니다. 다만, 해당 팀은 여러분의 사용자 계정을 포함해야 하며 조직 내에서 가능한 한 가장 작은 팀이어야 합니다.

   다음은 예시입니다:

     teams_to_roles:
       - organization: octocats
         team: admins
         roles:
           - access
   +       - no-sharing
   

3. 편집기에서 파일을 저장하고 닫아 변경 사항을 적용합니다.

4. Teleport 클러스터에서 로그아웃한 다음 다시 로그인하여 새 역할을 적용합니다.

SAML

1. saml 구성 리소스를 가져옵니다:

   $ tctl get --with-secrets saml/mysaml > saml.yaml
   

   --with-secrets 플래그는 spec.signing_key_pair.private_key 값을 saml.yaml 파일에 추가한다는 점에 유의하십시오. 이 키에는 민감한 값이 포함되어 있으므로, 리소스를 업데이트한 직후 saml.yaml 파일을 삭제해야 합니다.

2. saml.yaml을 편집하여 attributes_to_roles 섹션에 no-sharing을 추가합니다.

   이 역할에 매핑해야 할 속성은 조직의 역할 기반 액세스 제어(RBAC)를 어떻게 설계했는지에 따라 달라집니다. 다만, 해당 그룹은 여러분의 사용자 계정을 포함해야 하며 조직 내에서 가능한 한 가장 작은 그룹이어야 합니다.

   다음은 예시입니다:

     attributes_to_roles:
       - name: "groups"
         value: "my-group"
         roles:
           - access
   +       - no-sharing
   

3. 변경 사항을 적용합니다:

   $ tctl create -f saml.yaml
   

4. Teleport 클러스터에서 로그아웃한 다음 다시 로그인하여 새 역할을 적용합니다.

OIDC

1. oidc 구성 리소스를 가져옵니다:

   $ tctl get oidc/myoidc --with-secrets > oidc.yaml
   

   --with-secrets 플래그는 spec.signing_key_pair.private_key 값을 oidc.yaml 파일에 추가한다는 점에 유의하십시오. 이 키에는 민감한 값이 포함되어 있으므로, 리소스를 업데이트한 직후 oidc.yaml 파일을 삭제해야 합니다.

2. oidc.yaml을 편집하여 claims_to_roles 섹션에 no-sharing을 추가합니다.

   이 역할에 매핑해야 할 클레임은 조직의 역할 기반 액세스 제어(RBAC)를 어떻게 설계했는지에 따라 달라집니다. 다만, 해당 그룹은 여러분의 사용자 계정을 포함해야 하며 조직 내에서 가능한 한 가장 작은 그룹이어야 합니다.

   다음은 예시입니다:

     claims_to_roles:
       - name: "groups"
         value: "my-group"
         roles:
           - access
   +       - no-sharing
   

3. 변경 사항을 적용합니다:

   $ tctl create -f oidc.yaml
   

4. Teleport 클러스터에서 로그아웃한 다음 다시 로그인하여 새 역할을 적용합니다.

다음 단계#

추가 자료#

디렉터리 공유는 원격 데스크톱에서 파일을 편집하는 강력한 도구이므로, 사후 인시던트 회고를 수행하거나 의도하지 않은 사용을 조사할 수 있도록 포괄적인 감사 추적을 확보하는 것이 좋습니다. 데스크톱 접근을 위한 세션 녹화를 설정하는 방법을 알아보세요.

디렉터리 공유 외에도 Teleport 데스크톱 서비스를 사용하면 클립보드의 콘텐츠를 원격 데스크톱과 공유할 수 있습니다. 클립보드 공유를 사용하는 방법을 알아보세요.

디렉터리 공유 작동 방식#

브라우저에서#

디렉터리 공유는 로컬 워크스테이션의 브라우저와 원격 Windows 데스크톱을 포함합니다.

원격 측에서 디렉터리 공유는 원격 데스크톱 프로토콜(Remote Desktop Protocol, RDP) 내의 파일시스템 관련 메시징을 활용합니다. 로컬 측에서 Teleport Web UI는 브라우저의 File System Access API를 사용하여 사용자가 선택한 로컬 디렉터리를 읽고 씁니다.

Teleport Web UI는 Teleport 프록시 서비스와 안전한 WebSocket 세션을 설정하며, 프록시 서비스는 해당 트래픽을 관련 Teleport 데스크톱 서비스 인스턴스로 전달합니다.

Teleport 데스크톱 서비스는 Teleport 데스크톱 프로토콜(Teleport Desktop Protocol, TDP)을 구현하여 Web UI가 원격 데스크톱과 통신할 수 있게 하며, 이 프로토콜은 WebSocket 프로토콜과 RDP 사이의 추상화 계층을 생성합니다.

Teleport 데스크톱 서비스는 Teleport Web UI의 TDP 트래픽을 RDP 트래픽으로 변환하여 원격 데스크톱으로 전송합니다. 또한 데스크톱 서비스는 원격 데스크톱의 RDP 트래픽을 TDP 메시지로 변환하여 Teleport Web UI로 전송합니다. 이러한 메시지를 기반으로 Teleport Web UI는 공유 디렉터리에 대한 정보를 알리거나 수정을 수행합니다.

TDP에 대한 자세한 내용은 Teleport RFD 37에서, 디렉터리 공유가 이를 사용하는 방식은 RFD 67에서 확인할 수 있습니다.

Teleport Connect에서#

디렉터리 공유는 로컬 워크스테이션의 Teleport Connect 앱과 원격 Windows 데스크톱을 포함합니다.

원격 측에서 디렉터리 공유는 원격 데스크톱 프로토콜(RDP) 내의 파일시스템 관련 메시징을 활용합니다. 로컬 측에서 Teleport Connect는 Go의 네이티브 파일시스템 API를 사용하여 사용자가 선택한 디렉터리를 읽고 씁니다.

Teleport Connect는 Teleport 프록시 서비스에 안전한 mTLS 연결을 설정하며, 프록시 서비스는 해당 트래픽을 관련 Teleport 데스크톱 서비스 인스턴스로 전달합니다.

Web UI와 마찬가지로, Teleport Connect는 Teleport 데스크톱 프로토콜(TDP)을 사용하여 Teleport 데스크톱 서비스와 통신하며, 이 서비스는 다시 RDP를 통해 원격 데스크톱에 연결합니다.