SAML 디버깅 도구
- SAML 응답 생성
  - 수동으로 SAML 응답 생성
SAML 로그 검색
GitLab SAML 테스트
구성 확인
- 지문 계산
SSO 인증서 업데이트
구성 오류
사용자 로그인 배너 오류 메시지
기타 사용자 로그인 문제
Google Workspace 문제 해결 팁
메시지: “회원의 이메일 주소가 SAML 계정에 연결되지 않았습니다”
메시지: SAML 응답에 이메일 주소가 포함되어 있지 않습니다.

SAML 문제 해결

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

이 페이지에는 다음을 사용할 때 만날 수 있는 문제에 대한 가능한 해결 방법이 포함되어 있습니다.

SAML SSO for GitLab.com 그룹.
자체 관리형 인스턴스 수준의 SAML OmniAuth Provider.
Switchboard를 사용하여 GitLab Dedicated 인스턴스에 SAML을 구성합니다.

SAML 디버깅 도구

SAML 응답은 base64로 인코딩되므로 다음과 같은 브라우저 플러그인을 추천합니다.

SAML-tracer (Firefox용).
SAML Message Decoder (Chrome용).

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

특히 다음 사항에 유의하십시오:

사용자가 서명하고 있는지 확인하는 데 사용되는 NameID. 사용자가 이전에 로그인했다면, 저장된 값과 일치해야 합니다.
우리가 응답 서명을 확인하는 데 필요한 X509Certificate의 존재.
SubjectConfirmation 및 Conditions 구성 오류 시 발생할 수 있는 오류.

SAML 응답 생성

SAML 응답을 사용하여 ID 공급자를 사용하여 로그인을 시도하면서 assertions 목록으로 전송된 속성 이름과 값에 대한 미리보기를 제공합니다.

SAML 응답을 생성하려면:

브라우저 디버깅 툴 중 하나를 설치합니다.
새 브라우저 탭을 엽니다.
SAML 추적기 콘솔을 엽니다:
- Chrome: 페이지의 콘텍스트 메뉴에서 검사를 선택하고, 개발자 콘솔에서 SAML 탭을 선택합니다.
- Firefox: 브라우저 툴바에 있는 SAML-tracer 아이콘을 선택합니다.
GitLab.com 그룹의 경우:
- 그룹의 GitLab 단일 로그인 URL로 이동합니다.
- 승인을 선택하거나 로그인을 시도합니다.
자체 관리형 인스턴스의 경우:
- 인스턴스 홈페이지로 이동합니다.
- SAML 로그인 버튼을 클릭하여 로그인합니다.
콘솔에서 예상되는 예시 SAML 응답과 유사한 SAML 응답이 표시됩니다.
SAML 추적기에서 내보내기 아이콘을 선택하여 응답을 JSON 형식으로 저장합니다.

수동으로 SAML 응답 생성

개요는 다음과 같습니다. 브라우저 플러그인을 사용하지 않고(Chrome을 사용하여) 수동으로 SAML 응답 생성하는 비디오를 GitLab 지원팀이 업로드했습니다.

브라우저가 무엇이든 상관없이 다음과 같은 프로세스입니다:

새 브라우저에서 마우스 오른쪽 버튼을 클릭하고 검사를 선택하여 DevTools 창을 엽니다.
네트워크 탭을 선택합니다. 로그 유지가 선택되어 있는지 확인합니다.
브라우저 페이지로 전환하여 SAML SSO를 사용하여 GitLab에 로그인합니다.
DevTools 창으로 다시 전환하여 callback 이벤트를 필터링합니다.
callback 이벤트의 Payload 탭을 선택하고 값을 복사하기 위해 마우스 오른쪽 버튼을 클릭합니다.
이 값을 새로운 명령어에 붙여 넣고 다음 명령을 실행합니다: echo "<value>" | base64 --decode > saml_response.xml.
saml_response.xml을 코드 편집기에서 엽니다.
코드 편집기에 XML “prettifier”가 설치된 경우 응답을 자동으로 읽기 쉽도록 형식을 지정할 수 있어야 합니다.

SAML 로그 검색

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

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

구성 확인

편리를 위해 지원팀이 사용하는 예제 리소스를 포함했습니다. SAML 앱 구성을 검증하는 데 도움이 될 수 있지만, 현재 제3자 제품의 현재 상태를 반영하지는 않을 수 있습니다.

지문 계산

idp_cert_fingerprint를 사용하는 경우 SHA1 지문이어야 합니다. SHA1 지문을 계산하려면 인증서 파일을 다운로드하고 다음을 실행하십시오:

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

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

SSO 인증서 업데이트

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

구성 오류

잘못된 수신자

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

GitLab 콜백 URL을 ID 제공자 서버의 승인 수신자에 추가합니다.
issuer 문자열에 후행 공백을 피합니다.

키 유효성 검사 오류, 다이제스트 불일치 또는 지문 불일치

이러한 오류는 모두 SAML 인증서에서 나옵니다. SAML 요청은 지문, 인증서 또는 유효성 검사기를 사용하여 유효성을 검사해야 합니다.

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

지문을 사용하는 경우 올바른 SHA1 지문이어야 합니다. 올바른 SHA1 지문을 사용 중인지 확인하려면:
1. 인증서 파일을 다시 다운로드합니다.
2. 지문을 계산합니다.
3. 지문을 idp_cert_fingerprint에서 제공된 값과 비교합니다. 값은 동일해야 합니다.
설정에 인증서가 제공되지 않은 경우, 지문 또는 지문 유효성 검사기를 제공해야하며 응답에는 인증서(<ds:KeyInfo><ds:X509Data><ds:X509Certificate>)가 포함되어야 합니다.
설정에 인증서가 제공된 경우, 요청에 더 이상 포함되어 있지 않아야 합니다. 이 경우 지문 또는 지문 유효성 검사기는 선택 사항입니다.

위에 설명된 시나리오 중 어느 것도 유효하지 않으면 요청은 위에서 언급된 오류 중 하나와 실패합니다.

누락된 클레임 또는 `이메일은 비어 있을 수 없습니다` 오류

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

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

이 경우 동일한 정보가 ID 제공자에서 전송되지만 속성이 OmniAuth info 해시의 이름과 일치하지 않으면 이 오류가 발생할 수 있습니다. 이 경우, SAML 구성에서 attribute_statements를 설정하여 SAML 응답 속성 이름을 해당 OmniAuth info 해시 이름에 매핑해야 합니다.

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

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

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

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

이 문제를 해결하려면:

관리자에게 문의하여 IdP 계정이 할당된 NameID를 확인합니다.
SAML 디버깅 도구를 사용하여 SAML 응답에 유효한 ‘NameID’가 있는지 확인하세요.

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

SAML 인증 실패: 외부 uid가 이미 사용 중입니다. 관리자에게 문의하여 고유한 외부 UID(NameID)를 생성하세요.라는 오류가 발생할 수 있습니다.

이 문제는 그룹 SSO를 사용하여 기존 GitLab 계정을 SAML ID로 링크하려고 시도하지만 현재 NameID로 기존 GitLab 계정이 있는 경우 발생합니다.

이 문제를 해결하려면, 관리자에게 현재 NameID에 대해 고유한 외부 UID를 다시 생성하도록 요청하세요. 이 새로운 외부 UID가 GitLab NameID 제약 조건을 준수하는지 확인하세요.

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

메시지: “SAML 인증 실패: 사용자가 이미 선택되었습니다.”

로그인한 사용자가 이미 다른 ID와 SAML이 연결되어 있거나 NameID 값이 변경된 경우가 있습니다. 가능한 원인 및 해결책은 다음과 같습니다:

원인	해결책
특정 ID 제공자에 대해 동일한 사용자에게 여러 SAML ID를 링크하려고 시도했습니다.	다른 ID로 로그인합니다. 이를 위해 이전 SAML ID를 GitLab 계정 해제하고 다시 로그인을 시도하기 전에 GitLab 계정에서 이전 SAML ID를 해제하세요.
사용자가 SSO 식별을 요청할 때마다 `NameID`가 변경됩니다.	Check the `NameID`가 `Transient` 형식으로 설정되지 않았는지 또는 `NameID`가 연속해서 변경되지 않는지 확인하세요.

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

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

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

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

오류: 사용자가 이미 존재함

동시에 이러한 두 가지 오류를 받는다면, 식별 제공자가 제공한 NameID의 대문자 사용이 해당 사용자의 이전 값과 정확히 일치하지 않았다는 것을 시사합니다:

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

이를 방지하기 위해서는 NameID를 일관된 값으로 반환하도록 구성해야 합니다. 개별 사용자의 경우 식별자를 변경하여 문제를 해결할 수 있습니다. GitLab.com의 경우 사용자는 GitLab 계정과의 SAML 연결 해제를 해야 합니다.

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

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

또는 SAML 응답에는 samlp:Response 태그 내의 InResponseTo 속성이 누락될 수도 있는데, 이는 SAML gem에서 예상되는 것입니다. 식별 제공자 관리자는 로그인을 서비스 제공자뿐 아니라 식별 제공자에서도 시작했는지 확인해야 합니다.

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

Tier: 프리미엄, 얼티밋 Offering: GitLab.com

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

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

이 문제를 해결하려면 사용자는 올바른 GitLab 비밀번호를 사용하는지 확인해야 합니다. 다음 중 하나 이상이 해당되는 경우 사용자는 먼저 비밀번호를 재설정해야 합니다:

계정이 SCIM을 통해 프로비저닝되었으며
사용자가 처음으로 사용자 이름과 비밀번호로 로그인하는 경우

메시지: “SAML Name ID 및 이메일 주소가 사용자 계정과 일치하지 않음”

Tier: 프리미엄, 얼티밋 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 식별 공급자(IdP)에서 보낸 Name ID 값과 일치해야 합니다. IdP 구성에 따라 고유 ID, 이메일 주소 또는 다른 값을 사용할 수 있습니다.

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

이 오류는 IdP가 SAML 응답에 X.509 인증서를 포함하도록 설정되지 않은 것을 시사합니다:

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

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

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

기타 사용자 로그인 문제

`NameID` 확인

문제 해결을 위해 모든 인증된 사용자는 다음을 방문하여 GitLab이 해당 사용자에게 연결한 NameID를 확인할 수 있습니다: https://gitlab.com/api/v4/user 및 식별 자격 증명 아래의 extern_uid를 확인하는 것입니다.

자체 관리형의 경우, 관리자는 사용자 API를 사용하여 동일한 정보를 볼 수 있습니다.

그룹의 SAML을 사용하는 경우 해당 그룹의 역할이 있는 그룹 멤버들은 멤버 API를 사용하여 해당 그룹 멤버의 그룹 SAML 식별 정보를 볼 수 있습니다.

그 후에는 식별 제공자가 보내는 NameID와 비교하기 위해 SAML 디버깅 도구를 사용하여 메시지를 디코딩해야 합니다. 우리는 이를 통해 사용자를 식별하는 데 사용합니다.

로그인 “루프”에 갇힘

GitLab 단일 로그인 URL(GitLab.com의 경우)이나 인스턴스 URL(자체 관리형의 경우)이 식별 제공자의 SAML 앱의 “로그인 URL”(또는 유사한 필드)로 구성되었는지 확인하십시오.

GitLab.com의 경우, 사용자가 기존 GitLab.com 계정에 SAML을 연결해야 하는 경우, GitLab 단일 로그인 URL을 제공하고 사용자에게 첫 번째 로그인 시 SAML 앱을 사용하지 말도록 안내해야 합니다.

사용자가 404를 받음

Tier: 프리미엄, 얼티밋 Offering: GitLab.com

사용자가 성공적으로 로그인 한 후 404를 수신하는 경우, IP 제한이 구성되어 있는지 확인하십시오. IP 제한 설정은 다음 위치에 구성됩니다:

GitLab.com에서는 그룹 수준.
GitLab 자체 관리형의 경우는 인스턴스 수준.

그룹용 SAML SSO는 유료 기능이므로 GitLab.com에서 SAML SSO를 사용하여 로그인할 때 구독이 만료되면 404 오류가 발생할 수 있습니다. SAML을 사용하여 로그인하려는 경우 모든 사용자가 404를 수신하면 사용 중인 구독이 있는지 확인하십시오.

“SAML 구성 확인”을 사용하여 설정 중에 404을 받는 경우, 정확한 SHA-1 생성 지문을 사용했는지 확인하십시오.

사용자가 처음으로 로그인하려고 하는데 GitLab 단일 로그인 URL이 구성되지 않았으면, 사용자가 404를 볼 수도 있습니다. 사용자 액세스 섹션에 기술된 대로, 그룹 소유자가 사용자에게 해당 URL을 제공해야 합니다.

최상위 그룹이 이메일 도메인으로 회원 제한을 설정한 경우, 허용되지 않는 이메일 도메인을 가진 사용자가 SSO로 로그인하려고 시도하는 경우 해당 사용자는 404를 받을 수 있습니다. 사용자는 여러 개의 계정을 가지고 있을 수 있으며, 그들의 SAML 식별이 회사 도메인과 다른 이메일 주소를 가진 개인 계정과 연결되어 있을 수 있습니다. 이를 확인하려면 다음과 같은 사항을 확인하십시오:

최상위 그룹이 이메일 도메인으로 회원제한을 설정했는지 확인하십시오.
최상위 그룹의 감사 이벤트에 대한:
- 해당 사용자를 위해 그룹 SAML 인증으로 로그인함 동작을 볼 수 있는지 확인하십시오.
- 사용자의 사용자 이름이 SAML SSO에 구성한 사용자 이름과 동일한지 확인하십시오.
  - 사용자 이름이 SAML SSO에 구성한 사용자 이름과 다른 경우, 사용자에게 SAML 식별을 연결 해제해달라고 요청하십시오.

사용자가 IdP로 로그인한 후 모두 404를 받는 경우:

assertion_consumer_service_url을 확인하십시오:
- GitLab 구성에서 HTTPS 엔드포인트와 일치하도록 확인 [(/integration/saml.md#configure-saml-support-in-gitlab)하십시오.
- IdP의 SAML 앱을 설정할 때, Assertion Consumer Service URL 또는 해당 필드와 관련된지 확인하십시오.

특정 사용자 중 일부가 IdP로 로그인한 후 404를 받는 경우, 사용자가 그룹에 추가되고 즉시 제거되는 것에 대한 감사 이벤트를 확인하거나 사용자가 성공적으로 로그인할 수 있지만 최상위 그룹의 멤버로 표시되지 않는 경우:

사용자가 SAML 식별 제공자 및 구성된 경우 SCIM에 추가되었는지 확인하십시오.
SCIM 식별의 active 속성이 SCIM API를 사용하여 true로 설정되었는지 확인하십시오. active 속성이 false인 경우 문제를 해결하려면 다음 중 하나를 수행할 수 있습니다:
- 사용자를 SCIM 식별 제공자에서 동기화시킵니다. 예를 들어, Azure에는 “On Demand로 프로비저닝” 옵션이 있습니다.
- 사용자를 SCIM 식별 제공자에서 제거하고 다시 추가합니다.
- 사용자에게 가능한 경우 계정의 연결을 해제하고, 그런 다음 계정을 연결해달라고 요청하십시오.
- 내부 SCIM API를 사용하여 그룹의 SCIM 토큰을 사용하여 사용자의 SCIM 식별을 업데이트합니다. 그룹의 SCIM 토큰을 모르는 경우 토큰을 재설정하고, 새 토큰으로 SCIM 식별 공급자 앱을 업데이트합니다. 요청 예시:
```
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

SAML 로그인 페이지에서 되돌아올 때 GitLab에서 “500 에러”가 표시되는 경우, 다음 사항을 나타낼 수 있습니다:

GitLab이 SAML 사용자의 이메일 주소를 가져올 수 없습니다. 신원 제공자가 사용자의 이메일 주소를 포함한 클레임을 제공하는지 확인하세요. 클레임 이름에는 email 또는 mail이 포함되어야 합니다.
gitlab.rb 파일에 설정된 인증서 provider_cert_fingerprint 또는 provider_cert 파일이 잘못되었습니다.
gitlab.rb 파일이 provider_cert_fingerprint를 활성화하도록 설정되어 있고 provider_cert가 제공되고 있는 경우, 또는 그 반대의 경우입니다.

로그인 후 422 에러

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

SAML 로그인 페이지에서 리디렉션될 때 GitLab에서 “422 에러”가 표시되는 경우, 신원 제공자에 대한 올바르게 구성된 Assertion Consumer Service (ACS) URL이 있을 수 있습니다.

ACS URL이 올바른지 확인하고 여전히 에러가 발생하는 경우, 다른 Troubleshooting 섹션을 검토하세요.

허용되지 않은 이메일로 422 에러

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

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

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

왼쪽 사이드바에서 맨 아래에서 Admin을 선택하세요.
Settings > General을 선택하세요.
Sign-up restrictions를 확장하세요.
적절한 도메인을 가입 허용 도메인 및 가입 거부 도메인에 추가하거나 제거하세요.
변경 사항 저장을 선택하세요.

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

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

사용자가 SAML로 로그인할 때 차단된 이유는 다음과 같을 수 있습니다:

설정에서 gitlab_rails['omniauth_block_auto_created_users'] = true로 설정되어 사용자가 처음으로 로그인하는 경우입니다.
required_groups이 구성되었지만 사용자가 해당 그룹의 구성원이 아닌 경우입니다.

Google Workspace 문제 해결 팁

Google Workspace 문서인 SAML 앱 오류 메시지는 Google에서 로그인하는 동안 오류가 발생하는 경우에 디버깅에 도움이 됩니다. 특히 다음과 같은 403 에러에 특별한 주의를 기울이세요:

app_not_configured
app_not_cornfigured_for_user

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

Tier: Premium, Ultimate Offering: GitLab.com

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

이 메시지가 나타나는 경우:

사용자가 SAML 신원 제공자에 추가되었는지 확인하세요.
사용자가 이미 GitLab.com 계정에 SAML을 연결하도록 요청하거나 새로운 계정을 생성하도록 요청하세요. 그렇지 않은 경우 사용자에게 신원 제공자 대시보드를 통해 GitLab.com에 액세스하거나 수동으로 가입하여 새 계정에 SAML을 연결하도록 요청하세요.
사용자가 최상위 그룹의 구성원임을 확인하세요.

게다가 로그인 후 404을 받는 사용자의 문제 해결을 참조하세요.

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

이 오류가 표시되는 경우:

SAML 응답에 이메일 주소가 포함되어 있지 않습니다.
SAML 신원 제공자가 해당 사용자에게 속한 이메일 주소 속성을 보낼 수 있도록 구성되어 있지 않거나
신원 제공자 디렉터리에 사용자의 이메일 주소 값이 없는 경우

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

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

SAML 신원 제공자가 지원되는 메일 속성을 보낼 수 있도록 구성되어 있는지 확인하세요:

<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 디버깅 도구

SAML 응답 생성

수동으로 SAML 응답 생성

SAML 로그 검색

GitLab SAML 테스트

구성 확인

지문 계산

SSO 인증서 업데이트

구성 오류

잘못된 수신자

키 유효성 검사 오류, 다이제스트 불일치 또는 지문 불일치

누락된 클레임 또는 `이메일은 비어 있을 수 없습니다` 오류

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

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

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

메시지: “SAML 인증 실패: 사용자가 이미 선택되었습니다.”

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

오류: 사용자가 이미 존재함

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

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

메시지: “SAML Name ID 및 이메일 주소가 사용자 계정과 일치하지 않음”

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

기타 사용자 로그인 문제

`NameID` 확인

로그인 “루프”에 갇힘

사용자가 404를 받음

로그인 후 500 에러

로그인 후 422 에러

허용되지 않은 이메일로 422 에러

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

Google Workspace 문제 해결 팁

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

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

도움말

기능 사용 가능성과 제품 평가판

도움받기

SAML 문제 해결

SAML 디버깅 도구

SAML 응답 생성

수동으로 SAML 응답 생성

SAML 로그 검색

GitLab SAML 테스트

구성 확인

지문 계산

SSO 인증서 업데이트

구성 오류

잘못된 수신자

키 유효성 검사 오류, 다이제스트 불일치 또는 지문 불일치

누락된 클레임 또는 이메일은 비어 있을 수 없습니다 오류

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

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

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

메시지: “SAML 인증 실패: 사용자가 이미 선택되었습니다.”

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

오류: 사용자가 이미 존재함

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

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

메시지: “SAML Name ID 및 이메일 주소가 사용자 계정과 일치하지 않음”

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

기타 사용자 로그인 문제

NameID 확인

로그인 “루프”에 갇힘

사용자가 404를 받음

로그인 후 500 에러

로그인 후 422 에러

허용되지 않은 이메일로 422 에러

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

Google Workspace 문제 해결 팁

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

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

도움말

기능 사용 가능성과 제품 평가판

도움받기

누락된 클레임 또는 `이메일은 비어 있을 수 없습니다` 오류

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

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

`NameID` 확인

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