InfoGrab Docs

GitHub으로 싱글 사인온 설정

요약

이 가이드는 GitHub 조직의 팀을 Teleport의 사용자 및 역할에 자동으로 매핑할 수 있도록 GitHub 싱글 사인온(SSO)을 설정하는 방법을 설명합니다. Teleport 관리자는 Teleport Auth Service 백엔드에서 GitHub 인증 커넥터를 만들고 클러스터 인증 기본 설정을 만들어 Teleport 사용자가 GitHub을 통해 인증하도록 요구합니다.

이 가이드는 GitHub 조직의 팀을 Teleport의 사용자 및 역할에 자동으로 매핑할 수 있도록 GitHub 싱글 사인온(SSO)을 설정하는 방법을 설명합니다.

작동 방식#

Teleport 관리자는 Teleport Auth Service 백엔드에서 GitHub 인증 커넥터를 만들고 클러스터 인증 기본 설정을 만들어 Teleport 사용자가 GitHub을 통해 인증하도록 요구합니다.

사용자가 Teleport에 인증하면 GitHub을 사용하여 인증을 완료하는 지침을 받습니다. Teleport Auth Service는 GitHub에서 OAuth 2.0 액세스 토큰을 받고 해당 토큰을 인증합니다. (GitHub 인증 커넥터는 OAuth 2.0 클라이언트로 작동합니다.)

Auth Service는 OAuth 2.0 액세스 토큰에서 데이터를 읽어 사용자에게 단기 TLS 및 SSH 인증서를 발급합니다. 구체적으로 Auth Service는:

  • 사용자의 GitHub 팀을 Teleport 역할에 매핑하여 사용자 권한을 할당합니다.
  • 사용자의 Teleport 사용자 이름을 GitHub 사용자 이름으로 할당합니다.
Warning

GitHub 사용자 이름은 이메일 주소 형식이 아닙니다. 결과적으로 Teleport 사용자 이름을 기반으로 사용자에게 이메일을 보내려는 Teleport 플러그인은 예상대로 작동하지 않습니다. 예를 들어 PagerDuty 접근 요청 플러그인에는 이러한 제한이 있습니다.

사전 요구 사항#

  • 하나 이상의 팀이 있는 GitHub 조직.

    Teleport Community Edition에서는 이 조직에 외부 SSO가 설정되어 있지 않아야 합니다. 그렇지 않으면 Teleport가 GitHub 인증 커넥터 만들기를 거부합니다.

    Teleport Enterprise 및 Enterprise Cloud에서 조직은 GitHub Cloud 또는 GitHub Enterprise Server에서 호스팅될 수 있습니다.

  • 데스크톱에서 tctl을 사용하기 위해 github 리소스를 유지 관리할 수 있는 접근 권한이 있는 Teleport 역할. 기본 editor 역할에서 사용 가능합니다.

  • A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing `tctl` and `tsh` clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:

      $ TELEPORT_DOMAIN=
$ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

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

If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

1/3단계. GitHub OAuth 앱 만들기#

GitHub OAuth 앱을 만들고 등록합니다. 이때 OAuth 앱의 "Authentication callback URL"이 다음과 같은지 확인합니다:

https://PROXY_ADDRESS/v1/webapi/github/

PROXY_ADDRESS를 Teleport Proxy Service의 공개 주소 또는 Teleport Cloud 워크스페이스 URL(예: example.teleport.sh)로 교체합니다. 여러 공개 주소를 가진 셀프 호스팅 클러스터가 있는 경우 이 주소가 첫 번째로 나열된 것을 가리키도록 합니다.

앱은 org 및 팀 멤버십 세부 정보를 읽기 위해 read:org 범위가 있어야 합니다.

GitHub OAuth 앱 만들기 지침은 GitHub 문서에서 확인할 수 있습니다.

다음 단계에서 클라이언트 ID와 함께 사용할 클라이언트 시크릿을 만듭니다:

클라이언트 ID와 시크릿이 강조 표시된 GitHub OAuth 앱

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

이 섹션에서는 Teleport가 GitHub에 연결하고 사용자에게 인증서를 발급하는 데 필요한 정보를 제공하는 인증 커넥터를 만듭니다.

역할 매핑 할당#

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

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

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

<github_org_name>,<github_team_name>,<teleport_role_1>,<teleport_role_2>,...,<teleport_role_n>

예를 들어, 다음 역할 매핑은 gravitational org의 admins 팀의 모든 사용자가 Teleport 역할 editor와 auditor를 받는다는 것을 의미합니다:

gravitational,admins,editor,auditor

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

  • 더 허용적인 역할 매핑:
  • 더 제한적인 역할 매핑:

GitHub 조직과 팀은 표시 이름이 아닌 슬러그로 참조해야 합니다. 팀 슬러그를 만들기 위해 GitHub은 이름 문자열의 특수 문자를 대체하고, 모든 단어를 소문자로 변경하고, 공백을 - 구분자로 교체합니다.

예를 들어 My TEam Näme은 my-team-name이 됩니다. 조직 슬러그도 조직이 소문자로 변경되지 않는다는 점을 제외하고는 동일하게 처리됩니다. GitHub 웹 애플리케이션 URL이나 GitHub API를 통해 슬러그를 확인할 수 있습니다. 예: GitHub 웹 애플리케이션에서 팀 My Team으로 이동합니다. URL https://github.com/orgs/org-name/teams/my-team은 슬러그가 my-team임을 보여줍니다.

GitHub 인증 커넥터 구성#

이 섹션에서는 tctl을 사용하여 GitHub 인증 커넥터를 정의합니다.

워크스테이션에서 클라이언트 시크릿만 포함된 client-secret.txt 파일을 만듭니다.

다음을 포함하여 이 예제 명령을 업데이트합니다:

  • OAuth 앱의 클라이언트 ID와 이전 단계에서 만든 클라이언트 시크릿.
  • GitHub 조직에서 Teleport 역할로 매핑하려는 역할. 역할은 조직 설정의 Repository roles 섹션에 정의됩니다.

이 명령의 전체 플래그 참조는 tctl sso configure github를 확인하세요:

$ tctl sso configure github \
--id= \
--secret=$(cat client-secret.txt) \
--teams-to-roles= \
--teams-to-roles= \
> github.yaml

github.yaml의 내용은 다음과 유사해야 합니다:

kind: github
metadata:
  name: github
spec:
  api_endpoint_url: ""
  client_id: <client-id>
  client_secret: <client-secret>
  display: GitHub
  endpoint_url: ""
  redirect_url: https://<proxy-address>/v1/webapi/github/callback
  teams_to_logins: null
  teams_to_roles:
    - organization: ORG-NAME
      roles:
        - access
        - editor
      team: github-team
version: v3

kind: github
metadata:
  name: github
spec:
  api_endpoint_url: https://api.github.com
  client_id: <client-id>
  client_secret: <client-secret>
  display: GitHub
  endpoint_url: https://github.com
  redirect_url: https://<proxy-address>/v1/webapi/github/callback
  teams_to_logins: null
  teams_to_roles:
    - organization: org-name
      roles:
        - access
        - editor
        - reviewer
      team: github-team
version: v3
여러 역할 매핑

--teams-to-roles 플래그를 여러 번 추가하거나 커넥터 파일을 편집하여 여러 매핑을 정의할 수 있습니다. 예를 들어:

$  tctl sso configure github \
--id= \
--secret=$(cat client-secret.txt) \
--teams-to-roles= \
--teams-to-roles="org-name,administrators,admins \
--teams-to-roles="different-org,developers,dev \
> github.yaml

spec.
  teams_to_roles:
    - organization: org-name
      roles:
        - access
        - editor
      team: github-team
    - organization: org-name
      roles:
        - admins
      team: administrators
    - organization: different-org
      roles:
        - devs
      team: developers
GitHub Enterprise를 셀프 호스팅하고 있나요?

셀프 호스팅 GitHub Enterprise 서버의 경우 --endpoint-url, --api-endpoint-url 파라미터를 사용하여 서버 인스턴스 엔드포인트를 지정할 수 있습니다. 를 엔드포인트 URL로, 를 API 엔드포인트 URL로 교체합니다:

$ tctl sso configure github \
--id= \
--secret=$(cat client-secret.txt) \
--teams-to-roles= \
--endpoint-url=https://
--api-endpoint-url=https://
> github.yaml

...
spec:
  ...
  api_endpoint_url: https://<api-github-enterprise-server-address>
  endpoint_url: https://<github-enterprise-server-address>
  ...

커넥터 테스트#

클러스터에 적용하기 전에 커넥터 구성을 테스트할 수 있습니다. 활성 클러스터의 중단을 방지하기 위해 강력히 권장됩니다:

$ cat github.yaml | tctl sso test
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:52690/35714f6b-...
Success! Logged in as: alice
--------------------------------------------------------------------------------
Authentication details:
   roles:
   - access
   - editor
   traits:
     github_teams:
     - admins
     kubernetes_groups: null
     kubernetes_users: null
     logins:
     - alice
   username: alice
--------------------------------------------------------------------------------
[GitHub] Received claims:
organization_to_teams:
  Octocats:
  - admins
teams:
- admins
username: alice

--------------------------------------------------------------------------------
[GitHub] Connector team to roles mapping:
- organization: Octocats
  roles:
  - access
  - editor
  team: admins

--------------------------------------------------------------------------------
For more details repeat the command with --debug flag.

커넥터 만들기#

마지막으로 tctl을 사용하여 커넥터를 만듭니다:

$ tctl create -f github.yaml
authentication connector "github" has been created
Tip

처음으로 GitHub 인증 플로우를 진행할 때 "teams to logins" 매핑에 있는 모든 조직에 대한 접근 권한을 애플리케이션에 부여해야 합니다. 그렇지 않으면 Teleport가 이러한 조직의 팀 멤버십을 확인할 수 없습니다.

사용자가 인증한 후 Teleport는 해당 Teleport 세션의 internal.logins 속성에 사용자의 GitHub 사용자 이름을 추가합니다. 사전 설정 access 역할에는 GitHub 사용자를 승인된 SSH 로그인으로 포함하도록 이 속성 변수가 구성되어 있습니다. 다음은 속성 변수를 사용하는 역할 구성 예제입니다:

  allow:
    # 허용된 SSH 로그인 목록
    logins: ['{{internal.logins}}', ubuntu, debian]

    # 사용자가 SSH로 접근할 수 있는 노드 레이블
    node_labels:
      '*': '*'

이제 GitHub SSO를 사용하여 Teleport에 로그인할 수 있습니다. GitHub SSO를 사용하여 tsh에서 로그아웃하고 다시 로그인하려면 다음을 실행하세요.

$ tsh logout
# Logged out all users from all proxies.
$ tsh login --proxy=tele.example.com --auth=github
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:56334/6bf976e6-a4be-4898-94eb-8a7b01af2158

$ tsh logout
# Logged out all users from all proxies.
$ tsh login --proxy=mytenant.teleport.sh --auth=github
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:56334/6bf976e6-a4be-4898-94eb-8a7b01af2158

로그인 화면에서 Other sign-in options를 클릭하여 GitHub을 통해 웹 UI에도 로그인할 수 있습니다.

처음 로그인하면 GitHub OAuth 앱에 권한을 부여하라는 프롬프트가 표시됩니다:

GitHub SSO 인증 화면

Teleport는 read:org OAuth 범위만 요청합니다. GitHub의 문서에서 OAuth 범위에 대해 자세히 알아보세요: GitHub OAuth scopes

로그인 후 "Login Successful" 창이 표시되고 닫을 수 있습니다.

CLI에서 사용자 세션의 세부 정보를 받게 됩니다:

> Profile URL:        https://tele.example.com:443
  Logged in as:       jeff
  Cluster:            tele.example.com
  Roles:              access
  Logins:             jeff, ubuntu, debian
  Kubernetes:         enabled
  Kubernetes users:   dev
  Kubernetes groups:  developer
  Valid until:        2023-03-08 17:13:50 -0600 CST [valid for 7h51m0s]
  Extensions:         permit-port-forwarding, permit-pty, private-key-policy

> Profile URL:        https://tele.example.com:443
  Logged in as:       jeff
  Cluster:            tele.example.com
  Roles:              access, requester
  Logins:             jeff, ubuntu, debian
  Kubernetes:         enabled
  Kubernetes users:   dev
  Kubernetes groups:  developer
  Valid until:        2023-03-08 17:13:50 -0600 CST [valid for 7h51m0s]
  Extensions:         permit-port-forwarding, permit-pty, private-key-policy

> Profile URL:        https://mytenant.teleport.sh:443
  Logged in as:       jeff
  Cluster:            mytenant.teleport.sh
  Roles:              access, requester
  Logins:             jeff, ubuntu, debian
  Kubernetes:         enabled
  Kubernetes users:   dev
  Kubernetes groups:  developer
  Valid until:        2023-03-08 17:13:50 -0600 CST [valid for 7h51m0s]
  Extensions:         permit-port-forwarding, permit-pty, private-key-policy

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

이전 단계에서는 GitHub을 인증 유형으로 지정하여 GitHub 자격 증명으로 Teleport에 로그인했습니다. cluster_auth_preference 리소스를 편집하여 기본 인증 유형으로 만들 수 있습니다.

tctl을 사용하여 기존 cluster_auth_preference 리소스를 편집합니다:

$ tctl edit cap

기본 편집기에서 cluster_auth_preference 정의가 담긴 임시 파일이 열립니다.

cap.yaml에 다음 내용이 포함되어 있는지 확인합니다:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  type: github
  webauthn:
    rp_id: 'example.teleport.sh'
version: v2

rp_id에는 Teleport Proxy Service의 공개 주소 또는 Teleport Cloud 워크스페이스를 사용하세요.

임시 파일을 저장하고 닫으면 tctl이 리소스를 업데이트합니다:

#cluster auth preference has been updated
정적 구성 파일

다음을 포함하도록 Teleport 구성 파일을 편집할 수도 있습니다:

# /etc/teleport.yaml에서 발췌
auth_service:
  authentication:
    type: github

tsh에서 로그아웃한 후 --auth=github를 지정하지 않고 다시 로그인할 수 있습니다. 자동으로 GitHub 인증 플로우로 리다이렉트됩니다.

다음 단계#

Now that you have connected Teleport to your identity provider, you can customize the way Teleport includes IdP data in Teleport roles.

With role templates, you can include user data from your IdP directly in Teleport roles. If you use the external template variable in the value of a role field, Teleport passes that value from your IdP. In this example, all of the role options you can use for allowing users to assume certain principals on remote systems come from your 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}}']

For more information on using the external template variable, see Role Templates.

For an explanation of the fields listed above, see the Role Reference.

If you need to transform your IdP user data before you include it in Teleport roles, you can do so using Login Rules. Login Rules allow you to include external traits within Teleport roles even if your IdP provides user data in a different format than the one expected by Teleport. Read more about Login Rules.

문제 해결#

Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to:

  • Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport.
  • Be able to see how Teleport maps the received claims to role mappings as defined in the connector.
  • For self-hosted Teleport Enterprise clusters, ensure that HTTP/TLS certificates are configured properly for both the Teleport Proxy Service and the SSO provider.

If something is not working, we recommend to:

  • Double-check the host names, tokens and TCP ports in a connector definition.

Using the Web UI#

If you get "access denied" or other login errors, the number one place to check is the Audit Log. To view the recording, select Audit in the Teleport Web UI, then click Session Recordings in the menu.

Audit Log Entry for SSO Login error

Example of a user being denied because the role clusteradmin wasn't set up:

{
  "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 does not show the expected Nodes#

(!docs/pages/includes/node-logins.mdx!)

When configuring SSO, ensure that the identity provider is populating each user's traits correctly. For a user to see a Node in Teleport, the result of populating a template variable in a role's allow.logins must match at least one of a user's traits.logins.

In this example a user will have usernames ubuntu, debian and usernames from the SSO trait logins for Nodes that have a env: dev label. If the SSO trait username is bob then the usernames would include ubuntu, debian, and bob.

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

Single sign-on fails with OIDC#

When encountering the error message "Failed to verify JWT: oidc: unable to verify JWT signature: no matching keys", it typically indicates a discrepancy between the algorithm used to sign the JWT token and the algorithm(s) supported by the JSON Web Key Set (JWKS). Specifically, the token might be signed with one algorithm, e.g., HS256, while the JWKS only lists keys for a different algorithm. e.g., RS256. This issue predominantly arises when using identity providers that offer extremely low-level functionality.

Here are some things to check:

  • Verify the JWT header specifies the correct signing algorithm. This should match one of the algorithms listed in the keys section of the JWKS endpoint response.
  • Ensure the JWKS endpoint is returning all relevant public keys. Sometimes key rotation can cause valid keys to be omitted.

To resolve the issue, align the JWT algorithm header with a supported algorithm in the JWKS. Rotate keys if necessary. Verify the JWKS only publishes the active public keys. With proper configuration, the signature should validate successfully.

팀이 역할에 매핑되지 않는 경우#

팀이 예상대로 역할에 매핑되지 않는 경우 커넥터에서 조직과 팀의 슬러그를 사용하고 있는지 확인하세요. 슬러그를 만들기 위해 GitHub은 이름 문자열의 특수 문자를 대체하고, 모든 단어를 소문자로 변경하고, 공백을 - 구분자로 교체합니다. 예를 들어 "My TEam Näme"은 my-team-name이 됩니다. GitHub 웹 애플리케이션 URL과 GitHub API를 통해 슬러그를 확인할 수 있습니다.

예: GitHub 웹 애플리케이션에서 팀 My Team으로 이동합니다. URL https://github.com/orgs/org-name/teams/my-team은 슬러그가 my-team임을 보여줍니다. teams to roles 매핑을 업데이트합니다.

  teams_to_roles:
    - organization: my-org
      roles:
        - access
        - editor
        - reviewer
      team: my-team

GitHub으로 싱글 사인온 설정

원문 보기
요약

이 가이드는 GitHub 조직의 팀을 Teleport의 사용자 및 역할에 자동으로 매핑할 수 있도록 GitHub 싱글 사인온(SSO)을 설정하는 방법을 설명합니다. Teleport 관리자는 Teleport Auth Service 백엔드에서 GitHub 인증 커넥터를 만들고 클러스터 인증 기본 설정을 만들어 Teleport 사용자가 GitHub을 통해 인증하도록 요구합니다.

이 가이드는 GitHub 조직의 팀을 Teleport의 사용자 및 역할에 자동으로 매핑할 수 있도록 GitHub 싱글 사인온(SSO)을 설정하는 방법을 설명합니다.

작동 방식#

Teleport 관리자는 Teleport Auth Service 백엔드에서 GitHub 인증 커넥터를 만들고 클러스터 인증 기본 설정을 만들어 Teleport 사용자가 GitHub을 통해 인증하도록 요구합니다.

사용자가 Teleport에 인증하면 GitHub을 사용하여 인증을 완료하는 지침을 받습니다. Teleport Auth Service는 GitHub에서 OAuth 2.0 액세스 토큰을 받고 해당 토큰을 인증합니다. (GitHub 인증 커넥터는 OAuth 2.0 클라이언트로 작동합니다.)

Auth Service는 OAuth 2.0 액세스 토큰에서 데이터를 읽어 사용자에게 단기 TLS 및 SSH 인증서를 발급합니다. 구체적으로 Auth Service는:

  • 사용자의 GitHub 팀을 Teleport 역할에 매핑하여 사용자 권한을 할당합니다.
  • 사용자의 Teleport 사용자 이름을 GitHub 사용자 이름으로 할당합니다.
Warning

GitHub 사용자 이름은 이메일 주소 형식이 아닙니다. 결과적으로 Teleport 사용자 이름을 기반으로 사용자에게 이메일을 보내려는 Teleport 플러그인은 예상대로 작동하지 않습니다. 예를 들어 PagerDuty 접근 요청 플러그인에는 이러한 제한이 있습니다.

사전 요구 사항#

  • 하나 이상의 팀이 있는 GitHub 조직.

    Teleport Community Edition에서는 이 조직에 외부 SSO가 설정되어 있지 않아야 합니다. 그렇지 않으면 Teleport가 GitHub 인증 커넥터 만들기를 거부합니다.

    Teleport Enterprise 및 Enterprise Cloud에서 조직은 GitHub Cloud 또는 GitHub Enterprise Server에서 호스팅될 수 있습니다.

  • 데스크톱에서 tctl을 사용하기 위해 github 리소스를 유지 관리할 수 있는 접근 권한이 있는 Teleport 역할. 기본 editor 역할에서 사용 가능합니다.

  • A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing `tctl` and `tsh` clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:

      $ TELEPORT_DOMAIN=
$ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

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

If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

1/3단계. GitHub OAuth 앱 만들기#

GitHub OAuth 앱을 만들고 등록합니다. 이때 OAuth 앱의 "Authentication callback URL"이 다음과 같은지 확인합니다:

https://PROXY_ADDRESS/v1/webapi/github/

PROXY_ADDRESS를 Teleport Proxy Service의 공개 주소 또는 Teleport Cloud 워크스페이스 URL(예: example.teleport.sh)로 교체합니다. 여러 공개 주소를 가진 셀프 호스팅 클러스터가 있는 경우 이 주소가 첫 번째로 나열된 것을 가리키도록 합니다.

앱은 org 및 팀 멤버십 세부 정보를 읽기 위해 read:org 범위가 있어야 합니다.

GitHub OAuth 앱 만들기 지침은 GitHub 문서에서 확인할 수 있습니다.

다음 단계에서 클라이언트 ID와 함께 사용할 클라이언트 시크릿을 만듭니다:

클라이언트 ID와 시크릿이 강조 표시된 GitHub OAuth 앱

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

이 섹션에서는 Teleport가 GitHub에 연결하고 사용자에게 인증서를 발급하는 데 필요한 정보를 제공하는 인증 커넥터를 만듭니다.

역할 매핑 할당#

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

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

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

<github_org_name>,<github_team_name>,<teleport_role_1>,<teleport_role_2>,...,<teleport_role_n>

예를 들어, 다음 역할 매핑은 gravitational org의 admins 팀의 모든 사용자가 Teleport 역할 editor와 auditor를 받는다는 것을 의미합니다:

gravitational,admins,editor,auditor

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

  • 더 허용적인 역할 매핑:
  • 더 제한적인 역할 매핑:

GitHub 조직과 팀은 표시 이름이 아닌 슬러그로 참조해야 합니다. 팀 슬러그를 만들기 위해 GitHub은 이름 문자열의 특수 문자를 대체하고, 모든 단어를 소문자로 변경하고, 공백을 - 구분자로 교체합니다.

예를 들어 My TEam Näme은 my-team-name이 됩니다. 조직 슬러그도 조직이 소문자로 변경되지 않는다는 점을 제외하고는 동일하게 처리됩니다. GitHub 웹 애플리케이션 URL이나 GitHub API를 통해 슬러그를 확인할 수 있습니다. 예: GitHub 웹 애플리케이션에서 팀 My Team으로 이동합니다. URL https://github.com/orgs/org-name/teams/my-team은 슬러그가 my-team임을 보여줍니다.

GitHub 인증 커넥터 구성#

이 섹션에서는 tctl을 사용하여 GitHub 인증 커넥터를 정의합니다.

워크스테이션에서 클라이언트 시크릿만 포함된 client-secret.txt 파일을 만듭니다.

다음을 포함하여 이 예제 명령을 업데이트합니다:

  • OAuth 앱의 클라이언트 ID와 이전 단계에서 만든 클라이언트 시크릿.
  • GitHub 조직에서 Teleport 역할로 매핑하려는 역할. 역할은 조직 설정의 Repository roles 섹션에 정의됩니다.

이 명령의 전체 플래그 참조는 tctl sso configure github를 확인하세요:

$ tctl sso configure github \
--id= \
--secret=$(cat client-secret.txt) \
--teams-to-roles= \
--teams-to-roles= \
> github.yaml

github.yaml의 내용은 다음과 유사해야 합니다:

kind: github
metadata:
  name: github
spec:
  api_endpoint_url: ""
  client_id: <client-id>
  client_secret: <client-secret>
  display: GitHub
  endpoint_url: ""
  redirect_url: https://<proxy-address>/v1/webapi/github/callback
  teams_to_logins: null
  teams_to_roles:
    - organization: ORG-NAME
      roles:
        - access
        - editor
      team: github-team
version: v3

kind: github
metadata:
  name: github
spec:
  api_endpoint_url: https://api.github.com
  client_id: <client-id>
  client_secret: <client-secret>
  display: GitHub
  endpoint_url: https://github.com
  redirect_url: https://<proxy-address>/v1/webapi/github/callback
  teams_to_logins: null
  teams_to_roles:
    - organization: org-name
      roles:
        - access
        - editor
        - reviewer
      team: github-team
version: v3
여러 역할 매핑

--teams-to-roles 플래그를 여러 번 추가하거나 커넥터 파일을 편집하여 여러 매핑을 정의할 수 있습니다. 예를 들어:

$  tctl sso configure github \
--id= \
--secret=$(cat client-secret.txt) \
--teams-to-roles= \
--teams-to-roles="org-name,administrators,admins \
--teams-to-roles="different-org,developers,dev \
> github.yaml

spec.
  teams_to_roles:
    - organization: org-name
      roles:
        - access
        - editor
      team: github-team
    - organization: org-name
      roles:
        - admins
      team: administrators
    - organization: different-org
      roles:
        - devs
      team: developers
GitHub Enterprise를 셀프 호스팅하고 있나요?

셀프 호스팅 GitHub Enterprise 서버의 경우 --endpoint-url, --api-endpoint-url 파라미터를 사용하여 서버 인스턴스 엔드포인트를 지정할 수 있습니다. 를 엔드포인트 URL로, 를 API 엔드포인트 URL로 교체합니다:

$ tctl sso configure github \
--id= \
--secret=$(cat client-secret.txt) \
--teams-to-roles= \
--endpoint-url=https://
--api-endpoint-url=https://
> github.yaml

...
spec:
  ...
  api_endpoint_url: https://<api-github-enterprise-server-address>
  endpoint_url: https://<github-enterprise-server-address>
  ...

커넥터 테스트#

클러스터에 적용하기 전에 커넥터 구성을 테스트할 수 있습니다. 활성 클러스터의 중단을 방지하기 위해 강력히 권장됩니다:

$ cat github.yaml | tctl sso test
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:52690/35714f6b-...
Success! Logged in as: alice
--------------------------------------------------------------------------------
Authentication details:
   roles:
   - access
   - editor
   traits:
     github_teams:
     - admins
     kubernetes_groups: null
     kubernetes_users: null
     logins:
     - alice
   username: alice
--------------------------------------------------------------------------------
[GitHub] Received claims:
organization_to_teams:
  Octocats:
  - admins
teams:
- admins
username: alice

--------------------------------------------------------------------------------
[GitHub] Connector team to roles mapping:
- organization: Octocats
  roles:
  - access
  - editor
  team: admins

--------------------------------------------------------------------------------
For more details repeat the command with --debug flag.

커넥터 만들기#

마지막으로 tctl을 사용하여 커넥터를 만듭니다:

$ tctl create -f github.yaml
authentication connector "github" has been created
Tip

처음으로 GitHub 인증 플로우를 진행할 때 "teams to logins" 매핑에 있는 모든 조직에 대한 접근 권한을 애플리케이션에 부여해야 합니다. 그렇지 않으면 Teleport가 이러한 조직의 팀 멤버십을 확인할 수 없습니다.

사용자가 인증한 후 Teleport는 해당 Teleport 세션의 internal.logins 속성에 사용자의 GitHub 사용자 이름을 추가합니다. 사전 설정 access 역할에는 GitHub 사용자를 승인된 SSH 로그인으로 포함하도록 이 속성 변수가 구성되어 있습니다. 다음은 속성 변수를 사용하는 역할 구성 예제입니다:

  allow:
    # 허용된 SSH 로그인 목록
    logins: ['{{internal.logins}}', ubuntu, debian]

    # 사용자가 SSH로 접근할 수 있는 노드 레이블
    node_labels:
      '*': '*'

이제 GitHub SSO를 사용하여 Teleport에 로그인할 수 있습니다. GitHub SSO를 사용하여 tsh에서 로그아웃하고 다시 로그인하려면 다음을 실행하세요.

$ tsh logout
# Logged out all users from all proxies.
$ tsh login --proxy=tele.example.com --auth=github
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:56334/6bf976e6-a4be-4898-94eb-8a7b01af2158

$ tsh logout
# Logged out all users from all proxies.
$ tsh login --proxy=mytenant.teleport.sh --auth=github
If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:56334/6bf976e6-a4be-4898-94eb-8a7b01af2158

로그인 화면에서 Other sign-in options를 클릭하여 GitHub을 통해 웹 UI에도 로그인할 수 있습니다.

처음 로그인하면 GitHub OAuth 앱에 권한을 부여하라는 프롬프트가 표시됩니다:

GitHub SSO 인증 화면

Teleport는 read:org OAuth 범위만 요청합니다. GitHub의 문서에서 OAuth 범위에 대해 자세히 알아보세요: GitHub OAuth scopes

로그인 후 "Login Successful" 창이 표시되고 닫을 수 있습니다.

CLI에서 사용자 세션의 세부 정보를 받게 됩니다:

> Profile URL:        https://tele.example.com:443
  Logged in as:       jeff
  Cluster:            tele.example.com
  Roles:              access
  Logins:             jeff, ubuntu, debian
  Kubernetes:         enabled
  Kubernetes users:   dev
  Kubernetes groups:  developer
  Valid until:        2023-03-08 17:13:50 -0600 CST [valid for 7h51m0s]
  Extensions:         permit-port-forwarding, permit-pty, private-key-policy

> Profile URL:        https://tele.example.com:443
  Logged in as:       jeff
  Cluster:            tele.example.com
  Roles:              access, requester
  Logins:             jeff, ubuntu, debian
  Kubernetes:         enabled
  Kubernetes users:   dev
  Kubernetes groups:  developer
  Valid until:        2023-03-08 17:13:50 -0600 CST [valid for 7h51m0s]
  Extensions:         permit-port-forwarding, permit-pty, private-key-policy

> Profile URL:        https://mytenant.teleport.sh:443
  Logged in as:       jeff
  Cluster:            mytenant.teleport.sh
  Roles:              access, requester
  Logins:             jeff, ubuntu, debian
  Kubernetes:         enabled
  Kubernetes users:   dev
  Kubernetes groups:  developer
  Valid until:        2023-03-08 17:13:50 -0600 CST [valid for 7h51m0s]
  Extensions:         permit-port-forwarding, permit-pty, private-key-policy

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

이전 단계에서는 GitHub을 인증 유형으로 지정하여 GitHub 자격 증명으로 Teleport에 로그인했습니다. cluster_auth_preference 리소스를 편집하여 기본 인증 유형으로 만들 수 있습니다.

tctl을 사용하여 기존 cluster_auth_preference 리소스를 편집합니다:

$ tctl edit cap

기본 편집기에서 cluster_auth_preference 정의가 담긴 임시 파일이 열립니다.

cap.yaml에 다음 내용이 포함되어 있는지 확인합니다:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  type: github
  webauthn:
    rp_id: 'example.teleport.sh'
version: v2

rp_id에는 Teleport Proxy Service의 공개 주소 또는 Teleport Cloud 워크스페이스를 사용하세요.

임시 파일을 저장하고 닫으면 tctl이 리소스를 업데이트합니다:

#cluster auth preference has been updated
정적 구성 파일

다음을 포함하도록 Teleport 구성 파일을 편집할 수도 있습니다:

# /etc/teleport.yaml에서 발췌
auth_service:
  authentication:
    type: github

tsh에서 로그아웃한 후 --auth=github를 지정하지 않고 다시 로그인할 수 있습니다. 자동으로 GitHub 인증 플로우로 리다이렉트됩니다.

다음 단계#

Now that you have connected Teleport to your identity provider, you can customize the way Teleport includes IdP data in Teleport roles.

With role templates, you can include user data from your IdP directly in Teleport roles. If you use the external template variable in the value of a role field, Teleport passes that value from your IdP. In this example, all of the role options you can use for allowing users to assume certain principals on remote systems come from your 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}}']

For more information on using the external template variable, see Role Templates.

For an explanation of the fields listed above, see the Role Reference.

If you need to transform your IdP user data before you include it in Teleport roles, you can do so using Login Rules. Login Rules allow you to include external traits within Teleport roles even if your IdP provides user data in a different format than the one expected by Teleport. Read more about Login Rules.

문제 해결#

Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to:

  • Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport.
  • Be able to see how Teleport maps the received claims to role mappings as defined in the connector.
  • For self-hosted Teleport Enterprise clusters, ensure that HTTP/TLS certificates are configured properly for both the Teleport Proxy Service and the SSO provider.

If something is not working, we recommend to:

  • Double-check the host names, tokens and TCP ports in a connector definition.

Using the Web UI#

If you get "access denied" or other login errors, the number one place to check is the Audit Log. To view the recording, select Audit in the Teleport Web UI, then click Session Recordings in the menu.

Audit Log Entry for SSO Login error

Example of a user being denied because the role clusteradmin wasn't set up:

{
  "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 does not show the expected Nodes#

(!docs/pages/includes/node-logins.mdx!)

When configuring SSO, ensure that the identity provider is populating each user's traits correctly. For a user to see a Node in Teleport, the result of populating a template variable in a role's allow.logins must match at least one of a user's traits.logins.

In this example a user will have usernames ubuntu, debian and usernames from the SSO trait logins for Nodes that have a env: dev label. If the SSO trait username is bob then the usernames would include ubuntu, debian, and bob.

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

Single sign-on fails with OIDC#

When encountering the error message "Failed to verify JWT: oidc: unable to verify JWT signature: no matching keys", it typically indicates a discrepancy between the algorithm used to sign the JWT token and the algorithm(s) supported by the JSON Web Key Set (JWKS). Specifically, the token might be signed with one algorithm, e.g., HS256, while the JWKS only lists keys for a different algorithm. e.g., RS256. This issue predominantly arises when using identity providers that offer extremely low-level functionality.

Here are some things to check:

  • Verify the JWT header specifies the correct signing algorithm. This should match one of the algorithms listed in the keys section of the JWKS endpoint response.
  • Ensure the JWKS endpoint is returning all relevant public keys. Sometimes key rotation can cause valid keys to be omitted.

To resolve the issue, align the JWT algorithm header with a supported algorithm in the JWKS. Rotate keys if necessary. Verify the JWKS only publishes the active public keys. With proper configuration, the signature should validate successfully.

팀이 역할에 매핑되지 않는 경우#

팀이 예상대로 역할에 매핑되지 않는 경우 커넥터에서 조직과 팀의 슬러그를 사용하고 있는지 확인하세요. 슬러그를 만들기 위해 GitHub은 이름 문자열의 특수 문자를 대체하고, 모든 단어를 소문자로 변경하고, 공백을 - 구분자로 교체합니다. 예를 들어 "My TEam Näme"은 my-team-name이 됩니다. GitHub 웹 애플리케이션 URL과 GitHub API를 통해 슬러그를 확인할 수 있습니다.

예: GitHub 웹 애플리케이션에서 팀 My Team으로 이동합니다. URL https://github.com/orgs/org-name/teams/my-team은 슬러그가 my-team임을 보여줍니다. teams to roles 매핑을 업데이트합니다.

  teams_to_roles:
    - organization: my-org
      roles:
        - access
        - editor
        - reviewer
      team: my-team