GitLab을 OAuth 2.0 인증 ID 제공자로 구성하기

OAuth 2.0은 리소스 소유자를 대신하여 클라이언트 애플리케이션이 안전하게 위임된 서버 리소스 액세스를 제공합니다. OAuth 2는 인가 서버가 리소스 소유자 또는 최종 사용자의 승인으로 서드 파티 클라이언트에게 액세스 토큰을 발급할 수 있도록 합니다.

다음 유형의 OAuth 2 애플리케이션을 인스턴스에 추가하여 GitLab을 OAuth 2 인증 ID 제공자로 사용할 수 있습니다.

이러한 방법은 권한 수준에 따라 다릅니다. 기본 콜백 URL은 SSL URL https://your-gitlab.example.com/users/auth/gitlab/callback입니다. 대신 SSL URL을 사용할 수 있지만 SSL URL을 사용해야 합니다.

인스턴스에 OAuth 2 애플리케이션을 추가한 후 OAuth 2를 사용하여 다음을 수행할 수 있습니다.

  • 사용자가 GitLab.com 계정으로 애플리케이션에 로그인할 수 있도록 합니다.

  • 자세한 내용은 서버를 GitLab.com에 통합을 참조하세요.

  • 애플리케이션이 생성된 후 외부 서비스는 OAuth 2 API를 사용하여 액세스 토큰을 관리할 수 있습니다.

사용자 소유 애플리케이션 생성하기

사용자용 애플리케이션을 만들려면 다음을 수행하세요.

  1. 왼쪽 사이드바에서 아바타를 선택합니다.
  2. 프로필 편집을 선택합니다.
  3. 왼쪽 사이드바에서 애플리케이션을 선택합니다.
  4. 새 애플리케이션 추가를 선택합니다.
  5. 이름 및 리디렉션 URI를 입력합니다.
  6. Authorized Applications에 정의된 OAuth 2 범위를 선택합니다.
  7. 리디렉션 URI에는 사용자가 GitLab을 통해 승인한 후 전송되는 URL을 입력합니다.

  8. 애플리케이션 저장을 선택합니다. GitLab에서는 다음을 제공합니다.

    • 애플리케이션 ID에서 OAuth 2 클라이언트 ID 제공
    • GitLab 14.1 및 이전 버전: 비밀 필드에서 OAuth 2 클라이언트 비밀번호 제공
    • GitLab 14.2 및 이후 버전: 비밀 필드에서 복사를 선택하여 OAuth 2 클라이언트 비밀번호 제공
    • GitLab 15.9 이후 버전: 새 비밀 생성 기능을 사용하여 해당 응용 프로그램에 대한 새 비밀을 생성하고 복사합니다. 기존 애플리케이션이 기능하지 않도록 새로운 비밀을 생성하여 업데이트된 자격 증명을 사용합니다.

그룹 소유 애플리케이션 생성하기

그룹용 새 애플리케이션을 만들려면 다음을 수행하세요.

  1. 원하는 그룹으로 이동합니다.
  2. 왼쪽 사이드바에서 설정 > 애플리케이션을 선택합니다.
  3. 이름 및 리디렉션 URI을 입력합니다.
  4. Authorized Applications에 정의된 OAuth 2 범위를 선택합니다.
  5. 리디렉션 URI에는 사용자가 GitLab을 통해 승인한 후 전송되는 URL을 입력합니다.

  6. 애플리케이션 저장을 선택합니다. GitLab에서는 다음을 제공합니다.

    • 애플리케이션 ID에서 OAuth 2 클라이언트 ID 제공
    • GitLab 14.1 및 이전 버전: 비밀 필드에서 OAuth 2 클라이언트 비밀번호 제공
    • GitLab 14.2 및 이후 버전: 비밀 필드에서 복사를 선택하여 OAuth 2 클라이언트 비밀번호 제공
    • GitLab 15.9 이후 버전: 새 비밀 생성 기능을 사용하여 해당 응용 프로그램에 대한 새 비밀을 생성하고 복사합니다. 기존 애플리케이션이 기능하지 않도록 새로운 비밀을 생성하여 업데이트된 자격 증명을 사용합니다.

인스턴스 전역 애플리케이션 생성하기

Tier: Free, Premium, Ultimate Offering: Self-Managed

GitLab 인스턴스용 애플리케이션을 만들려면 다음을 수행하세요.

  1. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리 영역을 선택합니다.
  2. 애플리케이션을 선택합니다.
  3. 새 애플리케이션을 선택합니다.

관리 영역에서 애플리케이션을 만들 때 신뢰할 수 있는으로 표시합니다. 이 경우 사용자 승인 단계는 자동으로 건너뜁니다.

모든 인가된 애플리케이션 보기

  • k8s_proxy은 GitLab 16.4에 플래그명을 지정하여 도입되었으며 기본적으로 활성화됩니다.
  • 기능 플래그 k8s_proxy_pat은 GitLab 16.5에서 제거되었습니다.

GitLab 자격 증명으로 인가된 모든 애플리케이션을 확인하려면 다음을 수행하세요.

  1. 왼쪽 사이드바에서 아바타를 선택합니다.
  2. 프로필 편집을 선택한 다음 애플리케이션을 선택합니다.
  3. 인가된 애플리케이션 섹션을 확인합니다.

GitLab OAuth 2 애플리케이션은 애플리케이션이 여러 작업을 수행할 수 있게 하는 범위를 지원합니다. 모든 사용 가능한 범위에 대한 자세한 내용은 다음 표를 참조하세요.

범위 설명
api 그룹 및 프로젝트, 컨테이너 레지스트리, 의존성 프록시 및 패키지 레지스트리를 포함한 API에 대한 완전한 읽기/쓰기 액세스를 부여합니다.
read_user 인증된 사용자의 프로필에 대한 읽기 전용 액세스를 제공합니다. 이는 사용자 이름, 공개 이메일 및 전체 이름을 포함하며 /users 하위의 읽기 전용 API 엔드포인트에 대한 액세스도 부여합니다.
read_api 그룹 및 프로젝트, 컨테이너 레지스트리 및 패키지 레지스트리를 포함한 API에 대한 읽기 액세스를 부여합니다.
read_repository Git-over-HTTP 또는 리파지토리 파일 API를 사용하여 비공개 프로젝트의 저장소에 대한 읽기 전용 액세스를 부여합니다.
write_repository Git-over-HTTP를 사용하여 비공개 프로젝트의 저장소에 대한 읽기/쓰기 액세스를 부여합니다(API를 사용하지 않음).
read_registry 비공개 프로젝트의 컨테이너 레지스트리 이미지에 대한 읽기 전용 액세스를 부여합니다.
write_registry 비공개 프로젝트의 컨테이너 레지스트리 이미지에 대한 읽기/쓰기 액세스를 부여합니다.
sudo 관리자 사용자로 인증되었을 때 시스템에서 모든 사용자의 API 작업을 수행할 수 있는 권한을 부여합니다.
openid OpenID Connect를 사용하여 GitLab에서 인증하고 읽기 전용으로 사용자 프로필 및 그룹 멤버십에 액세스할 수 있도록 권한을 부여합니다.
profile OpenID Connect를 사용하여 사용자 프로필 데이터에 대한 읽기 전용 액세스를 부여합니다.
email OpenID Connect를 사용하여 사용자의 기본 이메일 주소에 대한 읽기 전용 액세스를 부여합니다.
create_runner 러너를 만들 수 있는 권한을 부여합니다.
k8s_proxy 쿠버네티스에이전트를 사용하여 Kubernetes API 호출을 수행할 수 있는 권한을 부여합니다.

언제든지 취소를 선택하여 모든 액세스를 취소할 수 있습니다.

액세스 토큰 만료

  • 소개: GitLab 14.3에 도입되었으며, 사용자가 선택하는 기능이 포함되어 있습니다.
  • 액세스 토큰 만료를 선택하지 않는 기능이 GitLab 15.0에서 제거되었습니다.
  • expires_in에 대한 데이터베이스 유효성 검사가 GitLab 15.10에 도입되었습니다. GitLab 인스턴스가 15.10 이상으로 업그레이드될 때 expires_in가 설정되지 않은 OAuth 액세스 토큰이 남아 있는 경우 데이터베이스 마이그레이션이 오류를 발생시킵니다. 해결 방법은 GitLab 15.10.0 업그레이드 문서를 참조하세요.

경고: 액세스 토큰 만료를 선택하지 않는 기능이 GitLab 14.3에서 폐기되었으며, 15.0에서는 제거되었습니다. 모든 기존 통합은 액세스 토큰 갱신을 지원하도록 업데이트해야 합니다.

액세스 토큰은 2시간 후에 만료됩니다. 액세스 토큰을 사용하는 통합은 refresh_token 속성을 사용하여 새로 생성해야 합니다. 만료된 액세스 토큰이라도 refresh_token을 사용할 수 있습니다. 만료된 액세스 토큰을 새로 고칠 방법에 대한 자세한 정보는 OAuth 2.0 토큰 문서를 참조하세요.

이 만료 설정은 GitLab 코드베이스에서 Doorkeeper에서 제공하는 access_token_expires_in 구성을 사용하여 설정됩니다. 유효 기간 설정은 구성할 수 없습니다.

애플리케이션이 삭제되면 해당 애플리케이션과 관련된 그랜트 및 토큰도 삭제됩니다.

해시화된 OAuth 애플리케이션 비밀

플래그: self-managed GitLab의 경우, 기본적으로 이 기능이 사용 가능합니다. 플래그를 숨기려면 관리자가 hash_oauth_secrets라는 플래그를 비활성화할 수 있습니다. GitLab.com의 경우, 이 기능을 사용할 수 있습니다.

기본적으로 GitLab은 데이터베이스에 OAuth 애플리케이션 비밀을 해시화된 형식으로 저장합니다. 이러한 비밀은 OAuth 애플리케이션을 만든 직후에 사용자에게만 사용할 수 있습니다. 이전 버전의 GitLab에서는 애플리케이션 비밀이 데이터베이스에 일반 텍스트로 저장되었습니다.

GitLab에서 OAuth 2를 사용하는 다른 방법

다음을 수행할 수 있습니다:

  • Applications API를 사용하여 OAuth 2 애플리케이션을 만들고 관리합니다.
  • 사용자가 타사 OAuth 2 제공업체를 사용하여 GitLab에 로그인할 수 있도록 합니다. 자세한 내용은 OmniAuth 문서를 참조하세요.
  • GitLab Importer를 사용하여 OAuth 2를 사용하여 사용자 자격 증명을 GitLab.com 계정에 공유하지 않고 저장소에 액세스할 수 있습니다.