Infograb logo
로그인 규칙 설정

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

사전 요구조건

  • 실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하여 무료 평가판을 이용해 보십시오.

  • tctl 관리자 도구 및 tsh 클라이언트 도구.

    tctltsh 다운로드에 대한 지침은 설치 를 방문하십시오.

  • 연결이 가능한지 확인하기 위해 tsh login 으로 로그인한 다음, 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
    tsh login --proxy=teleport.example.com --user=email@example.com
    tctl status

    클러스터 teleport.example.com

    버전 17.0.0-dev

    CA 핀 sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

    클러스터에 연결할 수 있고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 후속 tctl 명령어를 실행할 수 있습니다.
    자신의 Teleport 클러스터를 호스팅하는 경우, Teleport Auth Service를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

시작하기 전에 11.3.1 이상의 버전을 사용하는 Teleport Enterprise 또는 Cloud 클러스터가 실행 중이어야 합니다.

로그인 규칙은 SSO 로그인에서만 작동하므로 시작하기 전에 OIDC, SAML 또는 GitHub 커넥터를 구성했는지 확인하십시오. Single Sign-On 문서를 참조하여 이를 설정하는 방법을 알아보세요.

1/5단계. RBAC 구성

먼저, 로그인 규칙 리소스를 읽고 수정할 수 있는 권한이 있는 사용자로 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 사용자에게 할당하려면, 인증 제공자에 맞는 적절한 명령어를 실행하십시오:

  1. 로컬 사용자의 역할을 쉼표로 구분된 목록으로 가져옵니다:

    ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')
  2. 새로운 역할을 추가하기 위해 로컬 사용자를 수정합니다:

    tctl users update $(tsh status -f json | jq -r '.active.username') \ --set-roles "${ROLES?},loginrule-manager"
  3. Teleport 클러스터에서 로그아웃한 후 다시 로그인하여 새로운 역할을 가집니다.

  1. 텍스트 편집기에서 github 인증 커넥터를 엽니다:

    tctl edit github/github
  2. github 커넥터를 수정하여 teams_to_roles 섹션에 loginrule-manager 을 추가합니다.

    이 역할에 매핑해야 하는 팀은 조직의 역할 기반 액세스 제어(RBAC) 설계에 따라 다릅니다. 그러나 팀은 귀하의 사용자 계정을 포함해야 하며, 조직 내에서 가장 작은 팀이어야 합니다.

    예시는 다음과 같습니다:

      teams_to_roles:
        - organization: octocats
          team: admins
          roles:
            - access
    +       - loginrule-manager
    
  3. 파일을 편집하고 저장하여 변경 사항을 적용합니다.

  4. Teleport 클러스터에서 로그아웃한 후 다시 로그인하여 새로운 역할을 가집니다.

  1. saml 구성 리소스를 가져옵니다:

    tctl get --with-secrets saml/mysaml > saml.yaml

    --with-secrets 플래그는 spec.signing_key_pair.private_key 의 값을 saml.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하므로, 리소스를 업데이트한 후 즉시 saml.yaml 파일을 삭제해야 합니다.

  2. saml.yaml 을 수정하여 attributes_to_roles 섹션에 loginrule-manager 을 추가합니다.

    이 역할에 매핑해야 하는 속성은 조직의 역할 기반 액세스 제어(RBAC) 설계에 따라 다릅니다. 그러나 그룹은 귀하의 사용자 계정을 포함해야 하며, 조직 내에서 가장 작은 그룹이어야 합니다.

    예시는 다음과 같습니다:

      attributes_to_roles:
        - name: "groups"
          value: "my-group"
          roles:
            - access
    +       - loginrule-manager
    
  3. 변경 사항을 적용합니다:

    tctl create -f saml.yaml
  4. Teleport 클러스터에서 로그아웃한 후 다시 로그인하여 새로운 역할을 가집니다.

  1. oidc 구성 리소스를 가져옵니다:

    tctl get oidc/myoidc --with-secrets > oidc.yaml

    --with-secrets 플래그는 spec.signing_key_pair.private_key 의 값을 oidc.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하므로, 리소스를 업데이트한 후 즉시 oidc.yaml 파일을 삭제해야 합니다.

  2. oidc.yaml 을 수정하여 claims_to_roles 섹션에 loginrule-manager 을 추가합니다.

    이 역할에 매핑해야 하는 클레임은 조직의 역할 기반 액세스 제어(RBAC) 설계에 따라 다릅니다. 그러나 그룹은 귀하의 사용자 계정을 포함해야 하며, 조직 내에서 가장 작은 그룹이어야 합니다.

    예시는 다음과 같습니다:

      claims_to_roles:
        - name: "groups"
          value: "my-group"
          roles:
            - access
    +       - loginrule-manager
    
  3. 변경 사항을 적용합니다:

    tctl create -f oidc.yaml
  4. Teleport 클러스터에서 로그아웃한 후 다시 로그인하여 새로운 역할을 가집니다.

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 은 실행 시간에 Teleport 클러스터에서 평가되어 로그인하는 각 SSO 사용자의 특성을 결정하는 스크립트 형태입니다. 이 표현식은 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 공급자가 제공하는 특정 특성만 사용

groupsemail 특성만 유지하고 원래 값을 그대로 두려면:

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 원문 보기