이 가이드는 OpenID Connect(OIDC라고도 함)를 사용하는 SSO 프로바이더를 구성하여 특정 사용자 그룹에게 Teleport 자격 증명을 발급하는 방법을 설명합니다. 역할 기반 접근 제어(RBAC)와 함께 사용하면 OIDC를 통해 Teleport 관리자가 다음과 같은 정책을 정의할 수 있습니다:

• "DBA" 그룹의 구성원만 PostgreSQL 데이터베이스에 연결할 수 있습니다.
• 개발자는 프로덕션 서버에 절대 SSH 접근을 하면 안 됩니다.

작동 방식#

Teleport cluster를 your SSO provider에 애플리케이션으로 등록한 다음, 애플리케이션에 대한 정보를 Teleport에 제공하는 authentication connector 리소스를 생성할 수 있습니다. 사용자가 Teleport에 로그인하면 your SSO provider가 자체 인증 플로우를 실행한 후, 인증이 완료되었음을 알리기 위해 Teleport cluster에 HTTP 요청을 보냅니다.

Teleport는 수명이 짧은 인증서를 발급하여 사용자를 인프라에 인증합니다. 사용자가 SSO 인증 플로우를 완료하면 Teleport는 사용자에게 수명이 짧은 TLS 및 SSH 인증서를 발급합니다. 또한 Teleport는 Auth Service 백엔드에 임시 사용자를 생성합니다.

Teleport role은 사용자의 인증서에 인코딩됩니다. 사용자에게 Teleport role을 할당하기 위해 Auth Service는 authentication connector 내의 role mapping을 검사하며, 이는 your SSO provider의 사용자 데이터를 하나 이상의 Teleport role 이름과 연결합니다.

사전 요구사항#

• 그룹/역할에 할당된 사용자와 통합할 SSO/IdP에 대한 관리자 접근 권한.

• oidc 리소스를 유지 관리할 수 있는 권한을 가진 Teleport 역할. 이 권한은 기본 editor 역할에서 사용할 수 있습니다.

• 실행 중인 Teleport Enterprise 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

• tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

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

  2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 

Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음, 현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.

예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의 도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여 다음 명령을 실행합니다:

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

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

1/3단계. OIDC 프로바이더 구성#

사용할 외부 ID 공급자에 Teleport를 등록하고 client_id와 client_secret을 확보합니다. 이 정보는 ID 공급자 웹사이트에 문서화되어 있어야 합니다. 다음은 몇 가지 참고 링크입니다:

• Auth0 클라이언트 구성
• Google Identity Platform
• Keycloak 클라이언트 등록

ID 공급자에서 관련 정보를 저장하세요. 이 가이드를 더 쉽게 따라 할 수 있도록 여기에 클라이언트 ID를 추가하면 아래 예제 명령어에 포함됩니다:

Client ID: CLIENT-ID

OIDC 리디렉션 URL 선택#

OIDC는 인증이 완료된 후 제어권을 Teleport로 반환하기 위해 HTTP 리디렉션에 의존합니다. 리디렉션 URL은 Teleport 관리자가 사전에 선택해야 합니다.

Teleport에서 OIDC 인증을 위한 리디렉션 URL은 mytenant.teleport.sh:443/v1/webapi/oidc/callback입니다. mytenant.teleport.sh:443를 사용자의 Teleport Cloud 테넌트 또는 프록시 서비스 주소로 바꾸세요. 자체 호스팅 클러스터에 Teleport 프록시 서비스용 공개 주소(Teleport 구성 파일의 proxy_service.public_addr 값)가 여러 개 있는 경우, 이 주소가 목록의 첫 번째 주소를 가리키는지 확인하세요.

2/3단계. OIDC 프로바이더를 Teleport에 연결#

이 섹션에서는 Teleport가 IdP와 OIDC 메시지를 교환하고 사용자에게 인증서를 발급하는 데 필요한 정보를 제공하는 인증 커넥터를 생성합니다.

역할 매핑 할당#

사용자가 Teleport에 인증하면, Teleport Auth Service는 사용자의 Teleport 역할이 포함된 SSH 및 TLS 인증서를 사용자에게 발급합니다.

SSO 인증 커넥터의 경우, Auth Service는 인증 커넥터의 역할 매핑을 읽어 인증서에 어떤 역할을 인코딩할지 결정합니다. 역할 매핑은 아이덴티티 제공자가 사용자에 대해 저장하는 데이터를 기반으로 어떤 Teleport 역할을 할당할지 나타냅니다.

tctl CLI를 사용하여 인증 커넥터를 구성할 때, 역할 매핑은 다음 형식을 따릅니다:

<claim_name>,<claim_value>,<teleport_role_1>,<teleport_role_2>,...,<teleport_role_n>

예를 들어, 다음 역할 매핑은 값이 admins인 claim groups를 가진 모든 사용자가 Teleport 역할 auditor와 editor를 받는다는 것을 의미합니다:

groups,admins,auditor,editor

이 가이드의 목적을 위해 두 개의 개별 역할 매핑을 할당합니다:

• 더 관대한 역할 매핑: groups,admins,auditor,editor
• 더 제한적인 역할 매핑: groups,devs,access

OIDC 커넥터 구성#

다음 단계는 Teleport에 OIDC 커넥터를 추가하는 것입니다. 커넥터는 tctl 리소스 명령어 또는 Teleport 웹 UI를 사용하여 생성, 테스트, 추가 또는 제거됩니다.

워크스테이션에서 클라이언트 시크릿만 담긴 client-secret.txt 파일을 생성하세요.

새 커넥터를 생성하려면 tctl sso configure를 사용하세요. 다음 예제는 oidc-connector.yaml이라는 이름의 YAML 형식 커넥터 리소스 파일을 생성합니다:

$ tctl sso configure oidc --name  \
  --issuer-url  \
  --id CLIENT-ID \
  --secret $(cat client-secret.txt) \
  --claims-to-roles mapping_1 \
  --claims-to-roles mapping_2 > oidc-connector.yaml

• --name: 일반적으로 IdP의 이름이며, Teleport에서 커넥터가 식별되는 방식입니다.
• --issuer-url: .well-known/openid-configuration을 제외한, IdP의 OIDC 구성 엔드포인트에 대한 기본 경로입니다. 예를 들어 엔드포인트가 https://example.com/.well-known/openid-configuration이면 https://example.com을 사용합니다.
• --id: IdP에 정의된 클라이언트 ID입니다. ID 공급자에 따라 사용자가 직접 정의할 수 있는 값(예: teleport)이거나 할당된 문자열일 수 있습니다.
• --secret: 이 클라이언트를 인증하기 위해 IdP가 제공하는 클라이언트 토큰/시크릿입니다.

이러한 플래그와 사용 가능한 모든 플래그에 대한 자세한 내용은 Teleport CLI 레퍼런스 페이지의 tctl sso configure oidc 섹션을 참조하세요.

생성된 파일은 아래 예제와 같아야 합니다:

<div class="admonition note"><div class="admonition-title">Note</div><p>이 섹션의 내용은 원문 문서를 참조하세요. (<code>oidc-connector.yaml</code>)</p></div>

kind: oidc
metadata:
  name: keycloak
spec:
  claims_to_roles:
  - claim: groups
    roles:
    - access
    value: /devs
  - claim: groups
    roles:
    - auditor
    - editor
    value: /admins
  client_id: teleport
  client_secret: abc123...
  issuer_url: https://keycloak.example.com/realms/master
  redirect_url: https://teleport.example.com:443/v1/webapi/oidc/callback
version: v3

# --bind-addr sets the host and port tsh will listen on, and --callback changes
# what link is displayed to the user
$ tsh login --proxy=proxy.example.com --auth=github --bind-addr=localhost:1234 --callback https://remote.machine:1234

kind: oidc
metadata:
  name: example-connector
spec:
  client_redirect_settings:
    # a list of hostnames allowed for HTTPS client redirect URLs
    # can be a regex pattern
    allowed_https_hostnames:
      - remote.machine
      - '*.app.github.dev'
      - '^\d+-[a-zA-Z0-9]+\.foo.internal$'
    # a list of CIDRs allowed for HTTP or HTTPS client redirect URLs
    insecure_allowed_cidr_ranges:
      - '192.168.1.0/24'
      - '2001:db8::/96'

선택 사항: ACR 값#

Teleport는 OIDC 프로바이더로부터 인가 코드를 받을 때 인증 컨텍스트 클래스 참조(ACR) 값을 전송하는 기능을 지원합니다. 기본적으로 ACR 값은 설정되지 않습니다. 하지만 acr_values 필드가 설정되어 있으면, Teleport는 acr claim에서 동일한 값을 받을 것으로 예상하며, 그렇지 않으면 콜백을 유효하지 않은 것으로 간주합니다.

또한 Teleport는 OIDC 구성에서 provider 필드를 설정하여 활성화할 수 있는 OIDC 프로바이더별 ACR 값 처리를 지원합니다. 현재 내장 지원은 NetIQ에 대해서만 제공됩니다.

ACR 값과 프로바이더별 처리를 사용하는 예제는 다음과 같습니다:

# example connector which uses ACR values
kind: oidc
version: v2
metadata:
  name: "oidc-connector"
spec:
  issuer_url: "https://oidc.example.com"
  client_id: "xxxxxxxxxxxxxxxxxxxxxxx.example.com"
  client_secret: "zzzzzzzzzzzzzzzzzzzzzzzz"
  redirect_url: "https://mytenant.teleport.sh/v1/webapi/oidc/callback"
  display: "Login with Example"
  acr_values: "foo/bar"
  provider: netiq
  scope: [ "group" ]
  claims_to_roles:
     - claim: "group"
       value: "editor"
       roles: [ "editor" ]
     - claim: "group"
       value: "user"
       roles: [ "access" ]

선택 사항: 최대 유효 기간(Max age)#

max_age 필드는 사용자 세션이 강제로 재인증되기 전까지의 최대 유효 기간을 제어합니다. 기본적으로 max_age는 설정되지 않으며, 이는 사용자가 OIDC를 사용해 한 번 인증하면 구성된 OIDC 프로바이더가 강제하지 않는 한 재인증할 필요가 없다는 의미입니다. 이 값을 특정 기간으로 설정하면 사용자가 더 자주 재인증하도록 강제할 수 있습니다. max_age를 0초로 설정하면 사용자는 Teleport로 인증할 때마다 매번 OIDC 프로바이더로 재인증해야 합니다.

지정된 기간은 반드시 정수 초 단위여야 합니다. 24h는 1440s와 동일하므로 사용할 수 있지만, 60s500ms는 60.5초에 해당하므로 허용되지 않습니다.

# Extra parts of OIDC yaml have been removed.
spec:
  max_age: 24h

일부 OIDC 프로바이더는 max_age 설정을 지원하지 않습니다. Google과 GitLab은 모두 이를 지원하지 않는 것으로 알려져 있으며, max_age 필드가 설정된 경우 이러한 프로바이더와의 인증은 작동하지 않습니다.

선택 사항: Prompt#

OIDC 프로토콜에 따라 최종 사용자의 재인증 및 동의를 위한 인가 서버 프롬프트를 설정합니다. prompt 값을 설정하지 않으면 Teleport는 기본값으로 select_account를 사용합니다.

# Extra parts of OIDC yaml have been removed.
spec:
  # Valid values as defined from https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
  # none: The Authorization Server must not display any authentication or consent user interface pages.
  # select_account: The Authorization Server should prompt the End-User to select a user account.
  # login: The Authorization Server should prompt the End-User for reauthentication.
  # consent: The Authorization Server should prompt the End-User for consent before returning information to the Client.
  prompt: 'login'

선택 사항: 리디렉션 URL 및 타임아웃#

리디렉션 URL은 모든 사용자가 접근할 수 있어야 하며, 리디렉션 타임아웃은 선택 사항입니다.

# Extra parts of OIDC yaml have been removed.
spec:
  redirect_url: https://<cluster-url>.example.com:3080/v1/webapi/oidc/callback
  # Optional Redirect Timeout.
  # redirect_timeout: 90s

선택 사항: 이메일 확인 비활성화#

기본적으로 Teleport는 email_verified claim을 검증하며, 확인되지 않은 이메일 주소로 로그인을 시도하는 사용자는 로그인이 차단됩니다:

ERROR: SSO flow failed.
identity provider callback failed with error: OIDC provider did not verify email.
        email not verified by OIDC provider

테스트 및 기타 목적으로, OIDC 커넥터에서 allow_unverified_email을 활성화하여 이 동작을 옵트아웃할 수 있습니다. 이 옵션은 시스템의 전반적인 보안을 약화시키므로 활성화하지 않는 것을 권장합니다.

kind: oidc
version: v2
metadata:
  name: connector
spec:
  allow_unverified_email: true

선택 사항: 사용자 이름으로 사용할 claim 지정#

기본적으로 Teleport는 OIDC claim에 email claim이 있을 것으로 예상합니다. email claim의 값이 Teleport에서 사용자 이름으로 사용됩니다. 사용자 이름을 구성하는 데 다른 claim을 사용하려면 auth connector 스펙의 username_claim 필드로 기본적으로 예상되는 email claim을 재정의할 수 있습니다.

아래 예제는 username_claim 필드를 preferred_username 값으로 구성하는 방법을 보여줍니다. 이렇게 하면 Teleport가 email claim 대신 preferred_username claim을 쿼리하도록 구성됩니다.:

kind: oidc
metadata:
  # ...
spec:
  # ...
  username_claim: preferred_username

선택 사항: 요청 객체 모드#

Teleport는 RFC 9101을 따르는 "요청 객체"라고 불리는 JSON 웹 토큰(JWT)에 인가 요청 매개변수를 전송하는 기능을 지원합니다. 현재 Teleport는 값으로 전송되는 서명된 요청 객체만 지원합니다. 이 옵션을 사용하려면 요청 객체 서명을 검증하기 위해 OIDC IdP 통합에 사용되는 Teleport의 JSON 웹 키 세트(JWKS)를 IdP에 제공하거나 IdP가 이를 검색하도록 구성해야 합니다. 이 JWKS는 웹 API의 /.well-known/jwks-oidc 경로에서 찾을 수 있습니다.

또한 요청 객체 서명을 검증하는 데 사용할 공개 키는 tctl을 통해 확인할 수 있습니다.

$ tctl get cert_authority/oidc_idp/$CLUSTER_NAME --format=json | jq -r .[].spec.active_keys.jwt[].public_key

기본적으로 request_object_mode는 설정되지 않으며, 이는 인가 요청 매개변수가 인가 엔드포인트의 쿼리 문자열로 전송됨을 의미합니다.

kind: oidc
version: v2
metadata:
  name: connector
spec:
  # Use signed request objects when making authorization requests to the IdP.
  request_object_mode: signed

요청 객체는 MFA 확인에도 지원됩니다. MFA 클라이언트에서 request_object_mode가 명시적으로 설정되지 않은 경우, 기본적으로 로그인 클라이언트의 요청 객체 모드가 사용됩니다. 원한다면 MFA 클라이언트가 별도의 요청 객체 모드를 사용하도록 명시적으로 구성할 수 있습니다.

kind: oidc
version: v2
metadata:
  name: connector
spec:
  client_id: teleport_login
  client_secret: abc123...
  request_object_mode: none
  mfa:
    client_id: teleport_mfa
    client_secret: mfa123...
    request_object_mode: signed

참고: 요청 객체 지원은 Teleport Enterprise 17.7.2 이상 및 18.1.6 이상 버전에서 제공됩니다.

커넥터 테스트#

클러스터에 커넥터를 적용하기 전에, 올바르게 구성되었는지 테스트할 수 있습니다:

$ cat oidc-connector.yaml | tctl sso test

이렇게 하면 웹 브라우저가 열리고 IdP를 통해 Teleport 클러스터에 로그인을 시도합니다. 실패하는 경우, 문제 해결 정보를 위해 이 명령어의 출력을 검토하세요.

커넥터 생성#

테스트가 성공하면 커넥터를 생성하세요:

$ tctl create -f oidc-connector.yaml

3/3단계. 기본 OIDC 인증 활성화#

이 가이드에서 구성한 인증 커넥터를 Teleport 클러스터의 기본 인증 방식으로 설정할 수 있도록 클러스터 인증 기본 설정을 편집하십시오.

Teleport Web UI를 엽니다. 왼쪽 사이드바에서 Zero Trust Access > Auth Connectors로 이동합니다. 기본값으로 설정하려는 커넥터를 찾아 점 세 개 메뉴에서 Set as default를 선택하십시오.

Teleport 리소스를 구성 파일로 관리하는 경우, 동적 리소스를 사용하여 기본 인증 커넥터를 선택할 수 있습니다. 이 경우 tctl을 사용하여 cluster_auth_preference 값을 편집하십시오:

$ tctl edit cluster_auth_preference

spec.type 값을 oidc로 설정하십시오:

kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  type: oidc
  ...
version: v2

저장 후 편집기를 종료하면 tctl이 리소스를 업데이트합니다:

cluster auth preference has been updated

# Snippet from /etc/teleport.yaml
auth_service:
  authentication:
    type: oidc

아이덴티티 프로바이더를 구성하기 전에 다시 로그인해야 하는 경우, --auth=local 플래그를 사용하십시오.

다음 단계#

이제 Teleport를 자격 증명 공급자(identity provider)에 연결했으므로, Teleport가 IdP 데이터를 Teleport 역할에 포함하는 방식을 사용자 정의할 수 있습니다.

**역할 템플릿(role templates)**을 사용하면 IdP의 사용자 데이터를 Teleport 역할에 직접 포함할 수 있습니다. 역할 필드 값에 external 템플릿 변수를 사용하면, Teleport가 해당 값을 IdP에서 전달받습니다. 다음 예시에서는 사용자가 원격 시스템의 특정 프린시펄(principal)을 가정하도록 허용하는 데 사용할 수 있는 모든 역할 옵션이 IdP에서 옵니다:

kind: role
version: v7
metadata:
  name: sso-users
spec:
  allow:
    logins: ['{{external.logins}}']
    aws_role_arns: ['{{external.aws_role_arns}}']
    azure_identities: ['{{external.azure_identities}}']
    db_names: ['{{external.db_names}}']
    db_roles: ['{{external.db_roles}}']
    db_users: ['{{external.db_users}}']
    desktop_groups: ['{{external.desktop_groups}}']
    gcp_service_accounts: ['{{external.gcp_service_accounts}}']
    host_groups: ['{{external.host_groups}}']
    host_sudoers: ['{{external.host_sudoers}}']
    kubernetes_groups: ['{{external.kubernetes_groups}}']
    kubernetes_users: ['{{external.kubernetes_users}}']
    windows_desktop_logins: ['{{external.windows_desktop_logins}}']

external 템플릿 변수 사용에 대한 자세한 내용은 역할 템플릿을 참조하세요.

위에 나열된 필드에 대한 설명은 역할 레퍼런스를 참조하세요.

IdP 사용자 데이터를 Teleport 역할에 포함하기 전에 변환해야 하는 경우, **로그인 규칙(Login Rules)**을 사용하여 이를 수행할 수 있습니다. 로그인 규칙을 사용하면 IdP가 Teleport가 예상하는 형식과 다른 형식으로 사용자 데이터를 제공하더라도 외부 트레잇(external traits)을 Teleport 역할에 포함할 수 있습니다. 로그인 규칙에 대해 자세히 알아보세요.

문제 해결#