SAML IdP 속성 매핑
속성 매핑(Attribute Mapping)은 Teleport SAML ID 공급자가 SAML 응답에서 사용자 정의 속성을 어설션하도록 설정합니다. 속성 매핑은 Teleport 웹 UI에서 SAML 애플리케이션을 추가할 때 설정하거나, tctl create 또는 API를 통해 생성된 saml_idp_service_provider 리소스 스펙으로 설정할 수 있습니다.
속성 매핑(Attribute Mapping)은 Teleport SAML ID 공급자가 SAML 응답에서 사용자 정의 속성을 어설션하도록 설정합니다. Teleport SAML IdP는 속성 매핑을 위해 다음 세 가지 설정 필드를 지원합니다:
name: 출력 속성의 이름. 필수 항목. 속성 매핑 내에서 고유해야 합니다.value: 조건식(predicate expression)을 사용하여 정의된 값으로, Teleport 사용자 이름, 역할 또는 트레잇을 참조할 수 있습니다. 필수 항목.name_format: SAML 속성 이름 형식. 선택 항목. 다음 형식을 지원합니다:unspecified: 값이urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified와 동일합니다. 기본값으로 사용됩니다.uri: 값이urn:oasis:names:tc:SAML:2.0:attrname-format:uri와 동일합니다.basic: 값이urn:oasis:names:tc:SAML:2.0:attrname-format:basic와 동일합니다.
속성 매핑은 Teleport 웹 UI에서 SAML 애플리케이션을 추가할 때 설정하거나, tctl create 또는 API를 통해 생성된 saml_idp_service_provider 리소스 스펙으로 설정할 수 있습니다.
kind: saml_idp_service_provider
metadata:
name: example.com
spec:
entity_id: https://example.com/saml/metadata
acs_url: https://example.com/saml/metadata
attribute_mapping:
- name: username
value: uid
- name: firstname
name_format: basic # 선택 항목, 값을 제공하지 않으면 unspecified가 기본값으로 사용됩니다.
value: user.spec.traits.firstname
- name: groups
name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:basic # 선택 항목, 전체 urn 형식.
value: user.spec.roles
사전 요구사항#
-
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
tctlandtshclients.Installing `tctl` and `tsh` clients
-
Determine the version of your Teleport cluster. The
tctlandtshclients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at/v1/webapi/findand 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')" -
Follow the instructions for your platform to install
tctlandtshclients:
-
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.
- 서비스 프로바이더 리소스를 생성할 권한이 있는 Teleport 사용자. 사전 설정된
editor역할에 이 권한이 있습니다. - SAML을 처음 사용하신다면 진행하기 전에 SAML ID 공급자 레퍼런스를 먼저 확인하시기 바랍니다.
조건식(Predicate Expression)#
속성 값은 조건식을 사용하여 작성합니다.
서비스 프로바이더가 속성 매핑과 함께 생성되면, 내부적으로 속성 매핑 세부 정보(속성 이름, 이름 형식 및 해당 값)가 서비스 프로바이더 엔티티 디스크립터의 SAML 요청 속성 요소로 포함됩니다.
그런 다음, SSO 요청 중에 SAML 어설션 서비스는 엔티티 디스크립터에서 표현식을 추출하고 인증된 사용자 컨텍스트와 함께 조건식 평가기에 전달합니다.
표현식이 평가되면, 결과 값이 요청된 속성 이름 아래 SAML 응답에서 어설션됩니다.
평가 컨텍스트#
다음 사용자 속성을 Teleport IdP와 서비스 프로바이더 간의 매핑에 사용할 수 있습니다:
| 속성 | 문법 |
|---|---|
| 사용자 이름 | uid 또는 user.metadata.name. |
| 역할 | eduPersonAffiliation 또는 user.spec.roles. |
| 트레잇 | user.spec.traits.firstname, user.spec.traits.groups 등. |
올바르고 지원되는 조건식이 있다면, 요청된 속성이 Teleport에 존재하는 한 속성이 매핑됩니다. 존재하지 않는 값을 가리키는 속성 매핑은 SAML 어설션에 포함되지 않습니다.
조건식 문법#
속성 매핑을 위한 조건식은 위에 나열된 평가 컨텍스트를 사용하여 접근할 수 있는 사용자 속성에 대해 평가됩니다.
지원되는 함수 및 메서드는 다음 참조 사용자 스펙 파일에 대해 평가된 사용 문법 및 결과와 함께 아래에 나열됩니다:
# 참조 사용자 스펙 파일
kind: user
metadata:
name: foobar
spec:
roles:
- access
- editor
- dev-ssh
traits:
firstname:
- foo
lastname:
- BAR
displayname:
- foo bar
email:
- foobar@example.com
groups:
- okta-admin
- dev-sso
- dev-rdp
메서드#
add#
새 값을 추가합니다. user.spec.roles 및 user.spec.traits.groups에 작동합니다.
| 표현식 | 결과 |
|---|---|
user.spec.roles.add("staging-ssh") |
access, editor, dev-ssh, staging-ssh |
사용자 스펙 파일에 없는 완전히 새로운 값을 추가할 수도 있습니다. 예:
| 표현식 | 결과 |
|---|---|
set().add("prod-ssh") 또는 set("prod-ssh") |
prod-ssh |
remove#
값을 제거합니다. user.spec.roles 및 user.spec.traits.groups에 작동합니다.
| 표현식 | 결과 |
|---|---|
user.spec.roles.remove("editor", "access") |
dev-ssh |
contains#
일치하는 표현식에 대해 boolean 값을 반환합니다. ifelse와 같은 헬퍼 함수에서 사용합니다.
user.spec.roles 및 user.spec.traits.groups에 작동합니다.
| 표현식 | 결과 |
|---|---|
user.spec.traits.groups.contains("okta-admin") |
true |
헬퍼 함수#
strings.upper#
문자열을 대문자로 변환합니다.
| 표현식 | 결과 |
|---|---|
strings.upper(user.spec.traits.firstname) |
FOO |
strings.lower#
문자열을 소문자로 변환합니다.
| 표현식 | 결과 |
|---|---|
strings.lower(user.spec.traits.lastname) |
bar |
strings.replaceall#
일치하는 모든 문자열을 교체합니다.
| 표현식 | 결과 |
|---|---|
strings.replaceall(user.spec.traits.groups, "-", "+") |
okta+admin, dev+sso, dev+rdp |
strings.replaceall(user.spec.traits.groups, "admin", "dev") |
okta-dev, dev-sso, dev-rdp |
strings.split#
일치하는 문자에서 문자열을 분할합니다.
| 표현식 | 결과 |
|---|---|
strings.split(user.spec.traits.groups, "-") |
okta, admin, dev, sso, rdp |
ifelse#
조건부로 값을 반환합니다. contains와 같은 메서드와 함께 사용합니다.
시그니처: ifelse(조건, "조건이 참일 때 반환할 값", "조건이 거짓일 때 반환할 값")
| 표현식 | 결과 |
|---|---|
ifelse(user.spec.traits.groups.contains("okta-admin"), user.spec.traits.groups.add("new group"), user.spec.traits.groups) |
okta-admin, dev-sso, dev-rdp, new group |
union#
user.spec.traits.groups와 user.spec.roles의 값을 결합합니다.
| 표현식 | 결과 |
|---|---|
union(user.spec.traits.groups, user.spec.roles) |
okta-admin, dev-sso, dev-rdp, access, editor, dev-ssh |
union(user.spec.traits.groups.remove("okta-admin"), user.spec.roles) |
dev-sso, dev-rdp, access, editor, dev-ssh |
속성 매핑 테스트#
test-attribute-mapping 명령어#
속성 매핑은 tctl idp saml test-attribute-mapping 명령어로 테스트할 수 있습니다.
test-attribute-mapping 명령어는 세 가지 인수를 받습니다.
--users: 사용자 이름 또는 사용자 스펙이 포함된 파일 이름. 필수 항목.--sp: 속성 매핑이 포함된 서비스 프로바이더 스펙 파일 이름. 필수 항목.--format:yaml또는json. 선택 항목. 플래그를 제공하지 않으면 텍스트로 출력됩니다.
test-attribute-mapping 명령어는 Teleport 사용자 리소스에 대해 속성을 평가하며, 접근 목록을 통해 동적으로 부여된 역할은 포함되지 않습니다. 접근 목록을 통해 부여된 역할은 로그인 시 해결되어 실제 SAML 어설션에는 나타나지만 테스트 출력에는 나타나지 않습니다.
예: 사용자 이름과 서비스 프로바이더 스펙 파일로 테스트:
# 사용자 이름과 서비스 프로바이더 파일로 테스트
$ tctl idp saml test-attribute-mapping --users user1 --sp sp.yml
User: user1
Attribute Name Attribute Value
-------------- -----------------------------
firstname foo
lastname bar
roles access, editor, dev-ssh
groups okta-admin, dev-sso, dev-rdp
사용자 스펙 파일과 서비스 프로바이더 스펙 파일로 테스트:
$ tctl idp saml test-attribute-mapping --users user.yml --sp sp.yml
원하는 형식으로 결과 출력:
$ tctl idp saml test-attribute-mapping --users user.yml --sp sp.yml --format (json/yaml)
기본 속성 덮어쓰기#
Teleport는 모든 SAML 어설션에 다음 기본 속성을 포함합니다:
| 친숙한 이름 | 이름 | 설명 |
|---|---|---|
uid |
urn:oid:0.9.2342.19200300.100.1.1 |
Teleport 사용자 이름 |
eduPersonAffiliation |
urn:oid:1.3.6.1.4.1.5923.1.1.1.1 |
모든 Teleport 역할 |
기본 속성과 동일한 name으로 커스텀 속성 매핑을 정의하면 커스텀 매핑이 기본값을 덮어씁니다. 이는 서비스 프로바이더가 SAML 어설션에 크기 제한을 적용하는 경우 유용합니다. 예를 들어, AWS IAM Identity Center는 SAML 어설션에 50,000자 제한을 적용하는데, Teleport 역할이 많은 사용자는 이 제한을 초과할 수 있습니다.
기본 eduPersonAffiliation 속성을 덮어쓰고 역할의 일부만 포함하려면 매핑에서 전체 속성 이름(urn:oid:1.3.6.1.4.1.5923.1.1.1.1)을 사용하세요:
kind: saml_idp_service_provider
metadata:
name: example-sp
spec:
entity_id: https://example.com/saml/metadata
acs_url: https://example.com/saml/acs
attribute_mapping:
- name: urn:oid:1.3.6.1.4.1.5923.1.1.1.1
value: regexp.replace(user.spec.roles, "^prefix-.*", "$0")
name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
이 예시에서는 모든 Teleport 역할 대신 prefix- 접두사와 일치하는 역할만 어설션에 포함됩니다. prefix-를 실제 역할에서 사용하는 접두사로 교체하세요.
SAML 어설션에서 모든 역할을 완전히 제외하려면 빈 set()을 사용하세요:
attribute_mapping:
- name: urn:oid:1.3.6.1.4.1.5923.1.1.1.1
value: set()
name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri