Generic OIDC를 통해 모든 OIDC 공급자에 tbot 배포
Teleport v18.11요약
Teleport는 많은 클라우드 플랫폼과 ID 공급자를 기본으로 지원하지만, 전용 조인 방식이 없는 ID 공급자를 사용하여 봇을 조인해야 하는 경우도 여전히 많습니다. 이 가이드에서는 머신 및 워크로드 아이덴티티 봇을 만들고, Teleport 조인 방식이 없는 가상의 공급자에서 장기 자격 증명을 사용하지 않고 해당 봇이 조인할 수 있도록 Teleport를 설정합니다.
Teleport는 많은 클라우드 플랫폼과 ID 공급자를 기본으로 지원하지만, 전용 조인 방식이 없는 ID 공급자를 사용하여 봇을 조인해야 하는 경우도 여전히 많습니다. Generic OIDC를 사용하면 워크로드에 OIDC 호환 JWT가 발급되는 모든 플랫폼이나 공급자에서 봇을 조인할 수 있으며, 의도한 워크로드만 Teleport에 인증할 수 있도록 사용자 지정 규칙을 정의할 수 있습니다.
이 가이드에서는 머신 및 워크로드 아이덴티티 봇을 만들고, Teleport 조인 방식이 없는 가상의 공급자에서 장기 자격 증명을 사용하지 않고 해당 봇이 조인할 수 있도록 Teleport를 설정합니다.
작동 방식#
이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-how-it-works.mdx)
사전 요구사항#
-
실행 중인 Teleport (v18.11.0 or higher) 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.
-
tctlandtshclients.Installing `tctl` and `tsh` clients
-
Teleport 클러스터의 버전을 확인합니다.
tctlandtshclients는 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')" -
사용 중인 플랫폼에 대한 지침에 따라
tctlandtshclients를 설치합니다:
-
Mac
`tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
```code
$ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
```
Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
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
```
Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음,
현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.
예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의
도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여
다음 명령을 실행합니다:
$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster (=teleport.url=)
# Version (=teleport.version=)
# CA pin (=presets.ca_pin=)
cluster에 연결하여 tctl status 명령을 실행할 수 있다면, 현재 자격 증명을 사용하여
워크스테이션에서 이후의 tctl 명령을 실행할 수 있습니다.
자체 Teleport cluster를 호스팅하는 경우, 전체 권한을 얻기 위해 Teleport Auth Service를
호스팅하는 컴퓨터에서 tctl 명령을 실행할 수도 있습니다.
- 사용자에게 토큰 리소스를 만들 수 있는 권한이 있어야 합니다.
- 봇 환경에 JWT를 발급할 수 있는 OIDC 호환 ID 공급자가 이미 있어야 합니다.
보안 고려 사항 및 제한 사항#
이 섹션의 내용은 원문 문서를 참조하세요. (generic-oidc-security-notes.mdx)
1단계/3단계. 봇 만들기#
다음으로 Bot을 생성해야 합니다. Bot은 머신 또는 머신 그룹을 위한 Teleport identity입니다. 사용자와 마찬가지로 bot에는 무엇에 액세스할 수 있는지 정의하는 role 및 trait 집합이 있습니다.
bot.yaml을 생성합니다:
kind: bot
version: v1
metadata:
# name is a unique identifier for the Bot in the cluster.
name: example
spec:
# roles is a list of roles to grant to the Bot. Don't worry if you don't know
# what roles you need to specify here, the Access Guides will walk you through
# creating and assigning roles to the already created Bot.
roles: []
example을 Bot에 대한 고유하고 설명적인 이름으로 반드시 교체하십시오.
tctl을 사용하여 이 파일을 적용합니다:
$ tctl create bot.yaml
2단계/3단계. Generic OIDC용 조인 토큰 만들기#
워크로드가 Teleport 클러스터에 인증할 수 있도록 하려면 조인 토큰을 만들어야 합니다. 이 토큰은 Auth Service가 봇 또는 노드의 조인 허용 여부를 결정하는 기준을 정의합니다.
참조 토큰 가져오기#
generic_oidc 조인 토큰을 만들려면 먼저 사용 중인 OIDC 공급자를 확인한 다음,
조인 토큰과 규칙을 구성할 때 템플릿으로 사용할 참조 JWT를 찾거나 생성해야 합니다.
많은 공급자가 문서화된 토큰 예시를 제공합니다. 예를 들면 다음과 같습니다.
이러한 공급자 중 상당수(예: GitHub)에는 전용 Teleport 조인 방식이 있으며,
generic_oidc 대신 해당 방식을 사용해야 합니다.
또는 기존 워크로드 내부에서 JWT를 가져올 수 있다면
jwt-cli와 같은 도구로 디코딩할 수 있습니다.
$ echo "$EXAMPLE_TOKEN" | jwt decode -
공급자마다 워크로드에 토큰을 발급하는 방식이 다릅니다. 예를 들면 다음과 같습니다.
- 많은 CI/CD 공급자는 작업이 시작되기 전에 작업 환경에 토큰을 환경 변수로 주입합니다. 많은 공급자가 특정 단계나 워크플로에 대해 이를 활성화하는 설정 매개변수를 요구하거나, OIDC 토큰 발급을 활성화하는 프로젝트 수준 설정을 요구합니다.
- 일부 플랫폼에는 토큰을 가져와 stdout에 기록하는 CLI 도구가 있습니다.
- 다른 플랫폼에는 토큰을 요청할 때 조회할 수 있는 내부 비공개 HTTP API가 있습니다.
tbot이 조인할 때 사용하는 JWT의 출처로 다음 중 하나를 선택합니다.
- JWT가 담긴 환경 변수(
env) - JWT를 가져와 stdout에 기록하는 명령(
command) - JWT를 직접 또는 JSON 응답으로 반환하는 HTTP 엔드포인트(
http_request)
이 예시에서는 ExampleCI라는 가상의 공급자를 사용합니다.
이 공급자는 지정한 audience(aud) 값으로 토큰을 가져오는 명령을 제공하며,
토큰은 다음과 같은 형태입니다.
$ example-ci issue-token --audience=example.teleport.sh/example-bot | 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": "example.teleport.sh/example-bot"
}
조인 토큰 만들기#
이 JWT 템플릿을 기준으로, acme-corp/example-project 리포지터리 내의 모든 CI/CD 워크플로 실행에
접근을 허용하는 조인 토큰을 만듭니다. 시연을 위해 몇 가지 추가 제한도 포함합니다.
사용 가능한 규칙과 구문의 전체 목록은
조인 토큰 레퍼런스 페이지.
bot-token.yaml 파일을 만듭니다.
kind: token
version: v2
metadata:
name: example-bot
spec:
# The Bot role indicates that this token grants access to a bot user, rather
# than allowing a node to join. This role is built in to Teleport.
roles: [Bot]
join_method: generic_oidc
# The bot_name indicates which bot user this token grants access to. This
# should match the name of the bot that you created in the previous step.
bot_name: example
generic_oidc:
# Issuer is the JWT issuer, and must match the `iss` value in the token
# template. Additionally, it must serve OIDC discovery and JWKS documents,
# unless `static_jwks` is configured as well.
issuer: https://example.com
# The token audience, or `aud` value. If your provider lets you set or
# request this value, it should uniquely identify the Teleport cluster and
# token, like the example below. You can use a random value like a UUID
# if you prefer not to use the token.
# If your provider does not allow you to specify the audience, enter the
# value they provide here directly. Additionally, some providers include an
# array of audiences; if so, the value specified here must be present in the
# array.
# The audience is always validated regardless of any custom rules you
# specify.
audience: example.teleport.sh/example-bot
# These "field"-style matchers are "global" and are applied to all join
# attempts using this token. They're useful for ensuring all `allow_any`
# rules still check important fields, like the organization or namespace,
# and ensure that even a mistake in an `allow_any` rule that might otherwise
# allow joins from an unintended party still check at least that field.
#
# These match against the structure of the incoming JWT, so you can freely
# specify even nested fields. Note that only strings, numbers, and booleans
# can be used here. To check
# against lists, you must use `allow_any` rules.
#
# This field is optional if you only want to use `allow_any` rules; at least
# one rule is required between both rule categories.
must_match_fields:
# This ensures all joins at least come from the "acme-corp" namespace. Be
# cautious of only matching against bare repository names: they may not be
# adequately namespaced, so attackers might be able to make a repository
# with the same name in a different namespace. A `must_match_fields` check
# ensures all `allow_any` rules that allow different repositories or other
# sub-resources at least must fall within this namespace, even if a given
# expression accidentally allows unintended clients.
namespace_path: acme-corp
# Note the datatype: a plain 123 in YAML would parse a number and would
# not match the datatype in the template JWT (a number inside a string).
# As a security tip, for providers that provide both forms, it may be
# helpful to match both a name and unique ID:
# - Unique IDs help prevent name-reuse attacks if a repository or
# namespace is deleted
# - Named identifiers help give a readable name to an arbitrary number or
# UUID
# Combining both can help keep tokens both secure and auditable.
namespace_id: "123"
# You can nest fields freely. If a parent field doesn't exist, the join
# attempt is rejected.
runner:
environment: self-hosted
# These rules are evaluated after `must_match_fields` (if any), and only one
# needs to match for the join to be allowed. This lets you allow joins from
# multiple different repositories within the same token, if desired.
#
# This field is optional if you are satisfied with the "AND"-only rules of
# `must_match_fields`; at least one rule is required between both rule
# categories.
allow_any:
# This rule uses a Teleport Predicate expression to allow joins where the
# user email matches a given suffix via regex.
# All claim fields are available under the `claims` variable. Note that
# the `set()` helper must be used to wrap any list or string values for
# functions that expect a Set, like `regexp.match()` or `contains_all()`.
# Note that the expression is wrapped in single quotes ('...') due to the
# double quotes inside the expression itself.
- expression: 'regexp.match(set(claims.user_email), "^.+@example.com$")'
# This allows workflows from the `acme-corp/example-project` repo to join
# without further restrictions.
- conditions:
- attribute: project_path
eq:
value: acme-corp/example-project
# This allows workflows from `acme-corp/other-project`, but only if they
# are run against the `feature-branch-1` branch.
- conditions:
- attribute: project_path
eq:
value: acme-corp/other-project
- attribute: ref_type
eq:
value: branch
- attribute: ref
eq:
value: feature-branch-1
이 값들은 시연용이므로, 모든 규칙을 사용 중인 공급자와 환경에 맞는 값으로 교체해야 합니다. 일반적으로 다음과 같은 최소 규칙을 권장합니다.
-
must_match_fields에 조직 이름이나 ID와 같은 "전역" 요구 사항을 정의합니다. 이 요구 사항은 항상 필수이며, 의도하지 않은 클라이언트를 실수로 허용할 수 있는allow_any규칙에 대비하는 저렴한 보험입니다. 최악의 경우에도 영향 범위를 조직 내부로 제한할 수 있습니다. -
접근을 허용할 개별 리포지터리, 워크로드 또는 기타 단위를 허용하도록
expression또는conditions를 사용하여 하나 이상의allow_any규칙을 정의합니다.
또한 규칙 평가 순서를 알아 두어야 합니다.
- 먼저 모든
must_match_fields검사가 실행됩니다. 여기에 지정한 모든 값은 수신된 JWT에 존재해야 하며 해당 값과 일치해야 합니다.must_match_fields가 비어 있으면 이 단계는 건너뜁니다. - 다음으로
allow_any에 나열된 각 규칙이 순서대로 평가되며, 처음으로 일치하는 규칙(expression또는conditions)에서 평가가 중단됩니다. must_match_fields와allow_any사이에서 원하는 만큼 규칙을 조합할 수 있으며, 원하는 경우 둘 중 한쪽을 완전히 생략할 수도 있습니다. 두 규칙 유형을 합쳐 최소한 하나의 규칙 또는 값이 일치해야 합니다.
토큰 YAML을 작성한 후 tctl로 생성합니다.
$ tctl create -f bot-token.yaml
다음 명령으로 example-bot 토큰이 생성되었는지 확인합니다.
$ tctl tokens ls
Token Type Labels Expiry Time (UTC)
----------- ---- ------ ----------------------------------------------
example-bot Bot 01 Jan 00 00:00 UTC (2562047h47m16.854775807s)
3단계/3단계. 워크플로 내에서 tbot 설정#
generic_oidc를 사용할 수 있는 공급자나 플랫폼이 매우 다양하므로,
tbot 실행에 대해서는 일반적인 안내만 제공할 수 있습니다.
먼저 tbot을 설치하려면 Teleport 클러스터의 install.sh를 사용하여
적절한 버전을 다운로드하고 설치할 수 있습니다.
$ curl "https://example.teleport.sh:443/scripts/install.sh" | bash
다음으로 tbot이 Teleport 클러스터에 연결하도록 설정해야 하며,
실제로 JWT를 가져오도록도 설정해야 합니다.
이 설정은 tbot.yaml 안에서 할 수 있지만, 사용 중인 워크로드 유형이나 공급자에 따라
시작 템플릿이 조금 다를 수 있습니다.
임시 워크로드#
CI/CD 실행과 같은 임시 워크로드에는 장기 storage 디렉터리를 지정할 필요가 없으므로
memory 유형을 사용할 수 있습니다. 다음 tbot.yaml로 시작합니다.
version: v2
proxy_server: example.teleport.sh:443
onboarding:
join_method: generic_oidc
token: example-bot
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.
command: ["example-ci", "issue-token", "--audience=example.teleport.sh/example-bot"]
# 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: example.teleport.sh/example-bot
# # 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
storage:
# For ephemeral workloads, there is no need to store data persistently
type: memory
# Configure one or more services. Refer to the Access Guides to set up your
# desired services.
services: []
장기 실행 워크로드#
단일 tbot 인스턴스가 오랫동안 실행될 것으로 예상되고 영구 파일 시스템이 있는 배포에서는
다음 tbot.yaml로 시작할 수 있습니다.
version: v2
proxy_server: example.teleport.sh:443
onboarding:
join_method: generic_oidc
token: example-bot
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.
command: ["example-ci", "issue-token", "--audience=example.teleport.sh/example-bot"]
# 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: example.teleport.sh/example-bot
# # 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
storage:
# This writes long-lived bot data to the configured directory. Note that the
# Unix user that runs `tbot` must have write access to this path.
type: directory
path: /var/lib/teleport/bot
# Configure one or more services. Refer to the Access Guides to set up your
# desired services.
services: []
tbot 실행#
설정이 끝나면 tbot 클라이언트를 실행합니다.
$ tbot start -c tbot.yaml
tbot을 실행하는 정확한 방식은 특히 프록시나 기타 장기 실행 서비스를 제공하기 위해
백그라운드에서 실행해야 하는 경우, 공급자와 플랫폼에 따라 다릅니다.
다음 단계#
- 접근 가이드를 따라 역할을 할당하고 서비스를 설정하여
환경에 맞게
tbot설정을 마무리합니다. generic_oidc조인 방식에 대한 자세한 내용은 조인 토큰 레퍼런스 페이지anonymous-telemetry에 대한 자세한 정보.