이 가이드는 Teleport를 위한 OIDC 아이덴티티 프로바이더로 Microsoft Entra ID(구 Azure AD)를 구성하는 방법을 보여줍니다. 이 구성으로 사용자는 Entra ID로 인증하여 Teleport에 접근할 수 있으며, Entra ID의 그룹 멤버십에 따라 Teleport에서 리소스에 접근하거나 관리할 수 있는 권한이 부여됩니다.

SAML 기반 Entra ID IdP 구성 버전은 이 가이드에서 확인할 수 있습니다.

작동 방식#

Microsoft Entra ID 테넌트에서 엔터프라이즈 애플리케이션을 만들고 Teleport를 위한 OIDC 아이덴티티 프로바이더로 설정합니다. 사용자의 OIDC ID 토큰에 포함될 groups 클레임도 구성합니다.

Teleport에서 인증 커넥터 리소스를 만들고 Microsoft Entra ID를 OIDC 아이덴티티 프로바이더로 설정합니다. Entra ID 그룹을 Teleport 역할에도 매핑합니다.

사용자가 Microsoft Entra ID 계정으로 인증하여 Teleport에 로그인하면 Teleport는 먼저 groups 클레임에서 매핑된 Teleport 역할과 속성으로 임시 사용자 계정을 만듭니다. 속성은 사용자 속성(키-값 형식)입니다. OIDC ID 토큰에 있는 모든 클레임은 사용자 속성으로 보존됩니다. Teleport는 그런 다음 사용자 아이덴티티, 역할 및 속성을 인코딩하는 단기 TLS 및 SSH 인증서 쌍을 발급하여 새 세션을 시작합니다. 이러한 인증서는 Teleport에서 접근 권한을 부여하기 위해 평가됩니다.

Microsoft Entra ID 그룹과 Teleport 역할 매핑을 시연하기 위해 Microsoft Entra ID 테넌트에 두 사용자 그룹을 만들겠습니다:

1. ad-app-support. 이 그룹을 Teleport 사전 설정 requester 역할에 매핑합니다. 사전 설정 requester 역할은 Teleport에 등록된 리소스에 대한 접근을 요청할 수 있는 권한을 부여합니다.
2. ad-app-admin. 이 그룹을 Teleport 사전 설정 reviewer와 editor 역할에 매핑합니다. 사전 설정 editor 역할은 Teleport에서 리소스를 관리할 수 있는 권한을 부여합니다. 사전 설정 reviewer는 Teleport에서 리소스에 대한 접근을 검토할 수 있는 권한을 부여합니다.

새 그룹을 만드는 대신 이 가이드를 따르기 위해 기존 Microsoft Entra ID 그룹을 사용할 수 있습니다.

사전 요구 사항#

• Microsoft Entra ID 테넌트에서 엔터프라이즈 애플리케이션을 만들고, Microsoft Graph API 권한을 구성 및 부여하고, 그룹을 관리할 수 있는 권한.
• 인증 커넥터, 사용자 및 역할을 읽고 쓸 수 있는 사전 설정 editor 역할 또는 동등한 역할이 있는 Teleport 사용자.

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단계. Microsoft Entra ID 구성#

그룹 만들기#

Azure 포털에서 "Azure services" 메뉴 아래에 있는 "Groups" 메뉴를 선택합니다.

"Groups" UI에서 "New group" 버튼을 클릭하여 ad-app-admin이라는 새 사용자 그룹을 만듭니다.

원하는 사용자를 이 그룹에 추가할 수 있습니다. 이 단계를 반복하여 ad-app-support라는 다른 그룹을 만듭니다.

엔터프라이즈 애플리케이션 만들기#

Azure 포털에서 "Azure services" 메뉴에서 "Enterprise applications"를 선택합니다. + New Application 버튼을 클릭하고 + Create your own application 버튼을 클릭합니다. 애플리케이션 이름을 입력하고 애플리케이션을 만듭니다.

그룹 할당#

Azure 포털에서 엔터프라이즈 애플리케이션 UI에서 "Manage" 메뉴 아래에 있는 "Users and groups" 메뉴를 선택합니다.

"Users and groups" UI에서 +Add user/group 버튼을 클릭합니다.

이제 1단계에서 만든 두 그룹을 할당합니다. 기존 사용자 그룹으로 이 가이드를 따르는 경우 이 단계에서 해당 그룹을 선택합니다.

OIDC 구성#

OIDC 구성에는 신뢰 당사자(이 경우 Teleport)에 대한 리다이렉트 URI 설정, OIDC 클레임 설정 및 클라이언트 자격 증명 설정이 포함됩니다.

이러한 OIDC 구성은 "App registrations" 서비스에서 사용 가능합니다.

Azure 포털에서 "Azure services" 메뉴에서 "App registrations"를 선택합니다. "App registrations" UI에서 이 가이드를 따르면서 만든 엔터프라이즈 애플리케이션을 검색하고 선택합니다.

엔터프라이즈 애플리케이션의 "App registrations" UI에서 "Manage" 메뉴에서 "Authentication" 메뉴를 선택합니다. 이 구성 UI에서 "Platform configurations" 섹션 아래에서 + Add a platform 버튼을 클릭합니다.

Teleport의 OIDC 리다이렉트 URI는 OIDC 콜백 엔드포인트를 가리켜야 하며, 다음과 같은 URI 형식을 가집니다: https://example.teleport.sh/v1/webapi/oidc/callback.

아래에 Teleport 클러스터의 Teleport Proxy Service 호스트명을 입력하여 OIDC 콜백 URI를 생성합니다. 그런 다음 Azure 포털에서 해당 값을 복사하여 붙여넣어 OIDC 리다이렉트 URI를 구성합니다.

https://example.teleport.sh/v1/webapi/oidc/callback

리다이렉트 URI가 구성되면 구성을 저장합니다.

클라이언트 자격 증명 설정#

Teleport는 OIDC 인증 코드 플로우를 사용하여 사용자의 ID 토큰에 대한 OIDC 인증 코드를 교환합니다. ID 토큰을 교환하려면 Teleport에 대한 클라이언트 자격 증명을 설정해야 합니다.

엔터프라이즈 애플리케이션의 "App registrations" UI에서 "Manage" 메뉴에서 "Certificates & secrets"를 선택합니다. 이제 "Client secrets" 탭을 선택하고 + New client secret 버튼을 클릭합니다. 새 클라이언트 시크릿을 만듭니다.

시크릿이 만들어지면 값을 복사하고 작업 환경에 저장합니다:

$ echo 'secret value copied from entra id' > /tmp/client-secret

그룹 클레임 구성#

Teleport에서 접근을 구성하려면 groups 클레임을 구성해야 합니다.

엔터프라이즈 애플리케이션의 "App registrations" UI에서 "Manage" 메뉴에서 "Token configuration"을 선택합니다.

"Token configuration" UI에서 + Add groups claim 버튼을 클릭합니다.

사용자의 OIDC groups 클레임에 포함하려는 그룹 유형을 선택합니다.

아래 참고 이미지는 "Security groups" 유형이 선택된 것을 보여줍니다.

원하는 대로 다른 클레임을 구성할 수 있습니다. Microsoft Entra ID에서 발급하는 모든 클레임은 사용자 리소스의 사용자 속성으로 보존됩니다.

(선택 사항) 그룹 초과 클레임#

사용자의 그룹 멤버십이 200개 그룹 제한을 초과하면 Microsoft Entra ID는 예상되는 groups 클레임 대신 그룹 초과 클레임을 발급합니다. 그룹 초과 클레임에는 사용자의 그룹 멤버십을 Microsoft Graph API에서 쿼리해야 함을 나타내는 Azure AD Graph API 링크가 포함됩니다.

사용자의 그룹 멤버십이 그룹 제한을 초과하지 않는 경우 이 단계를 건너뛸 수 있습니다. 그렇지 않으면 Teleport에 Microsoft Graph API 권한을 부여하여 Microsoft Graph API를 사용하여 사용자의 그룹 멤버십을 가져올 수 있도록 해야 합니다.

사용자의 그룹 멤버십을 가져오기 위한 Graph API 권한이 이제 구성되었습니다. 사용자의 그룹 멤버십이 200개 그룹을 초과하면 Teleport는 Entra ID에서 발급한 그룹 초과 클레임을 따르고 Microsoft Graph API를 사용하여 사용자의 그룹 세부 정보를 가져옵니다.

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

이 섹션에서는 Teleport가 Microsoft Entra ID와 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

Entra ID의 groups 클레임에는 그룹의 객체 ID가 포함됩니다. 따라서 그룹 객체 ID를 사용하여 그룹을 매핑해야 합니다. mapping_1의 groups 값을 ad-app-admin의 객체 ID로, mapping_2를 ad-app-support의 객체 ID로 업데이트합니다.

OIDC 커넥터 만들기#

인증 커넥터 리소스를 만들기 전에 먼저 구성 사양을 생성하고 구성을 테스트하는 것이 유용합니다.

인증 커넥터 사양은 tctl sso configure 명령을 사용하여 구성할 수 있습니다. 다음 플래그로 명령을 실행하는 방법을 보여드리겠습니다:

• --name: Microsoft Entra ID 인증 커넥터의 Teleport 리소스 이름.
• --display: Microsoft Entra ID 인증 커넥터의 표시 이름.
• --issuer-url: Microsoft Entra ID OIDC 발급자 URL. 이 URL을 구성하려면 Microsoft Entra ID 테넌트 ID가 필요합니다. Entra ID tenant ID에 할당합니다.
• --id: 1단계에서 만든 엔터프라이즈 애플리케이션의 애플리케이션(클라이언트) ID. 이 값은 Azure 포털의 엔터프라이즈 애플리케이션 "Overview" 섹션에서 복사할 수 있습니다. Enterprise application client ID에 할당합니다.
• --secret: 이전에 만든 클라이언트 시크릿.

$ tctl sso configure oidc --name "entra-id" \
  --display "Entra ID" \
  --issuer-url https://login.microsoftonline.com/Entra ID tenant ID/v2.0 \
  --id Enterprise application client ID \
  --secret $(cat /tmp/client-secret) \
  --claims-to-roles groups,mapping_1 \
  --claims-to-roles groups,mapping_2 \
  --scope openid \
  --scope email \
  --scope profile > entraid-oidc-connector.yaml

kind: oidc
metadata:
  name: entra-id
spec:
  claims_to_roles:
  - claim: groups
    roles:
    - editor
    - reviewer
    value: da770259-8007-42da-a9c2-3b366a88bc1c
  - claim: groups
    roles:
    - requester
    value: ed5763df-9465-45e8-b10b-06a8979b072e
  client_id: d40666f7-3352-43e8-a8ad-b75e7a0a7be3
  client_secret: example-secret-value
  display: Entra ID
  issuer_url: https://login.microsoftonline.com/0297d2f3-62c3-4598-aaa1-2104929ba73c/v2.0
  redirect_url: https://example.teleport.sh:443/v1/webapi/oidc/callback
  scope:
  - openid
  - email
  - profile
version: v3

기본적으로 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

# --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'

커넥터 테스트#

파일을 tctl sso test 명령에 파이프하여 커넥터 리소스를 테스트합니다:

$ cat entraid-oidc-connector.yaml | tctl sso test

구성 테스트가 실패하면 tctl sso test 명령이 문제를 디버깅하는 데 도움이 되는 유용한 정보를 출력합니다.

커넥터 만들기#

구성이 작동하면 tctl create 명령을 사용하여 커넥터 리소스를 만듭니다:

$ tctl create -f entraid-oidc-connector.yaml

Microsoft Entra ID의 인증 커넥터 리소스가 이제 구성되었습니다.

3/3단계. 인증 기본 설정 구성#

이 가이드에서 구성한 인증 커넥터를 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 플래그를 사용하십시오.

다음 단계#

Microsoft Entra ID와 Teleport를 통합하는 방법을 알았으니 이제 조직에 더 잘 맞도록 구성을 개선할 수 있습니다.

OIDC 설정 편집#

Teleport가 지원하는 다른 OIDC 관련 구성에 대해 자세히 알아보세요.

Teleport 역할에서 IdP 속성 통합#

이제 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 역할에 포함할 수 있습니다. 로그인 규칙에 대해 자세히 알아보세요.

문제 해결#

아이덴티티 프로바이더 콜백 실패, 파라미터 "Name" 없음#

Teleport는 email 클레임을 사용자의 사용자 이름으로 사용합니다. 이 오류는 사용자의 OIDC ID 토큰 클레임에서 email 클레임을 찾을 수 없음을 나타냅니다.

이는 사용자에게 도메인이 검증된 이메일 계정이 없는 경우 발생할 수 있습니다.

또는 다른 클레임 값(고유하게 식별 가능한 값이어야 함)을 email 클레임의 대안으로 사용하도록 커넥터 사양을 업데이트할 수 있습니다.

예제:

kind: oidc
metadata:
  name: entra-id
spec:
  ... # 간략하게 다른 필드는 표시하지 않음
  username_claim: oid

oid 클레임을 찾을 수 없음#

사용자를 위해 그룹 초과 클레임이 발급되었지만 Teleport가 oid 클레임을 찾을 수 없는 경우 사용자가 이 오류를 받을 수 있습니다.

이를 해결하려면 인증 커넥터에 profile 범위가 구성되어 있는지 확인합니다.

kind: oidc
metadata:
  name: entra-id
spec:
  ... # 간략하게 다른 필드는 표시하지 않음
  scope:
  - openid
  - email
  - profile