Teleport 사용자는 조직의 싱글 사인 온(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 공급자는 자체 인증 흐름을 실행한 후 인증이 완료되었음을 나타내기 위해 Teleport 클러스터에 HTTP 요청을 보냅니다.

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=example.teleport.sh
tctl get users/<username>

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 SSO 통합을 통해 Teleport 클러스터에 로그인한 GitHub 사용자 myuser 에 대해 Teleport가 발급한 인증서의 Subject 필드입니다:

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 클러스터는 이를 Teleport의 access , editor , 및 auditor 역할에 매핑합니다. (자신의 SSO 공급자의 역할 매핑 구성 방법에 대한 가이드를 읽어보십시오.)

TELEPORT_CLUSTER=<클러스터 이름>
SSO_USER=<SSO 공급자 내 사용자 이름>
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 리소스 외에, SSO 공급자와 연결된 사용자의 계정에 대한 지속적인 백엔드 데이터는 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/<클러스터 이름> 디렉토리에 저장합니다. 또한 실행 중인 SSH 에이전트가 있을 경우 SSH 인증서를 추가합니다.

콜백 주소 변경

로컬 머신 대신 원격 머신에 콜백해야 할 경우 콜백 주소를 변경할 수 있습니다:

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

이 작업을 수행하려면 콜백에 사용될 원격 머신의 호스트 이름이나 CIDR이 인증 커넥터의 client_redirect_settings 를 통해 허용되어야 합니다:

kind: oidcmetadata:  name: example-connectorspec:  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

리소스를 생성합니다:

tsh로 클러스터에 로그인하여 tctl 명령을 실행할 수 있습니다.
tsh login --proxy=mytenant.teleport.sh --user=myuser
tctl create -f cap.yaml

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

(!/examples/resources/saml-connector.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

kind: oidc
metadata:
  name: oidc_connector
spec:
  claims_to_roles:
  - claim: groups
    roles:
    - access
    value: users
  - claim: groups
    roles:
    - editor
    value: admins
  client_id: <CLIENT-NAME>
  client_secret: <CLIENT-SECRET>
  issuer_url: https://idp.example.com/
  redirect_url: https://mytenant.teleport.sh:443/v1/webapi/oidc/callback
  max_age: 24h
  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: v3

(!/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

사용자 로그인

종종 Teleport 노드에 연결할 때 SSO 사용자가 고유한 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): OIDC 제공자로 Okta를 사용할 때 필요합니다.

현재로서는 spec.provider 필드를 다른 신원 공급자에 대해 설정해서는 안 됩니다.

외부 이메일 신원을 사용하는 방법

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

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

신원 공급자로부터 이메일 클레임 ({{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 서버에서 다음 명령을 실행하십시오:

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",
  "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 중 하나와 일치해야 합니다.

이 예시에서 사용자는 ubuntu , debian 사용자 이름과 SSO 특성 logins 에서 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로 인증할 때 사용한 단일 로그인 공급자의 값으로 대체됩니다.
Teleport 역할에서 변수 확장 작동 방식에 대한 전체 세부 정보는 Teleport 액세스 제어 참조를 참조하십시오.