OneLogin을 SSO 프로바이더로 사용한 Teleport 인증

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 

$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

1. 애플리케이션에 사용자를 추가합니다:

   

2. 인증 커넥터의 SAML 메타데이터를 얻습니다. 애플리케이션이 설정되면 More Actions 메뉴로 이동하여 SAML Metadata 옵션을 찾습니다:

   

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

2/3단계. OneLogin을 Teleport에 연결#

이 섹션에서는 Teleport가 OneLogin과 SAML 메시지를 교환하고 사용자에게 인증서를 발급하는 데 필요한 정보를 제공하는 인증 커넥터를 만듭니다.

역할 매핑 할당#

사용자가 Teleport에 인증하면, Teleport Auth Service는 사용자의 Teleport 역할이 포함된 SSH 및 TLS 인증서를 사용자에게 발급합니다.

SSO 인증 커넥터의 경우, Auth Service는 인증 커넥터의 역할 매핑을 읽어 인증서에 어떤 역할을 인코딩할지 결정합니다. 역할 매핑은 아이덴티티 제공자가 사용자에 대해 저장하는 데이터를 기반으로 어떤 Teleport 역할을 할당할지 나타냅니다.

tctl CLI를 사용하여 인증 커넥터를 구성할 때, 역할 매핑은 다음 형식을 따릅니다:

<attribute_name>,<attribute_value>,<teleport_role_1>,<teleport_role_2>,...,<teleport_role_n>

예를 들어, 다음 역할 매핑은 값이 admins인 attribute groups를 가진 모든 사용자가 Teleport 역할 auditor와 editor를 받는다는 것을 의미합니다:

groups,admins,auditor,editor

이 가이드의 목적을 위해 두 개의 개별 역할 매핑을 할당합니다:

• 더 관대한 역할 매핑: groups,admins,auditor,editor
• 더 제한적인 역할 매핑: groups,devs,access

SAML 커넥터 구성#

tctl을 사용하여 SAML 커넥터를 만듭니다. xml-path를 이전 단계에서 복사한 XML 문서의 URL로 업데이트합니다. XML 문서를 대신 다운로드했다면 XML 메타데이터 파일의 경로를 사용합니다:

$ tctl sso configure saml --preset onelogin \
--entity-descriptor xml-path \
--attributes-to-roles mapping_1 \
--attributes-to-roles mapping_2 > onelogin.yaml

이렇게 하면 커넥터 리소스를 설명하는 onelogin.yaml이 만들어집니다:

<div class="admonition note"><div class="admonition-title">Note</div><p>이 섹션의 내용은 원문 문서를 참조하세요. (<code>onelogin-connector.yaml</code>)</p></div>

커넥터 테스트#

새로 만든 구성을 테스트합니다:

$ cat onelogin.yaml | tctl sso test

tctl sso test는 브라우저를 열고 OneLogin으로 인증을 시도합니다. 성공하면 출력에 수신된 SAML 속성과 Teleport 역할에 매핑된 내용이 출력됩니다. 테스트가 실패하면 출력이 구성 문제 해결을 도와줍니다.

커넥터 만들기#

tctl 도구를 사용하여 커넥터를 만듭니다:

$ tctl create -f onelogin.yaml

3/3단계. 인증 기본 설정 구성#

이 가이드에서 구성한 인증 커넥터를 Teleport 클러스터의 기본 인증 방식으로 설정할 수 있도록 클러스터 인증 기본 설정을 편집하십시오.

Teleport Web UI를 엽니다. 왼쪽 사이드바에서 Zero Trust Access > Auth Connectors로 이동합니다. 기본값으로 설정하려는 커넥터를 찾아 점 세 개 메뉴에서 Set as default를 선택하십시오.

Teleport 리소스를 구성 파일로 관리하는 경우, 동적 리소스를 사용하여 기본 인증 커넥터를 선택할 수 있습니다. 이 경우 tctl을 사용하여 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이 리소스를 업데이트합니다:

cluster auth preference has been updated

# Snippet from /etc/teleport.yaml
auth_service:
  authentication:
    type: saml

아이덴티티 프로바이더를 구성하기 전에 다시 로그인해야 하는 경우, --auth=local 플래그를 사용하십시오.

다음 단계#

이제 Teleport를 자격 증명 공급자(identity provider)에 연결했으므로, Teleport가 IdP 데이터를 Teleport 역할에 포함하는 방식을 사용자 정의할 수 있습니다.

**역할 템플릿(role templates)**을 사용하면 IdP의 사용자 데이터를 Teleport 역할에 직접 포함할 수 있습니다. 역할 필드 값에 external 템플릿 변수를 사용하면, Teleport가 해당 값을 IdP에서 전달받습니다. 다음 예시에서는 사용자가 원격 시스템의 특정 프린시펄(principal)을 가정하도록 허용하는 데 사용할 수 있는 모든 역할 옵션이 IdP에서 옵니다:

kind: role
version: v7
metadata:
  name: sso-users
spec:
  allow:
    logins: ['{{external.logins}}']
    aws_role_arns: ['{{external.aws_role_arns}}']
    azure_identities: ['{{external.azure_identities}}']
    db_names: ['{{external.db_names}}']
    db_roles: ['{{external.db_roles}}']
    db_users: ['{{external.db_users}}']
    desktop_groups: ['{{external.desktop_groups}}']
    gcp_service_accounts: ['{{external.gcp_service_accounts}}']
    host_groups: ['{{external.host_groups}}']
    host_sudoers: ['{{external.host_sudoers}}']
    kubernetes_groups: ['{{external.kubernetes_groups}}']
    kubernetes_users: ['{{external.kubernetes_users}}']
    windows_desktop_logins: ['{{external.windows_desktop_logins}}']

external 템플릿 변수 사용에 대한 자세한 내용은 역할 템플릿을 참조하세요.

위에 나열된 필드에 대한 설명은 역할 레퍼런스를 참조하세요.

IdP 사용자 데이터를 Teleport 역할에 포함하기 전에 변환해야 하는 경우, **로그인 규칙(Login Rules)**을 사용하여 이를 수행할 수 있습니다. 로그인 규칙을 사용하면 IdP가 Teleport가 예상하는 형식과 다른 형식으로 사용자 데이터를 제공하더라도 외부 트레잇(external traits)을 Teleport 역할에 포함할 수 있습니다. 로그인 규칙에 대해 자세히 알아보세요.

문제 해결#

SSO 구성 문제를 해결하는 것은 까다로울 수 있습니다. 일반적으로 Teleport 관리자는 다음을 수행할 수 있어야 합니다:

• SSO 공급자가 Teleport로 내보내고 전달하는 SAML/OIDC 클레임과 값이 무엇인지 확인할 수 있어야 합니다.
• Teleport가 수신한 클레임을 커넥터에 정의된 역할 매핑에 어떻게 매핑하는지 확인할 수 있어야 합니다.
• 셀프 호스팅 Teleport Enterprise 클러스터의 경우, Teleport Proxy Service와 SSO 공급자 모두에 대해 HTTP/TLS 인증서가 올바르게 구성되어 있는지 확인해야 합니다.

무언가 제대로 동작하지 않는다면, 다음을 권장합니다:

• 커넥터 정의에서 호스트 이름, 토큰, TCP 포트를 다시 한 번 확인하십시오.

Web UI 사용하기#

"access denied" 또는 기타 로그인 오류가 발생하면 가장 먼저 확인해야 할 곳은 Audit Log입니다. 레코딩을 보려면 Teleport Web UI에서 Audit을 선택한 다음, 메뉴에서 Session Recordings를 클릭하십시오.

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에 예상한 Node가 표시되지 않음#

Teleport Auth Service는 Teleport에 연결된 리소스를 나열하라는 요청(예: Web UI 또는 tsh ls를 통한 리소스 표시)을 받으면, 현재 사용자가 볼 수 있는 권한이 있는 리소스만 반환합니다.

사용자의 Teleport cluster에 있는 각 리소스에 대해 Auth Service는 다음 검사를 순서대로 적용하며, 한 검사라도 실패하면 해당 리소스를 사용자에게 숨깁니다:

• 사용자의 role 중 어느 것도 리소스의 label과 일치하는 deny 규칙을 포함하지 않아야 합니다.
• 사용자의 role 중 적어도 하나는 리소스의 label과 일치하는 allow 규칙을 포함해야 합니다.

예상한 대로 리소스가 보이지 않는 경우, Access Controls Reference에 문서화된 대로 사용자의 role에 적절한 allow 및 deny 규칙이 포함되어 있는지 확인하십시오.

SSO를 구성할 때, ID 공급자가 각 사용자의 trait를 올바르게 채우고 있는지 확인하십시오. 사용자가 Teleport에서 Node를 보려면, 역할의 allow.logins에 있는 템플릿 변수를 채운 결과가 사용자의 traits.logins 중 적어도 하나와 일치해야 합니다.

이 예시에서 사용자는 env: dev 레이블이 있는 Node에 대해 사용자 이름 ubuntu, debian과 SSO trait logins의 사용자 이름을 갖게 됩니다. SSO trait 사용자 이름이 bob이라면, 사용자 이름에는 ubuntu, debian, bob이 포함됩니다.

kind: role
metadata:
  name: example-role
spec:
  allow:
    logins: ['{{external.logins}}', ubuntu, debian]
    node_labels:
      'env': 'dev'
version: v5

OIDC에서 싱글 사인온이 실패함#

"Failed to verify JWT: oidc: unable to verify JWT signature: no matching keys" 오류 메시지가 발생하는 경우, 이는 일반적으로 JWT 토큰에 서명하는 데 사용된 알고리즘과 JSON Web Key Set(JWKS)가 지원하는 알고리즘 간의 불일치를 나타냅니다. 구체적으로, 토큰은 하나의 알고리즘(예: HS256)으로 서명되었는데 JWKS는 다른 알고리즘(예: RS256)에 대한 키만 나열하고 있을 수 있습니다. 이 문제는 매우 낮은 수준의 기능을 제공하는 ID 공급자를 사용할 때 주로 발생합니다.

확인해야 할 사항은 다음과 같습니다:

• JWT 헤더가 올바른 서명 알고리즘을 지정하고 있는지 확인하십시오. 이는 JWKS 엔드포인트 응답의 keys 섹션에 나열된 알고리즘 중 하나와 일치해야 합니다.
• JWKS 엔드포인트가 관련된 모든 공개 키를 반환하고 있는지 확인하십시오. 때때로 키 로테이션으로 인해 유효한 키가 누락될 수 있습니다.

문제를 해결하려면, JWT 알고리즘 헤더를 JWKS에서 지원하는 알고리즘에 맞추십시오. 필요한 경우 키를 로테이션하십시오. JWKS가 활성화된 공개 키만 게시하는지 확인하십시오. 올바르게 구성하면 서명이 성공적으로 검증됩니다.