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

  일반적으로 Proxy Service의 웹 주소(예: 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 애플리케이션 서비스를 설치할 호스트에서 아래 지침을 따르세요:

To install a Teleport Agent on your Linux server:

The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

1. Assign to your Teleport cluster hostname and port, but not the scheme (https://).

2. Run your cluster's install script:

   $ curl "https:///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 애플리케이션 서비스 실행#

Configure the Teleport Application Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Application Service.

You can check the status of the Teleport Application Service with systemctl status teleport and view its logs with 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)에서 앱에 접근할 수 있습니다. Teleport 프록시 서버를 가리키도록 적절한 DNS 항목을 구성하는 경우 public_addr(예: grafana.acme.com)을 재정의할 수도 있습니다.

덤퍼 애플리케이션 실행#

테스트 및 디버깅 목적으로, "dumper"라는 기본 제공 디버그 앱을 제공합니다. debug_app: true를 사용하여 활성화할 수 있습니다.

app_service:
   enabled: true
   debug_app: true

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

공개 주소 사용자 지정#

기본적으로 애플리케이션은 <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

하위 디렉터리에 딥링크#

일부 애플리케이션은 하위 디렉터리에서 사용할 수 있습니다. 예를 들어 Kubernetes Dashboard가 있습니다. 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}} 템플릿 변수는 사용자 ID 정보를 포함하는 Teleport가 서명한 JWT 토큰으로 대체됩니다. 자세한 내용은 JWT 통합을 참조하세요.

외부 및 내부 특성을 Teleport가 채우는 방법을 포함하여 Teleport 역할 구성에 대한 자세한 내용은 접근 제어 참조를 참조하세요.

JWT 토큰 구성#

By default, Teleport includes a user's roles and traits in the JWT generated for application access, and the Teleport-Jwt-Assertion header is sent along with every request that Teleport makes to an upstream web application.

If your web application doesn't care about these values, or you are encountering an error due to exceeding the size limit of HTTP headers, you can configure Teleport to omit this information from the token.

- 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}}"

프론트엔드를 위한 백엔드 지원#

기본적으로 Teleport는 웹 UI에서 시작할 때만 요청된 앱에 대해 사용자를 인증하려고 시도합니다. 이것이 Teleport로 보호된 다른 백엔드 애플리케이션에 요청을 하는 클라이언트 애플리케이션인 경우, 사용자가 두 앱 모두로 인증할 때까지 클라이언트 애플리케이션은 해당 백엔드 애플리케이션에 요청을 할 수 없습니다. 이 문제를 해결하기 위해 클라이언트 앱의 spec에 있는 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는 대상 앱에 인증되지 않은 요청을 보내지 않습니다. 이는 API 요청을 위해 Teleport 내의 한 애플리케이션에서 다른 애플리케이션으로 보내는 프리플라이트 요청이 오류를 반환하고 실패함을 의미합니다. 이러한 프리플라이트 요청에 응답할 애플리케이션별 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 앱으로 접근하도록 웹 앱을 구성하는 방법을 알아봅니다.