Geo with Single Sign On (SSO)

Tier: Premium, Ultimate Offering: Self-managed

이 문서는 Geo별 SSO 고려 사항 및 구성에 대해서만 논의합니다. 일반적인 인증에 대한 자세한 정보는 GitLab 인증 및 권한 부여를 참조하세요.

인스턴스 전체 SAML 구성

준비 사항

인스턴스 전체 SAML은 기본 Geo 사이트에서 작동해야 합니다.

SAML은 기본 사이트에서만 구성합니다. 보조 사이트의 gitlab.rb의 gitlab_rails['omniauth_providers']를 구성해도 영향을 미치지 않습니다. 보조 사이트는 기본 사이트에서 구성된 SAML 제공자를 인증합니다. 보조 사이트의 URL 유형에 따라 기본 사이트에 추가 구성이 필요할 수 있습니다.

보조 사이트가 사용하는 URL 유형 결정

보조 사이트 구성에 따라 인스턴스 전체 SAML을 구성하는 방법이 다릅니다. 보조 사이트가 다음 중 어떤 유형의 URL을 사용하는지 확인하세요:

  • 통합된 URL, 즉 external_url이 기본 사이트의 external_url과 정확히 일치하는 경우.
  • 프록시 사용하여 분리된 URL 각각의 URL은 기본 사이트와는 다른 경우. GitLab 15.1 이상에서는 기본적으로 프록시가 활성화됩니다.
  • 프록시를 사용하지 않은 분리된 URL을 사용하는 경우.

통합된 URL을 사용하는 SAML

기본 사이트에서 SAML을 올바르게 구성했다면, 추가 구성 없이도 보조 사이트에서 작동해야 합니다.

프록시를 사용하여 분리된 URL을 사용하는 SAML

note
프록시를 사용하는 경우, SAML은 이중 사이트에서 로그인하는 데 사용될 수 있습니다. 이 경우 SAML IdP(Identity Provider)가 응용 프로그램에 여러 콜백 URL을 구성할 수 있도록 허용해야 합니다. 이 경우 보조 사이트는 기본 사이트의 SAML 콜백 URL을 허용하도록 SAML Identity Provider(IdP)를 구성합니다. 예를 들어, Okta를 구성하는 방법은 다음과 같습니다:
  1. Okta에 로그인합니다.
  2. Okta 관리 대시보드 > 응용 프로그램 > 애플리케이션 이름 > 일반으로 이동합니다.
  3. SAML 설정에서 수정을 선택합니다.
  4. 일반 설정에서 다음을 선택하여 SAML 설정으로 이동합니다.
  5. SAML 설정 > 일반에서 단일 로그인 URL이 기본 사이트의 SAML 콜백 URL인지 확인합니다. 예: https://gitlab-primary.example.com/users/auth/saml/callback. 그렇지 않은 경우, 이 필드에 기본 사이트의 SAML 콜백 URL을 입력합니다.
  6. 고급 설정 표시를 선택합니다.
  7. 신청 가능한 기타 SSO URL에 보조 사이트의 SAML 콜백 URL을 입력합니다. 예: https://gitlab-secondary.example.com/users/auth/saml/callback. 색인을 임의로 설정할 수 있습니다.
  8. 다음을 선택한 후 완료를 선택합니다.

기본 사이트의 gitlab.rb의 SAML 제공자 구성에서 assertion_consumer_service_url을 지정해서는 안됩니다. 아래는 예시입니다: 

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Okta", # optional label for login button, defaults to "Saml"
    args: {
      idp_cert_fingerprint: "B5:AD:AA:9E:3C:05:68:AD:3B:78:ED:31:99:96:96:43:9E:6D:79:96",
      idp_sso_target_url: "https://<dev-account>.okta.com/app/dev-account_gitlabprimary_1/exk7k2gft2VFpVFXa5d1/sso/saml",
      issuer: "https://<gitlab-primary>",
      name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    }
  }
]

이 구성을 통해:

  • 두 사이트가 각각 /users/auth/saml/callback를 해당 어설션 컨슈머 서비스(ACS) URL로 사용합니다.
  • 각 URL의 호스트가 해당 사이트의 호스트로 설정됩니다.

이를 확인하려면 각 사이트의 /users/auth/saml/metadata 경로를 방문하여 확인할 수 있습니다. 예를 들어, https://gitlab-primary.example.com/users/auth/saml/metadata를 방문하면 다음과 같은 메시지가 표시될 수 있습니다: 

<md:EntityDescriptor ID="_b9e00d84-d34e-4e3d-95de-122e3c361617" entityID="https://gitlab-primary.example.com"
  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://gitlab-primary.example.com/users/auth/saml/callback"    index="0" isDefault="true"/>
    <md:AttributeConsumingService index="1" isDefault="true">
      <md:ServiceName xml:lang="en">Required attributes</md:ServiceName>
      <md:RequestedAttribute FriendlyName="Email address" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/>
      <md:RequestedAttribute FriendlyName="Full name" Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/>
      <md:RequestedAttribute FriendlyName="Given name" Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/>
      <md:RequestedAttribute FriendlyName="Family name" Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/>
    </md:AttributeConsumingService>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

https://gitlab-secondary.example.com/users/auth/saml/metadata를 방문하면, md:AssertionConsumerService 필드의 Location 속성이 gitlab-secondary.example.com을 가리키는지 확인할 수 있습니다.

보조 사이트의 SAML 콜백 URL을 허용하도록 SAML IdP를 구성한 후에는 기본 사이트 및 보조 사이트에서 SAML을 사용하여 로그인할 수 있어야 합니다.

별도 URL을 사용하고 프록시 비활성화된 SAML

기본 사이트에 SAML을 올바르게 구성했다면, 추가 구성 없이 보조 사이트에서도 작동해야 합니다.

OpenID Connect

OpenID Connect (OIDC) OmniAuth 제공자를 사용하는 경우, 대부분의 경우 문제 없이 작동해야 합니다:

  • 통합된 URL을 사용하는 OIDC: 기본 사이트에 OIDC를 올바르게 구성했다면, 추가 구성 없이 보조 사이트에서도 작동해야 합니다.
  • 프록시 비활성화된 별도 URL을 사용하는 OIDC: 기본 사이트에 OIDC를 올바르게 구성했다면, 추가 구성 없이 보조 사이트에서도 작동해야 합니다.
  • 프록시 활성화된 별도 URL을 사용하는 OIDC: 프록시 활성화된 별도 URL은 OpenID Connect을 지원하지 않습니다. 자세한 정보는 이슈 396745를 확인하세요.

LDAP

기본 사이트에서 LDAP을 사용하는 경우, 각 보조 사이트에 보조 LDAP 서버를 설정해야 합니다. 그렇지 않으면 사용자는 보조 사이트에서 HTTP 기본 인증을 사용하여 HTTP(s)를 통해 Git 작업을 수행할 수 없습니다. 그러나 사용자는 여전히 SSH 및 개인 액세스 토큰을 사용하여 Git을 사용할 수 있습니다.

note
모든 보조 사이트가 LDAP 서버를 공유할 수 있지만 추가 지연 시간이 문제가 될 수 있습니다. 또한, 보조 사이트가 기본 사이트로 승격되는 경우 재해 복구 시나리오에서 사용 가능한 LDAP 서버를 고려하세요.

LDAP 서비스 설명서에서 사용 중인 소프트웨어나 서비스에 따라 복제 설정 방법이 다르므 때문에 사용 방법을 확인하세요. 예를 들어, OpenLDAP은 이 복제 설명서를 제공합니다.