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

작동 방식#

Teleport Enterprise 배포에서, Teleport SAML IdP는 Teleport 프록시 서비스의 일부로 실행되며 SAML IdP를 구현하는 프록시 서비스 HTTP API 경로를 노출합니다. SAML IdP 서비스 프로바이더라는 Teleport 동적 리소스를 생성하여 IdP에 서드파티 애플리케이션을 등록할 수 있으며, 이 리소스에는 애플리케이션에 대한 정보가 포함됩니다.

사전 요구사항#

• 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.

• SAML을 처음 사용하신다면 진행하기 전에 SAML ID 공급자 레퍼런스를 먼저 확인하시기 바랍니다.
• 테스트를 위한 SAML 애플리케이션(SAML 서비스 프로바이더 또는 SP라고도 함). 이 가이드에서는 RSA Simple Test Service Provider를 사용합니다. 이는 Teleport SAML IdP를 테스트할 수 있는 무료 서비스입니다. 이 테스트 서비스에는 보호된 페이지가 있으며, 유효한 SAML 어설션 플로우로 사이트에 페더레이션된 사용자만 접근할 수 있습니다. 이 가이드에서는 이 애플리케이션을 "IAMShowcase" 앱이라고 부릅니다.

1/4단계. 역할 생성#

첫 번째 단계로, IAMShowcase 앱의 saml_idp_service_provider 리소스를 관리할 권한을 부여하는 역할을 생성합니다. 이 역할은 또한 Teleport로 인증하여 이 애플리케이션에 로그인할 수 있는 권한도 부여합니다. 이 역할의 이름을 saml-admin으로 지정합니다.

Teleport 웹 UI의 사이드 탐색 메뉴에서 Zero Trust Access > Roles 메뉴를 선택합니다. Roles UI에서 Create New Role 버튼을 클릭합니다.

"saml-admin"을 역할 이름으로 입력하고 Next: Resources 버튼을 클릭하여 "Resources" 탭으로 이동합니다.

Resources 탭에서 + Add Teleport Resource Access 버튼을 클릭하여 드롭다운 메뉴를 열고 Application Access를 선택합니다. 레이블 키로 "env"를 입력하고 레이블 값으로 "saml-test"를 입력합니다. 이 가이드의 3단계에서는 이 역할에서 부여하는 권한 범위를 제한하는 일치하는 레이블 값 env: saml-test로 SAML 서비스 프로바이더 리소스를 생성합니다.

Next: Admin Rules 버튼을 클릭하여 Admin Rules 탭으로 이동합니다.

Admin Rules 탭에서 + Add New 버튼을 클릭합니다. Teleport Resources 입력 상자에서 saml_idp_service_provider 리소스를 검색하여 선택합니다. 그런 다음 Permissions 섹션에서 read, list, create, update, delete 권한을 체크합니다.

Next: Options 버튼을 클릭하여 다음 단계로 이동한 후 Create Role 버튼을 클릭하여 새 역할을 생성합니다.

`saml-admin` 역할에 대한 참조 YAML 스펙.

```yaml kind: role metadata: name: saml-admin spec: allow: app_labels: env: saml-test rules: - resources: - saml_idp_service_provider verbs: - read - list - create - update - delete version: v8 ```

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

2/4단계. 서비스 프로바이더 설정#

이 단계에서는 Teleport SAML IdP 메타데이터로 SAML 서비스 프로바이더를 설정합니다.

Teleport 웹 UI에서 제공하는 SAML 애플리케이션 설정 마법사를 통해 Teleport SAML IdP 메타데이터 값을 얻을 수 있습니다.

Teleport 웹 UI에서 Add New > Resource 메뉴를 선택하고 "saml application"을 검색합니다. "SAML Application (Generic)" 타일을 선택합니다.

SAML 애플리케이션 설정 마법사의 첫 번째 단계로, Teleport 웹 UI는 Teleport SAML IdP 메타데이터 값을 표시합니다.

SAML 서비스 프로바이더 설정 과정은 서비스 프로바이더마다 다릅니다. 일부 서비스 프로바이더는 Teleport SAML IdP의 엔티티 ID, SSO URL 및 X.509 인증서를 명시적으로 제공하도록 요청할 수 있습니다. 다른 서비스 프로바이더는 Teleport SAML IdP 메타데이터(SAML 엔티티 디스크립터) 파일을 업로드하도록 요청할 수 있습니다.

이 가이드가 기반으로 하는 IAMShowcase 앱의 경우, 올바른 형식의 IdP 페더레이션 SAML 어설션 데이터에 대해 보호된 페이지 접근을 허용하도록 설계되었습니다.

따라서 설정 마법사의 다음 단계로 이동하여 IAMShowcase 앱을 Teleport에 추가합니다.

3/4단계. Teleport에 서비스 프로바이더 추가#

Teleport에 서비스 프로바이더를 추가하려면 서비스 프로바이더 메타데이터를 설정해야 합니다. 서비스 프로바이더의 엔티티 ID와 ACS URL 값을 제공하거나, 서비스 프로바이더의 엔티티 디스크립터 값(메타데이터 파일이라고도 하며, XML 파일)을 제공하여 설정할 수 있습니다.

아래에 두 가지 설정 옵션을 모두 설명합니다.

옵션 1: 엔티티 ID와 ACS URL로 설정#

이 설정 방법을 사용하면, Teleport는 먼저 엔티티 ID 엔드포인트를 쿼리하여 엔티티 디스크립터를 가져오려고 시도합니다. 해당 엔드포인트에서 엔티티 디스크립터를 찾을 수 없는 경우, Teleport는 주어진 엔티티 ID와 ACS URL 값으로 새 엔티티 디스크립터를 생성합니다.

IAMShowcase 앱을 설정하려면 다음 값을 제공해야 합니다:

• 앱 이름: IAMShowcase.
• SP 엔티티 ID / 대상 URI: IAMShowcase. 서비스 프로바이더의 SAML 메타데이터 값 또는 엔드포인트.
• ACS URL / SP SSO URL: https://sptest.iamshowcase.com/acs. SAML 인증 후 사용자가 리디렉션될 엔드포인트. ACS URL은 SAML SSO URL이라고도 합니다.
• 레이블: env: saml-test. 레이블은 RBAC에서 사용됩니다.

Finish 버튼을 클릭합니다. "IAMShowcase" 앱이 Teleport에 추가됩니다.

옵션 2: 엔티티 디스크립터 파일로 설정#

이 옵션을 사용하면 서비스 프로바이더 메타데이터를 설정하는 데 필요한 모든 세부 정보가 포함된 서비스 프로바이더 엔티티 디스크립터 파일을 제공합니다.

서비스 프로바이더가 엔티티 디스크립터 파일을 다운로드하는 옵션을 제공하거나 엔티티 디스크립터를 더 세밀하게 제어해야 하는 경우, Teleport에 서비스 프로바이더를 추가하는 데 권장되는 옵션입니다.

IAMShowcase 앱을 설정하려면 다음 값을 제공해야 합니다:

• 앱 이름: IAMShowcase.
• 엔티티 디스크립터: IAMShowcase 앱의 엔티티 디스크립터로, 이 URL에서 사용 가능합니다: https://sptest.iamshowcase.com/testsp_metadata.xml.
• 레이블: env: saml-test.

Finish 버튼을 클릭합니다. "IAMShowcase" 앱이 Teleport에 추가됩니다.

중요: 엔티티 디스크립터가 제공된 경우, 그 내용은 엔티티 ID와 ACS URL에 제공된 값보다 우선합니다.

4/4단계. 보호된 페이지 접근 확인#

모든 것이 제대로 작동하는지 확인하려면 Teleport 웹 UI의 Resources 페이지로 이동하여 "IAMShowcase" 앱을 검색합니다.

"IAMShowcase" 앱 타일에서 Log in 버튼을 클릭하면, Teleport SAML IdP가 서명한 SAML 어설션 데이터와 함께 IAMShowcase 앱의 보호된 페이지로 이동합니다.

이 페이지는 Teleport SAML IdP에 의해 페더레이션된 역할 이름 등의 다른 속성과 함께 Teleport 사용자 세부 정보를 표시하며, Teleport에서 SAML 서비스 프로바이더가 성공적으로 설정되었음을 확인합니다.

tctl을 사용하여 SAML IdP 서비스 프로바이더 리소스 관리#

tctl을 사용하여 saml_idp_service_provider 리소스를 관리하는 예제입니다.

saml_idp_service_provider 리소스 생성#

먼저, 다음 saml_idp_service_provider 리소스 스펙으로 Teleport 리소스 스펙 파일을 생성합니다:

cat > iamshowcase.yaml << EOF
kind: saml_idp_service_provider
metadata:
  labels:
    env: saml-test
  # 서비스 프로바이더의 리소스 이름.
  name: IAMShowcase
spec:
  acs_url: https://sptest.iamshowcase.com/acs
  entity_id: IAMShowcase
version: v1
EOF

다음으로, tctl create 명령어를 사용하여 Teleport 리소스를 생성합니다:

$ tctl create iamshowcase.yaml
# SAML IdP service provider 'IAMShowcase' has been created.

saml_idp_service_provider 리소스 업데이트#

리소스를 업데이트하려면, 먼저 Teleport 클러스터에서 리소스 스펙의 최신 복사본을 가져옵니다.

$ tctl get saml_idp_service_provider/IAMShowcase > iamshowcase.yaml

그런 다음 iamshowcase.yaml을 수정하여 스펙을 업데이트하고, 저장한 후 tctl create -f 명령어를 사용하여 Teleport 리소스를 업데이트합니다:

$ tctl create -f iamshowcase.yaml

saml_idp_service_provider 리소스 목록 조회#

특정 서비스 프로바이더 목록 조회:

$ tctl get saml_idp_service_provider/IAMShowcase

모든 서비스 프로바이더 목록 조회:

$ tctl get saml_idp_service_provider

saml_idp_service_provider 리소스 삭제#

$ tctl rm saml_idp_service_provider/IAMShowcase

다음 단계#

• SAML IdP 서비스 프로바이더 리소스에 대한 접근 제어 방법을 알아봅니다.
• SAML 속성 매핑을 설정합니다.