Active Directory Federation Services와 SSO

이 가이드는 Active Directory Federation Services (ADFS)를 구성하여 특정 사용자 그룹에 대해 로그인 자격 증명을 발급하는 단일 사인온(SSO) 제공자로 사용하는 방법을 설명합니다. 역할 기반 접근 제어(RBAC)와 결합하여 사용하면 Teleport 관리자가 다음과 같은 정책을 정의할 수 있습니다:

"DBA" 그룹의 구성원만 PostgreSQL을 실행 중인 머신에 SSH 할 수 있습니다.
개발자는 프로덕션 서버에 SSH 할 수 없습니다.

전제 조건

관리 액세스가 있는 ADFS 설치 및 최소 두 개의 그룹에 사용자 할당.
saml 리소스를 유지 관리할 수 있는 Teleport 역할. 기본 editor 역할에서 사용할 수 있습니다.

실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하기 무료 체험판을 이용해 보세요.
tctl 관리 도구 및 tsh 클라이언트 도구 버전 >= 16.2.0.

tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하세요.

당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  16.2.0
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다. 자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

1단계/3. ADFS 구성

사용자에 대한 클레임을 내보내도록 ADFS를 구성해야 합니다(ADFS 용어에서 클레임 제공자 신뢰) 및 Teleport를 신뢰하도록 ADFS를 구성해야 합니다(ADFS 용어에서 의존하는 당사자 신뢰).

클레임 제공자 신뢰 구성에 대해 AD FS 관리 창을 엽니다. Claims Provider Trusts에서 Active Directory를 마우스 오른쪽 버튼으로 클릭하고 Edit Claim Rules를 선택합니다. 다음 두 가지 수신 클레임: Name ID 및 Group을 지정해야 합니다.

Name ID는 LDAP 속성 E-Mail-Addresses와 Name ID의 매핑이어야 합니다.
그룹 membership 클레임을 사용하여 사용자를 역할에 매핑해야 합니다(예: 일반 사용자와 관리자를 구분하기 위해).
동적 역할을 사용하는 경우 이를 통해 LDAP 속성 SAM-Account-Name을 Windows account name에 매핑하는 것이 유용할 수 있습니다:
그리고 E-Mail-Addresses를 UPN에 매핑하는 또 다른 매핑을 만듭니다:

의존하는 당사자 신뢰를 생성해야 합니다. 아래 정보를 사용하여 마법사를 안내합니다.

의존하는 당사자 신뢰 생성:
의존하는 당사자에 대한 데이터를 수동으로 입력합니다.
표시 이름을 Teleport와 같은 것으로 설정합니다.
토큰 암호화 인증서는 건너뜁니다.
*"SAML 2.0 Web SSO 프로토콜 지원 활성화"*를 선택하고 URL을 https://teleport.example.com/v1/webapi/saml/acs로 설정합니다. 도메인 이름을 Teleport 프록시 URL로 교체합니다.
의존하는 당사자 신뢰 식별자도 https://teleport.example.com/v1/webapi/saml/acs로 설정합니다.
접근 제어 정책에 대해 *"모두 허용"*을 선택합니다.

의존하는 당사자 신뢰가 생성되면 이에 대한 클레임 발급 정책을 업데이트합니다. 이전과 마찬가지로 최소한 Name ID 및 Group 클레임을 의존하는 당사자(Teleport)로 전송해야 합니다. 동적 역할을 사용하는 경우 LDAP 속성 SAM-Account-Name을 *"Windows account name"*에 매핑하고 E-Mail-Addresses를 *"UPN"*에 매핑하는 것이 유용할 수 있습니다.

마지막으로 Active Directory에서 생성한 사용자에게 이메일 주소가 연결되어 있는지 확인하십시오. 이를 확인하려면 Server Manager를 열고 *"도구 -> Active Directory 사용자 및 컴퓨터"*를 선택한 다음 사용자를 선택하고 마우스 오른쪽 버튼을 클릭하여 속성을 엽니다. 이메일 주소 필드가 채워져 있는지 확인합니다.

2단계/3. Teleport 역할 생성

관리자용과 일반 사용자용 두 개의 Teleport 역할을 생성해 보겠습니다. tctl create {파일 이름} CLI 명령을 사용하거나 웹 UI를 통해 생성할 수 있습니다.

# admin-role.yaml
kind: "role"
version: "v3"
metadata:
  name: "admin"
spec:
  options:
    max_session_ttl: "8h0m0s"
  allow:
    logins: [ root ]
    node_labels:
      "*": "*"
    rules:
      - resources: ["*"]
        verbs: ["*"]

# user-role.yaml
kind: "role"
version: "v3"
metadata:
  name: "dev"
spec:
  options:
    # 일반 사용자는 게스트만 허용되며, 인증서는 1시간의 TTL을 가집니다:
    max_session_ttl: "1h"
  allow:
    # ubuntu 또는 'windowsaccountname' 클레임으로만 로그인 허용
    logins: [ '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}', ubuntu ]
    node_labels:
      "access": "relaxed"

이 역할은 다음과 같이 선언합니다:

개발자는 access: relaxed로 라벨링된 노드에만 로그인할 수 있습니다.
개발자는 ubuntu 사용자로 로그인할 수 있습니다.
개발자는 이전 세션을 보거나 재생할 수 없으며 Teleport 클러스터를 재구성할 수 없습니다.

로그인 {{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}} 은 Teleport가 http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname ADFS 클레임을 확인하고 해당 필드를 각 사용자의 허용 로그인으로 사용하는 방식입니다. 클레임 이름의 양쪽에 있는 큰따옴표(")와 대괄호([])가 중요합니다.

3단계/3. SAML 커넥터 생성

tctl을 사용하여 SAML 커넥터 리소스를 생성합니다:

tctl sso configure saml --acs https://teleport.example.com/v1/webapi/saml/acs \  --preset adfs \  --entity-descriptor https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml \  --attributes-to-roles http://schemas.xmlsoap.org/claims/Group,teleadmins,editor \  --attributes-to-roles http://schemas.xmlsoap.org/claims/Group,Users,access \  > adfs.yaml

acs 필드는 이전에 ADFS에서 설정한 값과 일치해야 하며, "ADFS -> 서비스 -> 엔드포인트 -> 메타데이터" 아래 ADFS에서 entity_descriptor_url을 얻을 수 있습니다.

attributes_to_roles는 방금 생성한 Teleport 역할에 속성을 매핑하는 데 사용됩니다. 이 경우 "Group" 속성의 전체 이름인 http://schemas.xmlsoap.org/claims/Group을 값 *"teleadmins"*로 매핑하고 있으며, 값 *"users"*는 "users" 역할로 매핑되고 있습니다.

이 커넥터를 적용하기 전에 테스트할 수 있지만(cat adfs.yaml | tctl sso test), 다음 단계를 완료할 때까지 인증 과정이 완료되지 않습니다.

커넥터를 적용합니다:

tctl create -f adfs.yaml

서명 키 내보내기

마지막 단계로, 서명 키를 내보내야 합니다:

tctl saml export adfs > saml.cer

saml.cer를 ADFS 서버로 복사하고, "Relying Party Trust"를 열어 이 파일을 서명 확인 인증서 중 하나로 추가합니다:

웹 UI에는 이제 "MS Active Directory로 로그인"이라는 새로운 버튼이 포함됩니다. CLI는 이전과 동일합니다:

tsh --proxy=proxy.example.com login

이 명령은 SSO 로그인 URL을 출력하고 자동으로 브라우저에서 열려고 시도합니다.

팁

Teleport는 여러 SAML 커넥터를 사용할 수 있습니다. 이 경우 커넥터 이름을 tsh login --auth=connector_name을 통해 전달할 수 있습니다.

기본 SAML 인증 활성화

Teleport를 구성하여 로컬 사용자 데이터베이스 대신 기본적으로 SAML 인증을 사용하도록 설정합니다.

귀하의 Teleport 에디션에 대한 지침을 따르세요:

cluster_auth_preference 값을 편집하기 위해 tctl을 사용하세요:

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

auth_service 섹션에서 /etc/teleport.yaml을 업데이트하고 teleport 데몬을 재시작하세요.

auth_service:
  authentication:
    type: saml

Tip

SAML 공급자를 구성하기 전에 다시 로그인해야 하는 경우, 플래그 --auth=local를 사용하세요.

문제 해결

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

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

무언가가 작동하지 않는 경우, 다음을 권장합니다:

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

웹 UI 사용하기

"액세스가 거부되었습니다." 또는 다른 로그인이 오류가 발생하면 가장 먼저 확인해야 할 곳은 감사 로그입니다. 관리 영역 아래에서 Teleport 웹 UI의 활동 탭 내에서 액세스할 수 있습니다.

역할 clusteradmin이 설정되지 않아 사용자가 거부된 예:

{  
  "code": "T1001W",  
  "error": "role clusteradmin is not found",  
  "event": "user.login",  
  "method": "oidc",  
  "success": false,  
  "time": "2019-06-15T19:38:07Z",  
  "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"  
}

Teleport가 예상하는 노드를 표시하지 않음

When Teleport의 인증 서비스가 Teleport 노드를 나열하라는 요청을 받으면 (예: 웹 UI에서 노드를 표시하거나 tsh ls를 통해), 현재 사용자가 볼 수 있는 권한이 있는 노드만 반환합니다.

사용자의 Teleport 클러스터에 있는 각 노드에 대해 인증 서비스는 다음 검사를 순서대로 적용하며, 하나의 검사가 실패하면 해당 노드를 사용자에게 숨깁니다:

사용자의 역할 중 어느 것도 노드의 레이블과 일치하는 deny 규칙을 포함하지 않아야 합니다.
사용자의 역할 중 적어도 하나는 노드의 레이블과 일치하는 allow 규칙을 포함해야 합니다.

예상할 때 노드를 볼 수 없다면, 사용자의 역할에 Teleport 접근 제어 참조에 문서화된 적절한 allow 및 deny 규칙이 포함되어 있는지 확인하세요.

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

이 예에서 사용자는 env: dev 레이블이 있는 노드에 대해 ubuntu, debian 및 SSO 특성 logins에서 가져온 사용자 이름을 가집니다. SSO 특성 사용자 이름이 bob인 경우 사용자 이름에는 ubuntu, debian 및 bob이 포함됩니다.

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

OIDC로 단일 로그인 실패

"JWT 확인 실패: oidc: JWT 서명을 검증할 수 없음: 일치하는 키가 없음"이라는 오류 메시지를 받으면, 일반적으로 JWT 토큰 서명에 사용된 알고리즘과 JSON 웹 키 세트(JWKS)에서 지원되는 알고리즘 간의 불일치를 나타냅니다. 특히, 토큰이 한 알고리즘, 예를 들어 HS256으로 서명된 경우, JWKS는 다른 알고리즘에 대한 키만 나열할 수 있습니다. 예를 들어 RS256. 이 문제는 기본 기능을 제공하는 ID 공급자를 사용할 때 주로 발생합니다.

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

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

문제를 해결하려면 JWT 알고리즘 헤더를 JWKS에서 지원되는 알고리즘과 일치시킵니다. 필요한 경우 키를 회전시킵니다. JWKS가 활성 공개 키만 게시하는지 확인하십시오. 올바른 구성으로 서명이 성공적으로 검증되어야 합니다.

다음 단계

이 가이드에서 설명한 Teleport 역할에서 external 특성은 사용자가 Teleport에 인증받기 위해 사용한 단일 사인온 제공자로부터 값을 교체합니다. Teleport 역할에서 특성이 어떻게 작동하는지에 대한 전체 세부 사항은 Teleport 접근 제어 참조를 참조하세요.

Teleport 원문 보기