• 지원되는 공급자
• 공통 설정 구성
  • 초기 설정 구성
  • 공급자별 구성
  • OmniAuth를 통해 생성된 사용자의 비밀번호
• 기존 사용자를 위한 OmniAuth 활성화
• 가져오기 소스 비활성화 여부에 관계없이 OmniAuth로 로그인을 활성화 또는 비활성화
• OmniAuth 비활성화
• 기존 사용자를 OmniAuth 사용자에 연결
• 외부 프로바이더 디렉터리 생성
• 사용자 정의 OmniAuth 프로바이더 사용
  • 사용자 정의 OmniAuth 프로바이더 예제
• OmniAuth 사용자 프로필 최신 상태 유지
• 이중 인증 코드 우회
• 프로바이더 자동으로 로그인
• 커스텀 OmniAuth 제공자 아이콘 사용
• 앱이나 구성 변경
• 알려진 문제

OmniAuth

사용자는 Google, GitHub 및 기타 인기있는 서비스의 자격 증명을 사용하여 GitLab에 로그인할 수 있습니다. OmniAuth는 GitLab이 이러한 인증을 제공하는 데 사용하는 Rack 프레임워크입니다.

구성된 경우, 추가 로그인 옵션이 로그인 페이지에 표시됩니다.

지원되는 공급자

GitLab은 다음 OmniAuth 공급자를 지원합니다.

공통 설정 구성

OmniAuth 공급자를 구성하기 전에, 모든 공급자에 대해 공통으로 설정해야 하는 설정을 구성하세요.

초기 설정 구성

OmniAuth 설정을 변경하려면:

이러한 설정을 구성한 후, 선택한 공급자를 구성할 수 있습니다.

공급자별 구성

• 소개: GitLab 15.3에서 소개됨.

allow_single_sign_on이 설정된 경우, GitLab은 사용자 계정을 먼저 만들지 않고 로그인하는 사용자를 위해 OmniAuth auth_hash에서 반환된 다음 필드 중 하나를 선택하여 사용자의 GitLab에 대한 사용자 이름을 설정합니다. 존재하는 첫 번째 필드를 선택합니다.

• username.
• nickname.
• email.

args를 사용하여 공급자에 제공되는 공급자별 GitLab 구성을 만들 수 있습니다. 공급자에 대한 args에서 gitlab_username_claim 변수를 설정하면 GitLab 사용자 이름을 위해 다른 클레임을 선택할 수 있습니다. 선택한 클레임은 충돌을 피하기 위해 고유해야 합니다.

gitlab_rails['omniauth_providers'] = [
  
  # 이름이 PROVIDER_NAME인 공급자를 구성하는 일반적인 패턴
  
  gitlab_rails['omniauth_providers'] = {
    name: "PROVIDER_NAME"
    ...
    args: { gitlab_username_claim: 'sub' } # 해당 공급자로 로그인하는 사용자의 경우, GitLab 사용자 이름은 공급자로부터 받은 "sub"로 설정됩니다
  },
  
  # GitHub와 Kerberos를 사용하는 예시
  
  gitlab_rails['omniauth_providers'] = {
    name: "github"
    ...
    args: { gitlab_username_claim: 'name' } # GitHub을 사용하여 로그인하는 사용자의 경우, GitLab 사용자 이름은 GitHub으로부터 받은 "name"으로 설정됩니다
  },
  {
    name: "kerberos"
    ...
    args: { gitlab_username_claim: 'uid' } # Kerberos를 사용하여 로그인하는 사용자의 경우, GitLab 사용자 이름은 Kerberos으로부터 받은 "uid"으로 설정됩니다
  },
]

- { name: 'PROVIDER_NAME',
  ...
  args: { gitlab_username_claim: 'sub' }
}
- { name: 'github',
  ...
  args: { gitlab_username_claim: 'name' }
}
- { name: 'kerberos',
  ...
  args: { gitlab_username_claim: 'uid' }
}

OmniAuth를 통해 생성된 사용자의 비밀번호

통합 인증 방법을 통해 생성된 사용자의 생성된 비밀번호 가이드는 GitLab이 OmniAuth로 생성된 사용자의 비밀번호를 생성하고 설정하는 방법에 대한 개요를 제공합니다.

기존 사용자를 위한 OmniAuth 활성화

기존 사용자인 경우 GitLab 계정 생성 후 OmniAuth 프로바이더를 활성화할 수 있습니다. 예를 들어, LDAP로 처음 로그인 한 경우 Google과 같은 OmniAuth 프로바이더를 활성화할 수 있습니다.

1. GitLab 계정으로 로그인하여 GitLab 자격 증명, LDAP 또는 다른 OmniAuth 프로바이더를 선택합니다.
2. 왼쪽 사이드바에서 아바타를 선택합니다.
3. 프로필 편집을 선택합니다.
4. 왼쪽 사이드바에서 계정을 선택합니다.
5. 연결된 계정 섹션에서 Google과 같은 OmniAuth 프로바이더를 선택합니다.
6. 프로바이더로 리디렉션됩니다. GitLab을 승인하면 GitLab로 리디렉션됩니다.

이제 선택한 OmniAuth 프로바이더를 사용하여 GitLab에 로그인할 수 있습니다.

가져오기 소스 비활성화 여부에 관계없이 OmniAuth로 로그인을 활성화 또는 비활성화

관리자는 일부 OmniAuth 프로바이더에 대해 로그인을 활성화하거나 비활성화할 수 있습니다.

OmniAuth 프로바이더를 활성화 또는 비활성화하려면:

1. 왼쪽 사이드바에서 아래로 스크롤하여 관리 영역을 선택합니다.
2. 설정 > 일반을 선택합니다.
3. 로그인 제한을 확장합니다.
4. 활성화된 OAuth 인증 소스 섹션에서 활성화 또는 비활성화하려는 각 프로바이더의 확인란을 선택하거나 해제합니다.

OmniAuth 비활성화

OmniAuth는 기본적으로 활성화되어 있습니다. 그러나 OmniAuth는 프로바이더가 구성되고 활성화되어 있을 때만 작동합니다.

OmniAuth 프로바이더가 개별적으로 비활성화되어도 문제를 일으킬 경우 구성 파일을 수정하여 전체 OmniAuth 서브시스템을 비활성화할 수 있습니다.

gitlab_rails['omniauth_enabled'] = false

omniauth:
  enabled: false

기존 사용자를 OmniAuth 사용자에 연결

이메일 주소가 일치하는 경우 OmniAuth 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다.

다음 예제는 OpenID Connect 프로바이더 및 Google OAuth 프로바이더에 대한 자동 연결을 활성화합니다.

gitlab_rails['omniauth_auto_link_user'] = ["openid_connect", "google_oauth2"]

omniauth:
  auto_link_user: ["openid_connect", "google_oauth2"]

이 자동 연결 방법은 [SAML을]와(https://gitlab.com/gitlab-org/gitlab/-/issues/338293)을 제외한 모든 프로바이더에 대해 작동합니다. SAML의 자동 연결을 활성화하려면 SAML 설정 지침을 참조하세요.

외부 프로바이더 디렉터리 생성

외부 OmniAuth 프로바이더 디렉터리을 정의할 수 있습니다. 디렉터리에 나열된 프로바이더를 통해 계정을 생성하거나 GitLab에 로그인한 사용자는 내부 프로젝트에 액세스할 수 없으며 외부 사용자로 표시됩니다.

외부 프로바이더 디렉터리을 정의하려면 프로바이더의 전체 이름을 사용합니다. 예를 들어 Google의 경우 google_oauth2입니다. 프로바이더 이름에 대한 정보는 supported providers table의 OmniAuth provider name 열을 참조하세요.

gitlab_rails['omniauth_external_providers'] = ['saml', 'google_oauth2']

omniauth:
  external_providers: ['saml', 'google_oauth2']

사용자 정의 OmniAuth 프로바이더 사용

GitLab과 함께 통합되지 않은 인증 솔루션과 통합해야 하는 경우, 사용자 정의 OmniAuth 프로바이더를 사용할 수 있습니다.

이 단계는 일반적인 단계입니다. 정확한 구현 세부 정보에 대해서는 OmniAuth 프로바이더의 설명서를 참조하세요.

1. GitLab을 중지합니다:

   sudo service gitlab stop
   

2. 새로운 OmniAuth 프로바이더 gem을 Gemfile에 추가합니다:

   gem "omniauth-your-auth-provider"
   

3. 새로운 OmniAuth 프로바이더 gem을 설치합니다:

   sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment
   

   이 명령어는 초기 설치 시 젬 설치 명령어와 동일하지만 --deployment 대신에 --path vendor/bundle --no-deployment을 사용합니다.

4. GitLab을 시작합니다:

   sudo service gitlab start
   

사용자 정의 OmniAuth 프로바이더 예제

이미 통합되지 않은 프로바이더를 성공적으로 설정한 경우 알려주세요.

모든 가능한 인증 메커니즘을 공식적으로 지원할 수는 없지만, 구체적인 요구 사항을 가진 사용자를 돕고 싶습니다.

OmniAuth 사용자 프로필 최신 상태 유지

선택한 OmniAuth 프로바이더에서 프로필 동기화를 활성화할 수 있습니다. 다음 사용자 속성의 조합을 동기화할 수 있습니다:

• 이름
• 이메일
• 위치

LDAP를 사용하여 인증하는 경우 사용자의 이름과 이메일이 항상 동기화됩니다.

gitlab_rails['omniauth_sync_profile_from_provider'] = ['saml', 'google_oauth2']
gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'location']

omniauth:
  sync_profile_from_provider: ['saml', 'google_oauth2']
  sync_profile_attributes: ['email', 'location']

이중 인증 코드 우회

특정 OmniAuth 프로바이더를 사용하는 경우 사용자는 이중 인증(2FA) 없이 로그인할 수 있습니다.

이중 인증을 우회하려면 두 가지 방법이 있습니다.

• 배열을 사용하여 허용된 프로바이더를 정의합니다(예: ['saml', 'google_oauth2']).
• 모든 프로바이더를 허용하려면 true를, 어떤 것도 허용하고 싶지 않다면 false를 지정합니다.

이 옵션은 이미 2FA를 가지고 있는 프로바이더에만 구성해야 합니다. 기본값은 false입니다.

이 설정은 SAML에 적용되지 않습니다.

gitlab_rails['omniauth_allow_bypass_two_factor'] = ['saml', 'google_oauth2']

omniauth:
  allow_bypass_two_factor: ['saml', 'google_oauth2']

프로바이더 자동으로 로그인

GitLab 구성에 auto_sign_in_with_provider 설정을 추가하여 로그인 요청을 OmniAuth 프로바이더로 리디렉션하여 인증할 수 있습니다. 이렇게 하면 로그인하기 전에 프로바이더를 선택하는 단계가 제거됩니다.

예를 들어, Azure v2 통합을 위해 자동 로그인을 활성화하려면:

gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'azure_activedirectory_v2'

omniauth:
  auto_sign_in_with_provider: azure_activedirectory_v2

기억해야 할 점은 모든 로그인 시도가 OmniAuth 프로바이더로 리디렉션되므로 로컬 자격 증명을 사용하여 로그인할 수 없습니다. 최소한 하나의 OmniAuth 사용자가 관리자인지 확인하세요.

또한 https://gitlab.example.com/users/sign_in?auto_sign_in=false로 이동하여 자동 로그인을 우회할 수 있습니다.

커스텀 OmniAuth 제공자 아이콘 사용

대부분의 지원되는 제공자에는 렌더링된 로그인 버튼을 위한 기본 아이콘이 포함되어 있습니다.

자체 아이콘을 사용하려면 이미지가 64 x 64 픽셀에서 렌더링되도록 최적화되었는지 확인한 후, 아이콘을 덮어쓸 수 있는 두 가지 방법 중 하나를 사용하세요:

• 사용자 지정 이미지 경로 제공:

  1. GitLab 서버 도메인 외부에서 이미지를 호스팅하는 경우, 이미지 파일에 액세스할 수 있도록 콘텐츠 보안 정책이 구성되어 있는지 확인하세요.
  2. GitLab 설치 방법에 따라 GitLab 구성 파일에 사용자 정의 icon 매개변수를 추가하세요. OpenID Connect 제공자에 대한 예시는 OpenID Connect OmniAuth 제공자를 참조하세요.

• 구성 파일에 이미지 직접 포함: 이 예시는 이미지의 Base64로 인코딩된 버전을 사용하여 데이터 URL을 통해 제공할 수 있습니다:

  1. GNU base64 명령을 사용하여 이미지 파일을 인코딩하세요(예: base64 -w 0 <logo.png>). 이 명령은 단일 줄의 <base64-data> 문자열을 반환합니다.

  2. GitLab 구성 파일의 사용자 정의 icon 매개변수에 Base64로 인코딩된 데이터를 추가하세요:

     omniauth:
       providers:
         - { name: '...'
             icon: 'data:image/png;base64,<base64-data>'
             ...
           }
     

앱이나 구성 변경

GitLab의 OAuth는 동일한 외부 인증 및 권한 제공자를 여러 제공자로 설정하는 것을 지원하지 않기 때문에, 제공자나 앱을 변경할 때 GitLab 구성과 사용자 식별을 동시에 업데이트해야 합니다. 예를 들어, saml 및 azure_activedirectory_v2를 설정할 수 있지만 동일한 구성에 두 번째 azure_activedirectory_v2를 추가할 수는 없습니다.

이 지침은 GitLab이 extern_uid를 저장하고 사용자 식별에 사용하는 유일한 데이터인 인증 방법에 모두 적용됩니다.

제공자 내에서 앱을 변경하는 경우, 사용자의 extern_uid가 변경되지 않으면 GitLab 구성만 업데이트하면 됩니다.

구성을 교체하려면:

1. gitlab.rb 파일에서 제공자 구성을 변경하세요.
2. 이전 제공자에 대해 GitLab 식별이 있는 모든 사용자의 extern_uid를 업데이트하세요.

extern_uid를 찾으려면 동일한 사용자에 대해 현재 제공자의 적절한 필드와 일치하는 ID를 확인하세요.

extern_uid를 업데이트하는 두 가지 방법이 있습니다:

• 사용자 API를 사용합니다. 제공자 이름과 새 extern_uid를 전달하세요.

• Rails 콘솔을 사용합니다:

  Identity.where(extern_uid: 'old-id').update!(extern_uid: 'new-id')
  

알려진 문제

대부분의 지원되는 OmniAuth 제공자는 Git을 통한 HTTP 암호 인증을 지원하지 않습니다. 대안으로 개인 액세스 토큰을 사용하여 인증할 수 있습니다.