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

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

지원되는 공급자#

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

공통 설정 구성#

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

초기 설정 구성#

OmniAuth 설정을 변경하려면:

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

공급자별 구성#

allow_single_sign_on이 설정된 경우, GitLab은 OmniAuth auth_hash에서 반환된 다음 필드 중 하나를 사용하여 로그인하는 사용자의 GitLab 사용자 이름을 설정합니다. 먼저 존재하는 것을 선택합니다:

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

1. GitLab 자격 증명, LDAP 또는 다른 OmniAuth 공급자로 GitLab에 로그인하세요.
2. 오른쪽 상단 모서리에서 아바타를 선택하세요.
3. 프로필 편집을 선택하세요.
4. 왼쪽 사이드바에서 액세스 > 비밀번호 및 인증을 선택하세요.
5. 서비스 로그인 섹션에서 Google과 같은 OmniAuth 공급자를 선택하세요.
6. 공급자로 리디렉션됩니다. GitLab을 승인하면 GitLab으로 다시 리디렉션됩니다.

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

가져오기 소스 비활성화 없이 OmniAuth 공급자로 로그인 활성화 또는 비활성화#

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

OmniAuth 공급자를 활성화하거나 비활성화하려면:

1. 오른쪽 상단 모서리에서 관리를 선택하세요.
2. In the left sidebar, select Settings > General.
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을 제외한 모든 공급자에서 작동합니다. SAML에 대한 자동 연결을 활성화하려면 SAML 설정 지침을 참조하세요.

외부 공급자 목록 만들기#

외부 OmniAuth 공급자 목록을 정의할 수 있습니다. 나열된 공급자를 통해 계정을 만들거나 GitLab에 로그인하는 사용자는 내부 프로젝트에 접근할 수 없으며 외부 사용자로 표시됩니다.

외부 공급자 목록을 정의하려면 예를 들어 Google의 경우 google_oauth2와 같이 공급자의 전체 이름을 사용하세요. 공급자 이름은 지원되는 공급자 표의 OmniAuth 공급자 이름 열을 참조하세요.

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

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

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

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

• name
• email
• job_title
• location
• organization

LDAP을 사용하여 인증하면 사용자의 이름과 이메일이 항상 동기화됩니다.

이중 인증 우회#

특정 OmniAuth 공급자를 사용하면 사용자가 이중 인증(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 공급자를 참조하세요.

• 구성 파일에 이미지 직접 포함: 이 예는 Data URL을 통해 제공할 수 있는 이미지의 Base64 인코딩 버전을 만듭니다:

  1. GNU base64 명령(base64 -w 0 <logo.png> 등)으로 이미지 파일을 인코딩하면 단일 행 <base64-data> 문자열이 반환됩니다.

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

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

앱 또는 구성 변경#

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

이 지침은 GitLab이 extern_uid를 저장하고 사용자 인증에 유일하게 사용하는 모든 인증 방법에 적용됩니다.

공급자 내에서 앱을 변경할 때 사용자 extern_uid가 변경되지 않으면 GitLab 구성만 업데이트하면 됩니다.

구성을 교환하려면:

1. gitlab.rb 파일에서 공급자 구성을 변경하세요.
2. 이전 공급자에 대해 GitLab에 ID가 있는 모든 사용자의 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 비밀번호 인증을 지원하지 않습니다. 해결 방법으로 개인 액세스 토큰을 사용하여 인증할 수 있습니다.