로그인 규칙 설정 | Teleport 공식 기술 문서 한국판 by 인포그랩

로그인 규칙 설정

이 가이드는 Teleport 클러스터에 첫 번째 로그인 규칙을 작성하고 테스트하며 추가하는 과정을 안내합니다.

필수 조건

실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하기 무료 체험판을 이용해 보세요.
tctl 관리 도구 및 tsh 클라이언트 도구 버전 >= 16.2.0.

tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하세요.

당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  16.2.0
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다. 자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

시작하기 전에 11.3.1 이상의 버전에서 실행 중인 Teleport Enterprise 또는 Cloud 클러스터가 필요합니다.

로그인 규칙은 SSO 로그인에서만 작동하므로 시작하기 전에 OIDC, SAML 또는 GitHub 커넥터를 구성해야 합니다. 이를 설정하는 방법은 단일 로그인 문서를 확인하세요.

단계 1/5. RBAC 구성

먼저, login_rule 리소스를 읽고 수정할 수 있는 권한이 있는 사용자로 Teleport에 로그인했는지 확인합니다. 미리 설정된 editor 역할은 이미 이 권한이 있지만, 보다 사용자 정의된 구성을 사용하는 경우 loginrule-manager.yaml라는 역할을 다음 내용을 사용하여 생성하세요:

kind: role
metadata:
  name: loginrule-manager
spec:
  allow:
    rules:
      - resources: [login_rule]
        verbs: [list, create, read, update, delete]
version: v7

tctl을 사용하여 역할을 생성합니다:

tctl create loginrule-manager.yaml
role 'loginrule-manager' has been created

loginrule-manager 역할을 Teleport 사용자에게 할당하려면 인증 제공자에 맞는 적절한 명령어를 실행하세요:

로컬 사용자의 역할을 콤마로 구분된 목록으로 가져옵니다:
```
ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')
```

로컬 사용자를 편집하여 새로운 역할을 추가합니다:

tctl users update $(tsh status -f json | jq -r '.active.username') \  --set-roles "${ROLES?},loginrule-manager"

Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

github 인증 커넥터를 가져옵니다:
```
tctl get github/github --with-secrets > github.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 github.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 github.yaml 파일을 제거해야 합니다.
github.yaml을 편집하고 teams_to_roles 섹션에 loginrule-manager을 추가합니다.

이 역할에 매핑할 팀은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 하지만 팀에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 팀이어야 합니다.

여기에 예시가 있습니다:
```
  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - loginrule-manager
```
변경 사항을 적용합니다:
```
tctl create -f github.yaml
```
Teleport 클러스터에서 로그아웃한 후 새로운 역할을 assum 하기 위해 다시 로그인합니다.

saml 구성 리소스를 가져옵니다:
```
tctl get --with-secrets saml/mysaml > saml.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 saml.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 saml.yaml 파일을 제거해야 합니다.
saml.yaml을 편집하고 attributes_to_roles 섹션에 loginrule-manager을 추가합니다.

이 역할에 매핑할 속성은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 그러나 그룹에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 그룹이어야 합니다.

여기에 예시가 있습니다:
```
  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - loginrule-manager
```
변경 사항을 적용합니다:
```
tctl create -f saml.yaml
```
Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

oidc 구성 리소스를 가져옵니다:
```
tctl get oidc/myoidc --with-secrets > oidc.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 oidc.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 oidc.yaml 파일을 제거해야 합니다.
oidc.yaml을 편집하고 claims_to_roles 섹션에 loginrule-manager을 추가합니다.

이 역할에 매핑할 클레임은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 그러나 그룹에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 그룹이어야 합니다.

여기에 예시가 있습니다:
```
  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - loginrule-manager
```
변경 사항을 적용합니다:
```
tctl create -f oidc.yaml
```
Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

단계 2/5. 로그인 규칙 리소스 초안 작성

다음 예제는 모든 사용자에게 현재 username 특성을 소문자로 변환한 새 logins 특성을 설정합니다. 이 예제 규칙을 my_rule.yaml이라는 파일에 복사하여 가이드를 계속 진행하세요.

# my_rule.yaml
kind: login_rule
version: v1
metadata:
  # 각 로그인 규칙은 클러스터 내에서 고유한 이름이어야 합니다.
  name: my_rule

  # expires는 선택 사항이며 일반적으로 배포된 로그인 규칙에는 설정하지 않아야 하지만,
  # 새로운 로그인 규칙을 테스트하는 동안 사용자가 Teleport 클러스터에서 잠길 가능성을 방지하기 위해
  # 가까운 미래의 만료 시간을 설정하는 것이 유용할 수 있습니다.
  # expires: "2023-01-31T00:00:00-00:00"
spec:
  # priority는 클러스터에 여러 개의 로그인 규칙이 있는 경우의 평가 순서를 정합니다.
  # 우선 순위가 낮은 것이 먼저 평가됩니다.
  priority: 0

  # traits_expression은 로그인할 때 각 SSO 사용자에 대한 최종 특성을 결정하기 위해 평가될
  # 조건 표현식입니다.
  #
  # 이 예제 표현식은 "logins" 특성을 들어오는 "username" 특성을 소문자로 변환한 것으로 설정합니다.
  traits_expression: 'external.put("logins", strings.lower(external["username"]))'

각 로그인 규칙 리소스는 traits_map 또는 traits_expression 필드를 가져야 합니다. 이 가이드에서는 예제 traits_expression을 사용할 것입니다.

traits_expression은 로그인하는 각 SSO 사용자에 대한 특성을 결정하기 위해 Teleport 클러스터에서 실행 시 평가되는 스크립트 형식입니다. 표현식은 external 변수를 통해 사용자에 대한 들어오는 특성에 접근할 수 있습니다. external 변수는 특성 키를 해당 특성 값 집합으로 매핑하는 사전입니다.

단계 3/5. 로그인 규칙 테스트

tctl login_rule test 명령을 사용하여 새로운 로그인 규칙을 실험하고 구문을 확인하며 예제 들어오는 특성에서 어떻게 작동하는지 확인할 수 있습니다.

사용자의 현재 특성을 가져와 input.json에 저장한 다음, 해당 입력으로 새 로그인 규칙을 테스트합니다.

tctl get --format json users/username | jq 'first.spec.traits' > input.json
tctl login_rule test --resource-file my_rule.yaml input.json
access:- staginggroups:- dbs- devslogins:- alice

이 스크립트는 표현식의 구문 오류를 포착합니다. 모든 예상 특성이 출력에 있는지 확인하세요.

단계 4/5. 로그인 규칙 생성

다음 명령을 사용하여 클러스터에 로그인 규칙을 생성합니다:

tctl create my_rule.yaml

단계 5/5. 시도해 보기

마지막 단계로, 클러스터에서 로그아웃한 후 다시 로그인하여 사용자가 예상한 특성과 역할을 받았는지 확인하세요. 다음 명령을 사용하여 특성과 역할을 확인할 수 있습니다:

tctl get --format json users/username | jq '{traits: first.spec.traits, roles: first.spec.roles}'
{  "traits": {	"access": [	  "staging"    ],    "groups": [      "dbs",      "devs"    ],    "logins": [      "alice"    ]  },  "roles": [    "access",    "editor",    "auditor"  ]}

문제 해결

tctl sso test 명령을 사용하여 SSO 로그인을 디버그하고 SSO 제공자에 의해 전송되는 특성과 이들이 로그인 규칙에 의해 어떻게 매핑되는지를 확인할 수 있습니다.

tctl sso test는 커넥터 사양을 기대합니다. 클러스터에 현재 설치된 커넥터로 디버그하기 위해 다음 명령을 실행하세요.

tctl get connector/SSO connector name --with-secrets | tctl sso test

다음 단계

로그인 규칙 표현식 구문에 대한 자세한 내용을 알아보려면 로그인 규칙 참조 페이지를 확인하세요.

tctl login_rule test 명령에 대한 정보를 보려면 도움말 명령을 실행하거나 참조 페이지를 확인하세요.

tctl help login_rule test

다음 tctl 리소스 명령은 현재 클러스터에 설치된 로그인 규칙을 보고 수정하는 데 유용합니다.

명령	설명
`tctl get login_rules`	클러스터에 설치된 모든 로그인 규칙을 보여줍니다.
`tctl get login_rule/<rule_name>`	특정 설치된 로그인 규칙을 가져옵니다.
`tctl create login_rule.yaml`	새로운 로그인 규칙을 설치합니다.
`tctl create -f login_rule.yaml`	기존의 로그인 규칙을 덮어씁니다.
`tctl rm login_rule/<rule_name>`	로그인 규칙을 삭제합니다.

예제 로그인 규칙

그룹별로 정의된 정적 값 목록에 속성을 설정합니다

kind: login_rule
version: v1
metadata:
  name: example
spec:
  priority: 0
  traits_expression: |
    external.put("allow-env",
      choose(
        option(external.group.contains("dev"), set("dev", "staging")),
        option(external.group.contains("qa"), set("qa", "staging")),
        option(external.group.contains("admin"), set("dev", "qa", "staging", "prod")),
        option(true, set()),
      ))

OIDC/SAML 제공자가 제공한 특정 특성만 사용하기

groups와 email 특성만 유지하려면 원래 값으로 설정합니다:

kind: login_rule
version: v1
metadata:
  name: example
spec:
  priority: 0
  traits_map:
    groups:
      - external.groups
    email:
      - external.email

특정 특성 제거하기

특정 특성을 제거하고 나머지를 유지합니다:

kind: login_rule
version: v1
metadata:
  name: example
spec:
  priority: 0
  traits_expression: |
    external.remove("big-trait")

특정 특성을 추가적인 값으로 확장하기

kind: login_rule
version: v1
metadata:
  name: example
spec:
  priority: 0
  traits_expression: |
    external.add_values("logins", "ubuntu", "ec2-user")

한 로그인 규칙의 출력을 다른 규칙에 사용하기

kind: login_rule
version: v1
metadata:
  name: set_groups
spec:
  priority: 0
  traits_expression: |
    external.put("groups",
      ifelse(external.groups.contains("admins"),
        external["groups"].add("superusers"),
        external["groups"]))
---
kind: login_rule
version: v1
metadata:
  name: set_logins
spec:
  priority: 1
  traits_expression: |
    ifelse(external.groups.contains("superusers"),
      external.add_values("logins", "root"),
      external)

Teleport 원문 보기