이 가이드는 Terraform과 tctl을 사용하여 Teleport를 Microsoft Entra ID와 통합하는 방법을 보여줍니다. Terraform을 사용하여 Entra ID 측 설정을 구성하고 tctl을 사용하여 Teleport에 Entra ID 플러그인을 설치합니다.

지원되는 다른 설정 방법에 대해서는 다음 가이드를 참조하십시오:

• Entra ID 통합 시작하기
• Azure Portal을 사용하여 Entra ID 통합 설정

작동 방식#

Teleport Entra ID 통합을 처음 사용하신다면 통합 작동 방식을 먼저 읽어보십시오. entra-id-integration Terraform 모듈은 Microsoft Entra ID 엔터프라이즈 애플리케이션을 배포하고 Microsoft Entra ID를 통한 Teleport 인증을 활성화하기 위해 Teleport 클러스터의 SAML ID 공급자로 설정하여 통합을 구성합니다.

또한 모듈은 Microsoft Entra ID에서 사용자 및 그룹 데이터를 가져와 Teleport RBAC 리소스와 동기화하기 위해 Teleport Auth Service에 권한을 할당합니다. 설정에 따라 Terraform 모듈은 시스템 자격 증명(Microsoft Graph API 권한 ID)을 사용하거나 Teleport를 OIDC IdP로 사용하여 이를 수행합니다.

사전 요구 사항#

• Teleport 클러스터에 대한 Teleport Identity Governance 활성화.
• 사용자는 Microsoft Azure 및 Entra ID 테넌트에서 특권 관리자 권한이 있어야 합니다.

1/3단계. Terraform 준비#

Teleport Github 저장소에서 사용 가능한 Teleport Entra ID 통합 예제 모듈을 클론합니다.

예제는 Teleport Entra ID 통합에 필요한 속성으로 Entra ID 테넌트를 설정하는 설정 가능한 Terraform 모듈을 제공합니다. 이 모듈은 azuread 공급자를 기반으로 합니다.

예제는 환경에서 인증된 Azure CLI 세션이 사용 가능하다고 가정합니다. azuread 공급자는 테넌트 수준 액세스가 필요하므로 Azure CLI는 --allow-no-subscriptions 플래그를 사용하여 인증해야 합니다.

$ az login --allow-no-subscriptions

2/3단계. 설정 및 적용#

예제 Terraform 모듈은 Teleport Entra ID 통합에 대해 설정하려는 Microsoft Graph API 인증 방법을 기반으로 하는 Entra ID 설정 옵션을 제공합니다.

Teleport는 두 가지 유형의 Microsoft Graph API 인증 방법을 지원합니다: OIDC IdP로서의 Teleport와 시스템 자격 증명입니다.

Teleport Cloud를 사용하는 경우 Teleport를 OIDC IdP로 설정하는 옵션만 지원됩니다. 자체 호스팅 Teleport 클러스터가 있는 경우 Teleport Proxy Service가 공개적으로 액세스 가능한지 확인해야 합니다.

또는 자체 호스팅 Teleport 클러스터가 있거나 Teleport Proxy Service가 공개적으로 액세스 가능하지 않은 경우 시스템 자격 증명 설정이 가장 적합합니다. 이러한 인증 방법의 차이점에 대한 자세한 내용은 이 페이지에서 확인할 수 있습니다.

최소한 Terraform 예제는 다음 입력 변수가 필요합니다:

• app_name: Entra ID에서 생성될 엔터프라이즈 애플리케이션의 이름.
• proxy_service_address: Teleport Proxy Service 호스트, 예: example.teleport.sh.
• certificate_expiry_date: SAML 어설션 서명 인증서 만료 날짜. 예: 2026-05-01T01:02:03Z. 만료된 인증서는 사용자가 Teleport에 로그인하지 못하도록 방지합니다. 만료되면 Terraform에서 이 값을 업데이트하고 Entra ID에 대해 생성된 SAML 기반 Teleport Auth Connector에서도 업데이트해야 합니다.

cat > variables.auto.tfvars << EOF
app_name                = ""
proxy_service_address   = ""
certificate_expiry_date = ""
EOF

$ terraform plan

$ terraform apply

Connect-AzureAD
# This is a service principal object representing Microsoft Graph in Entra ID with a specific app ID.
$GraphServicePrincipal = Get-AzureADServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'"
# These are Microsoft Graph API permissions required by the managed identity.
$permissions = @(
  "Application.ReadWrite.OwnedBy"   # Permission to read application
  "Group.Read.All"     # Permission to read groups in the directory
  "User.Read.All"        # Permission to read users in the directory
)
# Filter and find the app roles in the Microsoft Graph service principal that matches with permissions.
# Only include roles where "AllowedMemberTypes" includes "Application" (suitable for managed identities).
$appRoles = $GraphServicePrincipal.AppRoles |
    Where-Object Value -in $permissions |
    Where-Object AllowedMemberTypes -contains "Application"
# Print ID of each of the three permissions.
foreach ($appRole in $appRoles) {
  "{0} : {1}" -f $appRole.Value, $appRole.Id
}

cat > variables.auto.tfvars << EOF
app_name                = ""
proxy_service_address   = ""
certificate_expiry_date = ""
use_system_credentials   = true
graph_permission_ids    = []
managed_id              = ""
EOF

$ terraform plan

$ terraform apply

변경 사항이 적용되면 Terraform 모듈은 애플리케이션 클라이언트 ID와 Entra ID 테넌트 ID 값을 출력으로 생성합니다. 다음 단계에서 이 값들이 필요합니다.

Entra ID가 이제 Teleport Entra ID 통합에 필요한 속성으로 설정되었습니다.

3/3단계. Entra ID 플러그인 설치#

통합 설정을 완료하려면 Teleport에 Entra ID 플러그인을 설치합니다. 플러그인은 tctl plugins install entraid 명령으로 설치할 수 있습니다.

$ tctl plugins install entraid \
    --name entra-id-default \
    --auth-connector-name entra-id \
    --default-owner= \
    --no-access-graph \
    --manual-setup

$ tctl plugins install entraid \
    --name entra-id-default \
    --auth-connector-name entra-id \
    --default-owner= \
    --no-access-graph \
    --use-system-credentials \
    --manual-setup

• --name 플래그는 Entra ID 플러그인의 리소스 이름을 지정합니다.
• --auth-connector-name 플래그는 이 통합이 생성할 인증 커넥터의 이름을 지정합니다.
• --default-owner 플래그는 Entra ID에서 가져온 그룹을 기반으로 Teleport에서 생성될 Access List의 기본 소유자를 지정합니다.
• --no-access-graph 플래그는 Identity Security 통합을 건너뛰도록 지정합니다.
• --use-system-credentials 플래그는 Managed Identity를 사용하여 설정된 시스템 자격 증명을 사용하도록 지정합니다. 시스템 자격 증명 기반 인증을 설정하려는 경우에만 이 플래그를 사용하십시오.
• --manual-setup 플래그는 수동 Entra ID 설정이 사용자에 의해 선택되었음을 지정합니다.

그런 다음 tctl은 2단계에서 Terraform을 사용하여 생성된 엔터프라이즈 애플리케이션의 Entra ID 테넌트 ID와 애플리케이션 클라이언트 ID를 묻습니다.

이 값을 입력하면 설치 명령이 Teleport에 SAML Auth Connector를 생성하고 Entra ID에서 Teleport로 사용자와 그룹을 가져오는 플러그인 서비스를 생성합니다.

다음 단계#

• Entra ID 사용자를 위한 액세스 설정 방법을 알아봅니다.
• 그룹 필터 설정.
• Entra ID 인증 커넥터 설정을 더 자세히 살펴봅니다.
• Entra ID와의 Identity Security 통합 작동 방식을 알아봅니다.
• Teleport Entra ID 통합 관련 FAQ를 확인합니다.