이 페이지에서는 Teleport로 애플리케이션 접근을 관리할 때 발생할 수 있는 일반적인 문제와 이를 우회하거나 해결하는 방법을 설명합니다.

애플리케이션에 접근할 수 없음#

애플리케이션 접근을 막는 가장 흔한 문제는 CSRF(Cross-Site Request Forgery) 또는 CORS(Cross-Origin Resource Sharing) 오류와 관련이 있습니다.

CSRF(Cross-Site Request Forgery)는 인증된 사용자의 아이덴티티를 이용해 사용자가 모르는 사이에 작업을 수행하는 공격 유형입니다. 예를 들어 CSRF 공격은 사용자의 자격 증명으로 위조된 요청을 전송하여 자금을 이체하거나, 비밀번호를 변경하거나, 구매를 진행할 수 있습니다. 브라우저와 애플리케이션에는 이러한 유형의 공격을 방지하기 위한 검사 기능이 있습니다. 그러나 이 검사가 특정 조건에서는 정상적인 요청까지 차단할 수도 있습니다.

증상#

브라우저가 보안 쿠키를 생성할 수 없거나 이전에 생성된 보안 쿠키로부터 로그인을 인가할 수 없는 경우 다음과 같은 오류가 표시될 수 있습니다.

Invalid or missing CSRF token

이 오류는 광고 차단 또는 스크립트 차단 확장 프로그램 때문에 발생하거나 브라우저 자체에서 발생할 수 있습니다. Teleport를 통한 애플리케이션 접근에서는 Grafana나 ArgoCD처럼 WebSocket을 광범위하게 사용하는 애플리케이션에서, 그리고 교차 사이트 스크립팅 제한으로 인해 트래픽을 명시적으로 허용해야 하는 브라우저에서 이 오류가 가장 자주 나타납니다.

CSRF(Cross-Site Request Forgery) 또는 CORS(Cross-Origin Resource Sharing) 문제는 대체로 애플리케이션 기능 손실, 트래픽이 허용되지 않았음을 나타내는 애플리케이션 자체의 오류, 또는 CORS나 CSRF 오류를 나타내는 애플리케이션 로그로 나타납니다.

대부분의 경우 각 애플리케이션에 대한 Teleport 설정에서 Origin 및 Host 헤더에 대한 명시적인 rewrite 설정을 추가하면 이러한 유형의 문제를 해결할 수 있습니다.

해결 방법 1: Application Service 설정 파일#

/etc/teleport.yaml에서 정적으로 구성된 앱을 사용하는 경우 CSRF 또는 CORS 문제를 해결하려면:

1. 애플리케이션 설정이 포함된 /etc/teleport.yaml 파일을 텍스트 편집기로 엽니다.

2. 다음 grafana 예시와 유사한 rewrite.headers 섹션을 추가합니다.

app_service:
  enabled: true
  apps:
  - name: grafana
    uri: http://localhost:3000
    public_addr: grafana.teleport.example.com
    rewrite:
      headers:
      - "Origin: https://grafana.teleport.example.com" # Teleport application subdomain prepended with "https://"
      - "Host: grafana.teleport.example.com" # Teleport application subdomain itself

3. 변경 사항을 저장하고 Teleport 서비스를 다시 시작합니다.

해결 방법 2: teleport-kube-agent values 파일#

Kubernetes 및 teleport-kube-agent를 사용하여 애플리케이션을 배포하는 경우 CSRF 또는 CORS 문제를 해결하려면:

1. 애플리케이션 설정이 포함된 teleport/examples/chart/teleport-kube-agent/values.yaml 파일을 텍스트 편집기로 엽니다.

2. values.yaml 파일에서 apps 섹션을 찾습니다.

# Details of at least one app to be proxied. Example:
# apps:
#  - name: grafana
#    uri: http://localhost:3000
apps: []

3. 다음 grafana 예시와 유사한 rewrite.headers 섹션을 추가합니다.

apps:
- name: grafana
  uri: http://localhost:3000
  public_addr: grafana.teleport.example.com
  rewrite:
    headers:
    - "Origin: https://grafana.teleport.example.com" # Teleport application subdomain prepended with "https://"
    - "Host: grafana.teleport.example.com" # Teleport application subdomain itself

해결 방법 3: 동적 앱 설정#

동적 설정으로 애플리케이션을 배포하는 경우 CSRF 또는 CORS 문제를 해결하려면:

1. 동적 앱 설정을 편집하여 rewrite.headers 섹션을 포함시킵니다.

kind: app
version: v3
metadata:
  name: grafana
  labels:
    env: dev
spec:
  uri: http://localhost:3000
  public_addr: grafana.teleport.example.com
  rewrite:
    headers:
    - name: "Origin"
      value: "https://grafana.teleport.example.com" # Teleport application subdomain prepended with "https://"
    - name: "Host"
      value: "grafana.teleport.example.com" # Teleport application subdomain itself

해결 방법 4: Kubernetes 앱 자동 검색#

Kubernetes 자동 검색을 사용하여 애플리케이션을 배포하는 경우 CSRF 또는 CORS 문제를 해결하려면:

1. Kubernetes Service 설정을 편집하여 rewrite.headers 섹션을 포함시킵니다.

apiVersion: v1
kind: Service
metadata:
  annotations:
    teleport.dev/app-rewrite: |
      headers:
      - name: "Origin"
        value: "https://grafana.teleport.example.com" # Teleport application subdomain prepended with "https://"
      - name: "Host"
        value: "grafana.teleport.example.com" # Teleport application subdomain itself

신뢰할 수 없는 인증서 오류#

기본적으로 Teleport Proxy Service가 제시하는 인증서는 신뢰할 수 있어야 하며 인정된 인증 기관(certificate authority)에서 발급된 것이어야 합니다.

증상#

자체 서명 인증서를 생성했거나 인정되지 않은 인증 기관이 서명한 인증서를 사용하는 경우 다음과 유사한 오류가 표시될 수 있습니다.

ERROR: "unable to verify HTTPS certificate chain in : \x1b[31mERROR: \x1b[0mWARNING:"

  The proxy you are connecting to has presented a certificate signed by a
  unknown authority. This is most likely due to either being presented
  with a self-signed certificate or the certificate was truly signed by an
  authority not known to the client.

해결 방법#

루트 인증 기관과 자체 서명 인증서를 올바르게 생성한 경우, --insecure 명령줄 옵션을 사용하여 클라이언트가 해당 인증서를 수락하도록 허용할 수 있습니다. 예를 들어 다음과 유사한 명령을 실행하여 자체 서명 인증서로 Teleport를 시작할 수 있습니다.

sudo teleport start --config=/etc/teleport.yaml --insecure

Teleport Proxy Service가 제시하는 인증서 체인을 검증하는 데 사용하려는 자체 인증 기관이 있는 경우, 명령줄에서 SSL_CERT_FILE 또는 SSL_CERT_DIR 환경 변수를 수동으로 설정할 수 있습니다. 예를 들면 다음과 같습니다.

sudo SSL_CERT_FILE="path/to/rootCA-pem" teleport start --config=/etc/teleport.yaml

sudo는 기본적으로 환경 변수를 상속하지 않으므로 SSL_CERT_FILE 및 SSL_CERT_DIR 환경 변수는 명령줄 옵션으로 지정해야 합니다.

요청 헤더가 너무 큼#

기본적으로 Teleport는 애플리케이션용으로 발급되는 JWT에 사용자의 Teleport 역할과 트레이트를 포함시킵니다. Teleport 사용자가 많은 수의 역할이나 트레이트를 가지고 있으면 JWT가 너무 커져 요청이 실패할 수 있습니다.

증상#

Teleport 뒤에 있는 HTTP 앱에 연결을 시도할 때 request header fields too large라고 표시하는 오류가 나타납니다.

해결 방법#

Teleport로 보호하는 애플리케이션이 사용자의 Teleport 역할이나 트레이트에 대한 정보를 알 필요가 없다면, 이 정보를 JWT에서 생략하도록 Teleport를 구성할 수 있습니다. 이렇게 하면 JWT가 더 작아져 한도를 초과할 가능성이 줄어듭니다.

이 설정은 애플리케이션의 rewrite 설정에 있는 jwt_claims 속성에서 사용할 수 있습니다. 자세한 내용은 웹 애플리케이션 접근을 참조하세요.