GitHub를 통한 싱글 사인 온 설정 | Teleport 공식 기술 문서 한국판 by 인포그랩

GitHub를 통한 싱글 사인 온 설정

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

전제 조건

최소한 하나의 팀이 있는 GitHub 조직.

Teleport Community Edition에서는 이 조직에 외부 SSO가 설정되어 있지 않아야 하며, 그렇지 않으면 Teleport가 GitHub 인증 커넥터를 생성할 수 없습니다.

Teleport Enterprise 및 Enterprise Cloud에서는 조직을 GitHub Cloud 또는 GitHub Enterprise Server에서 호스팅할 수 있습니다.
tctl 을 사용하기 위해 github 리소스를 유지 관리할 수 있는 Teleport 역할. 이것은 기본 editor 역할에서 사용할 수 있습니다.

실행 중인 Teleport 클러스터 버전 17.0.0-dev 이상. 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/4 단계. GitHub OAuth 앱 생성

GitHub OAuth 앱을 생성하고 등록합니다. 이때 OAuth 앱의 "인증 콜백 URL"이 다음과 같도록 합니다:

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

PROXY_ADDRESS 를 Teleport Proxy Service의 공용 주소 또는 Teleport Cloud 작업 공간 URL(예: example.teleport.sh )로 교체합니다.

앱은 조직 및 팀 구성원 세부 정보를 읽을 수 있도록 read:org 범위를 가져야 합니다.

GitHub OAuth 앱 생성 지침은 GitHub 문서에서 확인할 수 있습니다.

다음 단계에서 사용할 클라이언트 ID와 함께 사용할 클라이언트 비밀을 생성합니다:

2/4 단계. GitHub 인증 커넥터 생성

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

작업 공간에서 client-secret.txt 라는 파일을 생성하여 클라이언트 비밀만 포함시킵니다.

다음 예시 명령을 다음으로 업데이트합니다:

이전 단계에서 생성한 OAuth 앱의 클라이언트 ID 및 클라이언트 비밀.
GitHub 조직에서 Teleport 역할로 매핑할 역할. 역할은 조직 설정의 저장소 역할 섹션에서 정의됩니다.

다음에서 이 명령에 대한 전체 플래그 참조를 확인하십시오: tctl sso configure github

tctl sso configure github \--id=GITHUB-CLIENT-ID \--secret=$(cat client-secret.txt) \--teams-to-roles=ORG-NAME,github-team,access,editor \> github.yaml

Tip

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.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=GITHUB-CLIENT-ID \--secret=$(cat client-secret.txt) \--teams-to-roles=ORG-NAME,github-team,access,editor \--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 서버의 경우, --endpoint-url , --api-endpoint-url 매개변수를 사용하여 서버 인스턴스 엔드포인트를 지정할 수 있습니다:

tctl sso configure github \--id=GITHUB-CLIENT-ID \--secret=$(cat client-secret.txt) \--teams-to-roles=ORG-NAME,github-team,access,editor \--endpoint-url=https://github-enterprise-server-address
--api-endpoint-url=https://api-github-enterprise-server-address> 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
브라우저 창이 자동으로 열리지 않으면 다음 링크를 클릭하여 열 수 있습니다: http://127.0.0.1:52690/35714f6b-...성공! 로그인한 사용자: alice--------------------------------------------------------------------------------인증 세부 사항:   역할:   - access   - editor   특성:     github_teams:     - admins     kubernetes_groups: null     kubernetes_users: null     logins:     - alice   사용자 이름: alice--------------------------------------------------------------------------------[GitHub] 받은 청구:organization_to_teams:  Octocats:  - admins팀:- admins사용자 이름: alice
--------------------------------------------------------------------------------[GitHub] 커넥터 팀 역할 매핑:- organization: Octocats  roles:  - access  - editor  team: admins
--------------------------------------------------------------------------------자세한 내용을 보려면 --debug 플래그를 사용하여 명령을 반복하십시오.

마지막으로 tctl 을 사용하여 커넥터를 생성합니다:

tctl create -f github.yaml
인증 커넥터 "github"가 생성되었습니다.

Tip

GitHub 인증 흐름을 처음 진행할 때, 애플리케이션은 "팀을 로그인을 매핑"에 존재하는 모든 조직에 대한 액세스를 부여받아야 하며, 그렇지 않으면 Teleport가 이러한 조직의 팀 멤버십을 확인할 수 없습니다.

사용자가 인증하면 Teleport는 사용자의 GitHub 사용자 이름을 Teleport 세션의 internal.logins 특성에 추가합니다. 예정된 access 역할은 이 특성 변수를 사용하여 GitHub 사용자를 승인된 SSH 로그인을 포함하도록 구성되어 있습니다. 다음은 특성 변수를 사용하는 역할 구성 스니펫의 예입니다:

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

  # 사용자가 SSH로 접속할 수 있는 노드 레이블 목록
  node_labels:
    "*": "*"

3/4단계. GitHub를 사용하여 Teleport에 로그인

이제 GitHub SSO를 사용하여 Teleport에 로그인할 수 있습니다. 다음 명령어를 실행하여 Teleport에서 로그아웃하고 GitHub SSO를 사용하여 다시 로그인합니다.

tsh logout
모든 프록시에서 모든 사용자 로그아웃
tsh login --proxy=tele.example.com --auth=github
브라우저 창이 자동으로 열리지 않으면 링크를 클릭하여 열어주세요: http://127.0.0.1:56334/6bf976e6-a4be-4898-94eb-8a7b01af2158

tsh logout
모든 프록시에서 모든 사용자 로그아웃
tsh login --proxy=mytenant.teleport.sh --auth=github
브라우저 창이 자동으로 열리지 않으면 링크를 클릭하여 열어주세요: http://127.0.0.1:56334/6bf976e6-a4be-4898-94eb-8a7b01af2158

로그인 화면에서 기타 로그인 옵션을 클릭하여 GitHub를 통해 웹 UI에 로그인할 수도 있습니다.

처음 로그인하면 GitHub OAuth 앱을 승인하라는 메시지가 표시됩니다:

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

로그인에 성공하면 다음과 같은 화면이 표시됩니다:

CLI 내에서 사용자 세부 정보를 받을 수 있습니다:

> 프로필 URL:        https://tele.example.com:443  로그인 사용자:     jeff  클러스터:          tele.example.com  역할:              access  로그인:            jeff, ubuntu, debian  Kubernetes:        활성화됨  Kubernetes 사용자: dev  Kubernetes 그룹:   developer  유효 기간:        2023-03-08 17:13:50 -0600 CST [유효기간 7시간 51분 0초]  확장 프로그램:     permit-port-forwarding, permit-pty, private-key-policy

> 프로필 URL:        https://tele.example.com:443  로그인 사용자:     jeff  클러스터:          tele.example.com  역할:              access, requester  로그인:            jeff, ubuntu, debian  Kubernetes:        활성화됨  Kubernetes 사용자: dev  Kubernetes 그룹:   developer  유효 기간:        2023-03-08 17:13:50 -0600 CST [유효기간 7시간 51분 0초]  확장 프로그램:     permit-port-forwarding, permit-pty, private-key-policy

> 프로필 URL:        https://mytenant.teleport.sh:443  로그인 사용자:     jeff  클러스터:          mytenant.teleport.sh  역할:              access, requester  로그인:            jeff, ubuntu, debian  Kubernetes:        활성화됨  Kubernetes 사용자: dev  Kubernetes 그룹:   developer  유효 기간:        2023-03-08 17:13:50 -0600 CST [유효기간 7시간 51분 0초]  확장 프로그램:     permit-port-forwarding, permit-pty, private-key-policy

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

이전 단계에서는 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 이 리소스를 업데이트합니다:

클러스터 인증 기본 설정이 업데이트되었습니다

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

# /etc/teleport.yaml의 일부
auth_service:
  authentication:
    type: github

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

문제 해결

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가 활성 공개 키만 게시하는지 확인하십시오. 올바른 구성이 이루어지면 서명이 성공적으로 검증되어야 합니다.

팀이 역할에 매핑되지 않음

팀이 예상대로 역할에 매핑되지 않는 경우, 커넥터에서 조직 및 팀의 슬러그를 사용하고 있는지 확인하십시오. 슬러그를 생성하기 위해 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:
  - organization: my-org
    roles:
      - access
      - editor
      - reviewer
    team: my-team

다음 단계

이 가이드에서 설명한 역할은 internal.logins 특성을 사용하며, Teleport는 Teleport 로컬 사용자 데이터베이스의 값으로 이를 대체합니다. Teleport 역할에서 특성이 작동하는 방식에 대한 전체 세부정보는 Teleport 접근 제어 참고를 참조하십시오.

Teleport 원문 보기