Teleport는 대상 MCP server에 대한 각 요청과 함께 Teleport 권한(authority)으로 서명된 JWT 토큰을 Teleport-Jwt-Assertion 헤더에 담아 전송합니다.

JWT 토큰을 사용하여 인증된 Teleport 사용자와 그 역할 및 트레잇에 대한 정보를 얻을 수 있습니다. 이를 통해 다음을 수행할 수 있습니다:

• Teleport의 identity/roles/traits를 웹 애플리케이션의 identity/roles/traits에 매핑합니다.
• Teleport identity를 신뢰하여 사용자를 애플리케이션에 자동으로 로그인시킵니다.

JWT 소개#

JSON Web Token(JWT)은 정보를 JSON 객체 형태로 당사자 간에 안전하게 전송하는 방법을 정의하는 개방형 표준입니다.

자세한 설명은 https://jwt.io/introduction/를 참조하세요.

Teleport JWT는 세 가지 섹션으로 구성됩니다:

• Header
• Payload
• Signature

Header#

헤더 예시

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload#

페이로드 예시

{
  "aud": [
    "http://127.0.0.1:34679"
  ],
  "iss": "aws",
  "nbf": 1603835795,
  "sub": "alice",
  // Teleport user name.
  "username": "alice"
  // Teleport user roles.
  "roles": [
    "admin"
  ],
  // Teleport user traits.
  "traits": {
    "logins": [
      "root",
      "ubuntu",
      "ec2-user"
    ]
  },
  // Teleport identity expiration.
  "exp": 1603943800,
}

JWT는 Teleport-Jwt-Assertion 헤더와 함께 전송됩니다.

Teleport JWT Assertion 예시

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiaHR0cDovLzEyNy4wLjAuMTozNDY3OSJdLCJleHAiOjE2MDM5NDM4MDAsImlzcyI6ImF3cyIsIm5iZiI6MTYwMzgzNTc5NSwicm9sZXMiOlsiYWRtaW4iXSwic3ViIjoiYmVuYXJlbnQiLCJ1c2VybmFtZSI6ImJlbmFyZW50In0.PZGUyFfhEWl22EDniWRLmKAjb3fL0D4cTmkxEfb-Q30hVMzVhka5WB8AUsPsLPVhTzsQ6Nkk1DnXHdz6oxrqDDfumuRrDnpJpjiXj_l0D3bExrchN61enzBHxSD13VkRIqP1V6l4i8yt8kXDIBWc-QejLTodA_GtczkDfnnpuAfaxIbD7jEwF27KI4kZu7uES9LMu2iCLdV9ZqarA-6HeDhXPA37OJ3P6eVQzYpgaOBYro5brEiVpuJLr1yA0gncmR4FqmhCpCj-KmHi2vmjmJAuuHId6HZoEZJjC9IAsNlrSA4GHH9j82o7FF1F4J2s38bRy3wZv46MT8X8-QBSpg

클래식 JWT#

클래식 JWT는 Teleport JWT CA가 발급하고 .well-known/jwks.json에 있는 Teleport의 JWKS 엔드포인트를 통해 검증되는, Teleport가 생성한 JWT입니다. 이 토큰은 기본적으로 Teleport-Jwt-Assertion 헤더로 전송되지만, 어떤 헤더에도 주입할 수 있습니다.

클래식 JWT 주입#

headers passthrough 구성과 {{internal.jwt}} 템플릿 변수를 사용하여 모든 헤더에 JWT 토큰을 주입할 수 있습니다. 이 변수는 위에서 설명한 것과 같은 사용자 아이덴티티 정보를 포함하고 Teleport JWT CA로 서명된 JWT 토큰으로 대체됩니다.

예시:

- name: "my-mcp-server"
  uri: mcp+http://localhost:4321
  rewrite:
    headers:
    - "Authorization: Bearer {{internal.jwt}}"

클래식 JWT 검증#

Teleport는 JWT를 신뢰할 수 있는지 확인하기 위한 JSON Web Key Set(jwks) 엔드포인트를 제공합니다. 이 엔드포인트는 https://[cluster-name]/.well-known/jwks.json입니다:

jwks.json 예시

{
  "keys": [
    {
      "kty": "RSA",
      "n": "xk-0VSVZY76QGqeN9TD-FJp32s8jZrpsalnRoFwlZ_JwPbbd5-_bPKcz8o2tv1eJS0Ll6ePxRCyK68Jz2UC4V4RiYaqJCRq_qVpDQMB1sQ7p9M-8qvT82FJ-Rv-W4RNe3xRmBSFDYdXaFm51Uk8OIYfv-oZ0kGptKpkNY390aJOzjHPH2MqSvhk9Xn8GwM8kEbpSllavdJCRPCeNVGJXiSCsWrOA_wsv_jqBP6g3UOA9GnI8R6HR14OxV3C184vb3NxIqxtrW0C4W6UtSbMDcKcNCgajq2l56pHO8In5GoPCrHqlo379LE5QqpXeeHj8uqcjeGdxXTuPrRq1AuBpvQ",
      "e": "AQAB",
      "alg": "RS256"
    }
  ]
}

Teleport의 JWT 토큰을 검증하는 데 사용되는 예시 Go 프로그램은 저희 GitHub에서 확인할 수 있습니다.

ID 토큰(OIDC)#

ID 토큰은 Teleport OIDC CA가 발급하고 .well-known/openid-configuration에 있는 Teleport의 OIDC 디스커버리 문서를 통해 검증되는, Teleport가 생성한 JWT입니다.

ID 토큰 주입#

헤더 패스스루 설정과 {{internal.id_token}} 템플릿 변수를 사용하여 어떤 헤더에도 ID 토큰을 주입할 수 있습니다. 이 변수는 위에서 설명한 것과 같은 사용자 아이덴티티 정보를 담고 있는, Teleport OIDC CA가 서명한 ID 토큰으로 치환됩니다.

예시:

- name: "my-mcp-server"
  uri: mcp+http://localhost:4321
  rewrite:
    headers:
    - "Authorization: Bearer {{internal.id_token}}"

ID 토큰 검증#

Teleport는 ID 토큰을 신뢰할 수 있는지 검증할 수 있도록 OIDC 디스커버리 엔드포인트를 제공합니다. 이 엔드포인트는 https://[cluster-name]/.well-known/openid-configuration입니다.

{
  "issuer": "https://teleport.example.com",
  "jwks_uri": "https://teleport.example.com/.well-known/jwks-oidc",
  "claims": [ "iss", "sub", "obo", "aud", "jti", "iat", "exp", "nbf" ],
  "id_token_signing_alg_values_supported": [ "RS256" ],
  "response_types_supported": [ "id_token" ],
  "scopes_supported": [ "openid" ],
  "subject_types_supported": [ "public" ]
}

ID 토큰에서는 발급자 클레임 iss가 OIDC 사양에 따라 https://[cluster-name] 형식을 따릅니다. 그 밖의 모든 클레임은 클래식 JWT와 동일하게 유지되며, 대상 클레임 aud에는 Teleport 애플리케이션 URI가 설정됩니다.

Teleport가 생성한 ID 토큰을 수락하도록 Amazon Bedrock AgentCore MCP 게이트웨이를 구성하는 방법은 예시를 참고하세요.

문제 해결#

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

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

- name: "dashboard"
  uri: mcp+http://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}}"