OneLogin을 SSO 공급자로 사용하는 Teleport 인증

이 가이드는 OneLogin을 구성하여 특정 사용자 그룹에 Teleport 자격 증명을 발급하는 방법을 설명합니다. 역할 기반 액세스 제어(RBAC)와 결합하여 SSH 관리자가 다음과 같은 정책을 정의할 수 있습니다:

"DBA" 그룹의 구성원만 PostgreSQL 데이터베이스에 연결할 수 있습니다.
개발자는 프로덕션 서버에 SSH로 접근할 수 없습니다.
... 및 기타 여러 가지.

필수 조건

관리 권한이 있는 OneLogin 계정과 최소 두 개의 그룹에 할당된 사용자.
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. OneLogin에 Teleport 애플리케이션 만들기

OneLogin 제어판의 메인 메뉴에서 Applications -> Add App로 이동합니다. 검색 상자를 사용하여 "SAML Custom Connector (SP Shibboleth)"를 선택합니다:
새로운 애플리케이션을 정의합니다:

Teleport 아이콘을 업로드할 수 있는 링크는 다음과 같습니다:
- 사각형 아이콘
- 직사각형 아이콘
애플리케이션의 Configuration 페이지에서 다음 값을 설정합니다:

Tip
여기에 Teleport Proxy Service 주소 및 포트 또는 Teleport Enterprise Cloud 테넌트(예: company.teleport.sh:443)와 함께 teleport.example.com:443을 설정하여 아래의 값을 작성하십시오.
- Login URL:
  - https://teleport.example.com:443/web/login
- ACS (Consumer) URL, SAML Recipient, ACS (Consumer) URL Validator, 및 Audience:
  - https://teleport.example.com:443/v1/webapi/saml/acs/onelogin
Teleport는 사용자에게 그룹을 할당해야 합니다. Parameters 페이지에서 SAML 속성 문으로 노출된 일부 매개변수로 애플리케이션을 구성합니다:

중요
SAML assertion에 포함 체크박스를 반드시 선택하세요.
애플리케이션에 사용자를 추가합니다:
인증 커넥터에 대한 SAML 메타데이터를 가져옵니다. 애플리케이션 설정 후, More Actions 메뉴로 이동하여 SAML Metadata 옵션을 찾습니다:

옵션을 왼쪽 클릭하여 XML 문서를 로컬 파일로 다운로드하거나, 오른쪽 클릭하여 링크 주소를 복사할 수 있습니다. Teleport Auth Service는 제공된 문서를 읽거나 주소를 쿼리하여 SAML 메타데이터를 가져옵니다. Auth Service가 가장 최신 정보를 사용할 수 있도록 주소를 복사하는 것을 권장합니다.

2단계/3. SAML 커넥터 만들기

tctl을 사용하여 SAML 커넥터를 만듭니다. 이전 단계에서 복사한 XML 문서의 URL로 xml-path를 업데이트하십시오. XML 문서를 다운로드한 경우 XML 메타데이터 파일의 경로를 사용하세요:

tctl sso configure saml --preset onelogin \--entity-descriptor xml-path \--attributes-to-roles groups,admin,editor \--attributes-to-roles groups,dev,access > onelogin.yaml

이 명령어는 커넥터 리소스를 설명하는 onelogin.yaml을 생성합니다:

(!examples/resources/onelogin-connector.yaml!)

새로 생성된 구성을 테스트합니다:

cat onelogin.yaml | tctl sso test

tctl sso test는 브라우저를 열어 OneLogin으로 인증을 시도합니다. 성공하면 어떤 SAML 속성이 수신되어 Teleport 역할에 매핑되는지 출력됩니다. 테스트에 실패하면 출력에서 구성을 문제 해결하는 데 도움이 됩니다.

tctl 도구를 사용하여 커넥터를 생성합니다:

tctl create -f onelogin.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를 사용하세요.

3단계/3. 새로운 Teleport 역할 만들기

OneLogin의 외부 사용자 이름 데이터를 사용하여 호스트 리눅스 로그인에 매핑되는 새로운 역할을 만들 것입니다.

아래 설명된 역할에서, 개발자는 access: relaxed Teleport 레이블이 붙은 노드에만 로그인할 수 있습니다. 개발자는 자신의 주장에서 도착하는 사용자 이름으로 ubuntu로 로그인할 수 있습니다. 개발자는 Teleport에 대한 관리자 액세스를 얻기 위해 필요한 규칙이 없습니다.

# dev.yaml
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 -f dev.yaml

문제 해결

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에 인증하기 위해 사용한 SSO 공급자로부터의 값으로 대체됩니다. Teleport 역할에서 traits가 작동하는 방식에 대한 전체 세부사항은 Teleport 액세스 제어 참조를 참조하세요.

Teleport 원문 보기