• Supported providers
• Configure common settings
  • 초기 설정 구성
  • 공급자별 구성
  • OmniAuth로 생성된 사용자에 대한 비밀번호
• 기존 사용자에 대해 OmniAuth 활성화하기
• 가져오기 소스 비활성화 없이 OmniAuth 공급자로 로그인 활성화 또는 비활성화
• OmniAuth 비활성화
• 기존 사용자를 OmniAuth 사용자와 연결하기
• 외부 공급자 목록 만들기
• 사용자 정의 OmniAuth 공급자 사용하기
  • 커스텀 OmniAuth 제공자 예시
• OmniAuth 사용자 프로필을 최신 상태로 유지하기
• 이중 인증 우회하기
• 제공자로 자동 로그인하기
• 사용자 정의 OmniAuth 제공자 아이콘 사용하기
• 앱 또는 구성 변경
• 알려진 문제

OmniAuth

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

구성이 완료되면 로그인 페이지에 추가 로그인 옵션이 표시됩니다.

Supported providers

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

Configure common settings

OmniAuth 공급자를 구성하기 전에,
모든 공급자에 대해 공통적인 설정을 구성하세요.

초기 설정 구성

OmniAuth 설정을 변경하려면:

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

공급자별 구성

• 도입됨 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'] = [

  # 공급자 구성에 대한 일반 패턴 제공

  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에 로그인할 수 있습니다.

가져오기 소스 비활성화 없이 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 사용자와 연결하기

이메일 주소가 일치하는 경우, 기존 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 추가:

   gem "omniauth-your-auth-provider"
   

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

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

   이 명령은 초기 설치 중 gem 설치 명령과 동일하며, --deployment 대신 --path vendor/bundle --no-deployment를 사용합니다.

4. GitLab 시작:

   sudo service gitlab start
   

커스텀 OmniAuth 제공자 예시

이미 GitLab과 통합되지 않은 제공자를 성공적으로 설정했다면,

알려주세요.

모든 가능한 인증 메커니즘을 공식적으로 지원할 수는 없지만,

특정 요구를 가진 분들께 최소한 도움을 드리고 싶습니다.

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

선택한 OmniAuth 제공자로부터 프로필 동기화를 활성화할 수 있습니다.

다음 사용자 속성의 조합을 동기화할 수 있습니다:

• name
• email
• location

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를 설정해야 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']

제공자로 자동 로그인하기

auto_sign_in_with_provider 설정을 GitLab 구성에 추가하여 로그인 요청을 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를 확인하세요.

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

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

• Rails 콘솔을 사용합니다:

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

알려진 문제

대부분의 지원되는 OmniAuth 공급자는 HTTP 비밀번호 인증을 지원하지 않습니다.

우회 방법으로 개인 액세스 토큰을 사용하여 인증할 수 있습니다.