Teleport 사용자는 조직의 Single Sign-On(SSO) 제공자를 통해 서버, Kubernetes 클러스터, 데이터베이스, 웹 애플리케이션 및 Windows 데스크톱에 로그인할 수 있습니다.

• Azure Active Directory (AD): SSH, Kubernetes, 데이터베이스, 데스크톱 및 웹 앱을 위한 Azure Active Directory SSO를 구성합니다.
• Active Directory (ADFS): SSH, Kubernetes, 데이터베이스, 데스크톱 및 웹 앱을 위한 Windows Active Directory SSO를 구성합니다.
• Google Workspace: SSH, Kubernetes, 데이터베이스, 데스크톱 및 웹 앱을 위한 Google Workspace SSO를 구성합니다.
• GitHub: SSH, Kubernetes, 데이터베이스, 데스크톱 및 웹 앱을 위한 GitHub SSO를 구성합니다.
• GitLab: SSH, Kubernetes, 데이터베이스, 데스크톱 및 웹 앱을 위한 GitLab SSO를 구성합니다.
• OneLogin: SSH, Kubernetes, 데이터베이스, 데스크톱 및 웹 앱을 위한 OneLogin SSO를 구성합니다.
• OIDC: SSH, Kubernetes, 데이터베이스, 데스크톱 및 웹 앱을 위한 OIDC SSO를 구성합니다.
• Okta: SSH, Kubernetes, 데이터베이스, 데스크톱 및 웹 앱을 위한 Okta SSO를 구성합니다.

Teleport의 SSO 사용 방법

Teleport 클러스터를 SSO 제공자와 애플리케이션으로 등록할 수 있습니다. 사용자가 Teleport에 로그인하면, SSO 제공자는 자체 인증 흐름을 실행한 다음, 인증이 완료되었음을 나타내기 위해 HTTP 요청을 Teleport 클러스터로 전송합니다.

Teleport는 단기적으로 인증서를 발급함으로써 사용자를 인프라에 인증합니다. 사용자가 SSO 인증 흐름을 완료한 후, Teleport는 사용자에게 단기 인증서를 발급합니다. Teleport는 또한 Auth Service 백엔드에 임시 사용자도 생성합니다.

임시 user 리소스

사용자가 SSO 인증 흐름을 완료한 후, Teleport는 해당 사용자에 대한 임시 user 리소스를 생성합니다.

사용자가 tsh login으로 Teleport에 로그인하면, Teleport가 생성하는 user의 TTL을 구성할 수 있습니다. Teleport는 30시간의 제한을 시행하며(기본값은 12시간입니다).

Teleport 감사 로그에서, 임시 사용자에 대한 user.create 유형의 이벤트를 확인할 수 있습니다.

tctl을 원격으로 사용하기 위해 tsh로 클러스터에 로그인
tsh login --proxy=proxy.example.com --user=myuser
tctl get users/<username>

tctl을 원격으로 사용하기 위해 tsh로 클러스터에 로그인
tsh login --proxy=mytenant.teleport.sh --user=myuser
tctl get users

kind: user
metadata:
  expires: "2022-06-15T04:02:34.586688054Z"
  id: 0000000000000000000
  name: myuser
spec:
  created_by:
    connector:
      id: github
      identity: myuser
      type: github
    time: "2022-06-14T16:02:34.586688441Z"
    user:
      name: system
  expires: "0001-01-01T00:00:00Z"
  github_identities:
  - connector_id: github
    username: myuser
  roles:
  - editor
  - access
  - auditor
  status:
    is_locked: false
    lock_expires: "0001-01-01T00:00:00Z"
    locked_time: "0001-01-01T00:00:00Z"
  traits:
    github_teams:
    - my-team
    kubernetes_groups: null
    kubernetes_users: null
    logins:
    - root
version: v2

SSO 사용자 인증서

임시 사용자 생성과 함께, Teleport는 성공적으로 인증된 SSO 사용자의 머신에 SSH 및 X.509 인증서를 발급합니다. 이를 통해 SSO 사용자는 Teleport가 그들의 영구적인 기록을 생성할 필요 없이 클러스터에 인증할 수 있습니다.

예를 들어, X.509 인증서의 Subject 필드에는 임시 user 리소스에 정의된 것과 동일한 정보가 포함됩니다. 이를 통해 Teleport는 사용자가 클러스터의 리소스에 접근할 때 인증된 사용자에 대한 RBAC 규칙을 시행할 수 있습니다.

다음은 GitHub 사용자인 myuser를 위해 Teleport가 발급한 인증서의 Subject 필드입니다. 사용자는 GitHub SSO 통합을 통해 Teleport 클러스터에 로그인합니다:

Subject: L=myuser/street=teleport.example.com/postalCode={"github_teams":["my-team"],"kubernetes_groups":null,"kubernetes_users":null,"logins":["root"]}, O=access, O=editor, O=auditor, CN=myuser/1.3.9999.1.7=teleport.example.com

사용자는 GitHub 팀 my-team에 속하며, 이 Teleport 클러스터는 이를 access, editor, 및 auditor 역할에 매핑합니다. (역할 매핑을 구성하는 방법에 대한 가이드를 읽어보세요.)

TELEPORT_CLUSTER=<your cluster>
SSO_USER=<your username within your SSO provider>
openssl x509 -text -in ~/.tsh/keys/${TELEPORT_CLUSTER}/${SSO_USER}-x509.pem | grep "Subject:"

ssh-keygen -L -f ~/.tsh/keys/${TELEPORT_CLUSTER}/${SSO_USER}-ssh/${TELEPORT_CLUSTER}-cert.pub

여러 SSO 제공자

Teleport는 사용자가 SSO를 통해 인증할 때 임시 사용자를 생성하고 단기 인증서를 발급하므로, 여러 SSO 제공자와의 통합이 간단합니다. 임시 user 리소스를 제외하고, Teleport에서 사용자의 계정에 연결된 지속적인 백엔드 데이터는 없습니다.

이는 하나의 SSO 제공자가 사용할 수 없는 경우 사용자가 Teleport에 로그인할 때 다른 SSO 제공자를 선택하기만 하면 된다는 것을 의미합니다. 사용자는 첫 번째 SSO 제공자가 차단되었더라도, 두 번째 제공자를 통해 로그인하는 것만으로 Teleport가 새로운 인증서를 발급하고 인프라에 접근할 수 있도록 합니다.

만약 SSO 사용자의 사용자 이름이 Auth Service에 로컬로 등록된 사용자(즉, tctl users add를 통해 생성된 사용자)와 이미 존재하는 경우, SSO 로그인이 실패합니다.

SSO를 통한 로그인

사용자는 다음과 유사한 명령어를 실행하여 SSO 제공자를 통한 Teleport에 로그인할 수 있으며, --auth 플래그를 사용하여 제공자를 지정합니다:

이 명령은 자동으로 기본 웹 브라우저를 열어 사용자가 SSO 제공자와 함께 로그인 프로세스를 진행하게 합니다
tsh login --proxy=proxy.example.com --auth=github

이 명령은 브라우저 창을 열고, 사용자가 SSO 흐름을 완료하기 위해 터미널에서 방문할 수 있는 URL을 보여줍니다:

브라우저 창이 자동으로 열리지 않는 경우, 링크를 클릭하여 열어보세요:
http://127.0.0.1:45235/055a310a-1099-43ea-8cf6-ffc41d88ad1f

Teleport는 사용자가 인증할 때까지 최대 3분을 기다립니다. 인증에 성공하면, Teleport는 SSH 및 X.509 인증서를 검색하여 ~/.tsh/keys/<clustername> 디렉토리에 저장합니다. 도구는 또한 실행 중인 SSH 에이전트가 있으면 SSH 인증서를 SSH 에이전트에 추가합니다.

콜백 주소 변경

원격 머신으로 호출해야 할 경우 콜백 주소를 변경할 수 있습니다:

--bind-addr는 tsh가 수신 대기할 호스트와 포트를 설정하며, --callback은 사용자에게 표시되는 링크를 변경합니다
tsh login --proxy=proxy.example.com --auth=github --bind-addr=localhost:1234 --callback https://remote.machine:1234

작동하려면 콜백에 사용할 원격 머신의 호스트 이름이나 CIDR가 spec.client_redirect_settings을 통해 허용되어야 합니다:

spec:
  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'

SSO 구성하기

Teleport는 인증 커넥터의 개념에 의존하여 SSO 제공자와 작동합니다. 인증 커넥터는 SSO 사용자가 Teleport에 로그인하는 방법과 로그인을 완료한 후 어떤 Teleport 역할을 가질지 제어하는 구성 리소스입니다.

이는 사용자를 온보딩 및 오프보드하는 데 사용하는 솔루션을 변경할 필요 없이 Teleport 클러스터에 세분화된 RBAC 정책을 적용할 수 있음을 의미합니다.

지원되는 커넥터

다음 인증 커넥터가 지원됩니다:

인증 커넥터 생성

인증 커넥터를 생성하기 전에 해당 커넥터의 프로토콜을 통한 인증을 활성화해야 합니다.

기본 인증 유형을 saml, oidc 또는 github로 설정하려면 cluster_auth_preference 리소스를 생성합니다.

cap.yaml이라는 파일을 생성하십시오:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  # saml, oidc 또는 github으로 설정
  type: saml|oidc|github
version: v2

리소스를 생성합니다:

tctl 명령을 실행하기 위해 tsh로 클러스터에 로그인
tsh login --proxy=mytenant.teleport.sh --user=myuser
tctl create -f cap.yaml

다음으로, 인증 커넥터를 정의합니다. 아래의 예제 중 하나를 바탕으로 connector.yaml이라는 파일을 생성하십시오. Teleport 커뮤니티 에디션은 GitHub만 SSO 옵션으로 지원합니다.

(!/examples/resources/saml-connector.yaml!)

(!/examples/resources/onelogin-connector.yaml!)

(!/examples/resources/oidc-connector.yaml!)

(!/examples/resources/gworkspace-connector-inline.yaml!)

(!/examples/resources/adfs-connector.yaml!)

(!/examples/resources/saml-connector.yaml!)

(!/examples/resources/github.yaml!)

커넥터를 생성합니다:

tctl create -f connector.yaml

사용자 로그인이

SSO 사용자를 Teleport 노드에 연결할 때 고유한 UNIX 로그인으로 제한해야 할 경우가 종종 요구됩니다. 이를 지원하려면:

• SSO 제공자를 사용하여 unix_login이라는 필드를 생성합니다(다른 이름을 사용할 수 있습니다).
• unix_login 필드가 SAML/OIDC를 통한 클레임으로 노출되도록 합니다.
• Teleport 역할을 업데이트하여 허용된 로그인 목록에 {{external.unix_login}} 변수를 포함합니다:

kind: role
version: v5
metadata:
  name: sso_user
spec:
  allow:
    logins:
    - '{{external.unix_login}}'
    node_labels:
      '*': '*'

공급자별 우회 방법

특정 SSO 제공자는 Teleport의 SSO 흐름에 대해 변경이 필요하거나 이점이 있을 수 있습니다. 이러한 공급자별 변경은 커넥터 정의의 spec.provider 속성을 다음 값 중 하나로 설정하여 활성화할 수 있습니다:

• adfs (SAML): Active Directory (ADFS)와의 호환성을 위해 필요합니다; 전체 ADFS 가이드를 참조하십시오.
• netiq (OIDC): NetIQ-특정 ACR 값 처리를 활성화하는 데 사용됩니다; OIDC 가이드를 참조하십시오.
• ping (SAML 및 OIDC): Ping Identity(예: PingOne 및 PingFederate)와의 호환성을 위해 필요합니다.
• okta (OIDC): Okta를 OIDC 제공자로 사용할 때 필요합니다.

현재 다른 IDP에 대해 spec.provider 필드를 설정하면 안 됩니다.

외부 이메일 ID 작업

SSO 제공자는 그룹을 전송하는 것과 함께 사용자의 이메일 주소도 제공합니다. 많은 조직에서 개인이 시스템에 로그인하는 데 사용하는 사용자 이름은 이메일 주소의 첫 번째 부분, 즉 "로컬" 부분과 동일합니다.

예를 들어, dave.smith@example.com은 dave.smith 사용자 이름으로 로그인할 수 있습니다. Teleport는 이메일 주소의 첫 부분을 추출하여 사용자 이름으로 사용할 수 있는 간단한 방법을 제공합니다. 이것이 {{email.local}} 기능입니다.

IDP에서 전송된 이메일 클레임(이는 {{external.email}}를 통해 접근할 수 있음)이 있으며 이메일 주소가 포함되어 있다면, @ 기호 전에 이메일 주소의 "로컬" 부분을 다음과 같이 추출할 수 있습니다: {{email.local(external.email)}}

다음은 Teleport 역할에서 이 모습입니다:

kind: role
version: v5
metadata:
  name: sso_user
spec:
  allow:
    logins:
    # dave.smith@acme.com의 로컬 부분을 추출하므로 로그인 지원이 dave.smith가 됩니다.
    - '{{email.local(external.email)}}'
    node_labels:
      '*': '*'

여러 SSO 제공자 작업

Teleport는 여러 커넥터를 지원합니다. 예를 들어, Teleport 관리자는 위에서 보여준 것처럼 tctl create를 사용하여 여러 커넥터 리소스를 정의하고 생성할 수 있습니다.

구성된 모든 커넥터를 보려면, Auth Server에서 이 명령어를 실행합니다:

tctl get connectors

커넥터를 삭제/업데이트하려면, 일반적인 tctl rm 및 tctl create 명령을 사용하면 됩니다. 전체 리소스 참조를 참조하세요.

여러 인증 커넥터가 존재하는 경우, 클라이언트는 --auth 인수를 통해 tsh login에 커넥터 이름을 제공해야 합니다:

"okta" SAML 커넥터 사용:
tsh --proxy=proxy.example.com login --auth=okta

로컬 Teleport 사용자 DB 사용:
tsh --proxy=proxy.example.com login --auth=local --user=admin

다음 가이드를 참조하여 SAML 및 OIDC 유형의 인증 커넥터를 구성하세요:

• Okta로 SSH 인증
• OneLogin으로 SSH 인증
• ADFS로 SSH 인증
• OAuth2 / OpenID Connect로 SSH 인증

SSO 사용자 정의

인증 커넥터에서 display 필드를 사용하여 Teleport 웹 UI에 SSO 버튼의 모양을 제어할 수 있습니다.

제공자	YAML	예시
GitHub	display: GitHub
Microsoft	display: Microsoft
Google	display: Google
BitBucket	display: Bitbucket
OpenID	display: Okta

문제 해결

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

• SSO 제공자가 Teleport로 전달하는 SAML/OIDC 클레임 및 값이 무엇인지 확인할 수 있어야 합니다.
• Teleport가 수신한 클레임을 커넥터에 정의된 역할 매핑으로 어떻게 매핑하는지 확인할 수 있어야 합니다.

문제가 발생하면 다음을 권장합니다:

• 커넥터 정의에서 호스트 이름, 토큰 및 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가 예상하는 노드를 표시하지 않습니다

SSO를 구성할 때, IDP가 각 사용자의 특성을 올바르게 채우고 있는지 확인해야 합니다. 사용자가 Teleport에서 노드를 보려면, 역할의 allow.logins에서 템플릿 변수를 사용하는 결과가 사용자의 traits.logins 중 하나와 일치해야 합니다.

이 예시에서 사용자는 ubuntu, debian 및 SSO 특성 로그인의 사용자 이름을 가지며, env: dev 레이블이 있는 노드에는 해당합니다. SSO 특성 사용자 이름이 bob인 경우 사용자 이름은 ubuntu, debian, 그리고 bob을 포함하게 됩니다.

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

다음 단계

이 가이드에서 보여준 역할은 external 특성을 사용하며, Teleport는 이를 사용자가 인증할 때 사용한 SSO 제공자로부터의 값으로 교체합니다. Teleport 역할에서 변수 확장이 작동하는 방식에 대한 전체 정보는 Teleport 접근 제어 참조를 참조하세요.