이 문서는 Geo에 특정한 SSO 고려 사항과 구성만 다룹니다. 일반 인증에 대한 자세한 내용은 GitLab 인증 및 권한 부여를 참조하세요.

인스턴스 전체 SAML 구성#

사전 요구 사항#

인스턴스 전체 SAML이 기본 Geo 사이트에서 작동하고 있어야 합니다.

기본 사이트에서만 SAML을 구성합니다. 보조 사이트의 gitlab.rb에서 gitlab_rails['omniauth_providers']를 구성해도 효과가 없습니다. 보조 사이트는 기본 사이트에 구성된 SAML 공급자에 대해 인증합니다. 보조 사이트의 URL 유형에 따라 기본 사이트에서 추가 구성이 필요할 수 있습니다.

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

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

• 통합 URL: external_url이 기본 사이트의 external_url과 정확히 일치합니다.
• 프록시가 활성화된 별도 URL. 프록시는 GitLab 15.1 이상에서 기본적으로 활성화됩니다.
• 프록시가 비활성화된 별도 URL.

통합 URL을 사용한 SAML#

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

프록시가 활성화된 별도 URL을 사용한 SAML#

보조 사이트가 기본 사이트와 다른 external_url을 사용하는 경우 SAML ID 공급자(IdP)를 구성하여 보조 사이트의 SAML 콜백 URL을 허용합니다. 예를 들어 Okta를 구성하려면:

1. Okta에 로그인합니다.
2. Okta Admin Dashboard > Applications > Your App Name > General로 이동합니다.
3. SAML Settings에서 Edit를 선택합니다.
4. General Settings에서 Next를 선택하여 SAML Settings로 이동합니다.
5. SAML Settings > General에서 Single sign-on URL이 기본 사이트의 SAML 콜백 URL인지 확인합니다. 예를 들어 https://gitlab-primary.example.com/users/auth/saml/callback. 그렇지 않은 경우 기본 사이트의 SAML 콜백 URL을 이 필드에 입력합니다.
6. Show Advanced Settings를 선택합니다.
7. Other Requestable SSO URLs에 보조 사이트의 SAML 콜백 URL을 입력합니다. 예를 들어 https://gitlab-secondary.example.com/users/auth/saml/callback. Index는 임의로 설정할 수 있습니다.
8. Next를 선택한 다음 Finish를 선택합니다.

기본 사이트의 gitlab.rb의 gitlab_rails['omniauth_providers']에서 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"
    }
  }
]

이 구성으로 인해:

• 두 사이트 모두 assertion consumer service(ACS) URL로 /users/auth/saml/callback을 사용합니다.
• 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를 지원하지 않습니다. 자세한 내용은 이슈 396745를 참조하세요.

LDAP#

기본 사이트에서 LDAP를 사용하는 경우 보조 사이트는 인증과 관련된 요청을 기본 사이트에 프록시하기 때문에 동일한 LDAP 구성이 보조 사이트에도 적용됩니다.

재해 복구 시나리오를 대비하기 위해 각 보조 사이트에 보조 LDAP 서버를 설정해야 합니다. 이 경우 보조 사이트를 승격하면 사용자가 복제된 LDAP 서비스를 사용하여 인증할 수 있습니다. 그렇지 않으면 기본 사이트에 연결된 LDAP 서비스를 승격된 보조 사이트에서 사용할 수 없는 경우 사용자가 HTTP 기본 인증을 사용하여 보조 사이트에서 HTTP(S)를 통한 Git 작업을 수행할 수 없습니다. 그러나 LDAP 서비스를 사용할 수 없을 때 여러 번 로그인 시도가 실패하여 계정이 잠기지 않는 한 사용자는 SSH 및 개인 액세스 토큰으로 Git을 계속 사용할 수 있습니다.

LDAP 서비스에서 복제를 설정하는 방법은 LDAP 서비스 문서를 확인하세요. 사용하는 소프트웨어나 서비스에 따라 프로세스가 다릅니다. 예를 들어 OpenLDAP은 이 복제 문서를 제공합니다.