이 가이드는 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 사용자.

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.

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:///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 메시지를 교환하고 사용자에게 인증서를 발급하는 데 필요한 정보를 제공하는 인증 커넥터를 만듭니다.

역할 매핑 할당#

When a user authenticates to Teleport, the Teleport Auth Service issues SSH and TLS certificates to the user that contain the user's Teleport roles.

For SSO authentication connectors, the Auth Service determines which roles to encode in the certificate by reading the authentication connector's role mapping. The role mapping indicates which Teleport roles to assign based on data that your identity provider stores about the user.

When you configure an authentication connector using the tctl CLI, a role mapping takes the following format:

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

For example, the following role mapping means that any user with the claim groups with the value admins receives the Teleport roles auditor and editor:

groups,admins,auditor,editor

For the purpose of this guide, assign two separate role mappings:

• A more permissive role mapping:
• A more restrictive role mapping:

Entra ID의 groups 클레임에는 그룹의 객체 ID가 포함됩니다. 따라서 그룹 객체 ID를 사용하여 그룹을 매핑해야 합니다. 의 groups 값을 ad-app-admin의 객체 ID로, 를 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가 필요합니다. 에 할당합니다.
• --id: 1단계에서 만든 엔터프라이즈 애플리케이션의 애플리케이션(클라이언트) ID. 이 값은 Azure 포털의 엔터프라이즈 애플리케이션 "Overview" 섹션에서 복사할 수 있습니다. 에 할당합니다.
• --secret: 이전에 만든 클라이언트 시크릿.

$ tctl sso configure oidc --name "entra-id" \
  --display "Entra ID" \
  --issuer-url https://login.microsoftonline.com//v2.0 \
  --id  \
  --secret $(cat /tmp/client-secret) \
  --claims-to-roles groups, \
  --claims-to-roles groups, \
  --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://


콜백 주소 변경

The callback address can be changed if calling back to a remote machine
instead of the local machine is required:
# --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

For this to work the hostname or CIDR of the remote machine that will be used for
the callback will need to be allowed via your auth connector's client_redirect_settings:
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단계. 인증 기본 설정 구성#

Edit your cluster authentication preferences so you can make the authentication
connector you configured in this guide the default authentication method for
your Teleport cluster.
Open the Teleport Web UI. From the left sidebar, navigate to Zero Trust
Access > Auth Connectors. Find the connector you would like to make the
default and, from its three-dot menu, select Set as default.
If you are managing your Teleport resources as configuration files, you can
choose a default authentication connector using a dynamic resource. In this
case, use tctl to edit the cluster_auth_preference value:
$ tctl edit cluster_auth_preference

Set the value of spec.type to oidc:
kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  type: oidc
  ...
version: v2

After you save and exit the editor, tctl will update the resource:
cluster auth preference has been updated


Additional ways to edit cluster auth preferences
The cluster auth preference is available as a Teleport Terraform provider
resource. Find a list of configuration options in the Cluster Auth Preferences
Resource
Reference.
If you self-host Teleport, you can edit your Teleport Auth Service configuration
file to include the following:
# Snippet from /etc/teleport.yaml
auth_service:
  authentication:
    type: oidc


If you need to log in again before configuring your identity provider, use the
flag --auth=local.

다음 단계#
Microsoft Entra ID와 Teleport를 통합하는 방법을 알았으니 이제 조직에 더 잘 맞도록 구성을 개선할 수 있습니다.
OIDC 설정 편집#
Teleport가 지원하는 다른 OIDC 관련 구성에 대해 자세히 알아보세요.
Teleport 역할에서 IdP 속성 통합#

Now that you have connected Teleport to your identity provider, you can
customize the way Teleport includes IdP data in Teleport roles.
With role templates, you can include user data from your IdP directly in
Teleport roles. If you use the external template variable in the value of a
role field, Teleport passes that value from your IdP. In this example, all of
the role options you can use for allowing users to assume certain principals on
remote systems come from your 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}}']

For more information on using the external template variable, see Role
Templates.
For an explanation of the fields listed above, see the Role
Reference.
If you need to transform your IdP user data before you include it in Teleport
roles, you can do so using Login Rules. Login Rules allow you to include
external traits within Teleport roles even if your IdP provides user data in a
different format than the one expected by Teleport. Read more about Login
Rules.

문제 해결#
Note
이 섹션의 내용은 원문 문서를 참조하세요. (oidc-login-troubleshooting.mdx)
아이덴티티 프로바이더 콜백 실패, 파라미터 "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