SAML 문제 해결

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

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

SAML 디버깅 도구

SAML 응답은 base64로 인코딩되므로 다음과 같은 브라우저 플러그인을 추천하여 실시간으로 디코딩하는 것이 좋습니다:

다음을 특히 주의하세요:

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

SAML 응답 생성

SAML 응답을 사용하여 식별 공급자를 통해 로그인을 시도할 때 assertions 디렉터리에 보내진 속성 이름과 값 미리보기를 확인하세요.

SAML 응답을 생성하려면:

  1. 브라우저 디버깅 도구 중 하나를 설치합니다.
  2. 새 브라우저 탭을 엽니다.
  3. SAML 트레이서 콘솔을 엽니다:
    • Chrome: 페이지의 컨텍스트 메뉴에서 검사를 선택한 후 개발자 콘솔에서 SAML 탭을 선택합니다.
    • Firefox: 브라우저 툴바에 위치한 SAML-tracer 아이콘을 선택합니다.
  4. SAML 트레이서가 열린 상태의 동일한 브라우저 탭에서 그룹의 GitLab 단일 로그인 URL로 이동합니다.
  5. 인증을 선택하거나 로그인을 시도합니다. SAML 응답이 트레이서 콘솔에 표시되며, 예시 SAML 응답과 유사합니다.
  6. SAML 트레이서에서 내보내기 아이콘을 선택하여 응답을 JSON 형식으로 저장합니다.

GitLab SAML 테스트

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

구성 검증

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

지문 계산

idp_cert_fingerprint을 사용하는 경우, SHA1 지문이어야 합니다. SHA1 지문을 계산하려면 인증서 파일을 다운로드하고 아래 명령을 실행합니다: 

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

filename.crt를 인증서 파일의 이름으로 바꿉니다.

SSO 인증서 업데이트

신원 공급자에 사용된 인증서가 변경될 때(예: 인증서 갱신 또는 업데이트 시), 인증서 지문도 업데이트해야 합니다. 인증서 지문은 신원 공급자 UI에서 찾을 수 있습니다. 신원 공급자 UI에서 인증서를 얻을 수 없는 경우 지문 계산 설명서의 단계를 따릅니다.

SAML 응답을 위한 Rails 로그 검색

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

production_json.log에서 base64로 인코딩된 SAML 응답을 찾을 수 있습니다. 이 응답은 신원 공급자로부터 보내지며, GitLab에서 사용하는 사용자 정보가 포함되어 있습니다. SAML 통합의 많은 오류는 이 응답을 디코딩하고 GitLab 구성 파일의 SAML 설정과 비교함으로써 해결할 수 있습니다.

예를 들어, 그룹용 SAML에서는 다음 필터로 검색하여 base64로 인코딩된 SAML 응답을 찾을 수 있어야 합니다:

  • json.meta.caller_id: Groups::OmniauthCallbacksController#group_saml
  • json.meta.user 또는 json.username: username
  • json.method: POST
  • json.path: /groups/GROUP-PATH/-/saml/callback

관련 로그 항목에는 다음이 포함되어야 합니다:

  • "key": "SAMLResponse" 및 "value": (full SAML response)",
  • "key": "RelayState" 및 "value": "/group-path", 그리고
  • "key": "group_id" 및 "value": "group-path".

그리고 SAML 그룹 동기화를 구성한 경우 다음 필터로 디코딩된 SAML 응답을 확인해야 합니다:

  • json.class: GroupSamlGroupSyncWorker
  • json.args: <user ID> 또는 <group ID>

관련 로그 항목에는:

  • json.args는 <userID>, <group ID>, [group link ID 1, group link ID 2, ..., group link ID N] 형식으로 되어 있어야 합니다.
  • json.extra.group_saml_group_sync_worker.stats.* 필드는 그룹 동기화 실행이 사용자 멤버십을 얼마나 많이 added, removed, 또는 changed했는지 보여줍니다.

경우에 따라 SAML 응답이 긴 경우 "key": "truncated" 및 "value":"..."를 받을 수 있습니다. 이 경우 SAML 디버깅 도구 중 하나를 사용하거나, 그룹 소유자는 SAML SSO for 그룹에서 “SAML 설정 확인” 버튼을 선택하여 SAML 응답 사본을 얻을 수 있습니다.

SAML 응답을 사람이 읽을 수 있는 형식으로 보려면 base64 디코더를 사용하세요. 이를 온라인에 붙여넣어 디코딩하는 대신, 브라우저의 개발자 도구 콘솔을 사용하여 클립보드 데이터를 디코딩할 수 있습니다: 

atob(decodeURI("<paste_SAML_response_here>"))

MacOS에서는 다음을 실행하여 클립보드 데이터를 디코딩할 수 있습니다: 

pbpaste | base64 -D

이렇게 하면 XML 형식의 SAML 응답을 출력으로 받을 수 있어야 합니다.

구성 오류

잘못된 수신처

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

  • GitLab 콜백 URL을 식별 공급자 서버의 승인된 수신처에 추가합니다.
  • issuer 문자열에 후행 공백을 피합니다.

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

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

이 요구 사항에 대해 다음 사항을 고려하세요:

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

위에 설명된 시나리오 중 어느 것도 유효하지 않은 경우, 요청은 언급된 오류 중 하나로 실패합니다.

누락된 클레임 또는 이메일을 비워둘 수 없음 오류

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

이 정보가 제공되도록 확인하세요.

이 오류의 또 다른 원인은 식별 공급자가 올바른 정보를 전송하고 있지만 속성이 OmniAuth info 해시의 이름과 일치하지 않을 때 발생합니다. 이 경우 SAML 구성에서 attribute_statements를 설정하여 SAML 응답의 속성 이름을 해당하는 OmniAuth info 해시 이름에 매핑해야 합니다.

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

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

이 오류는 GitLab 사용자로서 로그인했지만 SAML 식별을 이미 다른 GitLab 사용자에 연결했음을 나타냅니다. 로그아웃한 다음 SAML을 사용하여 다시 로그인하면 연결된 사용자 계정으로 GitLab에 로그인됩니다.

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

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

현재 로그인한 사용자는 이미 다른 식별에 SAML이 연결되어 있거나 NameID 값이 변경되었습니다. 가능한 원인과 해결책은 다음과 같습니다:

원인 해결책
특정 식별 공급자를 위해 동일한 사용자에 대해 여러 SAML 식별을 연결하려고 시도했습니다. 로그인에 사용하는 식별을 변경합니다. 이를 위해 먼저 이전 SAML 식별을 이 GitLab 계정에서 연결 해제한 후 다시 로그인을 시도하세요.
NameID가 사용자가 SSO 식별을 요청할 때마다 변경됩니다. NameID를 확인하여 Transient 형식으로 설정되어 있지 않고 연속된 요청에서 NameID가 변경되지 않았는지 확인합니다.

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

원인 해결책
GitLab에 해당 이메일 주소로 이미 사용자 계정이 있지만 해당 사용자에게 SAML 식별이 연결되어 있지 않은 경우 사용자는 계정을 연결해야 합니다.

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

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

메시지: “SAML 인증 실패: 외부 UID가 이미 사용 중입니다, 사용자가 이미 존재합니다”

이 두 가지 오류가 동시에 발생하는 것은 식별 공급자가 해당 사용자의 이전 값과 정확히 일치하지 않는 NameID 대문자화를 제공했음을 나타냅니다.

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

메시지: “SAML 계정 연결 요청에 권한이 있어야 함”

GitLab 계정을 연결하려는 사용자가 식별 공급자의 SAML 앱에 사용자로 추가되었는지 확인하세요.

또는 SAML 응답에는 기대되는 samlp:Response 태그에서 InResponseTo 속성이 누락될 수 있습니다. 이는 SAML gem에서 기대되는 것입니다. 식별 공급자 관리자는 로그인이 식별 공급자뿐만 아니라 서비스 제공자에 의해 시작되도록 해야 합니다.

메시지: “해당 이메일 주소와 연결된 GitLab 계정이 이미 있습니다. 기존 자격 증명을 사용하여 조직 계정을 연결하세요”

Tier: Premium, Ultimate Offering: GitLab.com

사용자가 기존의 GitLab.com 계정에 매뉴얼으로 SAML을 연결하려고 시도할 때 이 메시지를 볼 수 있습니다.

이 문제를 해결하려면 사용자는 올바른 GitLab 암호를 사용하는지 확인해야 합니다. 다음 조건이 모두 해당되면 사용자는 먼저 암호를 재설정해야 합니다:

  • 계정이 SCIM으로 프로비저닝되었습니다.
  • 사용자가 처음으로 사용자 이름과 암호로 로그인하려고 합니다.

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

Tier: Premium, Ultimate Offering: GitLab.com

사용자는 “SAML 이름 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)가 없으며 설정에서 cert가 제공되지 않음”

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

이 문제를 해결하려면 IdP를 구성하여 SAML 응답에 X.509 인증서를 포함하도록 설정하십시오.

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

다른 사용자 로그인 문제

NameID 확인

문제 해결시, 모든 인증된 사용자는 https://gitlab.com/api/v4/user을 방문하여 extern_uid를 확인하여 GitLab이 이미 사용자에 연결한 NameID를 확인할 수 있습니다.

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

그룹에 SAML을 사용하는 경우, 해당 그룹의 적절한 권한이 있는 역할의 그룹 구성원은 구성원 API를 사용하여 그룹의 SAML 식별 정보를 볼 수 있습니다.

그런 다음 SAML 디버깅 도구를 사용하여 식별 공급자가 보내는 NameID와 비교할 수 있습니다. 우리는 이를 통해 사용자를 식별할 수 있도록 이들이 일치하도록 요구합니다.

로그인 “루프”에 갇힘

GitLab 싱글 사인온 URL (GitLab.com의 경우) 또는 인스턴스 URL (Self-managed의 경우)이 식별 공급자의 SAML 앱의 “로그인 URL” (또는 유사한 이름의 필드)로 구성되었는지 확인하십시오.

GitLab.com의 경우, 또한, 사용자가 기존 GitLab.com 계정에 SAML을 연결해야 하는 경우, 사용자에게 GitLab 싱글 사인온 URL을 제공하고 처음 로그인할 때 SAML 앱을 사용하지 말라고 안내할 수 있습니다.

사용자가 404를 받음

Tier: Premium, Ultimate Offering: GitLab.com

사용자가 성공적으로 로그인한 후에 404를 받는 경우, IP 제한이 구성되었는지 확인하십시오.

그룹용 SAML SSO는 유료 기능이므로 GitLab.com에서 SAML SSO를 사용하여 로그인하는 동안 구독이 만료되면 404 오류가 발생할 수 있습니다. SAML을 사용하여 모든 사용자가 404를 받는 경우에는, 활성 구독이 있는지 확인하세요. 세팅 점검 중에 404를 받는다면, 올바른 생성된 SHA-1 지문을 사용했는지 확인하십시오.

사용자가 처음으로 로그인하려고 시도하고 GitLab 싱글 사인온 URL이 구성되지 않은 경우, 404가 표시될 수 있습니다. 사용자 접근 섹션에서 설명했듯이, 여기에 대한 URL을 사용자에게 제공해야 하는 그룹 소유자가 있어야 합니다.

최상위 그룹이 이메일 도메인으로 회원 가입을 제한하도록 설정했으며, 허용되지 않은 이메일 도메인을 가진 사용자가 SSO로 로그인하려고 하면 404를 받을 수 있습니다. 사용자는 여러 개의 계정을 가질 수 있으며, SAML 식별이 회사 도메인과 다른 이메일 주소를 가진 개인 계정에 연결될 수 있습니다. 이를 확인하려면 다음을 확인하세요:

  • 최상위 그룹에서 이메일 도메인으로 회원 가입을 제한했는지 확인하세요.
  • 최상위 그룹에 대한 감사 이벤트에서:
    • 해당 사용자에 대해 GROUP_SAML 인증으로 로그인함 작업을 볼 수 있는지 확인합니다.
    • 사용자의 사용자 이름이 SAML SSO에 구성한 사용자 이름과 동일한지 확인합니다.
      • 사용자 이름이 SAML SSO에 구성한 사용자 이름과 다른 경우, 사용자에게 SAML 식별을 연결 해제하여 개인 계정으로부터 연결을 해제할 것을 요청하세요.

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

  • assertion_consumer_service_url을 확인하세요.
    • GitLab 구성에서 HTTPS 엔드포인트에 일치시킴으로써.
    • IdP에서 SAML 앱을 설정할 때 assertion_consumer_service_url 또는 해당하는 URL이 링크되어 있는지 확인하세요.

사용자 중 일부가 IdP에 로그인한 후에 404를 받는 경우, 먼저 사용자가 그룹에 추가되었다가 즉시 제거되는지에 대한 감사 이벤트를 확인하십시오. 또는 사용자가 성공적으로 로그인하지만 최상위 그룹의 구성원으로 표시되지 않는 경우:

  • 사용자가 SAML 식별 공급자에 추가되었는지 및 SCIM이 구성되었는지 확인하세요.
  • SCIM 식별의 active 속성이 SCIM API를 사용하여 true로 설정되었는지 확인하세요. active 속성이 false인 경우, 문제를 해결할 수 있는 다음 중 하나를 수행할 수 있습니다:
    • 사용자에 대한 SCIM 식별 공급자의 동기화를 트리거하세요. 예를 들어, Azure에는 “요구에 따라 제공” 옵션이 있습니다.
    • 사용자를 SCIM 식별 공급자에서 제거하고 다시 추가하세요.
    • 사용자에게 계정 연결 해제하여, 가능하다면, 그들에게 그들의 계정을 SAML에 연결하도록 요청하세요.

    • 내부 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 오류”를 보게 되면, 다음 사항을 나타낼 수 있습니다:

  • SAML 사용자의 이메일 주소를 GitLab이 가져올 수 없을 수 있습니다. 아이덴티티 제공자가 사용자의 이메일 주소를 포함한 클레임을 제공하는지 확인하세요. 클레임 이름이 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

SAML 로그인 페이지로부터 리디렉션된 후 GitLab에서 “422 오류”를 보게 되면, 아마도 정확하게 구성되지 않은 어설션 컨슈머 서비스 (ACS) URL이 있는 것일 수 있습니다.

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

ACS URL이 올바른 경우에도 오류가 발생한다면, 다른 문제 해결 섹션을 확인하세요.

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

“이메일은 가입할 수 없는 메일입니다. 귀하의 일반적인 이메일 주소를 사용해주세요.”라는 422 오류를 받을 수 있습니다.

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

이 해결 방법을 실행하려면:

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

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_configured_for_user

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

Tier: Premium, Ultimate Offering: GitLab.com

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

그룹에 사용자를 초대한 후 이 메시지를 보게 되면:

  1. 사용자가 SAML 아이덴티티 제공자에 추가되었는지 확인하세요.
  2. 사용자가 기존의 GitLab.com 계정에 SAML을 연결하도록 요청하세요. 그렇지 않은 경우, 사용자에게아이덴티티 제공자 대시보드를 통해 GitLab.com에 액세스하거나매뉴얼으로 등록하여 새 계정에 SAML을 연결하도록 요청하세요.
  3. 사용자가 최상위 그룹의 구성원인지 확인하세요.

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

메시지: SAML 응답에 이메일 주소가 포함되지 않았습니다. SAML 아이덴티티 제공자가 속성을 보내도록 구성되지 않았거나, 아이덴티티 제공자 디렉터리에 사용자의 이메일 주소 값이 없을 수 있습니다.

이 오류는 SAML 응답에 사용자의 이메일 주소가 email 또는 mail 속성으로 포함되지 않을 때 나타납니다. 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>