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

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

지원되는 공급자#

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

공통 설정 구성#

OmniAuth 공급자를 구성하기 전에 모든 공급자에 공통되는 설정을 구성합니다.

초기 설정 구성#

OmniAuth 설정을 변경하려면 다음과 같이 합니다.

이 설정을 구성한 후 원하는 공급자를 구성할 수 있습니다.

공급자별 구성#

allow_single_sign_on이 설정되어 있으면 GitLab은 로그인하는 사용자의 GitLab 사용자 이름을 만들기 위해 OmniAuth auth_hash에서 반환되는 다음 필드 중 존재하는 첫 번째 필드를 사용합니다.

• username.
• nickname.
• email.

공급자별로 GitLab 구성을 만들 수 있으며, 이는 args를 사용하여 공급자에 전달됩니다. 공급자의 args 에 gitlab_username_claim 변수를 설정하면 GitLab 사용자 이름에 사용할 다른 클레임을 선택할 수 있습니다. 선택한 클레임은 충돌을 방지하기 위해 고유해야 합니다.

gitlab_rails['omniauth_providers'] = [

  # The generic pattern for configuring a provider with name PROVIDER_NAME

  gitlab_rails['omniauth_providers'] = {
    name: "PROVIDER_NAME"
    ...
    args: { gitlab_username_claim: 'sub' } # For users signing in with the provider you configure, the GitLab username will be set to the "sub" received from the provider
  },

  # Here are examples using GitHub and Kerberos

  gitlab_rails['omniauth_providers'] = {
    name: "github"
    ...
    args: { gitlab_username_claim: 'name' } # For users signing in with GitHub, the GitLab username will be set to the "name" received from GitHub
  },
  {
    name: "kerberos"
    ...
    args: { gitlab_username_claim: 'uid' } # For users signing in with Kerberos, the GitLab username will be set to the "uid" received from Kerberos
  },
]

- { 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 공급자를 활성화할 수 있습니다.

프로필 설정을 통해 OmniAuth 공급자 연결#

프로필 설정을 통해 OmniAuth 공급자를 연결하려면 다음과 같이 합니다.

1. GitLab 자격 증명, LDAP, 또는 다른 OmniAuth 공급자로 GitLab에 로그인합니다.
2. 오른쪽 상단에서 아바타를 선택합니다.
3. Edit profile을 선택합니다.
4. 왼쪽 사이드바에서 Access > Password and authentication을 선택합니다.
5. Service sign-in 섹션에서 Google과 같은 OmniAuth 공급자를 선택합니다.
6. 공급자로 리디렉션됩니다. GitLab을 승인하면 다시 GitLab으로 리디렉션됩니다.

이제 선택한 OmniAuth 공급자를 사용하여 GitLab에 로그인할 수 있습니다.

OmniAuth로 로그인할 때 기존 계정 연결하기#

이메일 주소가 기존 GitLab 계정과 일치하는 OmniAuth 공급자로 로그인하면, GitLab은 로그인 오류를 표시하는 대신 해당 공급자를 기존 계정에 연결하도록 안내합니다.

auto_link_user가 활성화되어 있으면 로그인 흐름 없이 자동으로 연결됩니다.

안내형 연결 흐름은 다음과 같이 작동합니다.

1. OmniAuth 공급자로 로그인을 시도합니다.
2. GitLab은 공급자로부터 받은 이메일 주소가 기존 계정과 일치함을 감지합니다.
3. 다음 안내와 함께 로그인 페이지로 리디렉션됩니다. "<provider> 계정의 이메일 주소로 이미 계정이 존재합니다. 기존 자격 증명으로 로그인하여 <provider> 계정을 연결합니다."
4. 사용자 이름과 비밀번호 같은 기존 자격 증명으로 로그인합니다.
5. GitLab이 Authorize identity provider link 페이지를 표시합니다.
6. Authorize를 선택합니다.

GitLab은 기본 이메일과 확인된 보조 이메일 주소를 모두 대상으로 이메일 주소를 일치시킵니다. 연결 후에는 OmniAuth 공급자를 사용하여 GitLab에 로그인할 수 있습니다.

로그인하여 기존 계정의 소유권을 증명한 후에만 연결이 설정되므로, 이 흐름은 이메일 일치만으로 계정을 연결하는 auto_link_user보다 더 안전합니다.

가져오기 소스를 비활성화하지 않고 OmniAuth 공급자로 로그인 활성화 또는 비활성화#

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

OmniAuth 공급자를 활성화하거나 비활성화하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Sign-in restrictions를 펼칩니다.
4. Enabled OAuth authentication sources 섹션에서 활성화하거나 비활성화할 각 공급자의 체크박스를 선택하거나 선택 해제합니다.

OmniAuth 비활성화#

OmniAuth는 기본적으로 활성화되어 있습니다. 다만 OmniAuth는 공급자가 구성되고 활성화된 경우에만 작동합니다.

OmniAuth 공급자를 개별적으로 비활성화했는데도 문제가 발생하면 구성 파일을 수정하여 OmniAuth 하위 시스템 전체를 비활성화할 수 있습니다.

gitlab_rails['omniauth_enabled'] = false

omniauth:
  enabled: false

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

이메일 주소가 일치하면 OmniAuth 사용자를 기존 GitLab 사용자에 연결할 수 있습니다. 두 가지 방법을 사용할 수 있습니다.

• 자동 연결(auto_link_user): GitLab이 로그인 시 사용자의 별도 작업 없이 OmniAuth 아이덴티티를 일치하는 계정에 자동으로 연결합니다.
• 안내형 연결: auto_link_user가 비활성화되어 있으면 GitLab은 아이덴티티를 연결하기 전에 사용자에게 기존 자격 증명으로 로그인하여 소유권을 확인하도록 요청합니다. 자세한 내용은 OmniAuth로 로그인할 때 기존 계정 연결하기를 참고합니다.

자동 연결#

이메일 주소가 일치할 때 OmniAuth 사용자를 기존 GitLab 사용자에 자동으로 연결하려면, auto_link_user를 활성화합니다.

다음 예시는 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 provider name 열을 참고합니다.

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

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

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

선택한 OmniAuth 공급자로부터 프로필 동기화를 활성화할 수 있습니다. 다음 사용자 속성을 조합하여 동기화할 수 있습니다.

• name
• email
• job_title
• location
• organization

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

2단계 인증 우회#

특정 OmniAuth 공급자를 사용하면 사용자는 2단계 인증(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 공급자의 예시는 OpenID Connect OmniAuth 공급자를 참고합니다.

• 구성 파일에 이미지 직접 포함: 다음 예시는 Base64로 인코딩된 이미지 버전을 만들며, 이를 Data URL을 통해 제공할 수 있습니다.

  1. GNU base64 명령(예: base64 -w 0 <logo.png>)으로 이미지 파일을 인코딩합니다. 이 명령은 한 줄의 <base64-data> 문자열을 반환합니다.

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

     omniauth:
       providers:
         - { name: '...'
             icon: 'data:image/png;base64,<base64-data>'
             # Additional parameters removed for readability
           }
     

앱 또는 구성 변경#

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를 확인하여 동일한 사용자에 대해 현재 공급자의 해당 필드와 일치하는 ID를 찾습니다.

extern_uid를 업데이트하는 방법은 두 가지입니다.

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

• Rails 콘솔을 사용합니다.

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

알려진 문제#

지원되는 대부분의 OmniAuth 공급자는 HTTP를 통한 Git 비밀번호 인증을 지원하지 않습니다. 해결 방법으로 개인 액세스 토큰을 사용하여 인증할 수 있습니다.