• 지원되는 제공 업체
• 공통 설정 구성
  • 초기 설정 구성
  • 프로바이더별 구성
  • OmniAuth를 통해 생성된 사용자의 비밀번호
• 기존 사용자를 위해 OmniAuth 활성화
• 가져오기 소스 사용 중인 OmniAuth 프로바이더의 로그인 사용 가능 여부 설정 또는 해제
• OmniAuth 비활성화
• 기존 사용자를 OmniAuth 사용자에 연결
• 외부 프로바이더 디렉터리 생성
• 사용자 정의 OmniAuth 공급자 사용
  • 사용자 정의 OmniAuth 공급자 예시
• OmniAuth 사용자 프로필 최신 상태 유지
• 이중 인증 제외
• 공급자 자동 로그인
• 사용자 정의 OmniAuth 공급자 아이콘 사용
• 애플리케이션 또는 구성 변경
• 알려진 문제

OmniAuth

사용자는 Twitter, 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를 통해 생성된 사용자의 비밀번호

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

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

기존 사용자라면, GitLab 계정이 생성된 후에 OmniAuth 프로바이더를 활성화할 수 있습니다. 예를 들어, 원래 LDAP으로 로그인했다면 Twitter와 같은 OmniAuth 프로바이더를 활성화할 수 있습니다.

1. GitLab의 GitLab 자격 증명, LDAP 또는 다른 OmniAuth 프로바이더로 로그인하세요.
2. 왼쪽 사이드바에서 아바타를 선택하세요.
3. 프로필 편집을 선택하세요.
4. 왼쪽 사이드바에서 계정을 선택하세요.
5. 연결된 계정 섹션에서 Twitter와 같은 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 사용자에 연결

• GitLab 13.4에서 소개되었습니다.

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

다음 예시에서는 OpenID Connect 프로바이더와 Twitter OAuth 프로바이더에 대해 자동 연결을 활성화합니다.

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

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

이 자동 연결 기능은 SAML을 제외한 모든 프로바이더에 대해 작동합니다. SAML에 대해 자동 연결을 활성화하려면, SAML 설정 지침을 참조하세요.

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

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

외부 프로바이더 디렉터리을 정의하려면, 예를 들어 Google의 경우 google_oauth2와 같은 프로바이더의 전체 이름을 사용합니다. 프로바이더 이름에 대해서는 지원되는 프로바이더 테이블의 OmniAuth 프로바이더 이름 열을 참조하세요.

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

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

사용자 정의 OmniAuth 공급자 사용

GitLab에 포함된 OmniAuth 공급자 이외의 인증 솔루션과 통합해야 하는 경우 사용자 정의 OmniAuth 공급자를 사용할 수 있습니다.

이러한 단계는 일반적입니다. 정확한 구현 세부 정보에 대해서는 OmniAuth 공급자의 문서를 참조하십시오.

1. GitLab 중지:

   sudo service gitlab stop
   

2. 당신의 Gemfile에 젬 추가:

   gem "omniauth-your-auth-provider"
   

3. 새로운 OmniAuth 공급자 젬 설치:

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

   이 명령어들은 초기 설치 시 젬 설치 명령어와 동일하며 --path vendor/bundle --no-deployment로 변경됩니다.

4. GitLab 시작:

   sudo service gitlab start
   

사용자 정의 OmniAuth 공급자 예시

이미 GitLab에 통합되어 있지 않은 공급자를 성공적으로 설정한 경우 알려주세요.

우리는 모든 가능한 인증 메커니즘을 공식적으로 지원할 수는 없지만, 특정한 요구 사항을 가진 사용자들을 돕고자 합니다.

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

선택한 OmniAuth 공급자에서 프로필 동기화를 활성화할 수 있습니다. 다음 사용자 속성을 임의로 동기화할 수 있습니다:

• 이름
• 이메일
• 위치

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

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

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

이중 인증 제외

• GitLab 12.3에서 소개되었습니다.

특정 OmniAuth 공급자를 사용하는 경우 사용자는 이중 인증 (2FA)를 사용하지 않고 로그인할 수 있습니다.

알려진 이슈 때문에 사용자는 GitLab에 로그인할 때 2FA 설정을 해야한다. 그렇지 않으면 GitLab에 로그인할 때 2FA 설정을 하라는 메시지가 표시됩니다.

2FA를 제외하기 위해 다음과 같이 설정할 수 있습니다:

• 배열을 사용하여 허용된 공급자를 정의합니다 (예: ['twitter', 'google_oauth2']).
• 모든 공급자를 허용하려면 true를, 허용하지 않으려면 false를 지정합니다.

이 옵션은 이미 2FA를 지원하는 공급자에 대해서만 구성해야 합니다. 기본값은 false입니다.

이 구성은 SAML에는 적용되지 않습니다.

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

omniauth:
  allow_bypass_two_factor: ['twitter', '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 OmniAuth 공급자를 참조하십시오.

• 구성 파일에 이미지 포함:

  1. 이미지 파일을 GNU base64 명령어를 사용하여 인코딩합니다 (예: base64 -w 0 <logo.png>).

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

     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를 업데이트합니다.

extern_uid를 찾으려면 현재 공급자에 대한 사용자의 현재 extern_uid를 확인하고 동일한 사용자에 대한 현재 공급자의 적절한 필드와 일치하는 ID를 찾으십시오.

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

• 사용자 API 사용. 공급자 이름과 새 extern_uid를 전달합니다.

• Rails 콘솔 사용:

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

알려진 문제

대부분의 지원되는 OmniAuth 공급업체는 Git over HTTP 암호 인증을 지원하지 않습니다. 회피책으로 개인 액세스 토큰을 사용하여 인증할 수 있습니다.