📣 Teleport의 공식 파트너 인포그랩에서 OpenAI 기술 기반으로 자체 개발한 자동화 번역 프로그램을 통해 Teleport 공식 문서(v17.0.0)의 한글판을 국내 최초로 제공합니다.
Infograb logo
OneLogin을 SSO 공급자로 사용한 Teleport 인증

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

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

전제 조건

  • 관리 액세스가 있는 OneLogin 계정과 최소 두 개 그룹에 할당된 사용자.
  • saml 리소스를 유지 관리할 수 있는 Teleport 역할. 이는 기본 editor 역할에서 사용할 수 있습니다.

  • 실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하여 무료 평가판을 이용해 보십시오.

  • tctl 관리자 도구 및 tsh 클라이언트 도구.

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

  • 연결이 가능한지 확인하기 위해 tsh login 으로 로그인한 다음, 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어: 
    tsh login --proxy=teleport.example.com --user=email@example.com
    tctl status
    클러스터  teleport.example.com
    버전  17.0.0-dev
    CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    클러스터에 연결할 수 있고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 후속 tctl 명령어를 실행할 수 있습니다.
    자신의 Teleport 클러스터를 호스팅하는 경우, Teleport Auth Service를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

1/3단계. OneLogin에서 Teleport 애플리케이션 생성

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

  2. 새 애플리케이션을 정의합니다:

    업로드할 Teleport 아이콘은 다음 링크에서 찾을 수 있습니다:

  3. 애플리케이션의 구성 페이지에서 다음 값을 설정합니다:

    Tip

    여기에서

    teleport.example.com:443

    를 귀하의 Teleport Proxy Service 주소와 포트 또는 Teleport Enterprise Cloud 테넌트(예: company.teleport.sh:443 )로 설정하여 아래 값을 입력하십시오.

    • 로그인 URL:
      • https://teleport.example.com:443/web/login
    • ACS(소비자) URL, SAML 수신자, ACS(소비자) URL 검증기 및 청중:
      • https://teleport.example.com:443/v1/webapi/saml/acs/onelogin

  4. Teleport는 사용자에게 그룹을 할당해야 합니다. 매개변수 페이지에서 SAML 속성 문으로 표시된 매개변수를 사용하여 애플리케이션을 구성합니다:

    중요

    SAML assertion에 포함 체크박스를 선택했는지 확인하십시오.

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

  6. 인증 커넥터에 대한 SAML 메타데이터를 가져옵니다. 애플리케이션이 설정되면 추가 작업 메뉴로 이동하여 SAML 메타데이터 옵션을 찾습니다:

    옵션을 왼쪽 클릭하여 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 파일을 생성합니다:

kind: saml
version: v2
metadata:
  name: OneLogin
spec:
  acs: https://teleport.example.com/v1/webapi/saml/acs/onelogin
  attributes_to_roles:
  - name: groups
    roles:
    - editor
    value: admin
  - name: groups
    roles:
    - access
    value: dev
  audience: https://teleport.example.com:443/v1/webapi/saml/acs/onelogin
  cert: ""
  display: OneLogin
  entity_descriptor: |
    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.example.com/00000000000000000000">
      <md:IDPSSODescriptor WantAuthnRequestsSigned="false"
  entity_descriptor_url: ""
  issuer: ""
  service_provider_issuer: https://teleport.example.com:443/v1/webapi/saml/acs/onelogin
  sso: ""
  client_redirect_settings:
    # HTTPS 클라이언트 리디렉션 URL에 허용되는 호스트 이름 목록
    # 정규식 패턴일 수 있음
    allowed_https_hostnames:
      - remote.machine
      - '*.app.github.dev'
      - '^\d+-[a-zA-Z0-9]+\.foo.internal$'
    # HTTP 또는 HTTPS 클라이언트 리디렉션 URL에 허용되는 CIDR 목록
    insecure_allowed_cidr_ranges:
      - '192.168.1.0/24'
      - '2001:db8::/96'
version: v2

새로 생성된 구성을 테스트하세요:

cat onelogin.yaml | tctl sso test

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

tctl 도구를 사용하여 커넥터를 생성하세요:

tctl create -f onelogin.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 을 사용하십시오.

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",
  "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 역할에서 external 속성은 사용자가 Teleport에 인증하는 데 사용한 SSO 공급자에서 가져온 값으로 대체됩니다. Teleport 역할에서 속성이 어떻게 작동하는지에 대한 전체 세부정보는 Teleport 접근 제어 참고 자료를 참조하세요.

Teleport 원문 보기
인포레터에서 최신 DevOps 트렌드를 격주로 만나보세요!