로그인 규칙은 사용자가 Teleport에 로그인할 때 SSO 프로바이더가 제공하는 외부 속성을 변환하는 로직을 정의하여 클러스터의 사용자에게 일관된 접근 제어 정책을 제공합니다. Teleport 관리자는 로그인 규칙을 사용하여 IdP 구성을 변경하지 않고도 사용자 속성의 변환을 정의할 수 있습니다. 이는 조직의 아이덴티티 프로바이더(IdP)를 관리하는 팀이 Teleport를 관리하는 팀과 분리된 경우에 특히 유용합니다.

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

작동 방식#

로그인 규칙은 Auth Service 백엔드에 저장된 동적 Teleport 리소스입니다. 사용자가 IdP를 통해 Teleport에 인증하면 Teleport는 IdP의 데이터를 기반으로 사용자의 외부 속성을 채웁니다. 로그인 규칙은 사용자의 외부 속성을 조작하기 위한 로직을 정의합니다. 사용자가 Teleport에 로그인하면 Teleport Auth Service는 우선순위 순서로 로그인 규칙을 실행합니다. 모든 로그인 규칙을 실행한 후 Auth Service는 사용자에게 발급하는 인증서에 최종 외부 속성 세트를 인코딩합니다.

로그인 규칙 구성에 대한 자세한 내용은 로그인 규칙 참조를 참조하세요.

사전 요구 사항#

• A running Teleport Enterprise cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:

     $ TELEPORT_DOMAIN=
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. Follow the instructions for your platform to install tctl and tsh clients:

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

$ tsh login --proxy= --user=
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

시작하기 전에 버전 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

Assign the loginrule-manager role to your Teleport user by running the appropriate commands for your authentication provider:

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/ | jq 'first.spec.traits' > input.json
$ tctl login_rule test --resource-file my_rule.yaml input.json
access:
- staging
groups:
- dbs
- devs
logins:
- alice

이 스크립트는 표현식의 구문 오류를 잡아냅니다. 예상되는 모든 속성이 출력에 있는지 확인합니다.

4/5단계. 로그인 규칙 만들기#

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

$ tctl create my_rule.yaml

5/5단계. 확인#

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

$ tctl get --format json users/ | 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는 커넥터 사양을 기대합니다. 클러스터에 현재 설치된 커넥터로 디버깅하려면 다음 명령을 실행합니다. 을 Teleport에 등록한 SSO 커넥터의 이름으로 교체합니다:

$ tctl get connector/ --with-secrets | tctl sso test

다음 단계#

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

도움말 명령을 실행하거나 참조 페이지를 확인하여 tctl login_rule test 명령에 대해 알아보세요.

$ tctl help login_rule test

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

예제 로그인 규칙#

임의의 비표준 JSON 클레임이 있는 OIDC 프로바이더 사용#

표준 OIDC 클레임은 문자열 값과 목록으로 구성됩니다. 그러나 비표준 JSON 클레임을 반환하는 프로바이더가 있을 수도 있습니다. 기본적으로 Teleport는 claims_to_roles 매핑이나 사용자의 Teleport 속성에 이러한 클레임을 읽으려고 시도하지 않습니다.

예를 들어 여러 다른 프로바이더 소스의 사용자 클레임을 집계하는 사용자 정의 분산 IdP를 상상해 봅니다. 클레임 세트는 다음 형식의 JSON 객체처럼 보일 수 있습니다:

{
  "aggregated_claims": {
    "okta": {
      "groups": "okta_dev"
    },
    "auth0": {
      "groups": "auth0_devops"
    }
  }
}

다음 JSONPath 표현식은 이러한 클레임을 가져와 표준 groups 클레임으로 보간합니다:

kind: login_rule
version: v1
metadata:
  name: set_logins
spec:
  priority: 1
  traits_expression: |
    external.put("groups", jsonpath("$.aggregated_claims.*.groups"))

위의 클레임과 로그인 규칙으로 로그인하는 사용자는 다음과 같은 클레임을 가진 것처럼 처리됩니다:

{
  "groups": [
    "okta_dev",
    "auth0_devops"
  ]
}

이러한 보간된 클레임은 클레임-역할 매핑에 사용될 수 있으며, 표준 클레임과 마찬가지로 Teleport 속성으로 유지됩니다.

그룹당 정적 값 목록으로 속성 설정#

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)