SAML 문제 해결

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

이 페이지는 SAML을 사용할 때 발생할 수 있는 문제에 대한 가능한 솔루션을 포함합니다:

SAML 디버깅 도구

SAML 응답은 base64로 인코딩되므로, 이를 실시간으로 디코딩하기 위해 다음 브라우저 플러그인을 권장합니다:

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

특히 주의해야 할 사항:

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

SAML 응답 생성

SAML 응답을 사용하여 ID 공급자를 사용하여 로그인하는 동안 전송된 속성 이름 및 값을 미리 볼 수 있습니다.

SAML 응답을 생성하려면:

  1. 하나의 브라우저 디버깅 도구를 설치하십시오.
  2. 새로운 브라우저 탭을 엽니다.
  3. SAML 트레이서 콘솔을 엽니다:
    • Chrome: 페이지의 컨텍스트 메뉴에서 검사를 선택한 다음, 개발자 콘솔에서 SAML 탭을 선택합니다.
    • Firefox: 브라우저 도구 모음에 있는 SAML-tracer 아이콘을 선택합니다.
  4. GitLab.com 그룹의 경우:
    • 그룹의 GitLab 단일 로그인 URL로 이동합니다.
    • 승인을 선택하거나 로그인해 봅니다.
  5. 자체 관리 인스턴스의 경우:
    • 인스턴스 홈페이지로 이동합니다.
    • 로그인하기 위해 SAML 로그인 버튼을 클릭합니다.
  6. SAML 응답이 다음과 유사한 트레이서 콘솔에 표시됩니다
    예제 SAML 응답.
  7. SAML 트레이서 내에서 내보내기 아이콘을 선택하여 응답을 JSON 형식으로 저장합니다.

수동으로 SAML 응답 생성


개요는 브라우저 플러그인을 사용하지 않고 SAML 응답 생성에 대한 이 비디오를 참조하세요. GitLab Support에서 업로드했습니다.

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

  1. 새로운 브라우저에서 마우스 오른쪽 버튼을 클릭하고 검사를 클릭하여 DevTools 창을 엽니다.
  2. 네트워크 탭을 선택합니다. 로그 보존이 선택되어 있는지 확인합니다.
  3. 브라우저 페이지로 전환하고 SAML SSO를 사용하여 GitLab에 로그인합니다.
  4. DevTools 창으로 돌아가서 callback 이벤트를 필터링합니다.
  5. callback 이벤트의 Payload 탭을 선택하고 마우스 오른쪽 버튼을 클릭하여 값을 복사합니다.
  6. 이 값을 다음 명령어에 붙여넣습니다: echo "<value>" | base64 --decode > saml_response.xml.

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

    코드 편집기에 XML “예쁘게” 처리하는 도구가 설치되어 있다면 응답을 더 읽기 쉽게 자동으로 형식화할 수 있을 것입니다.

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

Tier: Free, Premium, Ultimate Offering: Self-managed

SAML 로그인에 대한 자세한 정보는 audit_json.log 파일에서 확인할 수 있습니다.

예를 들어 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"
  },
}

GitLab이 SAML 제공자로부터 수신한 사용자 세부 정보는 auth_json.log에서 확인할 수 있습니다. 예:

{
  "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을 문제 해결할 수 있습니다:

구성 확인

편의를 위해, 지원 팀에서 사용하는 예제 리소스를 포함했습니다. 이들이 SAML 앱 구성을 확인하는 데 도움이 될 수 있지만, 현재의 제3자 제품 상태를 반영한다고 보장할 수는 없습니다.

핑거프린트 계산

idp_cert_fingerprint를 사용하는 경우, SHA1 핑거프린트여야 합니다. SHA1 핑거프린트를 계산하려면, 인증서 파일을 다운로드하고 다음을 실행하세요:

openssl x509 -in <filename.crt> -noout -fingerprint -sha1

filename.crt를 인증서 파일의 이름으로 바꾸세요.

SSO 인증서 업데이트

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

구성 오류

유효하지 않은 청중

이 오류는 아이덴티티 제공자가 GitLab을 SAML 요청의 유효한 발신자 및 수신자로 인식하지 못함을 의미합니다. 다음 사항을 확인하세요:

  • GitLab 콜백 URL을 아이덴티티 제공자 서버의 승인된 청중에 추가하세요.
  • issuer 문자열에 후행 공백이 없는지 확인하세요.

키 검증 오류, 다이제스트 불일치 또는 핑거프린트 불일치

이 오류들은 모두 SAML 인증서와 관련이 있습니다. SAML 요청은 핑거프린트, 인증서 또는 검증기를 사용하여 검증해야 합니다.

이 요구 사항을 염두에 두고 다음 사항을 고려하세요:

  • 핑거프린트를 사용하는 경우, 올바른 SHA1 핑거프린트여야 합니다. 올바른 SHA1 핑거프린트를 사용하고 있는지 확인하려면:
    1. 인증서 파일을 다시 다운로드하세요.
    2. 핑거프린트 계산 하세요.
    3. 핑거프린트를 idp_cert_fingerprint에서 제공된 값과 비교하세요. 값이 같아야 합니다.
  • 설정에서 인증서가 제공되지 않는 경우, 핑거프린트 또는 핑거프린트 검증기를 제공해야 하며, 서버의 응답에는 인증서(<ds:KeyInfo><ds:X509Data><ds:X509Certificate>)가 포함되어야 합니다.
  • 설정에서 인증서가 제공되는 경우, 요청에 인증서를 포함할 필요가 없습니다. 이 경우 핑거프린트 또는 핑거프린트 검증자는 선택 사항입니다.

위에 설명된 시나리오가 유효하지 않으면 요청이 언급된 오류 중 하나로 실패합니다.

누락된 청구 또는 Email can't be blank 오류

아이덴티티 제공자 서버는 GitLab이 계정을 생성하거나 로그인 정보를 기존 계정과 일치시키기 위해 필요한 특정 정보를 전달해야 합니다. email은 전달해야 하는 최소한의 정보입니다. 아이덴티티 제공자 서버가 이 정보를 제공하지 않으면 모든 SAML 요청이 실패합니다.

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

또 다른 문제는 아이덴티티 제공자가 올바른 정보를 전송하더라도 속성이 OmniAuth info 해시의 이름과 일치하지 않을 때 발생할 수 있습니다. 이 경우, SAML 구성에서 attribute_statements를 설정하여 SAML 응답의 속성 이름을 해당 OmniAuth info 해시 이름에 매핑해야 합니다.

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

메시지: “SAML 인증 실패: SAML NameID가 SAML 응답에서 누락되었습니다.”

SAML 인증 실패: SAML NameID가 SAML 응답에서 누락되었습니다. 관리자가 연락하시기 바랍니다.라는 오류가 발생할 수 있습니다.

이 문제는 Group SSO를 사용하여 GitLab에 로그인하려고 시도할 때 발생하지만, SAML 응답에 NameID가 포함되지 않은 경우입니다.

이 문제를 해결하려면:

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

메시지: “SAML 인증 실패: 외부 uid가 이미 사용 중입니다.”

SAML 인증 실패: 외부 uid가 이미 사용 중입니다. 고유한 external_uid (NameID)를 생성하도록 관리자가 연락하시기 바랍니다.라는 오류가 발생할 수 있습니다.

이 문제는 Group SSO를 사용하여 기존 GitLab 계정을 SAML ID와 연결하려고 시도할 때 발생하지만, 현재 NameID와 일치하는 기존 GitLab 계정이 있을 때 발생합니다.

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

SAML 로그인을 위해 해당 GitLab 사용자를 사용하고 싶지 않은 경우, SAML 앱에서 GitLab 계정을 연결 해제할 수 있습니다.

메시지: “SAML 인증 실패: 사용자가 이미 존재합니다”

로그인한 사용자는 이미 다른 ID에 SAML이 연결되어 있거나 NameID 값이 변경되었습니다.

여기 가능한 원인과 해결책이 있습니다:

원인 해결책
동일한 사용자에 대해 여러 SAML ID를 연결하려고 했습니다(주어진 ID 공급자의 경우). 로그인할 수 있는 ID를 변경하세요. 그렇게 하려면, 로그인하려는 GitLab 계정에서 이전 SAML ID를 연결 해제하세요 하고 다시 로그인 시도하세요.
사용자가 SSO 식별 요청을 할 때마다 NameID가 변경됩니다. NameID가 Transient 형식으로 설정되지 않았는지 확인하거나, 이후 요청에서 NameID가 변경되지 않는지 확인하세요.

메시지: “SAML 인증 실패: 이메일이 이미 사용 중입니다”

원인 해결책
GitLab에 해당 이메일 주소를 가진 사용자 계정이 이미 존재하지만, 사용자가 자신의 계정에 SAML ID가 연결되어 있지 않은 경우입니다. 사용자가 계정을 연결해야 합니다.

사용자 계정은 다음 방법 중 하나로 생성됩니다:

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

오류: 사용자가 이미 존재합니다

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

  • SAML 인증 실패: 외부 UID가 이미 사용 중입니다.
  • 사용자가 이미 존재합니다.

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

메시지: “SAML 계정 연결 요청은 승인되어야 합니다”

GitLab 계정을 연결하려는 사용자가 ID 제공자의 SAML 앱 내에서 사용자로 추가되었는지 확인하십시오.

또는 SAML 응답에 InResponseTo 속성이 누락되었을 수 있습니다. 이는 SAML gem에서 예상되는 사항입니다.

ID 제공자 관리자는 로그인이 ID 제공자만이 아닌 서비스 제공자에 의해 시작되도록 해야 합니다.

메시지: 이미 이 이메일 주소에 연결된 GitLab 계정이 있습니다.

Tier: Premium, Ultimate Offering: GitLab.com

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

이미 이 이메일 주소에 연결된 GitLab 계정이 있습니다.
기존 자격 증명으로 로그인하여 조직의 계정을 연결하세요.

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

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

메시지: “SAML Name ID와 이메일 주소가 사용자 계정과 일치하지 않습니다”

Tier: Premium, Ultimate Offering: GitLab.com

사용자는 “SAML Name ID와 이메일 주소가 사용자 계정과 일치하지 않습니다. 관리자에게 문의하세요.”라는 오류 메시지를 받을 수 있습니다. 이는 다음을 의미합니다:

  • 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, 이메일 주소 또는 기타 값이 될 수 있습니다.

오류: 응답에서 인증서 요소 누락 (ds:x509certificate)

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

응답에서 인증서 요소 누락 (ds:x509certificate) 및 설정에서 제공된 인증서 없음

X.509 인증서는 응답에 포함되어야 합니다. 이 문제를 해결하려면 IdP를 구성하여 SAML 응답에 X.509 인증서를 포함하십시오.

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

기타 사용자 로그인 문제

NameID 확인

문제 해결 시, 인증된 모든 사용자가 API를 사용하여 https://gitlab.com/api/v4/user에 방문하여 GitLab이 사용자에게 이미 연결한 NameID를 확인할 수 있습니다. 여기서 identities 아래의 extern_uid를 확인합니다.

셀프 매니지드의 경우 관리자는 사용자 API를 사용하여 동일한 정보를 볼 수 있습니다.

그룹에 대해 SAML을 사용할 때, 적절한 권한이 있는 역할의 그룹 구성원은 구성원 API를 사용하여 그룹 구성원의 SAML 신원 정보를 확인할 수 있습니다.

그런 다음 이는 ID 제공자가 전송하는 NameID와 비교할 수 있으며, 메시지를 SAML 디버깅 도구로 디코딩하여 비교합니다. 사용자를 식별하려면 이들이 일치해야 합니다.

로그인 “루프”에 갇힌 경우

GitLab single sign-on URL (GitLab.com의 경우) 또는 인스턴스 URL (셀프 관리의 경우)이 ID 공급자의 SAML 앱에서 “로그인 URL” (또는 비슷한 이름의 필드)로 구성되어 있는지 확인하세요.

GitLab.com의 경우, 사용자가 기존 GitLab.com 계정과 SAML을 연결해야 할 때 대체로 GitLab single sign-on URL을 제공하고 첫 로그인 시 SAML 앱을 사용하지 않도록 사용자에게 안내합니다.

사용자가 404 오류를 받는 경우

Tier: Premium, Ultimate Offering: GitLab.com

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

그룹에 대한 SAML SSO는 유료 기능이므로, 귀하의 구독이 만료되면 GitLab.com에서 SAML SSO를 사용하여 로그인할 때 404 오류가 발생할 수 있습니다.

모든 사용자가 SAML을 사용하여 로그인할 때 404를 받는 경우, 이 SAML SSO 네임스페이스에서 사용 중인 활성 구독을 확인하세요.

설정 중 “구성 확인”을 사용할 때 404를 받으면, 올바른 SHA-1 생성 지문을 사용했는지 확인하세요.

사용자가 처음 로그인하려고 할 때 GitLab single sign-on URL이 구성되지 않았다면, 404를 볼 수 있습니다.

사용자 접근 섹션에 설명된 대로, 그룹 소유자가 URL을 사용자에게 제공해야 합니다.

상위 그룹이 이메일 도메인으로 회원 제한을 설정한 경우, 허용되지 않는 이메일 도메인을 가진 사용자가 SSO로 로그인하려고 시도하면 해당 사용자가 404를 받을 수 있습니다. 사용자는 여러 계정을 가질 수 있으며, 그들의 SAML ID가 회사 도메인과 다른 이메일 주소를 가진 개인 계정에 연결될 수 있습니다. 이를 확인하기 위해 다음을 검증하세요:

  • 상위 그룹이 이메일 도메인으로 회원 제한이 되어 있는지.
  • 상위 그룹의 감사 이벤트에서:
    • 해당 사용자에 대해 GROUP_SAML 인증으로 로그인 액션이 표시되는지.
    • 사용자의 사용자 이름이 SAML SSO에 대해 구성한 사용자 이름과 동일한지 확인합니다. Author 이름을 선택하여 확인합니다.
      • 사용자 이름이 SAML SSO에 대해 구성한 사용자 이름과 다르다면, 사용자에게 개인 계정에서 SAML ID를 분리할 것을 요청하세요.

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

일부 사용자가 IdP에 로그인한 후 404를 받는 경우, 먼저 감사 이벤트를 검증하여 사용자가 그룹에 추가된 후 즉시 제거되는지 확인하세요. 또는 사용자가 성공적으로 로그인했지만 상위 그룹의 멤버로 나타나지 않는 경우:

  • 사용자가 SAML ID 공급자에 추가되었는지, 그리고 SCIM이 구성되어 있는지 확인하세요.

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

    • SCIM ID 공급자에서 사용자 동기화를 트리거하세요. 예를 들어, Azure에는 “수요에 따라 프로비저닝” 옵션이 있습니다.
    • SCIM ID 공급자에서 사용자를 제거한 후 다시 추가하세요.
    • 가능하다면 사용자가 계정을 분리한 후 계정을 연결하도록 하세요.
    • 내부 SCIM API를 사용하여 그룹의 SCIM 토큰을 사용하여 사용자의 SCIM ID를 업데이트하세요. 그룹의 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 <SCIM_TOKEN>" --header "Content-Type: application/scim+json" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }'

로그인 후 500 오류

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

GitLab에서 SAML 로그인 페이지에서 리다이렉션된 후 “500 오류”가 표시되면, 다음을 나타낼 수 있습니다:

  • GitLab이 SAML 사용자의 이메일 주소를 가져올 수 없습니다. 신원 공급자가 email 또는 mail이라는 클레임 이름을 사용하여 사용자의 이메일 주소가 포함된 클레임을 제공하는지 확인하세요.

  • gitlab.rb 파일에 설정된 인증서의 identity provider_cert_fingerprint 또는 identity provider_cert 파일이 잘못되었습니다.

  • gitlab.rb 파일이 identity provider_cert_fingerprint를 활성화하도록 설정되어 있고, identity provider_cert가 제공되고 있거나 그 반대일 수 있습니다.

로그인 후 422 오류

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

GitLab에서 SAML 로그인 페이지에서 리다이렉션된 후 “422 오류”가 표시되면, 신원 공급자의 Assertion Consumer Service (ACS) URL이 잘못 구성된 것일 수 있습니다.

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

ACS URL이 올바른 경우에도 여전히 오류가 발생하면, 다른 문제 해결 섹션을 검토하세요.

허용되지 않는 이메일로 인한 422 오류

“가입에 허용되지 않는 이메일입니다. 일반 이메일 주소를 사용하세요.”라는 422 오류가 발생할 수 있습니다.

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

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

  1. 왼쪽 사이드바에서, 하단의 Admin을 선택하세요.

  2. Settings > General을 선택하세요.

  3. Sign-up restrictions를 확장하세요.

  4. Allowed domains for sign-ups 및 Denied domains for sign-ups에 적절히 도메인을 추가하거나 제거하세요.

  5. Save changes를 선택하세요.

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

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

SAML을 통해 로그인할 때 사용자가 차단되는 가장 가능성이 높은 이유는 다음과 같습니다:

  • 구성에서 gitlab_rails['omniauth_block_auto_created_users'] = true가 설정되어 있고, 이 사용자가 처음 로그인하는 경우입니다.

  • required_groups가 구성되어 있지만 사용자가 그 중 하나의 구성원이지 않은 경우입니다.

Google Workspace 문제 해결 팁

SAML 앱 오류 메시지에 대한 Google Workspace 문서는 Google로부터 로그인할 때 오류가 표시되는 경우에 디버깅하는 데 유용합니다. 다음의 403 오류에 특히 주의하세요:

  • app_not_configured
  • app_not_configured_for_user

메시지: “회원의 이메일 주소가 SAML 계정에 연결되어 있지 않습니다”

Tier: Premium, Ultimate Offering: GitLab.com

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

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

  1. 사용자가 SAML 신원 공급자에 추가되었는지 확인하세요.

  2. 사용자가 기존 GitLab.com 계정이 있는 경우 SAML을 기존 GitLab.com 계정에 링크하도록 요청하세요. 그렇지 않으면 사용자가 신원 공급자의 대시보드를 통해 GitLab.com에 접근하여 GitLab.com 계정을 생성하거나 수동으로 가입하고 새로운 계정에 SAML을 링크하도록 요청하세요.

  3. 사용자가 상위 그룹의 구성원인지 확인하세요.

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

메시지: SAML 응답에 이메일 주소가 포함되어 있지 않습니다.

이 오류가 표시되면:

SAML 응답에 이메일 주소가 포함되어 있지 않습니다.
SAML IdP(Identity Provider)가 속성을 전송하도록 구성되지 않았거나
IdP 디렉토리에 사용자에 대한 이메일 주소 값이 없습니다.

이 오류는 다음과 같은 경우에 발생합니다:

  • SAML 응답에 email 또는 mail 속성에 사용자의 이메일 주소가 포함되어 있지 않습니다.
  • 사용자가 자신의 계정에 SAML을 연결하려고 하지만 아직 신원 확인 프로세스를 완료하지 않았습니다.

SAML IdP가 지원되는 메일 속성을 전송하도록 구성되어 있는지 확인하세요:

<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>