GitLab을 SSO 제공자로 사용하는 인증

이 가이드는 GitLab을 사용하여 특정 사용자 그룹에 자격 증명을 발급하는 방법을 다룹니다. 역할 기반 접근 제어(RBAC)와 결합할 경우, 관리자는 다음과 같은 정책을 정의할 수 있습니다:

"DBA" 그룹의 구성원만 PostgreSQL 데이터베이스에 접근할 수 있습니다.
"ProductionKubernetes"의 구성원만 프로덕션 Kubernetes 클러스터에 접근할 수 있습니다.
개발자는 프로덕션 서버에 SSH로 접근할 수 없습니다.

전제 조건

사용자에게 할당된 최소 두 개의 GitLab 그룹이 필요합니다. 아래 예시에서는, company라는 그룹과 두 개의 하위 그룹, admin 및 dev가 있다고 가정합니다.
oidc 자원 유지 관리에 접근할 수 있는 Teleport 역할이 필요합니다. 이는 기본 editor 역할에서 사용할 수 있습니다.

실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하기 무료 체험판을 이용해 보세요.
tctl 관리 도구 및 tsh 클라이언트 도구 버전 >= 16.2.0.

tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하세요.

당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  16.2.0
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다. 자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

GitLab 구성

Teleport 역할에 매핑할 수 있는 최소한 하나의 그룹이 GitLab에 설정되어 있어야 합니다. 이 예에서는 gitlab-dev와 gitlab-admin이라는 이름을 사용합니다. 각 그룹에 사용자 를 할당합니다.

GitLab을 OAuth 제공자로 사용하여 Teleport에 연결할 수 있도록(그룹 개요 -> 설정 -> 애플리케이션) 그룹 중 하나에 애플리케이션을 생성합니다.

설정:
- 리디렉션 URL: https://<proxy url>/v1/webapi/oidc/callback.
- Confidential, openid, profile, 및 email을 선택합니다.
애플리케이션에서 Application ID와 Secret를 수집합니다. 이러한 값은 Teleport OIDC 인증 커넥터에서 사용됩니다:
GitLab 발급자 주소를 확인합니다.

GitLab.com의 경우 발급자 주소는 https://gitlab.com입니다. 이는 Teleport가 https://gitlab.com/.well-known/openid-configuration에서 Open-ID 구성을 접근할 수 있도록 합니다. 자체 호스팅하는 경우 발급자 주소는 GitLab 인스턴스의 경로입니다.

Teleport 구성

OIDC 커넥터 생성

tctl을 사용하여 OIDC 커넥터 리소스를 생성합니다.

작업 공간에서 client-secret.txt라는 파일을 생성하고, 그 안에 클라이언트 시크릿만 포함시킵니다.

GitLab에서 가져온 값으로 애플리케이션 ID와 비밀을 교체합니다:

tctl sso configure oidc --preset gitlab \--id <APPLICATION-ID> \--secret $( cat client-secret.txt) \--claims-to-roles groups,company/admin,admin \--claims-to-roles groups,company/dev,dev > oidc.yaml

GitLab에서 가져온 값으로 애플리케이션 ID와 비밀을 교체하고, https://gitlab.company.com을 자체 호스팅 GitLab 인스턴스의 경로로 교체합니다:

tctl sso configure oidc --preset gitlab \--id <APPLICATION-ID> \--issuer-url https://gitlab.company.com \--secret $( cat client-secret.txt) \--claims-to-roles groups,company/admin,admin \--claims-to-roles groups,company/dev,dev > oidc.yaml

이 예시는 부모 그룹 company의 두 하위 그룹 admin과 dev를 Teleport의 admin 및 dev 역할에 매핑하고, oidc.yaml 파일을 생성합니다:

kind: oidc
metadata:
  name: gitlab
spec:
  claims_to_roles:
  - claim: groups
    roles:
    - admin
    value: company/admin
  - claim: groups
    roles:
    - dev
    value: company/gitlab-dev
  client_id: <APPLICATION-ID>
  client_secret: <APPLICATION-SECRET>
  display: GitLab
  issuer_url: https://gitlab.com
  prompt: none
  redirect_url: https://teleport.example.com:443/v1/webapi/oidc/callback
version: v3

커넥터 리소스를 테스트하려면 파일을 tctl sso test로 파이프하여 실행합니다:

cat oidc.yaml | tctl sso test

GitLab에서 애플리케이션의 승인을 받은 후, 웹 브라우저에 로그인 성공 메시지가 나타나야 합니다. 그렇지 않은 경우, 명령의 출력을 참고하여 문제를 진단합니다.

tctl 도구를 사용하여 커넥터를 생성합니다:

tctl create -f oidc.yaml

Teleport 역할 생성

관리자 권한이 있는 특권 역할과 비특권 개발자 역할 2개를 생성할 것입니다.

kind: role
version: v5
metadata:
  name: admin
spec:
  options:
    max_session_ttl: 24h
  allow:
    logins: [root]
    node_labels:
      "*": "*"
    rules:
      - resources: ["*"]
        verbs: ["*"]

개발자 역할:

kind: role
version: v5
metadata:
  name: dev
spec:
  options:
    max_session_ttl: 24h
  allow:
    logins: [ "{{email.local(external.email)}}", ubuntu ]
    node_labels:
      access: relaxed

개발자는 access: relaxed 레이블이 있는 노드에만 로그인할 수 있습니다.
개발자는 ubuntu 사용자로 로그인할 수 있습니다.
{{external.email}} 로그인을 주목하세요. 이는 Teleport가 "email" GitLab 클레임을 보고, 그 필드를 각 사용자에 대한 허용된 로그인으로 사용하도록 구성합니다. email.local(external.trait) 함수는 @domain을 제거하고 사용자 이름 접두사를 보존합니다. Teleport 역할에서 변수 확장이 어떻게 작동하는지에 대한 자세한 내용은 Teleport 접근 권한 제어 참조를 참조하세요.
개발자는 "허용 규칙"이 없기 때문에 과거 세션을 보고 재구성할 수 없습니다.

인증 서버에 두 역할을 생성합니다:

tctl create -f admin.yaml
tctl create -f dev.yaml

기본 OIDC 인증 활성화

OIDC 인증을 기본으로 사용하도록 Teleport를 구성하고 로컬 사용자 데이터베이스 대신 사용하십시오.

귀하의 Teleport 에디션에 대한 지침을 따르십시오:

/etc/teleport.yaml의 auth_service 섹션을 업데이트하고 teleport 데몬을 재시작하십시오.

auth_service:
  authentication:
    type: oidc

cap.yaml이라는 파일을 만드십시오:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:    
  type: oidc
version: v2

리소스를 생성하십시오:

tctl create -f cap.yaml

웹 UI에는 이제 "GitLab로 로그인"이라는 새로운 버튼이 추가됩니다. CLI는 이전과 동일합니다:

tsh --proxy=teleport.example.com login

이 명령은 SSO 로그인 URL을 출력하고(자동으로 브라우저에서 열려고 시도합니다).

팁

Teleport는 여러 OIDC/SAML 커넥터를 사용할 수 있습니다. 이 경우 커넥터 이름을 tsh login --auth=connector_name을 통해 전달할 수 있습니다.

중요

Teleport는 OIDC 연결을 위해 발신자 주도 흐름만 지원합니다. 이는 귀하의 신원 제공자로부터 로그인을 시작할 수 없음을 의미하며, Teleport 웹 UI 또는 CLI에서 로그인을 시작해야 합니다.

문제 해결

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",  
  "method": "oidc",  
  "success": false,  
  "time": "2019-06-15T19:38:07Z",  
  "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"  
}

Teleport가 예상하는 노드를 표시하지 않음

When Teleport의 인증 서비스가 Teleport 노드를 나열하라는 요청을 받으면 (예: 웹 UI에서 노드를 표시하거나 tsh ls를 통해), 현재 사용자가 볼 수 있는 권한이 있는 노드만 반환합니다.

사용자의 Teleport 클러스터에 있는 각 노드에 대해 인증 서비스는 다음 검사를 순서대로 적용하며, 하나의 검사가 실패하면 해당 노드를 사용자에게 숨깁니다:

사용자의 역할 중 어느 것도 노드의 레이블과 일치하는 deny 규칙을 포함하지 않아야 합니다.
사용자의 역할 중 적어도 하나는 노드의 레이블과 일치하는 allow 규칙을 포함해야 합니다.

예상할 때 노드를 볼 수 없다면, 사용자의 역할에 Teleport 접근 제어 참조에 문서화된 적절한 allow 및 deny 규칙이 포함되어 있는지 확인하세요.

SSO를 구성할 때, 각 사용자의 특성이 올바르게 채워지고 있는지 확인하십시오. 사용자가 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 원문 보기