이 가이드는 SAML 인증 커넥터로 특정 사용자 그룹에게 자격 증명을 발급하는 SAML 아이덴티티 프로바이더로 Microsoft Entra ID(구 Azure AD)를 구성하는 방법을 다룹니다. 역할 기반 접근 제어(RBAC)와 함께 사용하면 Teleport 관리자가 다음과 같은 정책을 정의할 수 있습니다:

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

다음 단계는 Microsoft Entra ID 그룹과 보안 역할을 일치시키는 예제 SAML 인증 커넥터를 구성합니다. 다른 옵션을 구성하도록 선택할 수 있습니다.

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

작동 방식#

You can register your Teleport cluster as an application with Microsoft Entra ID, then create an authentication connector resource that provides Teleport with information about your application. When a user signs in to Teleport, Microsoft Entra ID executes its own authentication flow, then sends an HTTP request to your Teleport cluster to indicate that authentication has completed.

Teleport authenticates users to your infrastructure by issuing short-lived certificates. After a user completes an SSO authentication flow, Teleport issues short-lived TLS and SSH certificates to the user. Teleport also creates a temporary user on the Auth Service backend.

Teleport roles are encoded in the user's certificates. To assign Teleport roles to the user, the Auth Service inspects the role mapping within the authentication connector, which associates user data on Microsoft Entra ID with the names of one or more Teleport roles.

사전 요구 사항#

시작하기 전에 다음이 필요합니다:

• 갤러리 외 애플리케이션을 만들 수 있는 접근 권한이 있는 Microsoft Entra ID 관리자 계정(P2 라이선스).
• 디렉터리에 하나 이상의 사용자가 등록되어 있어야 합니다.
• Microsoft Entra ID에 최소 두 개의 보안 그룹을 만들고 각 그룹에 하나 이상의 사용자를 할당해야 합니다.
• saml 리소스를 유지 관리할 수 있는 접근 권한이 있는 Teleport 역할. 기본 editor 역할에서 사용 가능합니다.

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

1/3단계. Microsoft Entra ID 구성#

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

1. Entra ID -> Enterprise Applications를 선택합니다.

   

2. New application을 선택합니다.

   

3. Create your own application을 선택하고 애플리케이션 이름(예: Teleport)을 입력한 다음 **Integrate any other application you don't find in the gallery (Non-gallery)**를 선택합니다.

   

4. Manage 아래에서 Properties를 선택하고 **Assignment required?**를 No로 설정합니다.

   

   다음 단계로 진행하기 전에 Save를 클릭합니다.

SAML 구성#

1. Manage 아래에서 Single sign-on을 선택하고 SAML을 선택합니다.

   

2. Basic SAML Configuration을 편집합니다.

   

3. Entity ID 및 Reply URL 필드에 Teleport Proxy Service 호스트의 URL을 입력합니다. 예를 들어:

   https://mytenant.teleport.sh:443/v1/webapi/saml/acs/ad
   

   여러 공개 주소를 가진 셀프 호스팅 클러스터가 있는 경우 이 주소가 첫 번째로 나열된 것을 가리키도록 합니다.

   

   다음 단계로 진행하기 전에 Save를 클릭합니다.

4. SAML Certificates 섹션에서 App Federation Metadata URL 링크를 복사하고 Teleport 커넥터 구성에서 사용하기 위해 저장합니다:

   

속성 및 클레임 편집#

1. Required claim 아래에서 **Unique User Identifier (Name ID)**를 클릭합니다.

2. "name identifier format"을 Default로 변경합니다. 소스 속성이 user.userprincipalname인지 확인합니다.

   

3. 커넥터에서 사용자 보안 그룹을 사용할 수 있도록 그룹 클레임을 추가합니다:

   

4. (선택 사항) Entra ID 사용자 이름을 소문자로 변환하는 클레임을 추가하여 Teleport 역할에서 {{external.username}} 속성으로 사용합니다.

   Source를 "Transformation"으로 설정합니다. 새 패널에서:

   • Transformation 값을 "Extract()"로 설정합니다.

   • Attribute name을 user.userprincipalname으로 설정합니다.

   • Value를 @로 설정합니다.

   • "Add Transformation"을 클릭하고 Transformation을 ToLowercase()로 설정합니다.

     

2/3단계. Microsoft Entra ID를 Teleport에 연결#

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

역할 매핑 할당#

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

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

이 가이드에서는 Entra ID 보안 그룹(객체 ID로 식별)을 기반으로 하여 해당 그룹의 모든 구성원에게 하나 이상의 Teleport 역할을 할당하는 매핑을 구성합니다. 역할 매핑에서 각 속성이 다음 네임스페이스 접두사로 시작하는지 확인합니다:

http://schemas.microsoft.com/ws/2008/06/identity/claims/

두 개의 Entra ID 그룹을 서로 다른 수준의 Teleport 접근으로 매핑하기 위해 두 개의 별도 매핑을 사용합니다:

• 더 많은 권한이 있는 매핑 — 예: auditor 및 editor 역할을 받는 teleport-admins 그룹.
• 더 적은 권한이 있는 매핑 — 예: access 역할만 받는 teleport-developers 그룹.

계속하기 전에 매핑할 두 Entra ID 그룹의 객체 ID를 수집하고, 각 그룹이 받을 Teleport 역할을 결정합니다. 두 값은 모두 다음 섹션의 tctl 명령에 사용됩니다.

SAML 커넥터 구성#

이제 tctl을 사용하여 SAML 커넥터 리소스를 만듭니다.

$ tctl sso configure saml --preset ad \
  --entity-descriptor "https://login.microsoftonline.com//federationmetadata/2007-06/federationmetadata.xml?appid=" \
  --attributes-to-roles "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups,," \
  --attributes-to-roles "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups,," \
  > azure-connector.yaml

위 예제의 다음 값을 바꿉니다:

각 매핑할 그룹에 대해 --attributes-to-roles 플래그를 추가하거나 제거합니다.

azure-connector.yaml 파일은 이제 다음과 유사해야 합니다:

kind: saml
metadata:
  name: ad
spec:
  acs: https://mytenant.teleport.sh/v1/webapi/saml/acs/ad
  attributes_to_roles:
  - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
    roles:
    - dev
    value: 41c94563...
  - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
    roles:
    - access
    value: 8adac502...
  audience: https://mytenant.teleport.sh/v1/webapi/saml/acs/ad
  cert: ""
  display: Microsoft
  entity_descriptor: ""
  entity_descriptor_url: https://login.microsoftonline.com/ff882432.../federationmetadata/2007-06/federationmetadata.xml?appid=b8d06e01...
  issuer: ""
  service_provider_issuer: https://mytenant.teleport.sh/v1/webapi/saml/acs/ad
  sso: ""
version: v2

커넥터 테스트#

클러스터에 커넥터가 있으면 tctl로 테스트할 수 있습니다:

$ cat azure-connector.yaml | tctl sso test

브라우저가 열리고 Entra ID 자격 증명을 사용하여 Teleport 클러스터에 로그인합니다. 문제가 있는 경우 CLI 출력이 커넥터 구성 디버깅을 도와줍니다.

커넥터 만들기#

tctl 도구를 사용하여 커넥터를 만들려면 다음 명령을 실행합니다:

$ tctl create -f azure-connector.yaml

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 saml:

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

After you save and exit the editor, tctl will update the resource:

cluster auth preference has been updated

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

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

This feature is potentially unsafe and should be used with caution.

Enabling IdP-initiated login comes with notable security risks such as:
- Possibility of replay attacks on the SAML payload giving an attacker a secret web session

(선택 사항) 그룹 초과#

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

사용자의 그룹 멤버십이 150개 그룹 제한을 초과하지 않는 경우 이 단계를 건너뛸 수 있습니다.

SAML 커넥터가 Entra ID 통합을 사용하여 생성된 경우 Teleport는 이미 Microsoft Graph API에 인증하도록 구성되어 있으므로 커넥터 자격 증명 구성을 건너뛰고 Microsoft Graph API 권한 부여로 이동할 수 있습니다. SAML 커넥터가 Entra ID 통합을 사용하여 생성되었는지 확인하려면 Zero Trust Access -> Integrations -> Microsoft Entra ID -> SSO Connector로 이동하여 Enabled 배지를 찾습니다.

SAML 커넥터가 Entra ID 통합을 사용하여 생성되지 않은 경우 Entra ID에서 클라이언트 자격 증명을 만들고 해당 자격 증명을 SAML 커넥터에 구성하여 Teleport가 Microsoft Graph API에 인증할 수 있도록 해야 합니다.

커넥터 자격 증명 구성#

1단계에서 만든 동일한 앱 등록에 대해:

4. 자격 증명으로 커넥터를 업데이트합니다.

   kind: saml
   metadata:
     name: entra-id
   spec:
     ... # 간략하게 다른 필드는 표시하지 않음
     credentials:
       oauth:
         client_id: <client_id>
         client_secret: <client_secret>
   

Microsoft Graph API 권한 부여#

사용자의 그룹 멤버십이 150개 그룹을 초과하면 Teleport는 Entra ID에서 발급한 그룹 링크 속성을 따르고 Microsoft Graph API를 사용하여 사용자의 그룹 세부 정보를 가져옵니다.

토큰 암호화 (선택 사항)#

Entra ID의 SAML 토큰 암호화는 SSO 리다이렉트 중에 Teleport에 전송되는 SAML 어설션을 암호화합니다.

토큰 암호화는 Microsoft Entra ID 프리미엄 기능으로, 별도의 라이선스가 필요합니다. Entra ID와 Teleport Proxy Service 간의 트래픽이 이미 HTTPS를 사용하므로 토큰 암호화는 선택 사항입니다. 토큰 암호화를 활성화해야 하는지 결정하려면 Entra ID 문서를 읽어보세요.

Teleport 토큰 암호화 설정#

공개/개인 키와 인증서를 생성하는 것부터 시작합니다. Entra ID에 공개 인증서를 설정하고 Teleport에 개인 키를 설정합니다.

$ openssl req -nodes -new -x509 -keyout server.key -out server.cer

기존 커넥터를 수정하는 경우 편집기에서 엽니다:

$ tctl edit saml

Teleport가 signing_key_pair를 생성했음을 알 수 있습니다. 이 키 쌍은 응답에 서명하는 데 사용됩니다.

kind: saml
metadata:
  name: ad
spec:
  acs: https://mytenant.teleport.sh/v1/webapi/saml/acs/azure-saml
  attributes_to_roles:
  - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
    roles:
    - editor
    - access
    - auditor
    value: '*'
  audience: https://mytenant.teleport.sh/v1/webapi/saml/acs/azure-saml
  cert: ""
  display: Microsoft
  entity_descriptor:
  entity_descriptor_url: https://login.microsoftonline.com/ff882432.../federationmetadata/2007-06/federationmetadata.xml?appid=b8d06e01...
  issuer: https://sts.windows.net/your-id-here/
  service_provider_issuer: https://mytenant.teleport.sh/v1/webapi/saml/acs/azure-saml
  signing_key_pair:
    cert: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
  sso: https://login.microsoftonline.com/your-id-here/saml2
version: v2

server.key와 server.cer의 데이터를 사용하여 assertion_key_pair를 추가합니다.

편집 후 파일은 다음과 같이 보일 것입니다:

kind: saml
metadata:
  name: azure-saml
spec:
  acs: https://mytenant.teleport.sh/v1/webapi/saml/acs/azure-saml
  attributes_to_roles:
  - name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
    roles:
    - editor
    - access
    - auditor
    value: '*'
  audience: https://mytenant.teleport.sh/v1/webapi/saml/acs/azure-saml
  cert: ""
  display: Microsoft
  entity_descriptor:
  entity_descriptor_url: https://login.microsoftonline.com/ff882432.../federationmetadata/2007-06/federationmetadata.xml?appid=b8d06e01...
  issuer: https://sts.windows.net/your-id-here/
  service_provider_issuer: https://mytenant.teleport.sh/v1/webapi/saml/acs/azure-saml
  assertion_key_pair:
    cert: |
      -----BEGIN CERTIFICATE-----
      New CERT
      -----END CERTIFICATE-----
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      New private key
      -----END RSA PRIVATE KEY-----
  signing_key_pair:
    cert: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
  sso: https://login.microsoftonline.com/your-id-here/saml2
version: v2

편집기에서 파일을 저장하고 닫아 커넥터를 업데이트합니다.

토큰 암호화 활성화#

• Token Encryption으로 이동합니다:

• 인증서 가져오기

• 활성화

이 커넥터로 SSO 로그인이 성공하면 암호화가 작동하는 것입니다.

다음 단계#

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

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.

Teleport 역할에서 Microsoft Entra ID 속성 참조#

전체 네임스페이스 접두사를 포함한 Microsoft Entra ID의 속성을 참조하려면 다음 표기법으로 external 템플릿 변수를 사용해야 합니다:

kind: role
version: v5
metadata:
  name: dev
spec:
  options:
    max_session_ttl: 24h
  allow:
    # ubuntu 또는 'windowsaccountname' 클레임으로만 로그인 허용
    logins: [ '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}', ubuntu ]
    node_labels:
      access: relaxed

로그인 {{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}은 Teleport가 http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname 속성을 확인하고 그 필드를 각 사용자의 허용된 로그인으로 사용하도록 구성합니다. 속성 이름에 문자, 숫자, 밑줄 외의 문자가 포함되어 있으므로 속성 이름 주위에 큰따옴표(")와 대괄호([])를 사용해야 합니다.

문제 해결#

Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to:

• Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport.
• Be able to see how Teleport maps the received claims to role mappings as defined in the connector.
• For self-hosted Teleport Enterprise clusters, ensure that HTTP/TLS certificates are configured properly for both the Teleport Proxy Service and the SSO provider.

If something is not working, we recommend to:

• Double-check the host names, tokens and TCP ports in a connector definition.

Using the Web UI#

If you get "access denied" or other login errors, the number one place to check is the Audit Log. To view the recording, select Audit in the Teleport Web UI, then click Session Recordings in the menu.

Example of a user being denied because the role clusteradmin wasn't set up:

{
  "code": "T1001W",
  "error": "role clusteradmin is not found",
  "event": "user.login",
  "message": "Failed to calculate user attributes.\n\trole clusteradmin is not found",
  "method": "oidc",
  "success": false,
  "time": "2024-11-07T15:41:25.584Z",
  "uid": "71e46f17-d611-48bb-bf5e-effd90016c13"
}

Teleport does not show the expected Nodes#

(!docs/pages/includes/node-logins.mdx!)

When configuring SSO, ensure that the identity provider is populating each user's traits correctly. For a user to see a Node in Teleport, the result of populating a template variable in a role's allow.logins must match at least one of a user's traits.logins.

In this example a user will have usernames ubuntu, debian and usernames from the SSO trait logins for Nodes that have a env: dev label. If the SSO trait username is bob then the usernames would include ubuntu, debian, and bob.

kind: role
metadata:
  name: example-role
spec:
  allow:
    logins: ['{{external.logins}}', ubuntu, debian]
    node_labels:
      'env': 'dev'
version: v5

Single sign-on fails with OIDC#

When encountering the error message "Failed to verify JWT: oidc: unable to verify JWT signature: no matching keys", it typically indicates a discrepancy between the algorithm used to sign the JWT token and the algorithm(s) supported by the JSON Web Key Set (JWKS). Specifically, the token might be signed with one algorithm, e.g., HS256, while the JWKS only lists keys for a different algorithm. e.g., RS256. This issue predominantly arises when using identity providers that offer extremely low-level functionality.

Here are some things to check:

• Verify the JWT header specifies the correct signing algorithm. This should match one of the algorithms listed in the keys section of the JWKS endpoint response.
• Ensure the JWKS endpoint is returning all relevant public keys. Sometimes key rotation can cause valid keys to be omitted.

To resolve the issue, align the JWT algorithm header with a supported algorithm in the JWKS. Rotate keys if necessary. Verify the JWKS only publishes the active public keys. With proper configuration, the signature should validate successfully.