이 페이지에는 다음을 사용할 때 발생할 수 있는 문제의 해결 방법이 정리되어 있습니다:

• 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 tracer 콘솔을 엽니다:
   • Chrome: 페이지의 컨텍스트 메뉴에서 Inspect를 선택한 다음 개발자 콘솔에서 SAML 탭을 선택합니다.
   • Firefox: 브라우저 툴바에 있는 SAML-tracer 아이콘을 선택합니다.
4. GitLab.com 그룹의 경우:
   • 그룹의 GitLab 단일 로그온 URL로 이동합니다.
   • Authorize를 선택하거나 로그인을 시도합니다.
5. GitLab Self-Managed 인스턴스의 경우:
   • 인스턴스 홈 페이지로 이동합니다.
   • SAML Login 버튼을 선택해 로그인합니다.
6. 이 SAML 응답 예시와 유사한 SAML 응답이 tracer 콘솔에 표시됩니다.
7. SAML tracer에서 Export 아이콘을 선택해 응답을 JSON 형식으로 저장합니다.

SAML 응답 수동 생성#

개요는 GitLab 지원팀이 업로드한 브라우저 플러그인을 사용하지 않고 SAML 응답을 수동으로 생성하는 방법 영상(Google Chrome 사용)을 참고합니다.

사용하는 브라우저와 무관하게 절차는 다음과 비슷합니다:

1. 새 브라우저에서 마우스 오른쪽 버튼을 클릭하고 Inspect를 선택해 DevTools 창을 엽니다.

2. Network 탭을 선택합니다. Preserve log가 선택되어 있는지 확인합니다.

3. 브라우저 페이지로 이동해 SAML SSO로 GitLab에 로그인합니다.

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

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

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

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

   코드 편집기에 XML "prettifier"가 설치되어 있으면 응답을 읽기 쉬운 형식으로 자동으로 정렬할 수 있습니다.

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 오류#

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

이 정보가 제공되는지 확인합니다.

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

SAML 그룹 링크가 있지만 멤버십이 변경되지 않음#

SAML 그룹 링크를 구성하고 SAML 응답이 예상한 그룹을 담고 있는 것까지 확인했는데도 멤버십이 추가되거나 제거되지 않을 수 있습니다. 사용자는 정상적으로 로그인하고, 로그인 과정이나 로그 어디에도 오류가 보고되지 않습니다.

이 문제는 사용자를 인증한 공급자에 대해 GitLab이 groups_attribute 값을 확인하지 못할 때 발생합니다. 흔한 원인은 groups_attribute를 name 및 label과 같은 계층인 공급자 수준에 두지 않고 공급자의 args 해시 안에 넣은 것입니다. 값이 확인되지 않으면 그룹 동기화가 실행되지 않고 아무것도 보고하지 않습니다.

이 문제를 해결하려면 다음을 수행합니다:

1. groups_attribute를 구성의 공급자 수준으로 옮깁니다. 예시는 SAML 그룹 동기화 구성을 참고합니다.

2. 파일을 저장하고 GitLab을 재구성합니다:

   sudo gitlab-ctl reconfigure
   

3. 다시 로그인합니다.

4. audit_json.log에서 "meta.caller_id": "Auth::SamlGroupSyncWorker"가 있는 항목을 검색합니다. 그룹 동기화는 멤버십을 변경할 때 이 항목을 기록합니다. 멤버십이 변경되어야 하는 로그인 이후에도 이 항목이 없다면 그룹 동기화가 실행되지 않는 것입니다.

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

메시지: 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 사용자를 사용하지 않으려면 SAML 앱에서 GitLab 계정 연결을 해제할 수 있습니다.

메시지: 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#

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

또는 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 그룹 Owner가 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를 방문하고 identities 아래의 extern_uid를 확인하는 방식으로, GitLab이 자신의 사용자에 연결해 둔 NameID를 확인할 수 있습니다.

GitLab Self-Managed에서는 관리자가 사용자 API로 같은 정보를 볼 수 있습니다.

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

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

로그인 "루프"에 갇힘#

ID 공급자의 SAML 앱에서 GitLab single sign-on URL(GitLab.com의 경우) 또는 인스턴스 URL(GitLab Self-Managed의 경우)이 "Login URL"(또는 이와 비슷한 이름의 필드)로 구성되어 있는지 확인합니다.

GitLab.com에서는 사용자가 기존 GitLab.com 계정에 SAML을 연결해야 할 때 GitLab single sign-on 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 single sign-on URL이 구성되지 않았다면 404가 표시될 수 있습니다. 사용자 액세스 섹션에서 설명한 대로 그룹 Owner가 사용자에게 URL을 제공해야 합니다.

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

• 최상위 그룹에 이메일 도메인별 멤버십 제한이 설정되어 있습니다.
• 최상위 그룹의 감사 이벤트에서 다음을 확인합니다:
  • 해당 사용자에 대해 Signed in with GROUP_SAML authentication 작업이 보입니다.
  • Author 이름을 선택해 사용자의 사용자 이름이 SAML SSO에 구성한 사용자 이름과 같은지 확인합니다.
    • 사용자 이름이 SAML SSO에 구성한 사용자 이름과 다르다면 사용자에게 개인 계정에서 SAML 아이덴티티 연결을 해제하도록 요청합니다.

ID 공급자(IdP)에 로그인한 뒤 모든 사용자가 404를 받는다면 다음을 확인합니다:

• assertion_consumer_service_url을 확인합니다:
  • GitLab 구성에서 GitLab의 HTTPS 엔드포인트와 일치시켜 확인합니다.
  • IdP에서 SAML 앱을 설정할 때 Assertion Consumer Service URL 또는 이에 해당하는 값으로 확인합니다.
• 404가 Azure IdP에서 사용자에게 너무 많은 그룹이 할당된 것과 관련이 있는지 확인합니다.
• IdP 서버와 GitLab의 시계가 같은 시각으로 동기화되어 있는지 확인합니다.

IdP에 로그인한 뒤 일부 사용자가 404 오류를 받는다면, 먼저 사용자를 그룹에 추가한 다음 곧바로 제거했을 때 어떤 감사 이벤트가 반환되는지 확인합니다. 또는 사용자가 정상적으로 로그인할 수 있지만 최상위 그룹의 멤버로 표시되지 않는다면 다음을 확인합니다:

• 사용자가 SAML ID 공급자에 추가되었는지, 그리고 SCIM을 구성했다면 SCIM에도 추가되었는지 확인합니다.

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

  • SCIM ID 공급자에서 해당 사용자의 동기화를 트리거합니다. 예를 들어 Azure에는 "Provision on demand" 옵션이 있습니다.

  • 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 공급자의 Assertion Consumer Service(ACS) URL이 잘못 구성되어 있을 수 있습니다.

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

ACS URL이 올바른데도 오류가 계속된다면 다른 문제 해결 섹션을 검토합니다.

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

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

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

사전 요구 사항:

• 관리자 액세스 권한.

이 해결 방법을 적용하려면 다음을 수행합니다:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. New user account restrictions를 확장합니다.
4. Domains allowed for new users와 Domains denied for new users에서 도메인을 적절히 추가하거나 제거합니다.
5. Save changes를 선택합니다.

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 계정이 있다면 기존 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/와 같은 구문으로 시작하는 속성 이름은 기본적으로 지원됩니다.

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

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

글로벌 SAML 그룹 멤버십 잠금이 활성화되어 있으면 관리자만 UI에서 그룹 멤버와 서비스 계정을 관리할 수 있습니다. 그룹 Owner가 서비스 계정을 관리해야 한다면 대신 그룹 멤버 API를 사용할 수 있습니다.

지원 지식 기반#

여전히 문제가 있다면 GitLab 지원 지식 기반을 참고합니다.