SAML 인증 문제 해결

SAML SSO(Single Sign-On)를 사용하는데 사용자가 GitHub에 액세스하기 위해 인증할 수 없는 경우 문제를 해결할 수 있습니다.

이 문서의 내용

SAML 인증 문제 정보

GitHub Enterprise Server에서는 github-unicorn 컨테이너용 systemd 저널 로그에서 실패한 SAML 인증 관련 오류 메시지를 기록합니다. 이 로그에서 응답을 검토할 수 있으며 더 자세한 세부 정보 로깅을 구성할 수도 있습니다.

SAML 응답 요구 사항에 대한 자세한 내용은 "SAML 구성 참조"을(를) 참조하세요.

SAML 디버깅 구성

모든 SAML 인증 시도에 대해 자세한 디버그 로그를 작성하도록 GitHub Enterprise Server를 구성할 수 있습니다. 이 추가 출력을 통해 실패한 인증 시도 문제를 해결할 수 있습니다.

Warning

  • SAML 디버깅을 일시적으로만 사용하도록 설정하고 문제 해결을 완료한 직후 디버깅 사용을 중지하도록 설정합니다. 디버깅을 사용하도록 설정한 상태로 두면 로그의 크기가 평소보다 훨씬 빠르게 증가하여 GitHub Enterprise Server의 성능에 부정적인 영향을 줄 수 있습니다.
  • 프로덕션 환경에서 설정을 적용하기 전에 스테이징 환경에서 GitHub Enterprise Server 인스턴스에 대한 새 인증 설정을 테스트합니다. 자세한 내용은 "스테이징 인스턴스 설정"을(를) 참조하세요.

  1. GitHub Enterprise Server의 오른쪽 위 모서리에서 프로필 사진과 엔터프라이즈 설정을 차례로 클릭합니다.

    GitHub Enterprise Server에서 프로필 사진 클릭할 때 나타나는 드롭다운 메뉴의 스크린샷 "엔터프라이즈 설정" 옵션이 진한 주황색 윤곽선으로 강조 표시됩니다.

  2. 페이지 왼쪽의 엔터프라이즈 계정 사이드바에서 정책을 클릭합니다.

  3. 정책 아래에서 옵션을 클릭합니다.

  4. “SAML 디버깅”에서 드롭다운을 선택하고 사용을 클릭합니다.

  5. SAML IdP를 통해 GitHub Enterprise Server 인스턴스에 로그인을 시도합니다.

  6. GitHub Enterprise Server 인스턴스의 github-unicorn용 systemd 저널에서 디버그 출력을 검토합니다. 자세한 내용은 "시스템 로그 정보"을(를) 참조하세요.

  7. 문제 해결을 마쳤으면 드롭다운을 선택하고 사용 안 함을 클릭합니다.

응답 디코딩

github-unicorn용 systemd 저널의 일부 출력은 Base64로 인코딩될 수 있습니다. 관리 셸에 액세스하고 GitHub Enterprise Server 인스턴스에서 base64 유틸리티를 사용하여 이러한 응답을 디코딩할 수 있습니다. 자세한 내용은 "관리 셸(SSH)에 액세스"을(를) 참조하세요.

출력을 디코딩하려면 다음 명령을 실행하여 ENCODED_OUTPUT을 로그의 인코딩된 출력으로 바꿉니다.

base64 --decode ENCODED_OUTPUT

오류: “다른 사용자가 이미 계정을 소유하고 있습니다.”

사용자가 SAML 인증을 통해 처음으로 GitHub Enterprise Server 인스턴스에 로그인하면, GitHub Enterprise Server는 인스턴스에 사용자 계정을 만들고 SAML NameID 및 nameid-format을 계정에 매핑합니다.

사용자가 다시 로그인하면 GitHub Enterprise Server에서 계정의 NameID 및 nameid-format 매핑을 IdP의 응답과 비교합니다. IdP 응답의 NameID 또는 nameid-format이 GitHub Enterprise Server에서 사용자에게 예상하는 값과 더 이상 일치하지 않으면 로그인에 실패합니다. 다음과 같은 메시지가 표시됩니다.

다른 사용자가 이미 계정을 소유하고 있습니다. 관리자에게 인증 로그 확인을 요청하세요.

이 메시지는 일반적으로 IdP에서 사용자 이름 또는 메일 주소가 변경되었음을 나타냅니다. GitHub Enterprise Server의 사용자 계정에 대한 NameID 및 nameid-format 매핑이 IdP의 사용자 NameID 및 nameid-format과 일치하는지 확인합니다. 자세한 내용은 "사용자의 SAML NameID 업데이트"을(를) 참조하세요.

오류: SAML 응답의 수신자가 비어 있거나 유효하지 않음

Recipient가 GitHub Enterprise Server 인스턴스의 ACS URL과 일치하지 않는 경우 사용자가 인증을 시도할 때 인증 로그에 다음 두 오류 메시지 중 하나가 표시됩니다.

Recipient in the SAML response must not be blank.

Recipient in the SAML response was not valid.

IdP의 Recipient 값을 GitHub Enterprise Server 인스턴스의 전체 ACS URL로 설정해야 합니다. 예들 들어 https://ghe.corp.example.com/saml/consume입니다.

오류: "SAML 응답이 서명되지 않았거나 수정되었습니다."

IdP가 SAML 응답에 서명하지 않거나 서명이 내용과 일치하지 않으면 인증 로그에 다음 오류 메시지가 표시됩니다.

SAML Response is not signed or has been modified.

IdP에서 GitHub Enterprise Server 애플리케이션에 대해 서명된 어설션을 구성해야 합니다.

오류: “대상 그룹이 유효하지 않음” 또는 “어설션을 찾을 수 없음”

IdP의 응답에 Audience 값이 누락되었거나 잘못된 값인 경우 인증 로그에 다음 오류 메시지가 표시됩니다.

Audience is invalid. Audience attribute does not match https://YOUR-INSTANCE-URL

IdP의 Audience 값을 GitHub Enterprise Server 인스턴스의 EntityId, 즉 인스턴스에 대한 전체 URL로 설정해야 합니다. 예들 들어 https://ghe.corp.example.com입니다.

오류: "현재 시간이 NotBefore 조건보다 이전입니다."

이 오류는 IdP 및 일반적으로 자체 호스팅 IdP에서 발생하는 GitHub Enterprise Server 간의 시간 차이가 너무 큰 경우에 발생할 수 있습니다.

이 문제를 방지하려면 가능하면 어플라이언스가 IdP와 동일한 NTP(네트워크 시간 프로토콜) 원본을 가리키는 것이 좋습니다. 이 오류가 발생하면 어플라이언스의 시간이 NTP 서버와 올바르게 동기화되었는지 확인합니다. 관리 셸의 chronyc 명령을 사용하여 시간을 즉시 동기화할 수 있습니다. 자세한 내용은 "시간 동기화 구성"을(를) 참조하세요.

ADFS를 IdP로 사용하는 경우 GitHub에 대해서도 ADFS에서 NotBeforeSkew를 1분으로 설정합니다. NotBeforeSkew가 0으로 설정된 경우 밀리초를 포함하여 매우 작은 시간 차이라도 인증 문제가 발생할 수 있습니다.