• 지원되는 제공업체
• 공통 설정 구성
  • 초기 설정 구성
  • 프로바이더별 구성
  • OmniAuth를 통해 생성된 사용자의 비밀번호
• 기존 사용자용 OmniAuth 활성화
• Import 소스 비활성화 없이 OmniAuth를 통한 로그인 활성화 또는 비활성화
• OmniAuth 비활성화
• 기존 사용자를 OmniAuth 사용자에 연결
• 외부 프로바이더 목록 생성
• 커스텀 OmniAuth 제공자 사용
  • 커스텀 OmniAuth 제공자 예시
• OmniAuth 사용자 프로필 최신 상태로 유지
• 이중 인증을 우회
• 제공자 자동으로 로그인
• 커스텀 OmniAuth 제공자 아이콘 사용
• 앱 또는 구성 변경
• 알려진 문제

OmniAuth

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

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

지원되는 제공업체

GitLab은 다음 OmniAuth 제공업체를 지원합니다.

공통 설정 구성

OmniAuth 제공자를 구성하기 전에, 모든 제공자에 대해 공통으로 적용되는 설정을 구성하십시오.

초기 설정 구성

OmniAuth 설정을 변경하려면:

:::Tabs

1. /etc/gitlab/gitlab.rb 파일을 편집하십시오:

   # 주의!
   # 사용자가 먼저 계정을 만들지 않고 로그인할 수 있게합니다. 허용된 제공자를 배열로 정의하십시오. 예를 들어 ["saml", "google_oauth2"] 또는 true/false로 모든 제공자 또는 없음을 허용합니다.
   # 사용자 계정은 인증이 성공한 경우 자동으로 생성됩니다.
   gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'google_oauth2']
   gitlab_rails['omniauth_auto_link_ldap_user'] = true
   gitlab_rails['omniauth_block_auto_created_users'] = true
   

2. 파일을 저장하고 GitLab을 다시 구성하십시오:

   sudo gitlab-ctl reconfigure
   

1. Helm 값 내보내기:

   helm get values gitlab > gitlab_values.yaml
   

2. gitlab_values.yaml을 편집하고 globals.appConfig 하위의 omniauth 섹션을 업데이트하십시오:

   global:
     appConfig:
       omniauth:
         enabled: true
         allowSingleSignOn: ['saml', 'google_oauth2']
         autoLinkLdapUser: false
         blockAutoCreatedUsers: true
   

   자세한 내용은 글로벌 문서를 참조하십시오.

3. 파일을 저장하고 새 값 적용:

   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   

1. docker-compose.yml을 편집하십시오:

   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'google_oauth2']
           gitlab_rails['omniauth_auto_link_ldap_user'] = true
           gitlab_rails['omniauth_block_auto_created_users'] = true
   

2. 파일을 저장하고 GitLab을 다시 시작하십시오:

   docker compose up -d
   

1. /home/git/gitlab/config/gitlab.yml을 편집하십시오:

   ## OmniAuth settings
   omniauth:
     # Google, GitLab 등을 사용하여 OmniAuth 제공업체를 통해 로그인을 허용합니다
     # 11.4 이전의 버전에서는 true로 설정해야합니다.
     # enabled: true
   
     # 주의!
     # 사용자가 먼저 계정을 만들지 않고 로그인할 수 있게합니다. 허용된 제공자를 배열로 정의하십시오. 예를 들어 ["saml", "google_oauth2"] 또는 true/false로 모든 제공자 또는 없음을 허용합니다.
     # 사용자 계정은 인증이 성공한 경우 자동으로 생성됩니다.
     allow_single_sign_on: ["saml", "google_oauth2"]
   
     auto_link_ldap_user: true
   
     # 관리자가 승인 될 때까지 사용자를 제한합니다 (기본값: true)
     block_auto_created_users: true
   

2. 파일을 저장하고 GitLab을 다시 시작하십시오:

   # systemd를 실행하는 시스템의 경우
   sudo systemctl restart gitlab.target
   
   # SysV init를 실행하는 시스템의 경우
   sudo service gitlab restart
   

:::EndTabs

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

프로바이더별 구성

• GitLab 15.3에서 도입됨.

allow_single_sign_on이 설정된 경우, GitLab은 사용자가 로그인하는 데 사용하는 OmniAuth auth_hash에서 반환된 다음 필드 중 하나를 사용하여 GitLab에 사용자 이름을 설정합니다. 존재하는 첫 번째 값을 선택합니다.

• username.
• nickname.
• email.

각 프로바이더별로 GitLab 구성을 생성할 수 있으며, 이는 args를 사용하여 지원되는 프로바이더에 제공됩니다. 프로바이더의 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 자격 증명, LDAP 또는 다른 OmniAuth 프로바이더로 GitLab에 로그인합니다.
2. 왼쪽 사이드바에서 아바타를 선택합니다.
3. 프로필 편집을 선택합니다.
4. 왼쪽 사이드바에서 계정을 선택합니다.
5. 연결된 계정 섹션에서 Google과 같은 OmniAuth 프로바이더를 선택합니다.
6. 프로바이더로 리디렉션됩니다. GitLab을 승인한 후, GitLab로 리디렉션됩니다.

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

Import 소스 비활성화 없이 OmniAuth를 통한 로그인 활성화 또는 비활성화

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

참고: config/gitlab.yml에 구성된 모든 OAuth 프로바이더에 대해 로그인이 기본적으로 활성화됩니다.

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

1. 왼쪽 사이드바에서 하단에 관리자를 선택합니다.
2. 설정 > 일반을 선택합니다.
3. 로그인 제한을 확장합니다.
4. 활성화된 OAuth 인증 소스 섹션에서 각 프로바이더에 대해 확인란을 선택하거나 지웁니다.

OmniAuth 비활성화

OmniAuth은 기본적으로 활성화됩니다. 그러나 지정된 프로바이더가 구성 및 활성화되어 있는 경우에만 OmniAuth가 작동합니다.

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

gitlab_rails['omniauth_enabled'] = false

omniauth:
  enabled: false

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

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

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

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

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

이 방법은 SAML을 제외한 모든 프로바이더에 대해 자동 연결을 활성화합니다. SAML에 대한 자동 연결을 활성화하려면 SAML 설정 지침을 참조하십시오.

외부 프로바이더 목록 생성

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

외부 프로바이더 목록을 정의하려면 프로바이더의 전체 이름을 사용하십시오. 예를 들어, Google의 경우 google_oauth2를 사용합니다. 프로바이더 이름에 대한 자세한 내용은 지원되는 프로바이더 테이블의 OmniAuth 프로바이더 이름 열을 참조하십시오.

참고: OmniAuth 프로바이더를 외부 프로바이더 목록에서 제거하는 경우 해당 로그인 방법을 사용하는 사용자의 계정을 내부 계정으로 업그레이드하려면 수동으로 업데이트해야 합니다.

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

omniauth:
  external_providers: ['saml', '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 대신에 --deployment를 사용합니다.

4. GitLab을 시작하세요:

   sudo service gitlab start
   

커스텀 OmniAuth 제공자 예시

이미 GitLab과 통합되지 않은 제공자를 성공적으로 설정했다면 알려주세요.

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

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)를 사용하지 않고 로그인할 수 있습니다.

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

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 OmniAuth 제공자를 참조하여 OpenID Connect 제공자에 대한 예시를 확인하세요.

• 구성 파일에 이미지 첨부:

  1. 이미지 파일을 GNU base64 명령으로 인코딩하세요 (예: base64 -w 0 <logo.png>), 이렇게 하면 단일 <base64-data> 문자열을 반환합니다.

  2. GitLab 구성 파일에 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를 확인하세요.

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

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

• 레일스 콘솔의 사용:

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

알려진 문제

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