이 페이지에는 다음을 사용할 때 발생할 수 있는 문제에 대한 가능한 해결책이 포함되어 있습니다:

• GitLab.com 그룹의 SAML SSO.
• GitLab Self-Managed 인스턴스 수준 SAML OmniAuth 공급자.
• GitLab Dedicated 인스턴스에 대한 SAML을 구성하는 Switchboard.

SAML 디버깅 도구#

SAML 응답은 base64로 인코딩됩니다. 이를 즉석에서 디코딩하려면 SAML-tracer 브라우저 확장 프로그램(Firefox, Chrome)을 사용할 수 있습니다.

브라우저 플러그인을 설치할 수 없는 경우 대신 SAML 응답을 수동으로 생성하고 캡처할 수 있습니다.

다음 사항에 특별히 주의하세요:

• 로그인하는 사용자를 식별하는 NameID. 사용자가 이전에 로그인한 경우 이 값은 GitLab이 저장한 값과 일치해야 합니다.
• 응답 서명을 확인하는 데 필요한 X509Certificate의 존재.
• 잘못 구성된 경우 오류를 일으킬 수 있는 SubjectConfirmation 및 Conditions.

SAML 응답 생성#

SAML 응답을 사용하여 ID 공급자를 통해 로그인을 시도하는 동안 어설션 목록에 전송된 속성 이름과 값을 미리 봅니다.

SAML 응답을 생성하려면:

1. 브라우저 디버깅 도구 중 하나를 설치합니다.
2. 새 브라우저 탭을 엽니다.
3. SAML 추적기 콘솔을 엽니다:
   • Chrome: 페이지의 컨텍스트 메뉴에서 검사를 선택한 다음 개발자 콘솔에서 SAML 탭을 선택합니다.
   • Firefox: 브라우저 툴바에 있는 SAML-tracer 아이콘을 선택합니다.
4. GitLab.com 그룹의 경우:
   • 그룹의 GitLab 단일 로그온 URL로 이동합니다.
   • 승인을 선택하거나 로그인을 시도합니다.
5. GitLab Self-Managed 인스턴스의 경우:
   • 인스턴스 홈 페이지로 이동합니다.
   • SAML 로그인 버튼을 선택하여 로그인합니다.
6. 추적기 콘솔에 이 SAML 응답 예시와 유사한 SAML 응답이 표시됩니다.
7. SAML 추적기에서 내보내기 아이콘을 선택하여 응답을 JSON 형식으로 저장합니다.

SAML 응답 수동 생성#

개요를 보려면 GitLab 지원에서 업로드한 이 브라우저 플러그인을 사용하지 않고 SAML 응답을 수동으로 생성하는 방법에 대한 비디오(Google Chrome 사용)를 참조하세요.

사용하는 브라우저에 관계없이 프로세스는 다음과 유사합니다:

1. 새 브라우저를 마우스 오른쪽 버튼으로 클릭하고 검사를 선택하여 DevTools 창을 엽니다.

2. 네트워크 탭을 선택합니다. 로그 보존이 선택되어 있는지 확인합니다.

3. 브라우저 페이지로 전환하고 SAML SSO를 사용하여 GitLab에 로그인합니다.

4. DevTools 창으로 돌아가서 callback 이벤트를 필터링합니다.

5. callback 이벤트의 페이로드 탭을 선택하고 마우스 오른쪽 버튼을 클릭하여 값을 복사합니다.

6. 다음 명령에 이 값을 붙여 넣습니다: echo "<value>" | base64 --decode > saml_response.xml.

7. 코드 편집기에서 saml_response.xml을 엽니다.

   코드 편집기에 XML "프리티파이어"가 설치되어 있으면 응답을 자동으로 읽기 쉽게 형식화할 수 있습니다.

SAML 로그인에 대한 Rails 로그 검색#

audit_json.log 파일에서 SAML 로그인에 대한 자세한 정보를 찾을 수 있습니다.

예를 들어 system_access를 검색하여 사용자가 SAML을 사용하여 GitLab에 로그인한 시점을 보여주는 항목을 찾을 수 있습니다:

{
  "severity": "INFO",
  "time": "2024-08-13T06:05:35.721Z",
  "correlation_id": "01J555EZK136DQ8S7P32G9GEND",
  "meta.caller_id": "OmniauthCallbacksController#saml",
  "meta.remote_ip": "45.87.213.198",
  "meta.feature_category": "system_access",
  "meta.user": "bbtest",
  "meta.user_id": 16,
  "meta.client_id": "user/16",
  "author_id": 16,
  "author_name": "bbtest@agounder.onmicrosoft.com",
  "entity_id": 16,
  "entity_type": "User",
  "created_at": "2024-08-13T06:05:35.708+00:00",
  "ip_address": "45.87.213.198",
  "with": "saml",
  "target_id": 16,
  "target_type": "User",
  "target_details": "bbtest@agounder.onmicrosoft.com",
  "entity_path": "bbtest"
}

SAML 그룹 링크를 구성한 경우 로그에는 멤버십이 제거되는 것을 자세히 보여주는 항목도 표시됩니다:

{
  "severity": "INFO",
  "time": "2024-08-13T05:24:07.769Z",
  "correlation_id": "01J55330SRTKTD5CHMS96DNZEN",
  "meta.caller_id": "Auth::SamlGroupSyncWorker",
  "meta.remote_ip": "45.87.213.206",
  "meta.feature_category": "system_access",
  "meta.client_id": "ip/45.87.213.206",
  "meta.root_caller_id": "OmniauthCallbacksController#saml",
  "id": 179,
  "author_id": 6,
  "entity_id": 2,
  "entity_type": "Group",
  "details": {
    "remove": "user_access",
    "member_id": 7,
    "author_name": "BB Test",
    "author_class": "User",
    "target_id": 6,
    "target_type": "User",
    "target_details": "BB Test",
    "custom_message": "Membership destroyed",
    "ip_address": "45.87.213.198",
    "entity_path": "group1"
  }
}

auth_json.log에서 GitLab이 SAML 공급자로부터 받은 사용자의 세부 정보도 볼 수 있습니다. 예시:

{
  "severity": "INFO",
  "time": "2024-08-20T07:01:20.979Z",
  "correlation_id": "01J5Q9E59X4P40ZT3MCE35C2A9",
  "meta.caller_id": "OmniauthCallbacksController#saml",
  "meta.remote_ip": "xxx.xxx.xxx.xxx",
  "meta.feature_category": "system_access",
  "meta.client_id": "ip/xxx.xxx.xxx.xxx",
  "payload_type": "saml_response",
  "saml_response": {
    "issuer": [
      "https://sts.windows.net/03b8c6c5-104b-43e2-aed3-abb07df387cc/"
    ],
    "name_id": "ab260d59-0317-47f5-9afb-885c7a1257ab",
    "name_id_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "name_id_spnamequalifier": null,
    "name_id_namequalifier": null,
    "destination": "https://dh-gitlab.agounder.com/users/auth/saml/callback",
    "audiences": [
      "https://dh-gitlab.agounder.com/16.11.6"
    ],
    "attributes": {
      "http://schemas.microsoft.com/identity/claims/tenantid": [
        "03b8c6c5-104b-43e2-aed3-abb07df387cc"
      ],
      "http://schemas.microsoft.com/identity/claims/objectidentifier": [
        "ab260d59-0317-47f5-9afb-885c7a1257ab"
      ],
      "http://schemas.microsoft.com/identity/claims/identityprovider": [
        "https://sts.windows.net/03b8c6c5-104b-43e2-aed3-abb07df387cc/"
      ],
      "http://schemas.microsoft.com/claims/authnmethodsreferences": [
        "http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password"
      ],
      "email": [
        "bbtest@agounder.com"
      ],
      "firstname": [
        "BB"
      ],
      "name": [
        "bbtest@agounder.onmicrosoft.com"
      ],
      "lastname": [
        "Test"
      ]
    },
    "in_response_to": "_f8863f68-b5f1-43f0-9534-e73933e6ed39",
    "allowed_clock_drift": 2.220446049250313e-16,
    "success": true,
    "status_code": "urn:oasis:names:tc:SAML:2.0:status:Success",
    "status_message": null,
    "session_index": "_b4f253e2-aa61-46a4-902b-43592fe30800",
    "assertion_encrypted": false,
    "response_id": "_392cc747-7c8b-41de-8be0-23f5590d5ded",
    "assertion_id": "_b4f253e2-aa61-46a4-902b-43592fe30800"
  }
}

GitLab SAML 테스트#

다음 중 하나를 사용하여 SAML을 문제 해결할 수 있습니다:

• Docker compose를 사용하는 SAML이 포함된 완전한 GitLab 테스트 환경.
• SAML 공급자만 필요한 경우 플러그 앤 플레이 SAML 2.0 ID 공급자로 Docker 컨테이너를 시작하는 빠른 시작 가이드.
• GitLab Self-Managed 인스턴스에서 그룹의 SAML을 활성화하여 로컬 환경.

구성 확인#

편의를 위해 GitLab 지원 팀이 사용하는 일부 예시 리소스가 포함되어 있습니다. SAML 앱 구성을 확인하는 데 도움이 될 수 있지만, 이 리소스가 서드파티 제품의 현재 상태를 반영한다고 보장할 수 없습니다.

핑거프린트 계산#

idp_cert_fingerprint를 구성할 때는 가능하면 SHA256 핑거프린트를 사용해야 합니다. SHA1도 지원되지만 권장되지 않습니다. 핑거프린트를 계산하려면 인증서 파일에서 다음 명령을 실행하세요:

openssl x509 -in <certificate.crt> -noout -fingerprint -sha256

<certificate.crt>를 인증서 파일 이름으로 교체하세요.

idp_cert_fingerprint_algorithm: "http://www.w3.org/2001/04/xmlenc#sha256"

SSO 인증서 업데이트#

ID 공급자에 사용된 인증서가 변경되면(예: 인증서 업데이트 또는 갱신 시) 인증서 핑거프린트도 업데이트해야 합니다. ID 공급자의 UI에서 인증서 핑거프린트를 찾을 수 있습니다. ID 공급자 UI에서 인증서를 가져올 수 없는 경우 핑거프린트 계산 문서의 단계를 따르세요.

구성 오류#

잘못된 대상#

이 오류는 ID 공급자가 GitLab을 유효한 SAML 요청 발신자 및 수신자로 인식하지 않는다는 것을 의미합니다. 다음을 확인하세요:

• GitLab 콜백 URL을 ID 공급자 서버의 승인된 대상에 추가합니다.
• issuer 문자열의 후행 공백을 피합니다.

키 유효성 검사 오류, 다이제스트 불일치 또는 핑거프린트 불일치#

이러한 오류는 모두 SAML 인증서와 유사한 위치에서 발생합니다. SAML 요청은 핑거프린트, 인증서 또는 유효성 검사기를 사용하여 유효성을 검사해야 합니다.

이 요구 사항을 충족하려면 다음 사항을 고려하세요:

• 핑거프린트를 사용하는 경우 SHA256 핑거프린트를 확인합니다:
  1. 인증서 파일을 다시 다운로드합니다.
  2. 핑거프린트를 계산합니다.
  3. idp_cert_fingerprint에 제공된 값과 핑거프린트를 비교합니다. 값이 동일해야 합니다.
• 설정에 인증서가 제공되지 않은 경우 핑거프린트 또는 핑거프린트 유효성 검사기를 제공해야 하며 서버의 응답에 인증서(<ds:KeyInfo><ds:X509Data><ds:X509Certificate>)가 포함되어 있어야 합니다.
• 설정에 인증서가 제공된 경우 요청에 인증서가 포함될 필요가 없습니다. 이 경우 핑거프린트 또는 핑거프린트 유효성 검사기는 선택 사항입니다.

앞서 설명한 시나리오 중 어느 것도 유효하지 않은 경우 요청이 언급된 오류 중 하나와 함께 실패합니다.

누락된 클레임 또는 Email can't be blank 오류#

ID 공급자 서버는 GitLab이 계정을 만들거나 기존 계정과 로그인 정보를 매칭하기 위해 특정 정보를 전달해야 합니다. email은 전달해야 하는 최소한의 정보입니다. ID 공급자 서버가 이 정보를 제공하지 않으면 모든 SAML 요청이 실패합니다.

이 정보가 제공되는지 확인하세요.

이 오류를 야기할 수 있는 또 다른 문제는 ID 공급자가 올바른 정보를 보내지만 속성이 OmniAuth info 해시의 이름과 일치하지 않는 경우입니다. 이 경우 SAML 구성의 attribute_statements를 설정하여 SAML 응답의 속성 이름을 해당 OmniAuth info 해시 이름에 매핑해야 합니다.

사용자 로그인 배너 오류 메시지#

메시지: SAML authentication failed: SAML NameID is missing from your SAML response.#

SAML authentication failed: SAML NameID is missing from your SAML response. Please contact your administrator.라는 오류가 발생할 수 있습니다.

이 문제는 그룹 SSO를 사용하여 GitLab에 로그인하려고 하지만 SAML 응답에 NameID가 포함되어 있지 않을 때 발생합니다.

이 문제를 해결하려면:

• 관리자에게 IdP 계정에 NameID가 할당되어 있는지 확인하도록 문의하세요.
• SAML 디버깅 도구를 사용하여 SAML 응답에 유효한 NameID가 있는지 확인하세요.

메시지: SAML authentication failed: Extern uid has already been taken.#

SAML authentication failed: Extern uid has already been taken. Please contact your administrator to generate a unique external_uid (NameID).라는 오류가 발생할 수 있습니다.

이 문제는 그룹 SSO를 사용하여 기존 GitLab 계정을 SAML 아이덴티티에 연결하려고 하지만 현재 NameID를 가진 기존 GitLab 계정이 있을 때 발생합니다.

이 문제를 해결하려면 관리자에게 IdP 계정에 대한 고유한 Extern UID(NameID)를 다시 생성하도록 요청하세요. 이 새 Extern UID가 GitLab NameID 제약 조건을 준수하는지 확인하세요.

SAML 로그인으로 해당 GitLab 사용자를 사용하지 않으려면 GitLab 계정을 SAML 앱에서 연결 해제할 수 있습니다.

메시지: SAML authentication failed: User has already been taken#

로그인한 사용자가 이미 다른 아이덴티티에 SAML을 연결했거나 NameID 값이 변경된 것입니다. 가능한 원인 및 해결책은 다음과 같습니다:

메시지: SAML authentication failed: Email has already been taken#

사용자 계정은 다음 방법 중 하나로 만들어집니다:

• 사용자 등록
• OAuth를 통한 로그인
• SAML을 통한 로그인
• SCIM 프로비저닝

오류: 사용자가 이미 사용됨#

동시에 이 두 오류가 발생하면 ID 공급자가 제공한 NameID 대소문자가 해당 사용자의 이전 값과 정확히 일치하지 않음을 나타냅니다:

• SAML authentication failed: Extern UID has already been taken
• User has already been taken

이는 NameID를 일관된 값을 반환하도록 구성하면 방지할 수 있습니다. 개별 사용자에 대해 이를 수정하려면 사용자의 식별자를 변경해야 합니다. GitLab.com의 경우 사용자는 GitLab 계정에서 SAML 연결을 해제해야 합니다.

메시지: Request to link SAML account must be authorized#

ID 공급자의 SAML 앱에 GitLab 계정을 연결하려는 사용자가 추가되어 있는지 확인하세요.

또는 SAML 응답에 samlp:Response 태그의 InResponseTo 속성이 없을 수 있습니다. 이는 SAML gem에서 기대하는 값입니다. ID 공급자 관리자는 로그인이 서비스 공급자에 의해 시작되고 ID 공급자만에 의해 시작되지 않도록 해야 합니다.

메시지: There is already a GitLab account associated with this email address.#

사용자가 기존 GitLab.com 계정에 SAML을 수동으로 연결하려고 할 때 이 메시지가 표시될 수 있습니다:

There is already a GitLab account associated with this email address.
Sign in with your existing credentials to connect your organization's account

이 문제를 해결하려면 사용자가 올바른 GitLab 비밀번호를 사용하여 로그인하고 있는지 확인해야 합니다. 다음 두 조건이 모두 충족되는 경우 사용자는 먼저 비밀번호를 재설정해야 합니다:

• 계정이 SCIM에 의해 프로비저닝되었습니다.
• 처음으로 사용자 이름과 비밀번호로 로그인하는 경우.

메시지: SAML Name ID and email address do not match your user account#

사용자에게 "SAML Name ID and email address do not match your user account. Contact an administrator."라는 오류가 발생할 수 있습니다. 이 의미는:

• SAML이 보낸 NameID 값이 기존 SAML 아이덴티티의 extern_uid 값과 일치하지 않습니다. NameID와 extern_uid는 모두 대소문자를 구분합니다. 자세한 내용은 사용자 SAML 아이덴티티 관리를 참조하세요.
• SAML 응답에 이메일 주소가 포함되지 않았거나 이메일 주소가 사용자의 GitLab 이메일 주소와 일치하지 않습니다.

해결 방법은 GitLab 그룹 오너가 SAML API를 사용하여 사용자의 SAML extern_uid를 업데이트하는 것입니다. extern_uid 값은 SAML ID 공급자(IdP)가 보낸 Name ID 값과 일치해야 합니다. IdP 구성에 따라 이 값은 생성된 고유 ID, 이메일 주소 또는 기타 값일 수 있습니다.

오류: Certificate element missing in response (ds:x509certificate)#

이 오류는 IdP가 SAML 응답에 X.509 인증서를 포함하도록 구성되지 않았음을 나타냅니다:

Certificate element missing in response (ds:x509certificate) and not cert provided at settings

X.509 인증서는 응답에 포함되어야 합니다. 이 문제를 해결하려면 SAML 응답에 X.509 인증서를 포함하도록 IdP를 구성하세요.

자세한 내용은 IdP의 SAML 앱에 대한 추가 구성 문서를 참조하세요.

기타 사용자 로그인 문제#

NameID 확인#

문제 해결 시 인증된 사용자는 누구나 API를 사용하여 https://gitlab.com/api/v4/user를 방문하고 아이덴티티 아래의 extern_uid를 확인하여 GitLab이 자신의 사용자에게 연결한 NameID를 확인할 수 있습니다.

GitLab Self-Managed의 경우 관리자는 사용자 API를 사용하여 동일한 정보를 볼 수 있습니다.

그룹에 SAML을 사용하는 경우 적절한 권한을 가진 역할의 그룹 멤버는 멤버 API를 사용하여 그룹 멤버의 그룹 SAML 아이덴티티 정보를 볼 수 있습니다.

이를 SAML 디버깅 도구로 메시지를 디코딩하여 ID 공급자가 보낸 NameID와 비교할 수 있습니다. 사용자를 식별하려면 이 값이 일치해야 합니다.

로그인 "루프"에 갇힘#

ID 공급자의 SAML 앱에서 GitLab 단일 로그온 URL(GitLab.com의 경우) 또는 인스턴스 URL(GitLab Self-Managed의 경우)이 "로그인 URL"(또는 유사하게 명명된 필드)로 구성되어 있는지 확인하세요.

GitLab.com의 경우 또는 사용자가 기존 GitLab.com 계정에 SAML을 연결해야 할 때 GitLab 단일 로그온 URL을 제공하고 사용자에게 처음 로그인 시 SAML 앱을 사용하지 말도록 안내하세요.

사용자가 404를 받음#

로그인이 성공적으로 완료된 후 사용자가 404를 받는 경우 IP 제한이 구성되어 있는지 확인하세요. IP 제한 설정은 다음에서 구성됩니다:

• GitLab.com에서 그룹 수준.
• GitLab Self-Managed의 경우 인스턴스 수준.

그룹의 SAML SSO는 유료 기능이므로 구독이 만료되면 GitLab.com에서 SAML SSO를 사용하여 로그인할 때 404 오류가 발생할 수 있습니다. 모든 사용자가 SAML을 사용하여 로그인하려고 할 때 404를 받으면 이 SAML SSO 네임스페이스에서 사용 중인 활성 구독이 있는지 확인하세요.

설정 확인 시 "verify configuration"을 사용할 때 404를 받으면 올바른 SHA-1 생성 핑거프린트를 사용했는지 확인하세요.

사용자가 처음 로그인하려고 하고 GitLab 단일 로그온 URL이 구성되지 않은 경우 404가 표시될 수 있습니다. 사용자 액세스 섹션에서 설명한 대로 그룹 오너가 사용자에게 URL을 제공해야 합니다.

최상위 그룹에 이메일 도메인별 멤버십 제한이 설정되어 있고 허용되지 않는 이메일 도메인을 가진 사용자가 SSO로 로그인하려고 하면 404를 받을 수 있습니다. 사용자에게 여러 계정이 있을 수 있으며 SAML 아이덴티티가 회사 도메인과 다른 이메일 주소를 가진 개인 계정에 연결되어 있을 수 있습니다. 이를 확인하려면 다음을 확인하세요:

• 최상위 그룹에 이메일 도메인별 멤버십 제한이 있습니다.
• 최상위 그룹의 감사 이벤트에서:
  • 해당 사용자에 대해 GROUP_SAML 인증으로 로그인 작업을 볼 수 있습니다.
  • SAML SSO에 대해 구성된 사용자 이름과 사용자의 사용자 이름이 동일한지 작성자 이름을 선택하여 확인합니다.
    • SAML SSO에 대해 구성한 사용자 이름과 다른 경우 사용자에게 개인 계정에서 SAML 아이덴티티 연결 해제를 요청하세요.

ID 공급자(IdP)에 로그인한 후 모든 사용자가 404를 받는 경우:

• assertion_consumer_service_url을 확인합니다:
  • GitLab의 HTTPS 엔드포인트와 일치시켜 GitLab 구성에서 확인합니다.
  • IdP에서 SAML 앱을 설정할 때 어설션 소비자 서비스 URL 또는 동등한 값으로 확인합니다.
• 404가 Azure IdP에서 너무 많은 그룹이 할당된 사용자와 관련된 것인지 확인합니다.
• IdP 서버와 GitLab의 클록이 동일한 시간으로 동기화되어 있는지 확인합니다.

IdP에 로그인한 후 일부 사용자가 404 오류를 받는 경우 먼저 사용자가 그룹에 추가된 다음 즉시 제거되면 어떤 감사 이벤트가 반환되는지 확인하세요. 또는 사용자가 성공적으로 로그인할 수 있지만 최상위 그룹의 멤버로 표시되지 않는 경우:

• 사용자가 SAML ID 공급자에 추가되었는지, 구성된 경우 SCIM에도 추가되었는지 확인합니다.

• SCIM API를 사용하여 사용자의 SCIM 아이덴티티의 active 속성이 true인지 확인합니다. active 속성이 false인 경우 다음 중 하나를 수행하여 문제를 해결할 수 있습니다:

  • SCIM ID 공급자에서 사용자 동기화를 트리거합니다. 예를 들어 Azure에는 "주문형 프로비저닝" 옵션이 있습니다.

  • SCIM ID 공급자에서 사용자를 제거하고 다시 추가합니다.

  • 가능한 경우 사용자에게 계정 연결 해제 후 계정 연결을 안내합니다.

  • 그룹의 SCIM 토큰을 사용하여 내부 SCIM API를 사용하여 사용자의 SCIM 아이덴티티를 업데이트합니다. 그룹의 SCIM 토큰을 모르는 경우 토큰을 재설정하고 새 토큰으로 SCIM ID 공급자 앱을 업데이트합니다. 요청 예시:

    curl --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer " --header "Content-Type: application/scim+json" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }'
    

로그인 후 500 오류#

SAML 로그인 페이지에서 리디렉션된 후 GitLab에서 "500 오류"가 발생하면 다음을 나타낼 수 있습니다:

• GitLab이 SAML 사용자의 이메일 주소를 가져올 수 없었습니다. ID 공급자가 email 또는 mail 클레임 이름을 사용하여 사용자의 이메일 주소가 포함된 클레임을 제공하는지 확인합니다.
• gitlab.rb 파일에 설정된 identity provider_cert_fingerprint 또는 identity provider_cert 파일의 인증서가 올바르지 않습니다.
• gitlab.rb 파일이 identity provider_cert_fingerprint를 활성화하도록 설정되어 있지만 identity provider_cert가 제공되거나 그 반대의 경우입니다.

로그인 후 422 오류#

SAML 로그인 페이지에서 리디렉션된 후 GitLab에서 "422 오류"가 발생하면 ID 공급자에서 어설션 소비자 서비스(ACS) URL이 잘못 구성되어 있을 수 있습니다.

ACS URL이 https://gitlab.example.com/users/auth/saml/callback을 가리키는지 확인합니다. 여기서 gitlab.example.com은 GitLab 인스턴스의 URL입니다.

ACS URL이 올바른데도 오류가 계속 발생하면 다른 문제 해결 섹션을 검토하세요.

허용되지 않는 이메일이 있는 422 오류#

"Email is not allowed for sign-up. Please use your regular email address."라는 422 오류가 발생할 수 있습니다.

이 메시지는 도메인 허용 목록 또는 차단 목록 설정에서 도메인을 추가하거나 제거해야 함을 나타낼 수 있습니다.

사전 조건:

• 관리자 액세스.

이 해결 방법을 구현하려면:

1. 오른쪽 상단 모서리에서 관리자를 선택합니다.
2. 설정 > 일반을 선택합니다.
3. 가입 제한을 확장합니다.
4. 가입에 허용된 도메인 및 가입에 차단된 도메인에서 적절히 도메인을 추가하거나 제거합니다.
5. 변경 사항 저장을 선택합니다.

SAML을 통해 로그인할 때 사용자가 차단됨#

SAML을 통해 로그인할 때 사용자가 차단되는 가장 일반적인 이유는 다음과 같습니다:

• 구성에서 gitlab_rails['omniauth_block_auto_created_users'] = true가 설정되어 있고 이것이 사용자의 첫 번째 로그인입니다.
• required_groups가 구성되어 있지만 사용자가 그룹의 멤버가 아닙니다.

Google Workspace 문제 해결 팁#

로그인 시 Google에서 오류가 발생하는 경우 SAML 앱 오류 메시지에 대한 Google Workspace 문서가 디버깅에 도움이 됩니다. 특히 다음 403 오류에 주의하세요:

• app_not_configured
• app_not_configured_for_user

메시지: The member's email address is not linked to a SAML account#

이 오류는 SAML SSO 강제가 활성화된 GitLab.com 그룹(또는 그룹 내 서브그룹 또는 프로젝트)에 사용자를 초대하려고 할 때 나타납니다.

그룹에 사용자를 초대하려고 한 후 이 메시지가 표시되면:

1. 사용자가 SAML ID 공급자에 추가되었는지 확인합니다.
2. 사용자에게 기존 계정이 있는 경우 기존 GitLab.com 계정에 SAML 연결을 요청합니다. 그렇지 않으면 사용자에게 ID 공급자의 대시보드를 통해 GitLab.com에 액세스하거나 수동으로 가입하여 새 계정에 SAML을 연결하여 GitLab.com 계정을 만들도록 요청합니다.
3. 사용자가 최상위 그룹의 멤버인지 확인합니다.

또한 로그인 후 404를 받는 사용자 문제 해결을 참조하세요.

메시지: The SAML response did not contain an email address.#

다음 오류가 표시되는 경우:

The SAML response did not contain an email address.
Either the SAML identity provider is not configured to send the attribute, or the
identity provider directory does not have an email address value for your user

이 오류는 다음과 같은 경우에 나타납니다:

• SAML 응답에 email 또는 mail 속성의 사용자 이메일 주소가 포함되어 있지 않습니다.
• 사용자가 SAML 연결을 시도하지만 아직 아이덴티티 확인 프로세스를 완료하지 않은 경우.

SAML ID 공급자가 지원되는 메일 속성을 보내도록 구성되어 있는지 확인하세요:

<Attribute Name="email">
  <AttributeValue>user@example.com‹/AttributeValue>
</Attribute>

http://schemas.xmlsoap.org/ws/2005/05/identity/claims 및 http://schemas.microsoft.com/ws/2008/06/identity/claims/와 같은 구문으로 시작하는 속성 이름은 GitLab 16.7부터 기본적으로 지원됩니다.

<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress">
  <AttributeValue>user@example.com‹/AttributeValue>
</Attribute>

글로벌 SAML 그룹 멤버십 잠금으로 서비스 계정 추가 불가#

글로벌 SAML 그룹 멤버십 잠금이 활성화된 경우 관리자만 UI를 통해 그룹 멤버와 서비스 계정을 관리할 수 있습니다. 그룹 오너가 서비스 계정을 관리해야 하는 경우 대신 그룹 멤버 API를 사용할 수 있습니다.

지원 지식 기반#

여전히 문제가 있는 경우 GitLab 지원 지식 기반을 참조하세요.