InfoGrab DocsInfoGrab Docs

Generic OIDC를 통해 모든 OIDC 공급자로 서비스 조인

요약

Teleport는 많은 클라우드 플랫폼과 ID 공급자를 기본으로 지원하지만, 전용 조인 방식이 없는 ID 공급자를 사용하여 Teleport 서비스를 조인해야 하는 경우가 여전히 많습니다. 이 가이드에서는 선택한 OIDC 호환 발급자와 신뢰를 설정하여 Teleport 서비스가 Teleport 클러스터에 조인하도록 구성하는 Generic OIDC 조인 방식의 사용법을 설명합니다.

Teleport는 많은 클라우드 플랫폼과 ID 공급자를 기본으로 지원하지만, 전용 조인 방식이 없는 ID 공급자를 사용하여 Teleport 서비스를 조인해야 하는 경우가 여전히 많습니다. Generic OIDC를 사용하면 워크로드에 OIDC 호환 JWT가 발급되는 모든 플랫폼 또는 공급자에서 Teleport 서비스를 조인할 수 있으며, 의도한 호스트나 워크로드만 Teleport에 인증할 수 있도록 사용자 지정 규칙을 정의할 수 있습니다.

이 가이드에서는 선택한 OIDC 호환 발급자와 신뢰를 설정하여 Teleport 서비스가 Teleport 클러스터에 조인하도록 구성하는 Generic OIDC 조인 방식의 사용법을 설명합니다.

작동 방식#

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-how-it-works.mdx)

사전 요구사항#

  • 실행 중인 Teleport (v18.11.0 or higher) 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

  • tctl and tsh clients.

    Installing `tctl` and `tsh` clients
    1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

      $ TELEPORT_DOMAIN=teleport.example.com:443
      $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
      
    2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     
Warning
       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 
  • 선택한 OIDC 호환 발급자 (구체적인 요구사항은 아래를 참조하십시오)
  • OIDC 호환 발급자로부터 JWT를 가져올 수 있는 환경 또는 워크로드

Teleport 리소스를 관리하기 위한 다음 클라이언트 도구 중 하나:

보안 고려 사항 및 제한 사항#

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-security-notes.mdx)

1/2단계. Generic OIDC 조인 토큰 생성#

새 에이전트가 Teleport에 인증할 수 있도록 조인 토큰을 생성해야 합니다. 조인 토큰은 Teleport Auth Service가 조인 시도를 허용할지 거부할지 결정하는 기준을 정의합니다. 이 단계에서는 generic_oidc 유형의 조인 토큰을 생성합니다.

참조 토큰 가져오기#

generic_oidc 조인 토큰을 생성하려면 먼저 사용 중인 OIDC 공급자를 확인한 다음, 조인 토큰과 규칙을 작성하는 템플릿으로 사용할 참조 JWT를 찾거나 생성해야 합니다.

많은 공급자가 문서화된 토큰 예시를 제공합니다. 예를 들면 다음과 같습니다.

이러한 공급자 중 상당수(GitHub, GitLab, Google Cloud 등)에는 전용 Teleport 조인 방식이 있으므로 generic_oidc 대신 해당 방식을 사용해야 합니다.

또는 기존 워크로드 내부에서 JWT를 가져올 수 있다면 jwt-cli 같은 도구로 디코딩할 수 있습니다.

$ echo "$EXAMPLE_TOKEN" | jwt decode -

공급자마다 워크로드에 토큰을 발급하는 방식이 다릅니다. 예를 들면 다음과 같습니다.

  • 많은 CI/CD 공급자는 작업이 시작되기 전에 작업 환경에 토큰을 환경 변수로 삽입합니다. 많은 공급자가 특정 단계나 워크플로에서 이를 활성화하기 위한 구성 매개변수를 요구하거나, OIDC 토큰 발급을 활성화하기 위한 프로젝트 수준 설정을 요구합니다.
  • 일부 플랫폼에는 토큰을 가져와 stdout에 쓰는 CLI 도구가 있습니다.
  • 다른 플랫폼에는 토큰을 요청하기 위해 조회할 수 있는 내부 비공개 HTTP API가 있습니다.

공급자와 관계없이, 계속하려면 tbot 클라이언트가 토큰을 사용하도록 구성할 때 다음 소스 중 무엇을 사용할지 결정해야 합니다.

  • env: JWT가 들어 있는 환경 변수
  • command: JWT를 가져와 stdout에 쓰는 명령
  • http_request: JWT를 직접 또는 JSON 응답으로 반환하는 HTTP 엔드포인트

이 예시에서는 ExampleCI라는 가상의 공급자를 사용합니다. 이 공급자는 지정한 대상(aud) 값으로 토큰을 가져오는 명령을 제공하며, 토큰은 다음과 같습니다.

$ example-ci issue-token --audience=teleport.example.com/example-agent | jwt decode -
{
  "namespace_id": "123",
  "namespace_path": "acme-corp",
  "project_id": "456",
  "project_path": "acme-corp/example-project",
  "user_id": "1",
  "user_login": "alice",
  "user_email": "alice@example.com",
  "job_id": "100",
  "ref": "feature-branch-1",
  "ref_type": "branch",
  "ref_path": "refs/heads/feature-branch-1",
  "ref_protected": "false",
  "runner": {
    "environment": "self-hosted",
    "protected": "false",
    "action": "start"
  },
  "job_source": "push",
  "jti": "235b3a54-b797-45c7-ae9a-f72d7bc6ef5b",
  "iss": "https://example.com",
  "iat": 1681395193,
  "nbf": 1681395188,
  "exp": 1681398793,
  "sub": "project_path:acme-corp/example-project:ref_type:branch:ref:feature-branch-1",
  "aud": "teleport.example.com/example-agent"
}

조인 토큰 생성#

이 JWT 템플릿을 기준으로, acme-corp/example-project 리포지터리 내의 모든 CI/CD 워크플로 실행에 접근을 허용하는 조인 토큰을 생성합니다. 데모를 위해 몇 가지 추가 제한도 포함합니다. 사용 가능한 규칙과 구문의 전체 목록은 조인 토큰 레퍼런스 페이지에서 확인할 수 있습니다.

이를 위해 토큰을 생성할 방법(tctl로 직접, Teleport의 Terraform 공급자를 통해, 또는 Teleport의 쿠버네티스 오퍼레이터를 통해)을 정하고, 시작점으로 사용할 해당 토큰 템플릿을 참조하십시오.

다음 초기 내용으로 token.yaml을 생성합니다.

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-spec.mdx)

필요에 맞게 수정한 다음, 준비가 되면 토큰을 생성합니다.

$ tctl create token.yaml

마지막으로 토큰이 생성되었는지 확인합니다.

$ tctl get token/generic-oidc-token

kind: token
metadata:
  expires: "3000-01-01T00:00:00Z"
  name: generic-oidc-token
spec:
  join_method: generic_oidc
  roles:
  - Node
version: v2
must_match_fields limitation

현재 Teleport의 Terraform 공급자는 must_match_fields를 지원하지 않으며, 이 필드에 지정한 모든 규칙은 오류 없이 무시됩니다.

당분간은 모든 규칙을 allow_any 안에 작성하거나, tctl을 통해 generic_oidc 토큰을 생성하십시오.

다음 리소스를 Terraform 구성에 추가하고, 필요에 맞게 값과 규칙을 조정합니다.

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-spec-hcl.mdx)

must_match_fields limitation

Teleport의 쿠버네티스 오퍼레이터는 must_match_fields를 제한적으로 지원합니다. 규칙은 수신 JWT의 루트 수준 클레임에 대해서만 작성할 수 있으며, 중첩된 클레임 필드를 확인하려고 하면 오류가 발생합니다.

중첩된 필드를 확인해야 한다면 해당 검사를 allow_any 규칙 안에 작성하거나, 이러한 제한이 없는 tctl을 통해 generic_oidc 토큰을 생성하십시오.

다음 쿠버네티스 리소스 매니페스트를 추가하고, 필요에 맞게 값과 규칙을 조정합니다.

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-spec-kube.mdx)

위에 표시된 예시는 설명을 위한 것임에 유의하십시오. 가져온 참조 토큰을 참고하여 모든 규칙을 사용 중인 공급자와 환경에 맞는 값으로 바꾸십시오.

일반적으로 다음과 같은 최소 규칙을 권장합니다.

  • must_match_fields에 조직 이름이나 ID 같은 "전역" 요구사항을 정의합니다. 이 값은 항상 필요하며, 의도하지 않은 클라이언트를 실수로 허용할 수 있는 allow_any 규칙에 대한 저렴한 보험입니다. 최악의 경우에도 영향 범위를 조직 내부로 제한할 수 있습니다.

    위에 표시된 예시 JWT에서는 namespace_id와 namespace_path가 조인하는 모든 클라이언트에 대해 구성하기 좋은 전역 규칙일 수 있습니다.

  • expression 또는 conditions를 사용하여, 접근 권한을 부여해야 하는 개별 워크로드나 기타 컴퓨팅 단위를 허용하는 allow_any 규칙을 하나 이상 정의합니다.

    예시 JWT를 기준으로, project_id와 project_path는 조인 시도가 인가된 프로젝트에서 오는지 확인하기 위해 동등 비교를 수행하기에 유용한 필드일 수 있습니다.

    • conditions 규칙을 사용하면 클레임 속성이 일치해야 하는 단순 조건 (eq, not_eq, in, not_in) 목록을 지정할 수 있습니다.

    • expression 규칙 유형은 Teleport의 프레디킷 언어를 사용하여 복잡한 로직에 따라 클레임을 평가합니다.

      일부 기본 제공 프레디킷 함수를 사용할 때의 구체적인 호환성 참고 사항은 위의 제한 사항 섹션을 참조하십시오.

또한 규칙 평가 순서에 유의하십시오.

  • 먼저 모든 must_match_fields 검사가 실행됩니다. 여기에 지정한 모든 값은 수신 JWT에 존재해야 하며 해당 값과 일치해야 합니다. must_match_fields가 비어 있으면 이 단계는 건너뜁니다.
  • 다음으로 allow_any에 나열된 각 규칙이 순차적으로 평가되며, 처음 일치하는 규칙(expression 또는 conditions)에서 평가가 중단됩니다.
  • must_match_fields와 allow_any 사이에서 원하는 만큼 규칙을 조합할 수 있으며, 원한다면 둘 중 하나를 완전히 생략할 수도 있습니다. 두 규칙 유형을 통틀어 하나 이상의 규칙 또는 값이 일치해야 합니다.

2/2단계. 공급자에서 Teleport 설정#

Generic OIDC 조인 방식은 SSH, Proxy, Kubernetes, Application, Database 또는 Desktop Service를 실행하는 Teleport 프로세스에 사용할 수 있습니다.

  1. 대상 환경(VM 또는 물리 머신)에 Teleport를 설치합니다.

Linux 서버에 Teleport Agent를 설치하려면:

권장 설치 방법은 클러스터 설치 스크립트입니다. 이 스크립트는 클러스터에 맞는 올바른 버전, 에디션, 설치 모드를 선택합니다.

  1. teleport.example.com:443에 Teleport 클러스터의 호스트명과 포트를 할당하되, 스킴(https://)은 포함하지 마십시오.

  2. 클러스터의 설치 스크립트를 실행하십시오:

    $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
    
  3. 사용자 지정 teleport.yaml 파일로 Teleport 프로세스를 구성합니다. 다음 구성 예시와 같이 join_params 섹션에서 token_name은 1단계에서 생성한 토큰과 일치시키고 method: generic_oidc를 지정합니다.

    # /etc/teleport.yaml
    version: v3
    teleport:
      join_params:
        token_name: generic-oidc-token
        method: generic_oidc
        generic_oidc:
          # Configure exactly one of command, env, or http_request.
          # The JWT will be fetched from the configured source.
    
          # Specify a command to run. The first value must be the executable to run,
          # followed by arguments, one per list entry. This example calls
          # `example-provider issue-token ...` with a client-specified audience
          # request. Your provider will differ.
          command: ["example-ci", "issue-token", "--audience=teleport.example.com/example-agent"]
    
          # By default, command and http_request timeout after 1 minute.
          # If you need a different value, specify it in `timeout`
          # timeout: 1m
          # If the token can be found inside an environment variable,
          # you can simply specify the name of the variable containing the token.
          # env: ENV_VAR_NAME
    
          # If the token can be fetched from an HTTP endpoint, use `http_request`.
          # It fetches a JWT directly from an HTTP endpoint, which must return a 2xx status.
          # Redirects are not followed and HTTP proxy environment variables are ignored.
          # http_request:
          #   request:
          #     # Required: the endpoint that returns the JWT.
          #     url: https://issuer.example.com/token
          #     # HTTP method, defaults to GET. Requests have no body.
          #     method: GET
          #     # Optional query parameters. Values are URL-encoded and override
          #     # parameters with the same names in url.
          #     query_params:
          #       audience: teleport.example.com/example-agent
          #     # Optional request headers, with string values.
          #     headers:
          #       Accept: application/json
          #     # Defaults to false. HTTPS is allowed but plain HTTP is only allowed for 169.254.169.254 and 127.0.0.1.
          #     # Set true to allow other plain HTTP hosts.
          #     insecure_allow_http: false
          #   result:
          #     # Optional JSONPath expression to extract the JWT from a JSON response.
          #     # Must select exactly one string.
          #     # Omit result to use the response body directly as the JWT.
          #     json_path: $.id_token
    
      proxy_server: teleport.example.com:443
    ssh_service:
      enabled: true
    auth_service:
      enabled: false
    proxy_service:
      enabled: false
    
  4. Teleport를 시작합니다.

systemd 서비스를 생성하여 호스트가 부팅될 때 your Teleport instance이 자동으로 시작되도록 구성합니다. 지침은 your Teleport instance을 어떻게 설치했는지에 따라 다릅니다.

Package Manager

your Teleport instance을 실행할 호스트에서 Teleport를 활성화하고 시작합니다:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

TAR Archive

your Teleport instance을 실행할 호스트에서 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로 your Teleport instance의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.

  1. Teleport 프로세스가 클러스터에 연결하고 조인할 수 있는지 확인합니다. 모든 설정이 끝났습니다.

Generic OIDC를 통해 모든 OIDC 공급자로 서비스 조인

Teleport v18.11
원문 보기

요약

Teleport는 많은 클라우드 플랫폼과 ID 공급자를 기본으로 지원하지만, 전용 조인 방식이 없는 ID 공급자를 사용하여 Teleport 서비스를 조인해야 하는 경우가 여전히 많습니다. 이 가이드에서는 선택한 OIDC 호환 발급자와 신뢰를 설정하여 Teleport 서비스가 Teleport 클러스터에 조인하도록 구성하는 Generic OIDC 조인 방식의 사용법을 설명합니다.

Teleport는 많은 클라우드 플랫폼과 ID 공급자를 기본으로 지원하지만, 전용 조인 방식이 없는 ID 공급자를 사용하여 Teleport 서비스를 조인해야 하는 경우가 여전히 많습니다. Generic OIDC를 사용하면 워크로드에 OIDC 호환 JWT가 발급되는 모든 플랫폼 또는 공급자에서 Teleport 서비스를 조인할 수 있으며, 의도한 호스트나 워크로드만 Teleport에 인증할 수 있도록 사용자 지정 규칙을 정의할 수 있습니다.

이 가이드에서는 선택한 OIDC 호환 발급자와 신뢰를 설정하여 Teleport 서비스가 Teleport 클러스터에 조인하도록 구성하는 Generic OIDC 조인 방식의 사용법을 설명합니다.

작동 방식#

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-how-it-works.mdx)

사전 요구사항#

  • 실행 중인 Teleport (v18.11.0 or higher) 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

  • tctl and tsh clients.

    Installing `tctl` and `tsh` clients
    1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

      $ TELEPORT_DOMAIN=teleport.example.com:443
      $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
      
    2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     
Warning
       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 
  • 선택한 OIDC 호환 발급자 (구체적인 요구사항은 아래를 참조하십시오)
  • OIDC 호환 발급자로부터 JWT를 가져올 수 있는 환경 또는 워크로드

Teleport 리소스를 관리하기 위한 다음 클라이언트 도구 중 하나:

보안 고려 사항 및 제한 사항#

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-security-notes.mdx)

1/2단계. Generic OIDC 조인 토큰 생성#

새 에이전트가 Teleport에 인증할 수 있도록 조인 토큰을 생성해야 합니다. 조인 토큰은 Teleport Auth Service가 조인 시도를 허용할지 거부할지 결정하는 기준을 정의합니다. 이 단계에서는 generic_oidc 유형의 조인 토큰을 생성합니다.

참조 토큰 가져오기#

generic_oidc 조인 토큰을 생성하려면 먼저 사용 중인 OIDC 공급자를 확인한 다음, 조인 토큰과 규칙을 작성하는 템플릿으로 사용할 참조 JWT를 찾거나 생성해야 합니다.

많은 공급자가 문서화된 토큰 예시를 제공합니다. 예를 들면 다음과 같습니다.

이러한 공급자 중 상당수(GitHub, GitLab, Google Cloud 등)에는 전용 Teleport 조인 방식이 있으므로 generic_oidc 대신 해당 방식을 사용해야 합니다.

또는 기존 워크로드 내부에서 JWT를 가져올 수 있다면 jwt-cli 같은 도구로 디코딩할 수 있습니다.

$ echo "$EXAMPLE_TOKEN" | jwt decode -

공급자마다 워크로드에 토큰을 발급하는 방식이 다릅니다. 예를 들면 다음과 같습니다.

  • 많은 CI/CD 공급자는 작업이 시작되기 전에 작업 환경에 토큰을 환경 변수로 삽입합니다. 많은 공급자가 특정 단계나 워크플로에서 이를 활성화하기 위한 구성 매개변수를 요구하거나, OIDC 토큰 발급을 활성화하기 위한 프로젝트 수준 설정을 요구합니다.
  • 일부 플랫폼에는 토큰을 가져와 stdout에 쓰는 CLI 도구가 있습니다.
  • 다른 플랫폼에는 토큰을 요청하기 위해 조회할 수 있는 내부 비공개 HTTP API가 있습니다.

공급자와 관계없이, 계속하려면 tbot 클라이언트가 토큰을 사용하도록 구성할 때 다음 소스 중 무엇을 사용할지 결정해야 합니다.

  • env: JWT가 들어 있는 환경 변수
  • command: JWT를 가져와 stdout에 쓰는 명령
  • http_request: JWT를 직접 또는 JSON 응답으로 반환하는 HTTP 엔드포인트

이 예시에서는 ExampleCI라는 가상의 공급자를 사용합니다. 이 공급자는 지정한 대상(aud) 값으로 토큰을 가져오는 명령을 제공하며, 토큰은 다음과 같습니다.

$ example-ci issue-token --audience=teleport.example.com/example-agent | jwt decode -
{
  "namespace_id": "123",
  "namespace_path": "acme-corp",
  "project_id": "456",
  "project_path": "acme-corp/example-project",
  "user_id": "1",
  "user_login": "alice",
  "user_email": "alice@example.com",
  "job_id": "100",
  "ref": "feature-branch-1",
  "ref_type": "branch",
  "ref_path": "refs/heads/feature-branch-1",
  "ref_protected": "false",
  "runner": {
    "environment": "self-hosted",
    "protected": "false",
    "action": "start"
  },
  "job_source": "push",
  "jti": "235b3a54-b797-45c7-ae9a-f72d7bc6ef5b",
  "iss": "https://example.com",
  "iat": 1681395193,
  "nbf": 1681395188,
  "exp": 1681398793,
  "sub": "project_path:acme-corp/example-project:ref_type:branch:ref:feature-branch-1",
  "aud": "teleport.example.com/example-agent"
}

조인 토큰 생성#

이 JWT 템플릿을 기준으로, acme-corp/example-project 리포지터리 내의 모든 CI/CD 워크플로 실행에 접근을 허용하는 조인 토큰을 생성합니다. 데모를 위해 몇 가지 추가 제한도 포함합니다. 사용 가능한 규칙과 구문의 전체 목록은 조인 토큰 레퍼런스 페이지에서 확인할 수 있습니다.

이를 위해 토큰을 생성할 방법(tctl로 직접, Teleport의 Terraform 공급자를 통해, 또는 Teleport의 쿠버네티스 오퍼레이터를 통해)을 정하고, 시작점으로 사용할 해당 토큰 템플릿을 참조하십시오.

다음 초기 내용으로 token.yaml을 생성합니다.

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-spec.mdx)

필요에 맞게 수정한 다음, 준비가 되면 토큰을 생성합니다.

$ tctl create token.yaml

마지막으로 토큰이 생성되었는지 확인합니다.

$ tctl get token/generic-oidc-token

kind: token
metadata:
  expires: "3000-01-01T00:00:00Z"
  name: generic-oidc-token
spec:
  join_method: generic_oidc
  roles:
  - Node
version: v2
must_match_fields limitation

현재 Teleport의 Terraform 공급자는 must_match_fields를 지원하지 않으며, 이 필드에 지정한 모든 규칙은 오류 없이 무시됩니다.

당분간은 모든 규칙을 allow_any 안에 작성하거나, tctl을 통해 generic_oidc 토큰을 생성하십시오.

다음 리소스를 Terraform 구성에 추가하고, 필요에 맞게 값과 규칙을 조정합니다.

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-spec-hcl.mdx)

must_match_fields limitation

Teleport의 쿠버네티스 오퍼레이터는 must_match_fields를 제한적으로 지원합니다. 규칙은 수신 JWT의 루트 수준 클레임에 대해서만 작성할 수 있으며, 중첩된 클레임 필드를 확인하려고 하면 오류가 발생합니다.

중첩된 필드를 확인해야 한다면 해당 검사를 allow_any 규칙 안에 작성하거나, 이러한 제한이 없는 tctl을 통해 generic_oidc 토큰을 생성하십시오.

다음 쿠버네티스 리소스 매니페스트를 추가하고, 필요에 맞게 값과 규칙을 조정합니다.

Note

이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-spec-kube.mdx)

위에 표시된 예시는 설명을 위한 것임에 유의하십시오. 가져온 참조 토큰을 참고하여 모든 규칙을 사용 중인 공급자와 환경에 맞는 값으로 바꾸십시오.

일반적으로 다음과 같은 최소 규칙을 권장합니다.

  • must_match_fields에 조직 이름이나 ID 같은 "전역" 요구사항을 정의합니다. 이 값은 항상 필요하며, 의도하지 않은 클라이언트를 실수로 허용할 수 있는 allow_any 규칙에 대한 저렴한 보험입니다. 최악의 경우에도 영향 범위를 조직 내부로 제한할 수 있습니다.

    위에 표시된 예시 JWT에서는 namespace_id와 namespace_path가 조인하는 모든 클라이언트에 대해 구성하기 좋은 전역 규칙일 수 있습니다.

  • expression 또는 conditions를 사용하여, 접근 권한을 부여해야 하는 개별 워크로드나 기타 컴퓨팅 단위를 허용하는 allow_any 규칙을 하나 이상 정의합니다.

    예시 JWT를 기준으로, project_id와 project_path는 조인 시도가 인가된 프로젝트에서 오는지 확인하기 위해 동등 비교를 수행하기에 유용한 필드일 수 있습니다.

    • conditions 규칙을 사용하면 클레임 속성이 일치해야 하는 단순 조건 (eq, not_eq, in, not_in) 목록을 지정할 수 있습니다.

    • expression 규칙 유형은 Teleport의 프레디킷 언어를 사용하여 복잡한 로직에 따라 클레임을 평가합니다.

      일부 기본 제공 프레디킷 함수를 사용할 때의 구체적인 호환성 참고 사항은 위의 제한 사항 섹션을 참조하십시오.

또한 규칙 평가 순서에 유의하십시오.

  • 먼저 모든 must_match_fields 검사가 실행됩니다. 여기에 지정한 모든 값은 수신 JWT에 존재해야 하며 해당 값과 일치해야 합니다. must_match_fields가 비어 있으면 이 단계는 건너뜁니다.
  • 다음으로 allow_any에 나열된 각 규칙이 순차적으로 평가되며, 처음 일치하는 규칙(expression 또는 conditions)에서 평가가 중단됩니다.
  • must_match_fields와 allow_any 사이에서 원하는 만큼 규칙을 조합할 수 있으며, 원한다면 둘 중 하나를 완전히 생략할 수도 있습니다. 두 규칙 유형을 통틀어 하나 이상의 규칙 또는 값이 일치해야 합니다.

2/2단계. 공급자에서 Teleport 설정#

Generic OIDC 조인 방식은 SSH, Proxy, Kubernetes, Application, Database 또는 Desktop Service를 실행하는 Teleport 프로세스에 사용할 수 있습니다.

  1. 대상 환경(VM 또는 물리 머신)에 Teleport를 설치합니다.

Linux 서버에 Teleport Agent를 설치하려면:

권장 설치 방법은 클러스터 설치 스크립트입니다. 이 스크립트는 클러스터에 맞는 올바른 버전, 에디션, 설치 모드를 선택합니다.

  1. teleport.example.com:443에 Teleport 클러스터의 호스트명과 포트를 할당하되, 스킴(https://)은 포함하지 마십시오.

  2. 클러스터의 설치 스크립트를 실행하십시오:

    $ curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash
    
  3. 사용자 지정 teleport.yaml 파일로 Teleport 프로세스를 구성합니다. 다음 구성 예시와 같이 join_params 섹션에서 token_name은 1단계에서 생성한 토큰과 일치시키고 method: generic_oidc를 지정합니다.

    # /etc/teleport.yaml
    version: v3
    teleport:
      join_params:
        token_name: generic-oidc-token
        method: generic_oidc
        generic_oidc:
          # Configure exactly one of command, env, or http_request.
          # The JWT will be fetched from the configured source.
    
          # Specify a command to run. The first value must be the executable to run,
          # followed by arguments, one per list entry. This example calls
          # `example-provider issue-token ...` with a client-specified audience
          # request. Your provider will differ.
          command: ["example-ci", "issue-token", "--audience=teleport.example.com/example-agent"]
    
          # By default, command and http_request timeout after 1 minute.
          # If you need a different value, specify it in `timeout`
          # timeout: 1m
          # If the token can be found inside an environment variable,
          # you can simply specify the name of the variable containing the token.
          # env: ENV_VAR_NAME
    
          # If the token can be fetched from an HTTP endpoint, use `http_request`.
          # It fetches a JWT directly from an HTTP endpoint, which must return a 2xx status.
          # Redirects are not followed and HTTP proxy environment variables are ignored.
          # http_request:
          #   request:
          #     # Required: the endpoint that returns the JWT.
          #     url: https://issuer.example.com/token
          #     # HTTP method, defaults to GET. Requests have no body.
          #     method: GET
          #     # Optional query parameters. Values are URL-encoded and override
          #     # parameters with the same names in url.
          #     query_params:
          #       audience: teleport.example.com/example-agent
          #     # Optional request headers, with string values.
          #     headers:
          #       Accept: application/json
          #     # Defaults to false. HTTPS is allowed but plain HTTP is only allowed for 169.254.169.254 and 127.0.0.1.
          #     # Set true to allow other plain HTTP hosts.
          #     insecure_allow_http: false
          #   result:
          #     # Optional JSONPath expression to extract the JWT from a JSON response.
          #     # Must select exactly one string.
          #     # Omit result to use the response body directly as the JWT.
          #     json_path: $.id_token
    
      proxy_server: teleport.example.com:443
    ssh_service:
      enabled: true
    auth_service:
      enabled: false
    proxy_service:
      enabled: false
    
  4. Teleport를 시작합니다.

systemd 서비스를 생성하여 호스트가 부팅될 때 your Teleport instance이 자동으로 시작되도록 구성합니다. 지침은 your Teleport instance을 어떻게 설치했는지에 따라 다릅니다.

Package Manager

your Teleport instance을 실행할 호스트에서 Teleport를 활성화하고 시작합니다:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

TAR Archive

your Teleport instance을 실행할 호스트에서 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로 your Teleport instance의 상태를 확인하고 journalctl -fu teleport로 로그를 볼 수 있습니다.

  1. Teleport 프로세스가 클러스터에 연결하고 조인할 수 있는지 확인합니다. 모든 설정이 끝났습니다.