이 가이드는 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.comtctl 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
- Login URL:
-
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
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 액세스 제어 참조를 참조하세요.