Skip to main content

REST API를 사용하여 SCIM으로 사용자 프로비저닝

SCIM(System for Cross-domain Identity Management)을 위한 GitHub의 REST API를 사용하여 ID 공급자(IdP)의 GitHub.com에서 엔터프라이즈 사용자 계정의 수명 주기를 관리할 수 있습니다.

누가 이 기능을 사용할 수 있는 있나요?

ID 공급자를 사용하여 엔터프라이즈의 사용자를 관리하려면 GitHub Enterprise Cloud에서 사용할 수 있는 Enterprise Managed Users에 대해 엔터프라이즈를 사용하도록 설정해야 합니다. 자세한 내용은 "Enterprise Managed Users 정보"을 참조하세요.

Enterprise Managed Users에 대한 프로비저닝 정보

GitHub.com에서 엔터프라이즈 멤버에 대한 사용자 계정을 생성, 관리 및 비활성화하려면 IdP에서 GitHub과(와)의 통신을 위해 SCIM을 구현해야 합니다. SCIM은 시스템 사이에서 사용자 ID 관리를 위한 공개 사양입니다. 다양한 IdP에서 SCIM 프로비저닝 구성에 대해 다양한 환경을 제공합니다. GitHub Enterprise Cloud의 프로비저닝에 대한 자세한 내용은 "Enterprise Managed Users에 대한 SCIM 프로비저닝 구성"을(를) 참조하세요.

GitHub은(는) ID 관리 시스템의 일부 개발자와 협력하여 Enterprise Managed Users과(와) "편리한" 통합을 제공합니다. 회사에서 파트너 IdP를 사용하지 않는 경우 GitHub의 REST API와 통신하는 ID 시스템에서 프로비저닝을 구성할 수 있습니다. 이 가이드는 GitHub의 구현과 관련된 다음 항목을 이해하는 데 도움이 됩니다.

  • 엔터프라이즈에 대한 자세한 감사 로그를 검토하고 스트리밍하는 방법
  • SCIM 및 사용량 예상에 대한 엔드포인트를 포함한 REST API
  • 문제 해결

또는 인증 및 프로비저닝 모두에 파트너 IdP를 사용할 수 있습니다. 자세한 내용은 "Enterprise Managed Users 정보"을(를) 참조하세요.

GitHub이(가) 모든 IdP를 테스트하지 않았습니다. GitHub 지원은(는) 파트너 IdP에 대해 제한된 지원을 제공합니다. SCIM 사양 및 GitHub의 지침을 준수하는 IdP를 통합할 수 있지만, IdP 자체에 대한 지원 또는 통합 빌드는 개발자의 설명서, 지원 팀 또는 기타 리소스를 참조하세요.

필수 조건

  • 프로비저닝을 구성하기 전에 먼저 인증을 구성해야 합니다. 자세한 내용은 "Enterprise Managed User에 대한 인증 구성"을(를) 참조하세요.

  • 프로비저닝을 구성하기 전에 IdP에 대한 통합 요구 사항 및 지원 수준을 파악해야 합니다. 자세한 내용은 "Enterprise Managed Users 정보"을(를) 참조하세요.

  • GitHub의 REST API와 통합하려면 IdP에서 SCIM(System for Cross-domain Identity Management) 2.0 표준을 지원해야 합니다. 자세한 정보는 IETF 웹 사이트에서 다음 RFC를 참조하세요.

  • GitHub에서는 엔터프라이즈 설정 사용자와 연결된 personal access token (classic)을(를) 사용하여 SCIM의 REST API 엔드포인트에만 요청을 인증하도록 권장합니다. 토큰의 범위는 admin:enterprise여야 합니다. 자세한 내용은 "Enterprise Managed Users에 대한 SCIM 프로비저닝 구성"을(를) 참조하세요.

  • 인증 및 프로비저닝에 사용하는 시스템에 대한 사용자 레코드는 고유 식별자를 공유하고 GitHub의 일치 조건을 충족해야 합니다. 자세한 내용은 REST API 설명서의 "SCIM"를 참조하세요.

  • 처음 인증 및 프로비저닝을 구성한 후 GitHub에서는 인증 또는 프로비저닝을 위해 다른 플랫폼으로의 마이그레이션을 권장하지 않습니다. 인증 또는 프로비저닝을 위해 기존 엔터프라이즈를 다른 플랫폼으로 마이그레이션해야 하는 경우 GitHub의 영업 팀에서 영업 담당자에게 문의하세요.

감사 로그 스트리밍 구성

엔터프라이즈에 대한 감사 로그에는 기업의 활동에 대한 세부 정보가 표시됩니다. 감사 로그를 사용하여 SCIM 구성을 지원할 수 있습니다. 자세한 내용은 "엔터프라이즈의 감사 로그 정보"을(를) 참조하세요.

이 로그의 이벤트 볼륨으로 인해 GitHub은(는) 180일 동안의 데이터를 보존합니다. 감사 로그 데이터가 손실되지 않도록 하고 감사 로그에서 보다 세분화된 작업을 보려면 GitHub는 감사 로그 스트리밍을 구성할 것을 권장합니다. 감사 로그를 스트리밍할 때 필요에 따라 SCIM 프로비저닝을 위한 엔드포인트에 대한 요청을 포함하여 API 요청에 대한 이벤트를 스트리밍하도록 선택할 수 있습니다. 자세한 내용은 "엔터프라이즈에 대한 감사 로그 스트리밍"을(를) 참조하세요.

REST API for SCIM 이해

SCIM을 호출하고 사용자를 관리하려면 GitHub의 REST API를 사용합니다. REST API의 리소스 접근성에 대한 자세한 내용은 "REST API 시작"을(를) 참조하세요.

SCIM용 REST API 엔드포인트

다음 표에서는 REST API에서 제공하는 SCIM 엔드포인트에 대해 설명합니다. REST API 설명서에서 자세한 내용을 읽을 수 있습니다. 설명서에는 코드 샘플, 필수 헤더 및 경로 매개 변수 및 HTTP 응답 코드가 포함됩니다.

이러한 엔드포인트의 요청 인증에 대한 자세한 내용은 REST API 설명서의 "SCIM"을(를) 참조하세요.

REST API의 예상과 일치하지 않는 요청은 400 Bad Request 오류를 반환합니다.

사용자 관리를 위한 REST API 엔드포인트

사용자를 프로비전하려면 다음 REST API 엔드포인트를 요청합니다.

작업메서드엔드포인트 및 자세한 정보
사용자 만들기POSTSCIM 엔터프라이즈 사용자 프로비전
사용자 검색GET엔터프라이즈 사용자에 대한 SCIM 프로비저닝 정보 가져오기
사용자의 모든 특성 업데이트PUT프로비저닝된 엔터프라이즈 사용자에 대한 SCIM 정보 설정
개별 사용자 특성 업데이트PATCHSCIM 엔터프라이즈 사용자에 대한 특성 업데이트
모든 사용자 나열GET엔터프라이즈에 대해 SCIM 프로비저닝된 ID 나열
사용자 삭제DELETE엔터프라이즈에서 SCIM 사용자 삭제

그룹 관리를 위한 REST API 엔드포인트

엔터프라이즈의 리포지토리에 대한 액세스를 제어하기 위해 SCIM 통합은 IdP의 그룹을 통해 사용자의 조직 및 팀 멤버십을 관리할 수 있습니다. 자세한 내용은 “ID 공급자 그룹을 사용하여 팀 멤버 자격 관리”를 참조하세요.

그룹을 관리하려면 다음 REST API 엔드포인트를 요청합니다.

작업메서드엔드포인트 및 자세한 정보
그룹 만들기POSTSCIM 엔터프라이즈 그룹 프로비전
한 그룹 검색GET엔터프라이즈 그룹에 대한 SCIM 프로비저닝 정보 가져오기
한 그룹의 모든 특성 업데이트PUT프로비저닝된 엔터프라이즈 그룹에 대한 SCIM 정보 설정
개별 그룹 특성 업데이트PATCHSCIM 엔터프라이즈 그룹에 대한 특성 업데이트
모든 그룹 나열GET엔터프라이즈에 대해 프로비저닝된 SCIM 그룹 나열
그룹 삭제DELETE엔터프라이즈에서 SCIM 그룹 삭제

속도 제한 정보

GitHub Enterprise Cloud에서 속도 제한을 초과하지 않으려면 시간당 1,000명이 넘는 사용자를 IdP의 SCIM 통합에 할당하지 마세요. 그룹을 사용하여 IdP 애플리케이션에 사용자를 할당하는 경우 시간당 각 그룹에 1,000명 이상의 사용자를 추가하지 마세요. 이러한 임계값을 초과하는 경우 사용자를 프로비저닝하려고 시도하면 “속도 제한” 오류로 실패할 수 있습니다. IdP 로그를 검토하여 속도 제한 오류로 인해 SCIM 프로비저닝 또는 푸시 작업이 실패했는지 확인할 수 있습니다. 실패한 프로비저닝 시도에 대한 응답은 IdP에 따라 달라집니다.

자세한 내용은 "REST API에 대한 트래픽률 제한"을(를) 참조하세요.

사용자 및 그룹 특성

REST API에 대한 요청은 사용자 및 그룹에 대한 특정 특성을 지원합니다. 자세한 내용은 SCIM 운영에 대한 REST API 설명서의 "지원되는 SCIM 사용자 특성" 및 "지원되는 SCIM 그룹 특성"을 참조하세요.

예를 들어 roles 특성을 사용하여 엔터프라이즈의 역할을 사용자 또는 그룹에 할당할 수 있습니다. 사용자에게 다중 역할을 부여하는 경우 더 많은 권한 있는 액세스가 있는 역할이 우선합니다.

역할자세한 내용은 "엔터프라이즈의 역할" 참조
enterprise_owner"엔터프라이즈 소유자"
billing_manager"청구 관리자"
user"엔터프라이즈 멤버"
guest_collaborator"게스트 협력자"

외부 ID의 매핑 정보

인증에 성공하면 GitHub Enterprise Cloud은(는) SCIM에 의해 프로비전된 ID에 인증된 사용자를 연결합니다. 인증 및 프로비저닝에 대한 고유 식별자는 일치해야 합니다. 자세한 내용은 REST API 설명서에서 "SCIM"을 참조하세요.

GitHub.com에서 이 매핑을 볼 수 있습니다. 자세한 내용은 "엔터프라이즈에 대한 사용자의 SAML 액세스 보기 및 관리"을(를) 참조하세요.

사용자에게 원하는 액세스 권한이 있는지 확인

통합에서 IdP의 그룹을 사용하여 액세스를 관리하는 경우 사용자가 원하는 액세스 권한을 얻을 수 있는지 확인할 수 있습니다. REST API를 사용하여 IdP의 그룹 멤버십을 해당 그룹에 대한 GitHub의 이해와 비교할 수 있습니다. 자세한 내용은 REST API 설명서의 "외부 그룹" 및 "Teams"을 참조하세요.

사용자의 서스펜스 및 재프로비전 정보

GitHub.com에서 관리형 사용자 계정을(를) 완전히 삭제할 수는 없습니다. 대신 계정을 일시적으로 또는 영구적으로 일시 중단할 수 있습니다.

사용자를 일시적으로 일시 중단하려면 사용자 레코드의 active 특성을 false에 설정하며, 이는 PATCH 또는 PUT 요청을 사용합니다. 계정을 일시적으로 일시 중단한 후 사용자는 더 이상 GitHub.com에서 엔터프라이즈에 액세스하기 위해 로그인할 수 없습니다. 자세한 내용은 SCIM 운영에 대한 REST API 설명서에서 "SCIM 엔터프라이즈 사용자에 대한 특성 업데이트" 또는 "프로비전된 엔터프라이즈 사용자에 대한 SCIM 정보 설정"을 참조하세요.

사용자를 영구적으로 일시 중단하려면 DELETE 요청을 보냅니다. 계정을 영구적으로 일시 중단하는 경우 해당 계정은 다시 활성화할 수 없습니다. 자세한 내용은 SCIM 운영에 대한 REST API 설명서의 "엔터프라이즈에서 SCIM 사용자 삭제"를 참조하세요.

사용자를 다시 프로비전하려면 사용자 레코드의 active 특성을 true로 설정하고, 이는 POST, PUT 또는 PATCH 요청을 사용합니다. 계정을 영구적으로 일시 중단한 경우 후속 프로비저닝 이벤트는 로그인하는 사용자에 대한 새 계정을 만듭니다. 새로 프로비전된 계정은 원래 계정과 아무런 관계가 없습니다. 자세한 내용은 SCIM 운영에 대한 REST API 설명서에서 "SCIM 엔터프라이즈 사용자 프로비전", "프로비전된 엔터프라이즈 사용자에 대한 SCIM 정보 설정", 또는 "SCIM 엔터프라이즈 유저를 위한 특성 업데이트"를 참조하세요.

문제 해결

  • GitHub이(가) REST API에 대한 요청을 속도 제한하는 경우 "속도 제한 정보"에서 자세히 알아볼 수 있습니다.

  • API 요청에 대해 감사 로그 스트리밍 및 스트림 이벤트를 사용하도록 설정하는 경우 EnterpriseUsersScim 또는 EnterpriseGroupsScim 컨트롤러의 이벤트를 필터링하여 SCIM용 REST API 엔드포인트에 대한 모든 요청을 검토할 수 있습니다.

  • 통합에서 IdP의 그룹을 사용하여 액세스를 관리하는 경우 엔터프라이즈 감사 로그의 external_group 범주 이벤트를 검토하여 SCIM 호출의 성공을 확인할 수 있습니다. GitHub에 대한 웹 인터페이스에서 문제 해결 정보도 볼 수 있습니다. 자세한 내용은 "엔터프라이즈에 대한 감사 로그 이벤트" 및 "ID 공급자 그룹을 사용하여 팀 멤버십 문제 해결"을(를) 참조하세요.

추가 참고 자료