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

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

"DBA" 그룹의 구성원만 PostgreSQL 데이터베이스에 접근할 수 있습니다.
개발자는 절대 운영 서버에 SSH 접속하지 않아야 합니다.
HR 그룹의 구성원은 감사 로그를 볼 수 있지만 운영 환경은 볼 수 없습니다.

Teleport Enterprise Cloud 및 Self-Hosted Teleport Enterprise에서는 Teleport가 호스팅된 Okta 통합 등록의 일환으로 SSO 연결기를 자동으로 구성할 수 있습니다.

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

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

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

"통합 유형 선택" 메뉴에서 Okta 타일을 클릭합니다. Teleport가 Okta 통합 구성 과정을 안내합니다.

필수 조건

관리자 액세스가 있는 Okta 계정. 계정에는 사용자와 최소한 두 개의 그룹이 포함되어야 합니다. 만약 Teleport 역할에 할당할 Okta 그룹이 이미 없다면 걱정하지 마세요. 아래에서 예제 그룹을 생성할 것입니다.

실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하여 무료 평가판을 이용해 보십시오.
tctl 관리자 도구 및 tsh 클라이언트 도구.

tctl 및 tsh 다운로드에 대한 지침은 설치 를 방문하십시오.

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

tctl 및 tsh 클라이언트 도구의 버전은 >= 17.0.0-dev 입니다.
설치에서 설치 방법을 확인하세요.

tctl 및 tsh 클라이언트 도구의 버전은 >= 17.0.0-dev 입니다.
설치에서 설치 방법을 확인하세요.

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

Okta는 사용자의 그룹 멤버십을 Teleport에 제공하는 데이터의 SAML 어설션으로 표시합니다. 우리는 Teleport를 구성하여 okta-dev Okta 그룹의 구성원에게 "dev" 역할을 할당하고, okta-admin 그룹의 구성원에게는 기본 "editor" 역할을 할당할 것입니다.

Teleport에서 "dev" 및 "editor" 역할에 할당할 Okta 그룹이 이미 있다면, 다음 단계로 건너뛸 수 있습니다.

그룹 생성

"okta-dev"와 "okta-admin"이라는 두 개의 그룹을 생성합니다. Okta 대시보드에서 내비게이션 바로 가서 Directory -> Groups를 클릭한 후 Add group을 클릭합니다:

관리자 그룹도 동일하게 반복합니다:

2/4단계. Okta 구성

이 섹션에서는 Teleport 클러스터가 IdP 공급자로서 Okta에 접근할 수 있도록 Okta 대시보드에서 애플리케이션을 생성합니다. 또한, Teleport에 제공되는 IdP 메타데이터를 위한 Okta의 주소를 찾습니다.

먼저, Okta에서 SAML 2.0 웹 앱을 생성합니다:

주 내비게이션 메뉴에서 Applications -> Applications를 선택한 다음 Create App Integration을 클릭합니다. SAML 2.0을 선택한 후 Next를 클릭합니다.

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

앱 구성

다음 값을 각 필드에 입력합니다:

일반

Single sign on 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 format: EmailAddress
Application username: Okta username

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

속성 진술

Name: username | Name format: Unspecified | Value: user.login

그룹 속성 진술

Okta 그룹을 SAML 속성 진술(특별 서명된 메타데이터가 SAML XML 응답을 통해 노출됨)에 매핑하여 Teleport가 사용자의 그룹 멤버십을 발견하고 일치하는 역할을 할당할 수 있도록 합니다.

Name: groups | Name format: Unspecified
Filter: 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--------------------------------------------------------------------------------인증 세부정보:   roles:   - editor   - dev   traits:     groups:     - Everyone     - okta-admin     - okta-dev     username:     - alice@example.com   username: alice@example.com--------------------------------------------------------------------------------[SAML] 속성을 역할로:- name: groups  roles:  - editor  value: okta-admin- name: groups  roles:  - dev  value: okta-dev
--------------------------------------------------------------------------------[SAML] 속성 진술:groups:- Everyone- okta-admin- okta-devusername:- alice@example.com
--------------------------------------------------------------------------------자세한 내용은 --debug 플래그와 함께 명령을 반복하십시오.

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

tctl create okta-connector.yaml

기본 SAML 인증 활성화

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

sctl 을 사용하여 cluster_auth_preference 값을 편집합니다:

tctl edit cluster_auth_preference

spec.type 의 값을 saml 로 설정합니다:

kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  type: saml
  ...
version: v2

편집기를 저장하고 나가면, tctl 이 리소스를 업데이트합니다:

클러스터 인증 기본값이 업데이트되었습니다

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 사용자로 로그인하거나 이메일 접두사와 일치하는 사용자로 로그인할 수 있습니다.
그들은 "허용 규칙"이 없으므로 과거 세션을 확인하거나 Teleport 클러스터를 재구성할 수 없습니다.

{{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 클러스터에서 기본적으로 사용할 수 있는 프리셋 역할입니다.

테스트

웹 UI는 이제 로그인 화면에 새로운 "Okta" 버튼을 포함하고 있습니다. tsh CLI를 통해 인증하려면 Proxy Service 주소를 지정하면 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",
  "message": "Failed to calculate user attributes.\n\trole clusteradmin is not found",
  "method": "oidc",
  "success": false,
  "time": "2024-11-07T15:41:25.584Z",
  "uid": "71e46f17-d611-48bb-bf5e-effd90016c13"
}

Teleport에서 예상되는 노드가 표시되지 않음

Teleport의 Auth 서비스가 Teleport 노드를 목록화하라는 요청을 받을 때(예: 웹 UI에서 노드를 표시하거나 tsh ls 를 통해), 현재 사용자가 볼 수 있는 노드만 반환합니다.

사용자의 Teleport 클러스터의 각 노드에 대해 Auth 서비스는 다음과 같은 검사를 순서대로 적용하며, 하나의 검사가 실패할 경우 해당 노드를 사용자에게 숨깁니다:

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

예상치 못하게 노드가 보이지 않는 경우, 사용자의 역할에 적절한 allow 및 deny 규칙이 포함되어 있는지 확인하십시오. 이는 Teleport Access Controls Reference에서 문서화되어 있습니다.

SSO를 구성할 때, ID 공급자가 각 사용자의 특성을 올바르게 인구시키고 있는지 확인하십시오. 사용자가 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 원문 보기