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

이 가이드는 특정 사용자 그룹에 자격 증명을 발급하도록 GitLab을 구성하는 방법을 설명합니다. 역할 기반 액세스 제어(RBAC)와 함께 사용하면 관리자는 다음과 같은 정책을 정의할 수 있습니다:

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

전제 조건

  • 태그가 있는 최소 두 개의 GitLab 그룹이 있어야 합니다. 아래 예시에서는 company 라는 그룹과 두 개의 하위 그룹 admindev 를 가정합니다.
  • oidc 리소스를 유지 관리할 수 있는 액세스를 가진 Teleport 역할. 이는 기본 editor 역할에서 사용 가능합니다.
  • 실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하여 무료 평가판을 이용해 보십시오.

  • tctl 관리자 도구 및 tsh 클라이언트 도구.

    tctltsh 다운로드에 대한 지침은 설치 를 방문하십시오.

  • 연결이 가능한지 확인하기 위해 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 명령어를 실행할 수도 있습니다.

GitLab 구성

Teleport 역할에 매핑할 GitLab에 최소 하나의 그룹을 구성해야 합니다. 이 예에서는 gitlab-devgitlab-admin 이라는 이름을 사용합니다. 이 그룹에 사용자들을 할당합니다.

  1. GitLab의 한 그룹에 애플리케이션을 생성합니다 (그룹 개요 -> 설정 -> 애플리케이션) 분류할 수 있도록 OIDC 제공자로 Teleport를 사용할 수 있게 합니다.

    설정:

    • 리디렉션 URL: https://<proxy url>/v1/webapi/oidc/callback .
    • Confidential , openid , profile , 및 email 을 체크합니다.
  2. 애플리케이션에서 Application IDSecret 을 수집합니다. 이는 Teleport OIDC 인증 커넥터에서 사용됩니다:

  3. 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 의 두 하위 그룹 admindev 를 Teleport의 admindev 역할로 매핑하고 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.yaml
tctl 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 규칙을 포함합니다.

예상치 못하게 노드가 보이지 않는 경우, 사용자의 역할에 적절한 allowdeny 규칙이 포함되어 있는지 확인하십시오. 이는 Teleport Access Controls Reference에서 문서화되어 있습니다.

SSO를 구성할 때, ID 공급자가 각 사용자의 특성을 올바르게 인구시키고 있는지 확인하십시오. 사용자가 Teleport에서 노드를 보기 위해서는 역할의 allow.logins 에 있는 템플릿 변수의 결과가 사용자의 traits.logins 중 하나와 일치해야 합니다.

이 예에서 사용자는 env: dev 레이블이 있는 노드에 대해 ubuntu , debian 및 SSO 특성의 사용자 이름 logins 를 가집니다. SSO 특성 사용자 이름이 bob 인 경우 사용자 이름에는 ubuntu , debianbob 이 포함됩니다.

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 원문 보기