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

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

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

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

작동 방식#

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

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

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

사전 요구 사항#

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

• 갤러리에 없는 애플리케이션을 생성할 수 있는 권한(P2 라이선스)을 가진 Microsoft Entra ID 관리자 계정.

• 디렉터리에 하나 이상의 사용자를 등록.

• Microsoft Entra ID에 최소 두 개의 보안 그룹을 생성하고 각 그룹에 하나 이상의 사용자를 할당.

• saml 리소스를 관리할 접근 권한이 있는 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단계. 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 프록시 서비스 호스트의 URL을 입력합니다. 예:

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

   Teleport 프록시 서비스에 대해 여러 공개 주소(Teleport 설정 파일의 proxy_service.public_addr 값)를 가진 자체 호스팅 클러스터가 있는 경우, 이 주소가 목록에서 첫 번째로 나열된 주소를 가리키는지 확인하세요.

   

   다음 단계로 진행하기 전에 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. (선택 사항) Teleport 역할 내에서 {{external.username}} 속성으로 사용할 수 있도록 Entra ID 사용자 이름 형식을 소문자로 변환하는 클레임을 추가합니다.

   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 서비스는 해당 사용자의 Teleport 역할이 포함된 SSH 및 TLS 인증서를 사용자에게 발급합니다.

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

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

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

서로 다른 그룹이 서로 다른 수준의 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/tenant-id/federationmetadata/2007-06/federationmetadata.xml?appid=app-id" \
  --attributes-to-roles "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups,group-1-object-id,group-1-roles" \
  --attributes-to-roles "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups,group-2-object-id,group-2-roles" \
  > 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

이 기능은 잠재적으로 안전하지 않으므로 주의하여 사용해야 합니다.

IdP 시작 로그인을 활성화하면 다음과 같은 주목할 만한 보안 위험이 따릅니다:
- SAML 페이로드에 대한 재전송 공격으로 공격자가 비밀 웹 세션을 획득할 가능성

최적의 사용자 경험을 위해 필요한 경우가 아니라면 이 기능을 비활성화된 상태로 유지하는 것을 권장합니다.

이 URL을 얻을 수 있는 위치에 대한 자세한 내용은 SAML 프로바이더의 문서를 참조하십시오.

커넥터 테스트#

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

$ cat azure-connector.yaml | tctl sso test

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

커넥터 생성#

tctl 도구를 사용하여 커넥터를 생성하려면 다음 명령을 실행하세요:

$ tctl create -f azure-connector.yaml

(선택 사항) 그룹 오버리지#

사용자의 그룹 구성원 수가 150개 그룹 제한을 초과하는 경우, Microsoft Entra ID는 예상되는 groups 속성 대신 groups link 속성이 포함된 SAML 어설션을 발급합니다. groups link 속성에는 사용자의 그룹 구성원 정보를 Microsoft Graph API에서 조회해야 함을 나타내는 Azure AD Graph 링크가 포함되어 있습니다.

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

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

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

커넥터 자격 증명 구성#

1단계에서 생성한 것과 동일한 앱 등록에 대해:

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

   kind: saml
   metadata:
     name: entra-id
   spec:
     ... # other fields not displayed for brevity
     credentials:
       oauth:
         client_id: <client_id>
         client_secret: <client_secret>
   

Microsoft Graph API 권한 부여#

사용자의 그룹 구성원 수가 150개 그룹을 초과하는 경우, Teleport는 Entra ID가 발급한 groups link 속성을 따라가 Microsoft Graph API를 사용하여 사용자의 그룹 상세 정보를 가져옵니다.

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 값을 saml로 설정하십시오:

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

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

cluster auth preference has been updated

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

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

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

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

토큰 암호화는 Microsoft Entra ID 프리미엄 기능이며 별도의 라이선스가 필요합니다. Entra ID와 Teleport 프록시 서비스 간의 트래픽은 이미 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
  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

편집을 마치면 파일은 다음과 같은 형태가 됩니다:

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 특성 통합#

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

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

Microsoft Entra ID의 특성을 전체 네임스페이스 접두사와 함께 참조하려면, 다음 표기법과 같이 external 템플릿 변수를 사용해야 합니다:

kind: role
version: v5
metadata:
  name: dev
spec:
  options:
    max_session_ttl: 24h
  allow:
    # only allow login as either ubuntu or the 'windowsaccountname' claim
    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 속성을 확인하고 해당 필드를 각 사용자에게 허용된 로그인으로 사용하도록 구성합니다. 속성 이름에 문자, 숫자, 밑줄 외의 문자가 포함되어 있으므로, 속성 이름 앞뒤에 큰따옴표(")와 대괄호([])를 사용해야 합니다.

문제 해결#

SSO 구성 문제를 해결하는 것은 까다로울 수 있습니다. 일반적으로 Teleport 관리자는 다음을 수행할 수 있어야 합니다:

• SSO 공급자가 Teleport로 내보내고 전달하는 SAML/OIDC 클레임과 값이 무엇인지 확인할 수 있어야 합니다.
• Teleport가 수신한 클레임을 커넥터에 정의된 역할 매핑에 어떻게 매핑하는지 확인할 수 있어야 합니다.
• 셀프 호스팅 Teleport Enterprise 클러스터의 경우, Teleport Proxy Service와 SSO 공급자 모두에 대해 HTTP/TLS 인증서가 올바르게 구성되어 있는지 확인해야 합니다.

무언가 제대로 동작하지 않는다면, 다음을 권장합니다:

• 커넥터 정의에서 호스트 이름, 토큰, TCP 포트를 다시 한 번 확인하십시오.

Web UI 사용하기#

"access denied" 또는 기타 로그인 오류가 발생하면 가장 먼저 확인해야 할 곳은 Audit Log입니다. 레코딩을 보려면 Teleport Web UI에서 Audit을 선택한 다음, 메뉴에서 Session Recordings를 클릭하십시오.

clusteradmin 역할이 설정되지 않아 사용자가 거부되는 예시입니다:

{
  "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에 예상한 Node가 표시되지 않음#

Teleport Auth Service는 Teleport에 연결된 리소스를 나열하라는 요청(예: Web UI 또는 tsh ls를 통한 리소스 표시)을 받으면, 현재 사용자가 볼 수 있는 권한이 있는 리소스만 반환합니다.

사용자의 Teleport cluster에 있는 각 리소스에 대해 Auth Service는 다음 검사를 순서대로 적용하며, 한 검사라도 실패하면 해당 리소스를 사용자에게 숨깁니다:

• 사용자의 role 중 어느 것도 리소스의 label과 일치하는 deny 규칙을 포함하지 않아야 합니다.
• 사용자의 role 중 적어도 하나는 리소스의 label과 일치하는 allow 규칙을 포함해야 합니다.

예상한 대로 리소스가 보이지 않는 경우, Access Controls Reference에 문서화된 대로 사용자의 role에 적절한 allow 및 deny 규칙이 포함되어 있는지 확인하십시오.

SSO를 구성할 때, ID 공급자가 각 사용자의 trait를 올바르게 채우고 있는지 확인하십시오. 사용자가 Teleport에서 Node를 보려면, 역할의 allow.logins에 있는 템플릿 변수를 채운 결과가 사용자의 traits.logins 중 적어도 하나와 일치해야 합니다.

이 예시에서 사용자는 env: dev 레이블이 있는 Node에 대해 사용자 이름 ubuntu, debian과 SSO trait logins의 사용자 이름을 갖게 됩니다. SSO trait 사용자 이름이 bob이라면, 사용자 이름에는 ubuntu, debian, bob이 포함됩니다.

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

OIDC에서 싱글 사인온이 실패함#

"Failed to verify JWT: oidc: unable to verify JWT signature: no matching keys" 오류 메시지가 발생하는 경우, 이는 일반적으로 JWT 토큰에 서명하는 데 사용된 알고리즘과 JSON Web Key Set(JWKS)가 지원하는 알고리즘 간의 불일치를 나타냅니다. 구체적으로, 토큰은 하나의 알고리즘(예: HS256)으로 서명되었는데 JWKS는 다른 알고리즘(예: RS256)에 대한 키만 나열하고 있을 수 있습니다. 이 문제는 매우 낮은 수준의 기능을 제공하는 ID 공급자를 사용할 때 주로 발생합니다.

확인해야 할 사항은 다음과 같습니다:

• JWT 헤더가 올바른 서명 알고리즘을 지정하고 있는지 확인하십시오. 이는 JWKS 엔드포인트 응답의 keys 섹션에 나열된 알고리즘 중 하나와 일치해야 합니다.
• JWKS 엔드포인트가 관련된 모든 공개 키를 반환하고 있는지 확인하십시오. 때때로 키 로테이션으로 인해 유효한 키가 누락될 수 있습니다.

문제를 해결하려면, JWT 알고리즘 헤더를 JWKS에서 지원하는 알고리즘에 맞추십시오. 필요한 경우 키를 로테이션하십시오. JWKS가 활성화된 공개 키만 게시하는지 확인하십시오. 올바르게 구성하면 서명이 성공적으로 검증됩니다.

로그인에 실패하면, Teleport 감사 로그에서 Failed to process SAML callback 오류를 확인하세요. 메시지는 다음과 유사합니다:

Special characters are not allowed in resource names. Use a name composed only from
alphanumeric characters, hyphens, and dots: /web/users/ops_example.com#EXT#@opsexample.onmicrosoft.com/params

이 오류는 Entra ID가 반환한 Name ID에 Teleport가 리소스 이름에서 허용하지 않는 문자가 포함되어 있음을 의미합니다. Teleport는 각 외부 SSO 아이덴티티를 내부 사용자 리소스에 매핑하며, 이러한 리소스는 영숫자(a-z, A-Z, 0-9), 하이픈(-), 점(.)만 사용해야 합니다.

이를 해결하려면, 어설션에 정확한 사용자 식별자가 포함되도록 Entra ID 애플리케이션의 Single sign-on 설정에서 Name ID 형식을 Email address로 변경하세요.