Teleport를 SAML 아이덴티티 공급자로 사용하기

이 가이드는 Teleport를 SAML 아이덴티티 공급자(IdP)로 사용하는 방법에 대한 예제를 자세히 설명합니다. Teleport SAML IdP를 설정하면 Teleport 사용자가 Teleport를 통해 외부 서비스에 인증할 수 있습니다.

필수 조건

실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하여 무료 평가판을 이용해 보십시오.
tctl 관리자 도구 및 tsh 클라이언트 도구.

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

연결이 가능한지 확인하기 위해 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 명령어를 실행할 수도 있습니다.
SAML에 익숙하지 않다면 진행하기 전에 SAML 아이덴티티 공급자 참조를 검토하는 것이 좋습니다.
서비스 제공자 리소스를 생성할 수 있는 권한이 있는 사용자. 사전 설정된 editor 역할이 이 권한을 가지고 있습니다.
테스트용 SAML 애플리케이션(서비스 제공자 또는 SP라고도 함). 이 가이드에서는 Teleport SAML IdP를 테스트할 수 있는 무료 테스트 서비스인 RSA Simple Test Service Provider를 사용할 것입니다. 테스트 서비스에는 보호된 페이지가 있으며, 사용자가 유효한 SAML 주장을 통해 사이트에 연합될 때만 접근할 수 있습니다.

1/3단계. Teleport에 서비스 제공자 추가

Teleport에 서비스 제공자를 추가하려면 서비스 제공자 메타데이터를 구성해야 합니다. 이는 서비스 제공자의 Entity ID 및 ACS URL 값을 제공하거나, 서비스 제공자의 엔터티 설명자 값(메타데이터 파일, XML 파일이라고도 함)을 제공하여 구성할 수 있습니다.

아래에서는 두 가지 구성 옵션을 보여드립니다.

먼저 웹 UI에서 Access Management를 클릭한 후 Enroll New Resource 메뉴를 선택합니다. 검색 상자에 "saml"을 입력하면 SAML 애플리케이션 통합 타일이 표시됩니다. 타일을 클릭합니다.

첫 번째 구성 단계인 Configure Service Provider with Teleport's Identity Provider Metadata에서는 Teleport SAML IdP 메타데이터 값을 보여줍니다. 이 가이드에서는 Next 버튼을 클릭하여 Add Service Provider To Teleport 단계로 이동할 수 있습니다.

옵션 1: Entity ID와 ACS URL로 구성

이 옵션의 경우, 서비스 제공자를 추가하는 데 필요한 최소 구성 값은 다음과 같습니다:

Entity ID: SAML 메타데이터 값 또는 서비스 제공자의 엔드포인트.
ACS URL: SAML 인증 후 사용자가 리디렉션되는 엔드포인트. ACS URL은 SAML SSO URL이라고도 합니다.

Simple Test Service Provider를 구성하기 위해 제공해야 하는 값은 다음과 같습니다:

App Name: iamshowcase
SP Entity ID / Audience URI: iamshowcase
ACS URL / SP SSO URL: https://sptest.iamshowcase.com/acs

Finish 버튼을 클릭하면 iamshowcase 앱이 이제 Teleport에 추가됩니다.

다음 saml_idp_service_provider 사양은 Simple Test Service Provider를 Teleport에 추가하는 참고용입니다:

kind: saml_idp_service_provider
metadata:
  # 서비스 제공자의 친근한 이름. 이는 서비스 제공자를 관리하는 데 사용됩니다
  # 그리고 아이덴티티 공급자 주도 SSO에서도 사용됩니다.
  name: iamshowcase
spec:
  # entity_id는 서비스 제공자의 메타데이터 값 또는 엔드포인트입니다
  # 엔터티 설명자를 제공하는, 즉 SP 메타데이터입니다.
  entity_id: iamshowcase
  # acs_url은 사용자가 SAML 인증 후 리디렉션되는 엔드포인트입니다.
  acs_url: https://sptest.iamshowcase.com/acs
version: v1

tctl 을 사용하여 사양을 Teleport에 추가하세요:

tctl create iamshowcase.yaml
SAML IdP 서비스 제공자 'iamshowcase'가 생성되었습니다.

Note

이 구성 방법을 사용하면, Teleport는 먼저 entity_id 엔드포인트를 쿼리하여 엔터티 설명자를 가져오려고 시도합니다. 해당 엔드포인트에서 엔터티 설명서를 찾을 수 없는 경우, Teleport는 주어진 entity_id 및 acs_url 값을 사용하여 새로운 엔터티 설명자를 생성합니다.

옵션 2: 엔터티 설명자 파일로 구성하기

서비스 제공자가 엔터티 설명자 파일을 다운로드할 수 있는 옵션을 제공하거나 엔터티 설명자에 대한 더 많은 제어가 필요한 경우, 이는 Teleport에 서비스 제공자를 추가하는 권장 옵션입니다.

이 옵션에서는 서비스 제공자 엔터티 설명자 파일을 제공하며, 이 파일에는 서비스 제공자 메타데이터를 구성하는 데 필요한 모든 세부정보가 포함되어 있습니다.

Teleport에 서비스 제공자 추가 페이지에서 SAML 서비스 제공자 이름(iamshowcase )을 입력합니다. 이제 + 엔터티 설명자 추가 (선택사항) 버튼을 클릭하면 엔터티 설명자 편집기가 확장됩니다. Simple Test Service Provider 메타데이터 파일을 복사하여 URL https://sptest.iamshowcase.com/testsp_metadata.xml 에서 가져오고, 이를 Teleport 웹 UI의 엔터티 설명자 편집기에 붙여넣습니다.

끝내기 버튼을 클릭하면 iamshowcase 앱이 이제 Teleport에 추가됩니다.

먼저 Simple Test Service Provider에서 서비스 제공자 메타데이터를 iamshowcase.xml 로 다운로드합니다:

curl -o iamshowcase.xml https://sptest.iamshowcase.com/testsp_metadata.xml

아래 템플릿을 사용하여 iamshowcase.yaml 이라는 파일을 만듭니다. 방금 다운로드한 메타데이터를 saml_idp_service_provider 객체의 entity_descriptor 필드에 할당합니다:

kind: saml_idp_service_provider
metadata:
  # 서비스 제공자의 친숙한 이름입니다. 이는 서비스 제공자를 관리하는 데 사용됩니다.
  # 또한 아이덴티티 제공자 주도 SSO에도 사용됩니다.
  name: iamshowcase
spec:
  # entity_descriptor는 서비스 제공자 XML입니다.
  entity_descriptor: |
    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"...
version: v1

이 파일을 tctl 을 사용하여 Teleport에 추가합니다:

tctl create iamshowcase.yaml
SAML IdP 서비스 제공자 'samltest-id'가 생성되었습니다.

Important

entity_descriptor 가 제공되면, 그 내용이 entity_id 및 acs_url 에 제공된 값보다 우선합니다.

Teleport는 서비스 제공자가 처음 생성될 때만 엔터티 설명자를 가져오거나 생성하려고 시도합니다. 이후 업데이트에는 서비스 제공자 사양에 엔터티 설명자가 존재해야 합니다. 따라서 서비스 제공자를 업데이트할 때는 먼저 Teleport에 저장된 사양을 가져오고, 그 후에 구성을 수정해야 합니다.

서비스 제공자 사양 가져오기
tctl get saml_idp_service_provider/<service provider name> > service-provider.yml

2/3단계. 서비스 제공자가 Teleport의 SAML IdP를 인식하도록 구성하기

이 단계는 서비스 제공자에 따라 다릅니다. 일부 서비스 제공자는 Teleport SAML IdP 엔터티 ID, SSO URL 및 X.509 인증서를 제공할 것을 요청할 수 있습니다. 다른 서비스 제공자는 Teleport SAML IdP 메타데이터 파일을 업로드할 것을 요청할 수 있습니다.

이 값들은 Teleport 웹 UI의 Teleport의 아이덴티티 제공자 메타데이터로 서비스 제공자 구성 UI에서 찾을 수 있으며, 이는 SAML 앱 등록 흐름의 첫 번째 단계로 표시됩니다.

이 가이드를 기반으로 한 Simple Test Service Provider의 경우, 샘플 앱은 잘 형식화된 IdP 연합 SAML assertion 데이터에 대해 보호된 페이지에 대한 액세스를 허용하도록 설계되었습니다.

따라서 이전 단계에서 끝내기 버튼을 클릭하면, Simple Test Service Provider의 보호된 페이지가 리소스 페이지에서 이미 접근할 수 있습니다.

3단계 중 3. iamshowcase 보호 페이지에 대한 액세스 확인

모든 것이 작동하는지 확인하기 위해 Teleport Web UI의 리소스 페이지로 이동합니다.

이제 "iamshowcase" 앱이 리소스 타일 아래에 나타납니다. 이 타일 내에서 로그인 버튼을 클릭하면 iamshowcase 보호 페이지로 이동합니다.

이 페이지는 Teleport 사용자 세부정보와 함께 역할과 같은 다른 속성이 Teleport SAML IdP에 의해 연합됨을 보여줍니다.

이것은 작동하는 idp 시작 SSO 로그인 흐름으로 구성된 Teleport에 서비스 공급자를 추가하는 것을 보여줍니다.

권장: 서비스 공급자를 관리하기 위한 전용 역할 만들기

운영 환경에서는 서비스 공급자를 관리하기 위한 전용 역할을 만드는 것을 권장합니다.

전용 역할을 만들려면 먼저 saml_idp_service_provider 객체를 읽고 수정할 수 있는 권한이 있는 사용자로 Teleport에 로그인되어 있는지 확인합니다. 기본 editor 역할은 이미 이 권한이 있지만, 더 맞춤화된 구성을 사용하는 경우, 다음 내용을 포함하는 sp-manager.yaml 이라는 역할을 생성하세요:

kind: role
metadata:
  name: sp-manager
spec:
  allow:
    rules:
      - resources:
          - saml_idp_service_provider
        verbs:
          - list
          - create
          - read
          - update
          - delete
version: v7

tctl 로 역할을 생성합니다:

tctl create sp-manager.yaml
역할 'saml-idp-service-provider-manager'가 생성되었습니다.

다음으로, 이 역할을 사용자에게 추가합니다.

sp-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?},sp-manager"

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

텍스트 편집기에서 github 인증 커넥터를 엽니다:
```
tctl edit github/github
```
github 커넥터를 수정하여 teams_to_roles 섹션에 sp-manager 을 추가합니다.

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

예시는 다음과 같습니다:
```
  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - sp-manager
```
파일을 편집하고 저장하여 변경 사항을 적용합니다.
Teleport 클러스터에서 로그아웃한 후 다시 로그인하여 새로운 역할을 가집니다.

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 섹션에 sp-manager 을 추가합니다.

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

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

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 섹션에 sp-manager 을 추가합니다.

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

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

다음 단계

SAML 속성 매핑 구성.

Teleport 원문 보기