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

웹 애플리케이션 접근

전제 조건

실행 중인 Teleport 클러스터 버전 이상. Teleport를 시작하려면, 가입하기 위해 무료 평가판에 등록하거나 데모 환경 설정하기를 참조하세요.
tctl 관리 도구와 tsh 클라이언트 도구.

tctl과 tsh 다운로드에 대한 지침은 설치를 방문하세요.

당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  16.2.0
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다. 자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.
Grafana와 같은 연결할 웹 애플리케이션.
Teleport 애플리케이션 서비스를 실행할 호스트.

토큰 생성

클러스터에 가입하기 위해 Teleport 애플리케이션 서비스의 승인을 위해 가입 토큰이 필요합니다. 단기적인 가입 토큰을 생성하고 예를 들어 /tmp/token에 저장하세요:

로컬 머신에서 tctl을 사용할 수 있도록 tsh로 클러스터에 로그인합니다.
tsh login --user=myuser --proxy=teleport.example.com
tctl tokens add \    --type=app \    --app-name=grafana \    --app-uri=http://localhost:3000

TLS 요구 사항

TLS는 Teleport Access Platform과 모든 연결된 애플리케이션을 보호하는 데 필요합니다. Teleport를 설정할 때 최소 요구 사항은 Teleport Proxy Service를 위한 인증서와 이에 대한 와일드카드 인증서입니다. 여기에서 모든 사용자가 Teleport에 로그인합니다.

애플리케이션 접근 및 DNS

Teleport은 애플리케이션 접근을 위해 구성한 각 애플리케이션에 서브도메인을 할당합니다. 예를 들어, Grafana를 리소스로 등록하면 Teleport은 리소스를 grafana.teleport.example.com 서브도메인에 할당합니다.

Teleport 클러스터를 자체 네트워크에서 호스팅하는 경우, 애플리케이션 서브도메인을 반영하도록 DNS 구성을 업데이트해야 합니다.
DNS를 업데이트하는 방법은 두 가지가 있습니다:

서브도메인 이름에 대한 와일드카드 치환을 사용하여 단일 DNS 주소(A) 또는 정식 이름(CNAME) 레코드를 생성합니다. 예를 들어, *.teleport.example.com이라는 이름으로 DNS 레코드를 생성합니다.
각 애플리케이션 서브도메인에 대해 별도의 DNS 주소(A) 또는 정식 이름(CNAME) 레코드를 생성합니다.

DNS 수정은 인증 기관(예: Let's Encrypt)이 각 서브도메인에 대해 인증서를 발급할 수 있도록 하며, 클라이언트가 접근하는 애플리케이션에 관계없이 Teleport 호스트를 확인할 수 있도록 합니다.

Teleport 클라우드 플랫폼을 사용하는 경우, DNS 업데이트가 필요하지 않습니다. 왜냐하면 Teleport 클러스터가 자동으로 서브도메인과 서명된 TLS 인증서를 제공하기 때문입니다.

이 예에서:

teleport.example.com은 Teleport Auth Service 및 Teleport Proxy Service를 호스팅하며, 이는 Teleport Access Platform의 핵심 클러스터 서비스로 구성됩니다.
*.teleport.example.com은 모든 애플리케이션을 호스팅하며, 예를 들어 grafana.teleport.example.com입니다.

인터넷에서 Teleport를 실행하는 경우, Let's Encrypt를 사용하여 키와 인증서를 자동으로 받는 것을 권장합니다. 사설 네트워크나 맞춤형 배포의 경우, 자체 개인 키와 인증서를 사용하세요.

Let's Encrypt는 Teleport 클러스터의 도메인 이름을 제어하고 있는지 확인하기 위해
Teleport Proxy Service의 포트 443에서 수신 대기 중인 HTTPS 서버와 통신합니다.

Teleport Proxy Service를 구성하여 시작할 때 Let's Encrypt
확인 프로세스를 완료할 수 있습니다.

Teleport Auth Service와 Proxy Service를 시작할 호스트에서,
다음 teleport configure 명령을 실행하십시오.
tele.example.com을 Teleport 클러스터의 도메인
이름으로 지정하고 user@example.com을
알림에 사용할 이메일 주소로 지정하십시오 (어떤 도메인도 사용할 수 있습니다):

sudo teleport configure -o file \
    --acme --acme-email=user@example.com \      --cluster-name=tele.example.com

Teleport Proxy Service 호스트의 포트 443은 모든 출처의 트래픽을 허용해야 합니다.

Teleport 호스트에 유효한 개인 키와 인증서 체인을 /var/lib/teleport/privkey.pem
및 /var/lib/teleport/fullchain.pem에 각각 배치하십시오.

리프 인증서는 Teleport 호스트의 도메인에 해당하는 주제를 가져야 합니다. 예를 들어,
*.teleport.example.com.

Teleport Auth Service와 Proxy Service를 시작할 호스트에서,
다음 teleport configure 명령을 실행하십시오.
tele.example.com을 Teleport 클러스터의 도메인 이름으로 지정하십시오.

sudo teleport configure -o file \
    --cluster-name=tele.example.com \      --public-addr=tele.example.com:443 \      --cert-file=/var/lib/teleport/fullchain.pem \      --key-file=/var/lib/teleport/privkey.pem

사용자 생성

Teleport 사용자는 애플리케이션에 접근하기 위해 역할의 권한이 필요합니다. Teleport는 모든 앱에 접근을 허용하는 내장 access 역할을 제공합니다:

tctl users add --roles=access appuser

CLI 플래그로 애플리케이션 서비스 시작

Teleport를 설치합니다:

Linux 서버에 Teleport 설치하기:

Teleport 에디션에 따라 edition을(를) 다음 중 하나로 지정합니다:

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

에디션	값
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-v16.2.0.sh | bash -s ${TELEPORT_VERSION} edition
```
설치 스크립트는 Linux 서버에서 패키지 관리자를 감지하고 이를 사용하여 Teleport 바이너리를 설치합니다. 설치를 사용자 지정하려면 설치 가이드에서 Teleport 패키지 리포지토리에 대해 알아보세요.

단일 CLI 명령으로 Teleport 애플리케이션 서비스를 시작할 수 있습니다:

sudo teleport start \    --roles=app \    --token=/tmp/token \    --auth-server=teleport.example.com:3080 \    --app-name="grafana" \    --app-uri="http://localhost:3000" \    --labels=env=dev

--auth-server 플래그는 항상 클러스터의 프록시 엔드포인트를 가리켜야 합니다. 이는 애플리케이션 서비스가 항상 리버스 터널을 통해 클러스터에 연결하기 때문입니다.

애플리케이션 이름

애플리케이션 이름은 유효한 서브도메인이어야 합니다. (<=63자, 공백 없음, 허용되는 문자: a-z 0-9 -)

Teleport가 실행된 후, 사용자는 app-name.proxy_public_addr.com에서 앱에 접근할 수 있습니다. 예를 들어 grafana.teleport.example.com. 적절한 DNS 항목을 구성하면 public_addr을 재정의할 수도 있습니다. 예를 들어 grafana.acme.com.

구성 파일로 Teleport 애플리케이션 서비스 시작

예시 teleport.yaml 구성:

version: v3
teleport:
  # 애플리케이션 프록시 서비스의 데이터 디렉터리. Auth/Proxy 서비스와 동일한 노드에서 실행하는 경우
  # 서로 다른 데이터 디렉터리를 사용해야 합니다.
  data_dir: /var/lib/teleport-app
  # 클러스터와의 초기 등록 시 지정된 파일에서 인증 토큰을 로드하도록 서비스에 지시합니다.
  auth_token: /tmp/token
  # 연결할 프록시 주소. 이는 항상 프록시 주소여야 하며,
  # 애플리케이션 서비스는 항상 리버스 터널을 통해 클러스터에 연결됩니다.
  proxy_server: teleport.example.com:3080
app_service:
    enabled: yes
    # Teleport는 애플리케이션 접근이 올바르게 작동하는지 확인하는 데 사용할 수 있는 "dumper"라는 소규모 디버그 앱을 제공합니다.
    debug_app: true
    # 이 섹션에는 이 서비스에 의해 프록시된 모든 애플리케이션의 정의가 포함됩니다.
    # 여러 항목을 포함할 수 있습니다.
    apps:
      # 애플리케이션 이름. 식별 용도로 사용됩니다.
    - name: "grafana"
      # 애플리케이션이 사용 가능한 URI 및 포트.
      uri: "http://localhost:3000"
      # 선택적 애플리케이션 공개 주소를 재정의할 수 있습니다.
      public_addr: "grafana.teleport.example.com"
      # 애플리케이션에 할당할 선택적 정적 레이블. RBAC에서 사용됩니다.
      labels:
        env: "prod"
      # 애플리케이션에 할당할 선택적 동적 레이블. RBAC에서 사용됩니다.
      commands:
      - name: "os"
        command: ["/usr/bin/uname"]
        period: "5s"
auth_service:
  enabled: "no"
ssh_service:
  enabled: "no"
proxy_service:
  enabled: "no"

애플리케이션 서비스를 시작합니다:

sudo teleport start --config=/path/to/teleport.yaml

고급 옵션

덤퍼 애플리케이션 실행

테스트와 디버깅을 위해, "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 헤더는 ID 제공자로부터 오는 사용자의 외부 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}}"

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

다음 단계

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

Teleport 원문 보기