Azure Active Directory(AD)로 텔레포트 인증

이 가이드는 Microsoft Azure Active Directory를 구성하여 SAML 인증 커넥터를 사용하여 특정 사용자 그룹에 자격 증명을 발급하는 방법을 다룹니다. 역할 기반 액세스 제어(RBAC)와 결합하여 사용하면 텔레포트 관리자가 다음과 같은 정책을 정의할 수 있습니다:

"DBA" Azure AD 그룹의 구성원만 PostgreSQL 데이터베이스에 연결할 수 있습니다.
개발자는 프로덕션 서버에 SSH로 접속할 수 없습니다.

다음 단계에서는 Azure AD 그룹과 보안 역할을 일치시키는 예제 SAML 인증 커넥터를 구성합니다. 다른 옵션을 구성할 수도 있습니다.

사전 요구 사항

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

비갤러리 애플리케이션을 생성할 수 있는 액세스 권한이 있는 Azure AD 관리자 계정(P2 라이센스).
디렉터리에 사용자 하나 이상을 등록합니다.
Azure AD에서 보안 그룹을 두 개 이상 만들고 각 그룹에 사용자 하나 이상을 할당합니다.
saml 자원 유지 관리에 액세스할 수 있는 텔레포트 역할. 이는 기본 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단계. Azure AD 구성

엔터프라이즈 애플리케이션 생성

Azure AD -> 엔터프라이즈 애플리케이션을 선택합니다.
새 애플리케이션을 선택합니다.
자신의 애플리케이션 만들기를 선택하고 애플리케이션 이름(예: 텔레포트)을 입력한 후 **갤러리에서 찾을 수 없는 다른 애플리케이션 통합(비갤러리)**을 선택합니다.
관리에서 속성을 선택하고 **할당 필요?**를 아니요로 설정합니다.

다음 단계로 진행하기 전에 저장을 클릭합니다.

SAML 구성

관리에서 단일 로그인을 선택하고 SAML을 선택합니다.
기본 SAML 구성을 편집합니다.
다음 필드에 텔레포트 프록시 서비스 호스트의 URL을 입력합니다: Entity ID와 Reply URL:
```
https://mytenant.teleport.sh:443/v1/webapi/saml/acs/ad
```
다음 단계로 진행하기 전에 저장을 클릭합니다.
SAML 인증서 섹션에서 App Federation Metadata URL 링크를 복사하여 텔레포트 커넥터 구성에 사용하기 위해 저장합니다:

속성 및 클레임 편집

필수 클레임 아래의 **고유 사용자 식별자(Name ID)**를 클릭합니다.
"이름 식별자 형식"을 기본값으로 변경합니다. 소스 속성이 user.userprincipalname인지 확인합니다.
사용자 보안 그룹을 커넥터에 사용할 수 있도록 그룹 클레임을 추가합니다:
Azure AD 사용자 이름의 형식을 소문자로 변환하여 텔레포트에 전달하는 클레임을 추가합니다. 소스를 "Transformation"으로 설정합니다. 새 패널에서:
- 변환 값을 "Extract()"로 설정합니다.
- 속성 이름을 user.userprincipalname으로 설정합니다.
- 값을 ToLowercase()로 설정합니다.

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

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

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

위 예제에서:

--entity-descriptor는 이전 단계에서 저장한 앱 연합 메타데이터 URL을 지정합니다.
각 --attributes-to-roles는 그룹의 스키마 정의 이름, 그룹, AD 그룹의 UUID, 그리고 그룹 구성원이 할당될 텔레포트 역할을 지정합니다.

파일 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

브라우저가 열리고 Azure AD 자격 증명을 사용하여 텔레포트 클러스터에 로그인합니다. 문제가 발생하면 CLI 출력이 커넥터 구성 문제를 디버깅하는 데 도움이 될 것입니다.

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

tctl create -f azure-connector.yaml

3단계/3단계. 새로운 텔레포트 역할 생성

Azure AD 커넥터의 외부 사용자 이름 데이터를 사용하여 호스트에서 허용할 리눅스 로그인을 결정하는 텔레포트 역할 리소스를 생성합니다.

dev 역할을 가진 사용자는 단지 access: relaxed 텔레포트 레이블이 있는 노드에 로그인할 수 있습니다. 그들은 ubuntu 또는 Azure AD 커넥터에서 전달된 사용자 이름으로 로그인할 수 있습니다. 이 역할을 가진 사용자는 텔레포트에 대한 관리 액세스를 얻을 수 없습니다.

kind: role
version: v5
metadata:
  name: dev
spec:
  options:
    max_session_ttl: 24h
  allow:
    logins: [ "{{external.username}}", ubuntu ]
    node_labels:
      access: relaxed

서버에서 사용할 수 있는 리눅스 로그인으로 ubuntu를 교체합니다.

tctl create dev.yaml

기본 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를 사용하세요.

토큰 암호화(선택 사항)

Azure AD의 SAML 토큰 암호화는 SSO 리디렉션 동안 텔레포트로 전송되는 SAML 주장을 암호화합니다.

토큰 암호화는 Azure Active Directory 프리미엄 기능이며 별도의 라이센스가 필요합니다. Azure AD와 텔레포트 프록시 서비스 간의 트래픽이 이미 HTTPS를 사용하므로, 토큰 암호화는 선택 사항입니다. 토큰 암호화를 활성화해야 하는지 확인하려면 Azure AD 문서를 참조하십시오.

텔레포트 토큰 암호화 설정

먼저 공개/개인 키와 인증서를 생성합니다. 공개 인증서는 Azure AD에 설정하고 개인 키는 텔레포트에 설정합니다.

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

기존 커넥터를 수정하는 경우 YAML을 파일에 먼저 기록합니다:

tctl get saml --with-secrets > azure-out.yaml

텔레포트가 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

편집 후 파일은 다음과 같아야 합니다:

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

커넥터를 업데이트합니다:

tctl create -f azure-connector.yaml

토큰 암호화 활성화

토큰 암호화로 이동합니다:

인증서 가져오기

활성화합니다.

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

문제 해결

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가 활성 공개 키만 게시하는지 확인하십시오. 올바른 구성으로 서명이 성공적으로 검증되어야 합니다.

SAML 콜백 처리 실패

"Failed to process SAML callback" 오류가 발생하면 감사 로그를 확인하십시오.

리소스 이름에 특수 문자를 사용할 수 없습니다. 알파벳 문자, 하이픈 및 점으로만 구성된 이름을 사용하십시오: /web/users/ops_example.com#EXT#@opsexample.onmicrosoft.com/params

위 오류는 텔레포트의 명명 규칙과 호환되지 않는 Name ID 형식으로 인해 발생합니다.

Name ID 형식을 이메일을 사용하도록 변경합니다:

추가 읽기

텔레포트 구성 리소스 참조
이 가이드에서 설명한 텔레포트 역할에서는 external 특성이 사용자가 텔레포트에 인증할 때 사용한 단일 로그인 공급자로부터의 값으로 대체됩니다. 텔레포트 역할에서 특성이 작동하는 방식에 대한 전체 세부정보는 텔레포트 액세스 제어 참조를 참조하십시오.

Teleport 원문 보기