웹 애플리케이션 접근

https://.

     `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에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

     ```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 설치판의 모든 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
     ```
   

 

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

• Teleport를 자체 호스팅하는 경우 시스템이 Teleport에 등록된 애플리케이션을 위한 TLS 인증서를 프로비저닝하도록 해야 합니다. 사용할 방법은 자체 호스팅 Teleport 배포에서 원래 TLS를 어떻게 설정했는지에 따라 달라지며, 이는 이 가이드의 범위를 벗어납니다.

  일반적으로, 프록시 서비스의 웹 주소(예: teleport.example.com)에 서명된 TLS 인증서를 프로비저닝하는 것과 동일한 시스템이 애플리케이션에 사용되는 와일드카드 주소(예: *.teleport.example.com)에 대한 인증서도 프로비저닝해야 합니다.

1/2단계. Teleport 애플리케이션 서비스 배포#

이 단계에서는 대상 애플리케이션을 프록시하도록 Teleport 애플리케이션 서비스를 구성한 다음, 이 서비스를 실행하기 위해 Teleport 에이전트를 배포합니다.

토큰 생성#

Teleport 애플리케이션 서비스가 클러스터에 조인하도록 인가하려면 조인 토큰이 필요합니다.

1. 단기 조인 토큰을 생성합니다. app-name은 애플리케이션의 이름으로, app-uri는 애플리케이션의 도메인 이름과 포트로 반드시 변경하세요:

   $ tctl tokens add \
       --type=app \
       --app-name=my-app \
       --app-uri=app.example.com:3000 \
       --ttl=1h
   

   이 명령은 TTL이 1시간인 조인 토큰을 생성합니다.

2. 토큰을 복사하여 Teleport 애플리케이션 서비스를 실행할 Linux 서버의 /tmp/token에 저장합니다.

Teleport 애플리케이션 서비스 설치#

Teleport 애플리케이션 서비스를 설치할 호스트에서 아래 지침을 따르세요:

Linux 서버에 Teleport Agent를 설치하려면:

권장 설치 방법은 클러스터 설치 스크립트입니다. 이 스크립트는 클러스터에 맞는 올바른 버전, 에디션, 설치 모드를 선택합니다.

1. teleport.example.com:443에 Teleport 클러스터의 호스트명과 포트를 할당하되, 스킴(https://)은 포함하지 마십시오.

2. 클러스터의 설치 스크립트를 실행하십시오:

   $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
   

Teleport 애플리케이션 서비스 구성#

1. Teleport 애플리케이션 서비스를 실행할 호스트에서, 다음 내용으로 /etc/teleport.yaml 파일을 생성합니다:

   version: v3
   teleport:
     join_params:
       token_name: "/tmp/token"
       method: token
     proxy_server: "teleport.example.com:443"
   auth_service:
     enabled: false
   proxy_service:
     enabled: false
   ssh_service:
     enabled: false
   app_service:
     enabled: true
     apps:
     - name: my-app
       uri: "app.example.com:3000"
       labels:
         env: "demo"
   

2. /etc/teleport.yaml을 편집하여 teleport.example.com:443을 Teleport 프록시 서비스 또는 Teleport Enterprise(Cloud) 계정의 호스트 및 포트(예: example.teleport.sh:443)로 바꿉니다.

3. app.example.com:3000을 여러분의 웹 애플리케이션의 호스트 및 포트에 맞게 변경합니다.

   app_service 필드는 Teleport 애플리케이션 서비스를 구성합니다. app_service.apps 내의 각 항목은 애플리케이션 구성입니다. labels 필드는 각 애플리케이션에 라벨을 할당합니다. 이 가이드의 뒷부분에서 시연할 것처럼, Teleport 라벨을 사용하여 사용자의 리소스 접근을 허용하거나 거부할 수 있습니다.

Teleport 애플리케이션 서비스 실행#

systemd 서비스를 생성하여 호스트가 부팅될 때 the Teleport Application Service이 자동으로 시작되도록 구성합니다. 지침은 the Teleport Application Service을 어떻게 설치했는지에 따라 다릅니다.

Package Manager

the Teleport Application Service을 실행할 호스트에서 Teleport를 활성화하고 시작합니다:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

TAR Archive

the Teleport Application Service을 실행할 호스트에서 Teleport용 systemd 서비스 구성을 생성하고, Teleport 서비스를 활성화한 후 Teleport를 시작합니다:

$ sudo teleport install systemd -o /etc/systemd/system/teleport.service
$ sudo systemctl enable teleport
$ sudo systemctl start teleport

systemctl status teleport로 the Teleport Application Service의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.

2/2단계. RBAC 구성 및 애플리케이션 접근#

1. 이전에 등록한 애플리케이션에 할당한 env:demo 라벨이 있는 애플리케이션에 대한 접근을 허용하는 demo-app-access라는 역할을 생성합니다:

   kind: role
   version: v7
   metadata:
     name: demo-app-access
   spec:
     allow:
       app_labels:
         env: "demo"
   

2. demo-app-access 역할을 가진 appuser라는 사용자를 생성합니다:

   $ tctl users add --roles=demo-app-access appuser
   

appuser가 Teleport 웹 UI를 통해 이전에 등록한 애플리케이션에 접근을 시도하면, Teleport 프록시 서비스는 Teleport로 서명된 JSON 웹 토큰과 함께 요청을 Teleport 애플리케이션 서비스로 전달합니다. 애플리케이션 서비스는 사용자의 역할을 확인하고, allow.app_labels의 값이 애플리케이션에 할당된 라벨 중 하나와 일치하므로, 애플리케이션 서비스는 요청을 애플리케이션으로 전달합니다.

1. appuser로 Teleport 웹 UI에 로그인합니다. 등록한 웹 애플리케이션을 방문할 수 있는 옵션이 표시됩니다.

고급 옵션#

애플리케이션 이름#

애플리케이션 이름은 유효한 하위 도메인이 되어야 합니다(63자 이하, 공백 없음, a-z 0-9 -만 허용). 또한 트러스티드 클러스터 환경에 배포하는 경우, 루트 클러스터와 리프 클러스터 전체에서 고유해야 합니다.

Teleport가 실행되면, 사용자는 app-name.proxy_public_addr.com(예: grafana.teleport.example.com)으로 애플리케이션에 접근할 수 있습니다. 적절한 DNS 항목을 구성하여 Teleport 프록시 서버를 가리키도록 하면, public_addr(예: grafana.acme.com)을 재정의할 수도 있습니다.

dumper 애플리케이션 실행#

테스트 및 디버깅 목적으로, "dumper"라는 내장 디버그 앱을 제공합니다. debug_app: true로 활성화할 수 있습니다.

app_service:
   enabled: true
   debug_app: true

dumper 앱은 응답에 모든 요청 헤더를 덤프합니다.

공개 주소 사용자 지정#

기본적으로 애플리케이션은 <app-name>.<proxy-host>:<proxy-port> 주소에서 사용할 수 있습니다. 공개 주소를 재정의하려면 public_addr 필드를 지정하세요:

- name: "jira"
  uri: "https://localhost:8001"
  # The public address must be a unique DNS name and not conflict with the Teleport cluster's public addresses.
  public_addr: "jira.example.com"

TLS 인증서 확인 건너뛰기#

Teleport는 애플리케이션이 제공하는 인증서가 신뢰할 수 있는 인증 기관에 의해 서명되었는지 확인합니다. 내부 애플리케이션에 자체 서명 인증서를 사용하는 경우, 이 확인 단계를 건너뛰려면 insecure_skip_verify: true를 사용하세요:

- name: "app"
  uri: "https://localhost:8443"
  public_addr: "app.example.com"
  insecure_skip_verify: true

하위 디렉터리로 딥링크#

일부 애플리케이션은 하위 디렉터리에서 사용할 수 있습니다. 예를 들어 쿠버네티스 대시보드가 있습니다. URI를 업데이트하여 하위 디렉터리를 포함해야 합니다:

- name: "k8s"
  uri: "http://10.0.1.60:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/#/overview"
  public_addr: "k8s.example.com"

리다이렉트 재작성#

내부 리다이렉트를 수행하는 웹 앱을 지원하기 위해, 애플리케이션 접근 기능은 리다이렉트 응답의 Location 헤더 호스트 이름을 애플리케이션의 공개 주소로 재작성하는 옵션을 제공합니다:

- name: "jenkins"
  uri: "https://localhost:8001"
  public_addr: "jenkins.example.com"
  rewrite:
    # Rewrite the "Location" header on redirect responses replacing the
    # host with the public address of this application.
    redirect:
    - "localhost"
    - "jenkins.internal.dev"

헤더 패스스루#

웹 애플리케이션으로 전달되는 요청에 추가 헤더를 삽입하도록 애플리케이션 접근을 구성할 수 있습니다.

- name: "dashboard"
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  rewrite:
    headers:
    # Inject a static header.
    - "X-Custom-Header: example"
    # Inject headers with internal/external user traits.
    - "X-Internal-Trait: {{internal.logins}}"
    - "X-External-Trait: {{external.env}}"
    # Inject header with Teleport-signed JWT token.
    - "Authorization: Bearer {{internal.jwt}}"
    # Override Host header.
    - "Host: dashboard.example.com"

kind: app
version: v3
metadata:
  name: "dashboard"
spec:
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  rewrite:
    headers:
      # Inject a static header.
      - name: X-Custom-Header
        value: example
      # Inject headers with internal/external user traits.
      - name: X-Internal-Trait
        value: "{{internal.logins}}"
      - name: X-External-Trait
        value: "{{external.env}}"
      # Inject header with Teleport-signed JWT token.
      - name: Authorization
        value: "Bearer {{internal.jwt}}"
      # Override Host header.
      - name: Host
        value: dashboard.example.com

이 방법으로 삽입된 헤더는 애플리케이션이 보낼 수 있는 같은 이름의 헤더를 재정의합니다. 다음 헤더는 예약되어 있으며 재작성할 수 없습니다:

• Teleport-Jwt-Assertion
• Cf-Access-Token
• X-Teleport-* 패턴과 일치하는 헤더
• X-Forwarded-* 패턴과 일치하는 헤더

재작성된 헤더 값은 역할 템플릿과 동일한 템플릿 변수를 지원합니다. 위의 예시에서, X-Internal-Trait 헤더에는 내부 사용자 트레이트 logins의 값이 채워지고, X-External-Trait 헤더에는 ID 공급자에서 가져온 사용자의 외부 env 트레이트 값이 채워집니다.

또한, {{internal.jwt}} 템플릿 변수는 사용자 아이덴티티 정보가 포함된 Teleport가 서명한 JWT 토큰으로 대체됩니다. 자세한 내용은 JWT와 통합하기를 참고하세요.

external 및 internal 트레이트를 Teleport가 채우는 방식을 포함하여 Teleport 역할 구성에 대한 자세한 내용은 접근 제어 레퍼런스를 참고하세요.

JWT 토큰 구성#

기본적으로 Teleport는 애플리케이션 액세스를 위해 생성되는 JWT에 사용자의 role과 trait을 포함하며, Teleport가 업스트림 web application으로 보내는 모든 요청에 Teleport-Jwt-Assertion 헤더가 함께 전송됩니다.

web application이 이러한 값을 필요로 하지 않거나, HTTP 헤더의 크기 제한을 초과하여 오류가 발생하는 경우 이 정보를 토큰에서 생략하도록 Teleport를 구성할 수 있습니다.

- name: "dashboard"
  uri: https://localhost:4321
  rewrite:
    # Specify whether to include roles or traits in the JWT.
    # Options:
    # - roles-and-traits: include both roles and traits
    # - roles: include only roles
    # - traits: include only traits
    # - none: exclude both roles and traits from the JWT token
    # Default: roles-and-traits
    jwt_claims: roles-and-traits
    headers:
    # Inject header with Teleport-signed JWT token.
    - "Authorization: Bearer {{internal.jwt}}"

Backends-for-Frontends 지원#

기본적으로 Teleport는 웹 UI에서 실행된 경우에만 요청된 앱에 대해 사용자를 인증하려고 시도합니다. 클라이언트 애플리케이션이 마찬가지로 Teleport로 보호되는 다른 백엔드 애플리케이션에 요청을 보내는 경우, 사용자가 두 앱 모두에 인증하기 전까지는 클라이언트 애플리케이션이 해당 백엔드 애플리케이션에 요청을 보낼 수 없습니다. 이를 해결하려면, 클라이언트 앱의 스펙에 있는 required_apps 필드에 백엔드 애플리케이션 이름을 추가할 수 있으며, 그러면 사용자가 클라이언트 애플리케이션을 실행할 때 나열된 각 필수 앱에 대해 자동으로 인증을 시도합니다.

- name: 'dashboard'
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  # Optional list of Teleport application names that require a session for this app to function correctly.
  # When launching this app, any app listed here will also be launched, and a session will be created.
  # These sessions follow their respective RBAC policies.
  required_apps:
    - 'my-api'
    - 'prod-database'
    # Add more required app names as needed

프리플라이트 요청을 위한 CORS 지원#

Teleport는 대상 앱으로 인증되지 않은 요청을 전혀 보내지 않습니다. 이는 Teleport 내에서 한 애플리케이션이 API 요청을 위해 다른 애플리케이션으로 보내는 프리플라이트 요청은 오류를 반환하며 실패한다는 것을 의미합니다. 이러한 프리플라이트 요청에 응답할 애플리케이션별 CORS 스펙을 지정할 수 있습니다. 이는 요청된 경로에 대한 대상 앱의 CORS 정책을 덮어쓰지 않으며, 요청된 경로로 보내지는 OPTION 요청에만 사용됩니다.

- name: 'dashboard'
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  # Optional CORS policy is used for preflight requests only. It does not overwrite the contained
  # app's CORS policy per route but is used by Teleport to respond to unauthenticated OPTION requests.
  # Important Notes:
  # - Each field in the CORS spec is optional.
  # - The allowed_headers field accepts wildcard entries. However, in requests with "allow_credentials: true",
  #   a wildcard is treated as the literal header name "*" without special semantics.
  # - The Authorization header can't be set with a wildcard and always needs to be listed explicitly.
  cors:
    # Specifies which origins are allowed to make cross-origin requests.
    allowed_origins:
      - 'https://example.com'
      - 'https://app.example.com'
    # HTTP methods that are allowed when accessing the resource.
    allowed_methods:
      - 'GET'
      - 'POST'
      - 'PUT'
      - 'DELETE'
      - 'OPTIONS'
    # HTTP headers that can be used during the actual request.
    allowed_headers:
      - 'Content-Type'
      - 'Authorization'
      - 'X-Custom-Header'
    # Headers that browsers are allowed to access.
    exposed_headers:
      - 'Content-Type'
      - 'X-Custom-Response-Header'
    # Indicates whether the request can include credentials.
    allow_credentials: true
    # Indicates how long (in seconds) the results of a preflight request can be cached.
    max_age: 3600

Teleport에서 애플리케이션 확인#

Teleport는 연결된 애플리케이션을 빠르게 실행할 수 있는 UI를 제공합니다.

클러스터의 웹 UI로 이동하여 "Applications" 탭을 선택하면 애플리케이션을 확인할 수 있습니다. URL 구조는 다음과 같습니다:

https://[cluster-url:cluster-port]/web/cluster/[cluster-name]/apps

애플리케이션 로그아웃#

애플리케이션에 로그인하면, 정의된 RBAC에 따라 인증서와 로그인 세션을 받게 됩니다. 이 기간이 끝나기 전에 강제로 로그아웃하려면 /teleport-logout 엔드포인트를 호출하면 됩니다:

• https://internal-app.teleport.example.com/teleport-logout

다음 단계#

• 웹 앱을 VNet을 통해 접근하도록 TCP 앱으로 구성하는 방법을 알아보세요.