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, 즉 external_url이 기본 사이트의 external_url과 정확히 일치하는 경우.
  • 프록시 사용이 가능한 분리된 URL 사용. GitLab 15.1 이후에는 기본 설정에서 프록시가 활성화됩니다.
  • 프록시 비활성화된 분리된 URL 사용.

통합 URL로 SAML

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

프록시 사용이 가능한 분리된 URL로 SAML

note
프록시를 사용하면 SAML은 보조 사이트에서 로그인하는 데만 사용할 수 있습니다. SAML ID 공급자 (IdP)가 응용 프로그램이 여러 콜백 URL을 구성할 수 있도록 허용하는지 확인해야 합니다. 이 경우 IdP 제공 업체 지원팀과 확인하세요.

보조 사이트가 기본 사이트와 다른 external_url을 사용하는 경우, SAML ID 공급자(IdP)를 구성하여 보조 사이트의 SAML 콜백 URL을 허용하십시오. 예를 들어 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", # 선택적 로그인 버튼 레이블, "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:EntityDescriptor ID="_bf71eb57-7490-4024-bfe2-54cec716d4bf" 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-secondary.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>

md:AssertionConsumerService 필드의 Location 속성은 gitlab-secondary.example.com을 가리킵니다.

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

별도의 URL 및 프록시 비활성화 상태에서의 SAML

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

OpenID Connect

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

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

LDAP

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

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

귀하의 LDAP 서비스 설명서를 확인하여 LDAP 서비스에서 복제를 설정하는 방법에 대한 지침을 찾아보세요. 이 과정은 사용하는 소프트웨어나 서비스에 따라 다릅니다. 예를 들어, OpenLDAP은 이 복제 설명서를 제공합니다.