인포레터에서 최신 DevOps 트렌드를 격주로 만나보세요!
GitLab을 SSO 제공자로 사용하는 인증
이 가이드는 특정 사용자 그룹에 자격 증명을 발급하도록 GitLab을 구성하는 방법을 설명합니다. 역할 기반 액세스 제어(RBAC)와 함께 사용하면 관리자는 다음과 같은 정책을 정의할 수 있습니다:
- "DBA" 그룹의 구성원만 PostgreSQL 데이터베이스에 액세스할 수 있습니다.
- "ProductionKubernetes"의 구성원만 프로덕션 Kubernetes 클러스터에 액세스할 수 있습니다.
- 개발자는 프로덕션 서버에 SSH로 접속해서는 안 됩니다.
전제 조건
- 태그가 있는 최소 두 개의 GitLab 그룹이 있어야 합니다. 아래 예시에서는
company
라는 그룹과 두 개의 하위 그룹admin
및dev
를 가정합니다. oidc
리소스를 유지 관리할 수 있는 액세스를 가진 Teleport 역할. 이는 기본editor
역할에서 사용 가능합니다.
-
실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하여 무료 평가판을 이용해 보십시오.
-
tctl
관리자 도구 및tsh
클라이언트 도구.tctl
및tsh
다운로드에 대한 지침은 설치 를 방문하십시오.
- 연결이 가능한지 확인하기 위해
tsh login
으로 로그인한 다음, 현재 자격 증명을 사용하여tctl
명령어를 실행할 수 있는지 확인하십시오. 예를 들어:클러스터에 연결할 수 있고tsh login --proxy=teleport.example.com --user=email@example.comtctl status클러스터 teleport.example.com
버전 17.0.0-dev
CA 핀 sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 후속tctl
명령어를 실행할 수 있습니다.
자신의 Teleport 클러스터를 호스팅하는 경우, Teleport Auth Service를 호스팅하는 컴퓨터에서 전체 권한으로tctl
명령어를 실행할 수도 있습니다.
GitLab 구성
Teleport 역할에 매핑할 GitLab에 최소 하나의 그룹을 구성해야 합니다. 이 예에서는 gitlab-dev
와 gitlab-admin
이라는 이름을 사용합니다. 이 그룹에 사용자들을 할당합니다.
-
GitLab의 한 그룹에 애플리케이션을 생성합니다 (그룹 개요 -> 설정 -> 애플리케이션) 분류할 수 있도록 OIDC 제공자로 Teleport를 사용할 수 있게 합니다.
설정:
- 리디렉션 URL:
https://<proxy url>/v1/webapi/oidc/callback
. Confidential
,openid
,profile
, 및email
을 체크합니다.
- 리디렉션 URL:
-
애플리케이션에서
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 역할 생성
우리는 루트로 로그인할 수 있고 클러스터를 관리할 수 있는 특권 역할인 admin과 비특권 역할인 dev의 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 액세스 제어 참조를 참조하십시오.- 개발자는 "허용 규칙"이 없으므로 과거 세션을 보고 복원하거나 Teleport 클러스터를 재구성할 수 없습니다.
인증 서버에서 두 역할을 생성합니다:
tctl create -f admin.yamltctl create -f dev.yaml
기본 OIDC 인증 활성화
Teleport를 로컬 사용자 데이터베이스 대신 OIDC 인증을 기본값으로 사용하도록 구성합니다.
cluster_auth_preference
리소스를 편집합니다:
tctl edit cap
편집기에서 파일에 다음 내용이 포함되어 있는지 확인합니다:
kind: cluster_auth_preference
metadata:
name: cluster-auth-preference
spec:
type: oidc
version: v2
웹 UI에는 "GitLab로 로그인"이라는 새로운 버튼이 추가됩니다. CLI는 이전과 동일합니다:
tsh --proxy=teleport.example.com login
이 명령은 SSO 로그인 URL을 출력하고 자동으로 브라우저에서 열 수 있도록 시도합니다.
팁
Teleport는 여러 OIDC/SAML 커넥터를 사용할 수 있습니다. 이 경우 커넥터 이름은
tsh login --auth=connector_name
를 통해 전달될 수 있습니다.
중요
Teleport는 OIDC Connect에 대해 수신자 주도 흐름을 전송하는 것만 지원합니다. 이는 신원 공급자에서 로그인 initiating할 수 없으며, 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",
"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가 활성 공개 키만 게시하는지 확인하십시오. 올바른 구성이 이루어지면 서명이 성공적으로 검증되어야 합니다.