Teleport sends a JWT token signed with Teleport's authority with each request to a target MCP server in a Teleport-Jwt-Assertion header.

You can use the JWT token to get information about the authenticated Teleport user, its roles, and its traits. This allows you to:

• Map Teleport identity/roles/traits onto the identity/roles/traits of your web application.
• Trust Teleport identity to automatically sign in users into your application.

Introduction to JWTs#

JSON Web Token (JWT) is an open standard that defines a secure way to transfer information between parties as a JSON Object.

For an in-depth explanation please visit https://jwt.io/introduction/.

Teleport JWTs include three sections:

• Header
• Payload
• Signature

Header#

Example Header

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

Payload#

Example 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,
}

The JWT will be sent with the header: Teleport-Jwt-Assertion.

Example 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 주입#

You can inject a JWT token into any header using headers passthrough configuration and the {{internal.jwt}} template variable. This variable will be replaced with JWT token signed by Teleport JWT CA containing user identity information like described above.

예:

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

클래식 JWT 검증#

Teleport provides a JSON Web Key Set (jwks) endpoint to verify that the JWT can be trusted. This endpoint is https://[cluster-name]/.well-known/jwks.json:

Example jwks.json

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

GitHub의 예제 Go 프로그램에서 Teleport의 JWT 토큰을 검증하는 방법을 확인하세요.

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는 https://[cluster-name] 형식의 OIDC 사양을 따릅니다. 다른 모든 클레임은 클래식 JWT와 동일하며 대상 클레임 aud는 Teleport 애플리케이션 URI로 설정됩니다.

Amazon Bedrock AgentCore MCP 게이트웨이가 Teleport 생성 ID 토큰을 수락하도록 구성하는 예제를 참조하세요.

문제 해결#

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 MCP server.

If your MCP server 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: 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}}"