웹 애플리케이션 접근 | Teleport 공식 기술 문서 한국판 by 인포그랩

웹 애플리케이션 접근

이 안내서는 역할 기반 접근 제어, 감사 로깅 및 기타 Teleport 기능을 설정하기 위해 웹 애플리케이션을 Teleport 클러스터에 등록하는 방법을 보여줍니다.

작동 방식

웹 애플리케이션을 Teleport 클러스터에 등록하기 위해 Teleport 애플리케이션 서비스를 배포하며, 이 서비스는 조인 토큰을 사용하여 Teleport 인증 서비스와 신뢰를 구축합니다. 사용자는 Teleport 웹 UI를 통해 Teleport로 보호되는 웹 애플리케이션에 방문합니다. Teleport 프록시 서비스는 브라우저 트래픽을 Teleport 애플리케이션 서비스로 라우팅하며, 이 서비스는 타겟 애플리케이션과 HTTP 요청을 주고받습니다.

전제 조건

실행 중인 Teleport 클러스터 버전 17.0.0-dev 이상. Teleport를 시작하려면 가입하여 무료 평가판을 이용하거나 데모 환경 설정 방법을 확인하십시오.
tctl 관리자 도구와 tsh 클라이언트 도구.

tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하십시오.

Teleport로 보호하려는 웹 애플리케이션. 웹 애플리케이션은 프라이빗 네트워크에서 실행되어야 합니다. 이 안내서에서는 웹 애플리케이션이 app.example.com:3000 에서 사용 가능하다고 가정합니다.
Teleport 애플리케이션 서비스를 실행할 Linux 서버. 여러분의 네트워크는 서버가 웹 애플리케이션에 연결할 수 있도록 설정되어야 합니다.
연결이 가능한지 확인하기 위해 tsh login 으로 로그인한 다음, 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  17.0.0-dev
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결할 수 있고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 후속 tctl 명령어를 실행할 수 있습니다.
자신의 Teleport 클러스터를 호스팅하는 경우, Teleport Auth Service를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

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

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

토큰 생성

Teleport 애플리케이션 서비스가 클러스터에 조인하기 위해서는 조인 토큰이 필요합니다.

단기 조인 토큰을 생성합니다. app-name 을 애플리케이션 이름으로, app-uri 를 애플리케이션의 도메인 이름과 포트로 변경해야 합니다:
```
tctl tokens add \    --type=app \    --app-name=my-app \    --app-uri=app.example.com:3000 \    --ttl=1h
```
이 명령은 TTL이 1시간인 조인 토큰을 생성합니다.
토큰을 복사하여 Teleport 애플리케이션 서비스를 실행할 Linux 서버의 /tmp/token 에 저장합니다.

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

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

Linux 서버에 Teleport 설치하기:

Teleport 에디션에 따라 edition를 다음 중 하나로 할당합니다:

에디션 값
Teleport Enterprise Cloud cloud
Teleport Enterprise (자가 호스팅) enterprise
Teleport Community Edition oss
설치할 Teleport 버전을 가져옵니다. 클러스터에서 자동 에이전트 업데이트가 활성화된 경우, 최신 Teleport 버전을 쿼리하여 업데이트된 내용과의 호환성을 확인합니다:
```
TELEPORT_DOMAIN=example.teleport.com
TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"
```
그렇지 않으면, Teleport 클러스터의 버전을 가져옵니다:
```
TELEPORT_DOMAIN=example.teleport.com
TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"
```
Linux 서버에 Teleport를 설치합니다:
```
curl https://cdn.teleport.dev/install-v15.4.11.sh | bash -s ${TELEPORT_VERSION} edition
```
설치 스크립트는 Linux 서버에서 패키지 관리자를 감지하고 이를 사용하여 Teleport 바이너리를 설치합니다. 설치를 사용자 정의하려면 설치 가이드에서 Teleport 패키지 리포지토리에 대해 알아보세요.

에디션	값
Teleport Enterprise Cloud	`cloud`
Teleport Enterprise (자가 호스팅)	`enterprise`
Teleport Community Edition	`oss`

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

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

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

/etc/teleport.yaml 에서 teleport.example.com:443 를 Teleport 프록시 서비스 또는 Teleport Enterprise(클라우드) 계정의 호스트 및 포트로 교체합니다. 예: example.teleport.sh:443 .
app.example.com:3000 을 자신의 웹 애플리케이션의 호스트 및 포트에 맞게 변경합니다.

app_service 필드는 Teleport 애플리케이션 서비스를 구성합니다. app_service.apps 내의 각 항목은 애플리케이션 구성입니다. labels 필드는 각 애플리케이션에 레이블을 할당합니다. 나중에 이 안내서에서 보여줄 것처럼 Teleport 레이블을 사용하여 사용자가 리소스에 접근할 수 있도록 허용하거나 거부할 수 있습니다.

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

호스트가 부팅될 때 Teleport 애플리케이션 서비스가 자동으로 시작되도록 systemd 서비스를 생성하여 구성합니다. 지침은 Teleport 애플리케이션 서비스를 설치한 방법에 따라 다릅니다.

Teleport 애플리케이션 서비스를 실행할 호스트에서 Teleport를 활성화하고 시작합니다:

sudo systemctl enable teleport
sudo systemctl start teleport

Teleport 애플리케이션 서비스를 실행할 호스트에서 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 로 Teleport 애플리케이션 서비스의 상태를 확인하고, journalctl -fu teleport 로 로그를 볼 수 있습니다.

2/3단계. [선택 사항] 웹 애플리케이션의 TLS 및 DNS 구성

Teleport 애플리케이션 서비스가 웹 애플리케이션에 트래픽을 프록시하는 동안, Teleport 프록시 서비스는 다음 URL에서 애플리케이션을 사용할 수 있게 합니다:

https://<APPLICATION_NAME>.<TELEPORT_DOMAIN>

예를 들어, Teleport 도메인 이름이 teleport.example.com 인 경우, my-app 이라는 이름의 애플리케이션은 https://my-app.teleport.example.com 에서 사용할 수 있습니다. 프록시 서비스는 이 도메인 이름에 대해 브라우저가 인증 기관에 대해 검증할 수 있는 TLS 인증서를 제공합니다.

Teleport Enterprise(Cloud)를 사용 중인 경우, 이 도메인 이름에 대한 DNS 레코드와 TLS 인증서는 자동으로 제공됩니다. Teleport를 자체 호스팅하는 경우, 이를 스스로 구성해야 합니다:

다음 중 하나를 생성합니다:
- Teleport 프록시 서비스 도메인의 와일드카드 하위 도메인(예: *.teleport.example.com )과 Teleport 프록시 서비스의 IP 주소를 연결하는 DNS A 레코드.
- Teleport 프록시 서비스 도메인의 와일드카드 하위 도메인(예: *.teleport.example.com )과 Teleport 프록시 서비스의 도메인 이름을 연결하는 DNS CNAME 레코드.
시스템에서 Teleport에 등록된 애플리케이션을 위한 TLS 인증서를 프로비저닝하는지 확인합니다. 사용할 방법은 자체 호스팅 Teleport 배포를 설정한 방법에 따라 다르며, 이 가이드의 범위를 벗어납니다.

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

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

이전에 등록한 애플리케이션에 할당한 env:demo 레이블이 있는 애플리케이션에 대한 액세스를 허용하는 demo-app-access 라는 역할을 생성합니다:
```
kind: role
version: v7
metadata:
  name: demo-app-access
spec:
  allow:
    app_labels:
      env: "demo"
```
demo-app-access 역할을 가진 appuser 라는 사용자를 생성합니다:
```
tctl users add --roles=demo-app-access appuser
```
appuser 가 이전에 등록한 애플리케이션에 Teleport Web UI를 통해 접근할 때, Teleport 프록시 서비스는 Teleport 서명된 JSON 웹 토큰과 함께 요청을 Teleport 애플리케이션 서비스로 전송합니다. 애플리케이션 서비스는 사용자의 역할을 확인하며, allow.app_labels 의 값이 애플리케이션에 할당된 레이블 중 하나와 일치하기 때문에 애플리케이션 서비스는 요청을 애플리케이션으로 전달합니다.
appuser 로 Teleport Web 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"라는 내장 디버그 앱을 제공합니다.
debug_app: true 를 사용하여 활성화할 수 있습니다.

app_service:
  enabled: yes
  debug_app: true

덤퍼 애플리케이션은 응답에 모든 요청 헤더를 덤프합니다.

공개 주소 사용자 정의

자체 호스팅 환경 전용

클라우드 호스팅된 Teleport 테넌트에서는 TLS 인증서 제한으로 인해 앱의 공개 주소를 변경하거나 재정의할 수 없습니다.

클라우드 호스팅 고객의 경우, 앱은 항상 https://<app-name>.example.teleport.sh 에서 사용할 수 있으며, 여기서 example 은 클라우드 호스팅 Teleport 테넌트에 대해 선택한 이름입니다.

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

- name: "jira"
  uri: "https://localhost:8001"
  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 대시보드가 있습니다. 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:
    # 리다이렉트 응답에서 "Location" 헤더를 재작성하여
    # 호스트를 이 애플리케이션의 공개 주소로 바꿉니다.
    redirect:
      - "localhost"
      - "jenkins.internal.dev"

헤더 패스스루

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

teleport.yaml 구성에서 정의된 앱의 경우, 각 앱의 headers 필드는 문자열 목록입니다. 전체 값을 따옴표로 묶어 정확하게 구문 분석되도록 주의하십시오.

- name: "dashboard"
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  rewrite:
    headers:
      # 정적 헤더를 삽입합니다.
      - "X-Custom-Header: example"
      # 내부/외부 사용자 특성과 함께 헤더를 삽입합니다.
      - "X-Internal-Trait: {{internal.logins}}"
      - "X-External-Trait: {{external.env}}"
      # Teleport 서명 JWT 토큰으로 헤더를 삽입합니다.
      - "Authorization: Bearer {{internal.jwt}}"
      # Host 헤더를 재정의합니다.
      - "Host: dashboard.example.com"

동적 app 리소스에서는 spec.rewrite.headers 필드를 사용하여 헤더 재작성을 구성합니다. 값은 재작성하고자 하는 각 헤더의 이름과 값을 지정하는 매핑 목록입니다.

kind: app
version: v3
metadata:
  name: "dashboard"
spec:
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  rewrite:
    headers:
      # 정적 헤더를 삽입합니다.
      - name: X-Custom-Header
        value: example
      # 내부/외부 사용자 특성과 함께 헤더를 삽입합니다.
      - name: X-Internal-Trait
        value: "{{internal.logins}}"
      - name: X-External-Trait
        value: "{{external.env}}"
      # Teleport 서명 JWT 토큰으로 헤더를 삽입합니다.
      - name: Authorization
        value: "Bearer {{internal.jwt}}"
      # Host 헤더를 재정의합니다.
      - name: Host
        value: dashboard.example.com

이렇게 주입된 헤더는 애플리케이션에서 보낼 수 있는 동일한 이름의 헤더를 재정의합니다. 재작성할 수 없는 예약된 헤더는 다음과 같습니다:

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

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

추가로, {{internal.jwt}} 템플릿 변수는 사용자 신원 정보를 포함한 Teleport에서 서명한 JWT 토큰으로 대체됩니다. 자세한 내용은 JWT와 통합하기를 참조하십시오.

Teleport 역할 구성에 대한 전체 세부 정보는 Teleport 접근 제어 참고를 참조하십시오.

JWT 토큰 구성

기본적으로 Teleport는 애플리케이션 접근을 위해 생성된 JWT에 사용자의 역할 및 특성을 포함합니다. 애플리케이션이 이러한 값에 신경 쓰지 않거나, HTTP 헤더의 크기 제한을 초과하여 오류가 발생하는 경우, Teleport가 이 정보를 토큰에서 생략하도록 구성할 수 있습니다.

- name: "dashboard"
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  rewrite:
    # JWT에 역할 또는 특성을 포함할지 여부를 지정합니다.
    # 옵션:
    # - roles-and-traits: 역할과 특성을 모두 포함
    # - roles: 역할만 포함
    # - traits: 특성만 포함
    # - none: 역할과 특성을 모두 JWT 토큰에서 제외
    # 기본값: roles-and-traits
    jwt_claims: roles-and-traits
    headers:
      # Teleport 서명 JWT 토큰을 포함하도록 헤더 삽입.
      - "Authorization: Bearer {{internal.jwt}}"

Backends-for-Frontends 지원

기본적으로 Teleport는 웹 UI에서 실행될 때 요청된 앱에 대해 사용자 인증을 시도합니다. 만약 이 앱이 다른 백엔드 애플리케이션에 요청하는 클라이언트 애플리케이션이라면, 해당 백엔드 애플리케이션에 대해 사용자 인증이 완료되기 전까지 클라이언트 애플리케이션은 요청을 할 수 없습니다. 이를 해결하기 위해, 클라이언트 앱의 사양에서 required_apps 필드에 백엔드 애플리케이션 이름을 추가하면 사용자가 클라이언트 애플리케이션을 시작할 때 나열된 모든 필수 앱에 대해 자동으로 인증을 시도합니다.

- name: "dashboard"
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  # 이 앱이 올바르게 작동하는 데 세션이 필요한 Teleport 애플리케이션 이름의 선택적 목록입니다.
  # 이 앱을 시작할 때 여기 나열된 앱도 함께 시작되며, 세션이 생성됩니다.
  # 이러한 세션은 각각의 RBAC 정책을 따릅니다.
  required_apps:
    - "my-api"
    - "prod-database"
    # 필요한 앱 이름을 추가합니다.

사전 요청에 대한 CORS 지원

Teleport는 목적지 앱에 인증되지 않은 요청을 보내지 않습니다. 이는 API 요청을 위해 애플리케이션이 Teleport 내의 다른 애플리케이션에 보낸 모든 사전 요청이 오류를 반환하고 실패한다는 것을 의미합니다. 이러한 사전 요청에 응답할 CORS 사양을 각 애플리케이션에 지정할 수 있습니다. 이는 요청된 경로의 CORS 정책을 덮어쓰지 않지만, 요청된 경로에 보내진 OPTION 요청에 대해서만 사용됩니다.

- name: "dashboard"
  uri: https://localhost:4321
  public_addr: dashboard.example.com
  # 선택적 CORS 정책은 사전 요청에만 사용됩니다. 이는 포함된
  # 앱의 CORS 정책을 경로별로 덮어쓰지 않지만, Teleport가 인증되지 않은 OPTION 요청에 응답하는 데 사용됩니다.
  # 중요 사항:
  # - CORS 사양의 각 필드는 선택적입니다.
  # - allowed_headers 필드는 와일드카드 항목을 허용합니다. 그러나 "allow_credentials: true" 요청에서는
  #   와일드카드가 특별한 의미 없이 리터럴 헤더 이름 "*"으로 처리됩니다.
  # - Authorization 헤더는 와일드카드로 설정할 수 없으며 항상 명시적으로 나열해야 합니다.
  cors:
    # 어떤 출처가 크로스-오리진 요청을 할 수 있는지를 지정합니다.
    allowed_origins:
      - "https://example.com"
      - "https://app.example.com"
    # 자원에 접근할 때 허용되는 HTTP 방법입니다.
    allowed_methods:
      - "GET"
      - "POST"
      - "PUT"
      - "DELETE"
      - "OPTIONS"
    # 실제 요청 중에 사용될 수 있는 HTTP 헤더입니다.
    allowed_headers:
      - "Content-Type"
      - "Authorization"
      - "X-Custom-Header"
    # 브라우저가 접근할 수 있는 헤더입니다.
    exposed_headers:
      - "Content-Type"
      - "X-Custom-Response-Header"
    # 요청에 자격 증명을 포함할 수 있는지를 나타냅니다.
    allow_credentials: true
    # 사전 요청 결과를 얼마나 오랫동안(초 단위로) 캐시할 수 있는지를 나타냅니다.
    max_age: 3600

Teleport에서 애플리케이션 보기

Teleport는 연결된 애플리케이션을 빠르게 시작하기 위한 UI를 제공합니다.

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

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

애플리케이션 로그아웃

애플리케이션에 로그인하면 정의된 RBAC에 따라 인증서와 로그인 세션을 받게 됩니다. 이 기간 전에 강제로 로그아웃하려면 /teleport-logout 엔드포인트를 통해 수행할 수 있습니다:

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

다음 단계

VNet을 통해 접근하기 위해 웹 앱을 TCP 앱으로 구성하는 방법을 배웁니다.

Teleport 원문 보기