Okta를 SSO 제공자로 사용하는 인증

이 가이드는 Teleport Enterprise 및 Teleport Enterprise Cloud에 단일 로그인(Single Sign-On, SSO) 신원을 제공하기 위해 Okta를 구성하는 방법을 다룹니다. 역할 기반 액세스 제어(RBAC)와 함께 사용될 때, 이는 Teleport 관리자가 다음과 같은 정책을 정의할 수 있게 해줍니다:

"DBA" 그룹의 구성원만 PostgreSQL 데이터베이스에 접근할 수 있습니다.
개발자는 프로덕션 서버에 SSH로 접속할 수 없습니다.
HR 그룹의 구성원은 감사 로그를 볼 수 있지만 프로덕션 환경은 볼 수 없습니다.

Teleport Enterprise Cloud 및 Self-Hosted Teleport Enterprise에서, Teleport는 호스팅된 Okta 통합을 등록하는 과정의 일환으로 자동으로 SSO 커넥터를 구성할 수 있습니다.

Teleport Web UI에서 Okta 통합을 등록할 수 있습니다.

Teleport Web UI를 방문하고 화면의 왼쪽 상단에 있는 드롭다운 메뉴를 찾습니다. Management 옵션을 선택합니다.

왼쪽 사이드바에서 Enroll New Integration을 클릭하여 "Enroll New Integration" 페이지로 이동합니다:

"Select Integration Type" 메뉴에서 Okta 타일을 클릭합니다. 그러면 Teleport가 Okta 통합 구성 과정을 안내합니다.

사전 요구 사항

관리 액세스가 있는 Okta 계정. 귀하의 계정에는 사용자와 최소 두 개의 그룹이 포함되어야 합니다. Teleport 역할에 할당할 Okta 그룹이 아직 없다면 걱정하지 마세요. 아래에 예시 그룹을 만들겠습니다.

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

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

saml 리소스를 편집하고 유지 관리할 수 있는 Teleport 역할. 이는 기본 editor 역할에서 사용 가능합니다.

tctl 및 tsh 클라이언트 도구 버전 >= 16.2.0은
귀하의 Teleport 계정을 방문하여 다운로드할 수 있습니다.

tctl 및 tsh 클라이언트 도구 버전 >= 16.1.7. 이러한 도구를 설치하려면 설치 페이지를 참조하세요.

1단계/4단계. 그룹 생성 및 할당

Okta는 SAML 어설션을 통해 사용자의 그룹 멤버십을 Teleport에 제공합니다. 우리는 Teleport가 okta-dev Okta 그룹의 구성원에게 "dev" 역할을 할당하고, okta-admin 그룹의 구성원에게는 사전 정의된 "editor" 역할을 할당하도록 구성할 것입니다.

이미 "dev" 및 "editor" 역할에 할당할 Okta 그룹이 있는 경우 다음 단계로 건너뛰어도 됩니다.

그룹 생성

"okta-dev" 및 "okta-admin"이라는 두 개의 그룹을 만듭니다. Okta 대시보드에서 탐색 모음으로 이동하여 Directory -> Groups를 클릭한 다음 Add group을 클릭합니다:

관리자 그룹에 대해서도 반복합니다:

2단계/4단계. Okta 구성

이 섹션에서는 Okta 대시보드에서 Teleport 클러스터가 Okta를 IdP 제공자로 사용할 수 있도록 애플리케이션을 생성할 것입니다. 또한 Okta가 Teleport에 제공하는 IdP 메타데이터 주소를 찾아보겠습니다.

먼저, Okta에서 SAML 2.0 웹 애플리케이션을 생성합니다:

주 탐색 메뉴에서 Applications -> Applications를 선택하고 Create App Integration을 클릭합니다. SAML 2.0을 선택한 다음 Next를 클릭합니다.

다음 화면(General Settings)에서 새 앱의 이름과 선택적 로고를 제공한 후 Next를 클릭합니다. 그러면 Configure SAML 섹션으로 이동합니다.

앱 구성

다음 값을 해당 필드에 제공합니다:

일반

단일 로그인 URL: https://<cluster-url>:<port>/v1/webapi/saml/acs/okta
Audience URI (SP Entity ID): https://<cluster-url>:<port>/v1/webapi/saml/acs/okta
Name ID 형식 EmailAddress
애플리케이션 사용자 이름 Okta username

<cluster-url>을 Teleport 프록시 서비스 주소 또는 엔터프라이즈 클라우드 테넌트(예: mytenant.teleport.sh)로 바꾸십시오. <port>는 프록시 서비스의 수신 포트(기본값: 443)로 바꿉니다.

속성 문

이름: username | 이름 형식: Unspecified | 값: user.login

그룹 속성 문

우리는 Okta 그룹을 SAML 속성 문으로 매핑하여 Teleport가 사용자의 그룹 멤버십을 발견하고 일치하는 역할을 할당할 수 있도록 할 것입니다.

이름: groups | 이름 형식: Unspecified
필터: Matches regex | .*

구성 페이지는 이제 다음과 같은 모습을 갖추어야 합니다:

Warning

"Matches regex" 필터는 그룹 속성 문에서 모든 콘텐츠와 일치하기 위해 리터럴 문자열 .*가 필요합니다.

Tip

"NameID"를 이메일 형식으로 설정하고 그룹을 와일드카드 정규 표현식으로 매핑했음을 유의하십시오. 또한 "Audience" 및 SSO URL을 동일한 값으로 설정했습니다. 이렇게 하면 Teleport가 Okta 사용자의 이메일 주소를 읽고 이를 기반으로 Teleport의 사용자 이름을 생성할 수 있습니다.

필수 필드를 모두 채운 후 Next를 클릭하고 앱 생성 마법사를 완료합니다.

신규 애플리케이션 페이지의 Assignments 탭에서 Assign을 클릭합니다. 새로 생성된 그룹에 앱에 대한 액세스를 할당합니다.

IdP 메타데이터 경로 저장

Okta는 사용자 신원을 신뢰할 수 있는 출처로 식별하고 확인하기 위해 클라이언트가 사용하는 IdP 메타데이터 블록을 제공합니다.

Okta가 HTTPS를 통해 이 콘텐츠를 제공하므로, Teleport가 이 경로를 로컬 복사본 대신 사용할 수 있도록 구성할 수 있습니다. 로컬 복사본은 오래될 수 있습니다.

애플리케이션의 Sign On 탭에서 SAML Signing Certificates로 스크롤하여 SHA-2 항목의 Actions를 클릭한 다음 "View IdP metadata"를 클릭합니다:

메타데이터 파일의 URL을 복사하여 Teleport 구성에 사용합니다.

Tip

"View IdP metadata" 링크를 우클릭하고 "Copy Link" 또는 "Copy Link Address"를 선택할 수도 있습니다.

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

tctl을 사용하여 Okta SAML 커넥터를 정의합니다. 이 예제 명령에서 메타데이터 파일의 경로로 업데이트하고, 사용자 정의 그룹 할당을 위해 --attributes-to-roles 값을 편집하십시오. 이 명령의 플래그에 대한 전체 참조는 tctl sso configure saml를 참조하십시오:

tctl sso configure saml --preset=okta \--entity-descriptor https://example.okta.com/app/000000/sso/saml/metadata \--attributes-to-roles=groups,okta-admin,editor \--attributes-to-roles=groups,okta-dev,dev > okta-connector.yaml

okta-connector.yaml의 내용은 다음과 유사해야 합니다:

kind: saml
metadata:
  name: okta
spec:
  acs: https://teleport.example.com:443/v1/webapi/saml/acs/okta
  attributes_to_roles:
  - name: groups
    roles:
    - editor
    value: okta-admin
  - name: groups
    roles:
    - dev
    value: okta-dev
  audience: https://teleport.example.com:443/v1/webapi/saml/acs/okta
  cert: ""
  display: "Okta"
  entity_descriptor: ""
  entity_descriptor_url: https://example.okta.com/app/000000/sso/saml/metadata
  issuer: ""
  service_provider_issuer: https://teleport.example.com:443/v1/webapi/saml/acs/okta
  sso: ""
version: v2

커넥터 리소스의 attributes_to_roles 필드는 Okta의 어설션에서 키/값 쌍 같은 속성을 Teleport 세션에 적용할 역할 목록으로 매핑합니다.

spec.allow_idp_initiated 플래그를 SAML 커넥터에서 활성화하면 사용자가 IdP에서 제공하는 대시보드에서 한 번의 클릭으로 Teleport에 로그인을 할 수 있습니다.

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

IdP-시작 로그인을 활성화하면 다음과 같은 주목할 만한 보안 위험이 있습니다:

공격자가 비밀 웹 세션을 얻는 SAML 페이로드에 대한 재전송 공격의 가능성
SAML 통신을 가로채는 것에 기반한 세션 하이재킹 및 사칭 공격의 위험 증가

커넥터를 클러스터에 적용하기 전에 테스트할 수 있습니다. 이는 활성 클러스터의 중단을 피하기 위해 강력히 권장됩니다:

cat okta-connector.yaml | tctl sso test
브라우저 창이 자동으로 열리지 않으면 링크를 클릭하여 엽니다:  http://127.0.0.1:52519/0222b1ca...성공! 로그인한 사용자: alice@example.com--------------------------------------------------------------------------------인증 세부 사항:   역할:   - editor   - dev   특성:     groups:     - Everyone     - okta-admin     - okta-dev     username:     - alice@example.com   사용자 이름: alice@example.com--------------------------------------------------------------------------------[SAML] 속성을 역할에 매핑:- 이름: groups  역할:  - editor  값: okta-admin- 이름: groups  역할:  - dev  값: okta-dev
--------------------------------------------------------------------------------[SAML] 속성 문서:groups:- Everyone- okta-admin- okta-devusername:- alice@example.com
--------------------------------------------------------------------------------자세한 내용은 --debug 플래그와 함께 명령을 반복하십시오.

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

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

4단계/4단계. 개발자 Teleport 역할 생성

이제 okta-dev 그룹의 구성원에게 할당할 Teleport 역할을 생성하겠습니다. 아래 내용을 포함하는 로컬 파일 dev.yaml을 만듭니다.

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

이 역할의 구성원들은 여러 속성을 부여받습니다:

access: relaxed 레이블이 붙은 노드에만 로그인할 수 있습니다.
ubuntu 사용자로 로그인하거나 자신의 이메일 접두사가 일치하는 사용자로 로그인할 수 있습니다.
"allow rules"가 없으므로 과거 세션을 보거나 재구성할 수 없습니다.

{{external.username}} 로그인을 유의하세요. 이는 Teleport가 "username" Okta 클레임을 보고 이 필드를 각 사용자의 허용된 로그인으로 사용할 수 있도록 구성합니다. 이 예제에서는 이메일을 사용자 이름 형식으로 사용하고 있습니다. email.local(external.username) 함수 호출은 @domain을 제거하고 사용자 이름 접두사만 남깁니다. Teleport 역할의 변수 확장 작동 방식에 대한 전체 세부 정보는 Teleport Access Controls Reference를 참조하십시오.

tctl을 사용하여 Teleport Auth Service에 이 역할을 생성하십시오:

tctl create dev.yaml

"editor" 역할은 모든 Teleport 클러스터에서 기본으로 사용 가능한 사전 정의된 역할이므로 이 과정을 반복할 필요가 없습니다.

테스트

Web UI에는 이제 로그인 화면에 새로운 "Okta" 버튼이 있습니다. tsh CLI를 통해 인증하기 위해 프록시 서비스 주소를 지정하면 tsh가 자동으로 기본 인증 유형을 사용합니다:

tsh login --proxy=proxy.example.com

이 명령은 SSO 로그인 URL을 인쇄하며 (자동으로 열려고 시도합니다).

Tip

Teleport는 여러 SAML 커넥터를 사용할 수 있습니다. 이 경우, --auth 플래그를 통해 커넥터 이름을 전달할 수 있습니다. 위에서 생성한 커넥터의 경우:

tsh login --proxy=proxy.example.com --auth=okta

문제 해결

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 원문 보기