Geo with Single Sign On (SSO)

상세 정보: Tier: 프리미엄, 얼티밋 Offering: Self-Managed

이 문서에서는 지오별 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

참고: 프록시가 활성화된 경우 SAML은 보조 사이트에서 로그인에만 사용할 수 있습니다. SAML IDP(Identity Provider)가 애플리케이션이 여러 콜백 URL을 구성할 수 있도록 허용해야 합니다. 이를 확인하려면 IDP 제공 업체 지원팀과 확인하세요.

보조 사이트가 기본 사이트와 다른 external_url을 사용하는 경우 SAML Identity Provider (IDP)를 구성하여 보조 사이트의 SAML 콜백 URL을 허용해야 합니다. 예를 들어 Okta를 구성하는 경우:

Okta에 로그인합니다.
Okta Admin 대시보드 > 애플리케이션 > Your App Name > General로 이동합니다.
SAML 설정을 선택하여 편집합니다.
일반 설정을 선택한 후 SAML 설정으로 이동하려면 다음을 선택합니다.
SAML 설정 > 일반에서 Single sign-on URL이 기본 사이트의 SAML 콜백 URL인지 확인합니다. 예: https://gitlab-primary.example.com/users/auth/saml/callback. 그렇지 않은 경우 이 필드에 기본 사이트의 SAML 콜백 URL을 입력합니다.
고급 설정 표시를 선택합니다.
기타 요청 가능한 SSO URL에서 보조 사이트의 SAML 콜백 URL을 입력합니다. 예: https://gitlab-secondary.example.com/users/auth/saml/callback. 인덱스를 원하는 값으로 설정할 수 있습니다.
다음을 선택한 후 완료를 선택합니다.

기본 사이트의 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: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 콜백 URL을 허용하도록 SAML IdP를 구성한 후 기본 사이트 및 보조 사이트에서 SAML로 로그인할 수 있어야 합니다.

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

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

OpenID Connect

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

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

LDAP

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

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

LDAP 서비스 문서를 확인하여 해당 LDAP 서비스에서 복제를 설정하는 방법에 대한 지침을 확인하십시오. 이 과정은 사용된 소프트웨어나 서비스에 따라 다릅니다. 예를 들어, OpenLDAP은 이 복제 문서를 제공합니다.