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 정보"을 참조하세요.

이 문서의 내용

참고:

  • GitHub의 공용 SCIM 스키마를 사용하여 사용자를 프로비저닝하는 기능에 대한 지원은 퍼블릭 베타 버전이며 변경될 수 있습니다.
  • GitHub에서는 IdP 및 GitHub.com의 프로덕션 데이터와 격리된 환경에서 프로비저닝을 테스트하도록 권장합니다.

Enterprise Managed Users의 IAM 정보

GitHub의 엔터프라이즈가 Enterprise Managed Users에 대해 생성된 경우 사용자 계정을 프로비전하고 기본 외부 ID 관리 시스템을 구성해야 합니다. ID 관리 시스템에서는 다음 기능을 제공해야 합니다.

  • 다음 두 SSO(Single Sign-On) 표준 중 하나를 구현하는 Single Sign-On 인증:
    • SAML(Security Assertion Markup Language) 2.0
    • Microsoft Entra ID(이전 Azure AD)를 사용하는 경우에만 지원되는 OIDC(OpenID Connect)
  • SCIM(System for Cross-domain Identity Management)을 사용한 사용자 수명 주기 관리

엔터프라이즈에 대한 인증 및 프로비전을 구성할 때 파트너 IdP를 사용하거나 ID 관리 시스템의 다른 조합을 사용할 수 있습니다.

파트너 ID 공급자 사용

각 파트너 IdP는 SSO 및 사용자 수명 주기 관리를 모두 구현하는 "paved-path" 응용 프로그램을 제공합니다. Enterprise Managed Users의 구성을 간소화하기 위해 GitHub은(는) 인증 및 프로비전 모두에 파트너 IdP의 응용 프로그램을 사용할 것을 권장합니다. 자세한 내용 및 파트너 IdP 목록은 "Enterprise Managed Users 정보"을(를) 참조하세요.

인증 및 프로비전 모두에 단일 파트너 IdP를 사용하는 경우 GitHub은(는) 파트너 IdP의 응용 프로그램과 GitHub Enterprise Cloud의 IdP 통합을 지원합니다.

파트너 IdP를 사용하여 SCIM 프로비전을 구성하는 방법에 대한 자세한 내용은 "Enterprise Managed Users에 대한 SCIM 프로비저닝 구성"을(를) 참조하세요.

다른 ID 관리 시스템 사용

마이그레이션 오버헤드, 라이선스 비용 또는 조직의 타성으로 인해 인증 및 프로비전 모두에 파트너 IdP를 사용할 수 없는 경우, 다른 ID 관리 시스템 또는 시스템 조합을 사용할 수 있습니다. 시스템은 SCIM을 사용하여 SAML 및 사용자 수명 주기 관리를 사용하여 인증을 제공해야 하며 GitHub의 통합 지침을 준수해야 합니다.

GitHub은(는) 모든 ID 관리 시스템과의 통합을 테스트하지 않았습니다. Enterprise Managed Users과(와)의 통합이 가능할 수 있지만 GitHub의 지원 팀은 이러한 시스템과 관련한 문제를 지원하지 못할 수 있습니다. 파트너 IdP가 아닌 ID 관리 시스템에 대한 도움이 필요하거나 SAML 인증에만 파트너 IdP를 사용하는 경우, 시스템의 설명서, 지원 팀 또는 기타 리소스를 참조해야 합니다.

필수 조건

GitHub의 REST API를 사용한 SCIM 프로비전의 모범 사례

GitHub Enterprise Cloud에서 사용자 또는 사용자 그룹을 프로비전하도록 ID 관리 시스템을 구성할 때 GitHub은(는) 다음 지침을 준수할 것을 적극 권장합니다.

ID 관리 시스템이 쓰기 작업의 유일한 소스인지 확인

환경에 단일 정보 소스가 있는지 확인하려면, ID 관리 시스템에서 SCIM 프로비전을 위한 REST API에 프로그래밍 방식으로만 작성해야 합니다. GitHub은(는) 하나의 시스템만 API에 POST, PUT, PATCH 또는 DELETE 요청을 보내도록 할 것을 적극 권장합니다.

하지만 스크립트의 GET 요청 또는 엔터프라이즈 소유자의 임시 요청을 통해 GitHub의 API에서 정보를 안전하게 검색할 수 있습니다.

경고: SCIM 프로비전에 파트너 IdP를 사용하는 경우, IdP의 응용 프로그램은 API에 대한 쓰기 요청을 만드는 유일한 시스템이어야 합니다. POST, PUT, PATCH 또는 DELETE 메서드를 사용하여 임시 요청을 하는 경우 후속 동기화 시도가 실패하고 프로비전이 엔터프라이즈에 대해 제대로 작동하지 않습니다.

REST API 엔드포인트에 유효한 요청 전송

SCIM을 사용하여 사용자를 프로비전하기 위한 GitHub의 REST API 엔드포인트에는 올바른 형식의 요청이 필요합니다. 다음 지침을 유의하세요.

  • API의 예상과 일치하지 않는 요청은 400 Bad Request 오류를 반환합니다.
  • SCIM을 사용하여 사용자를 프로비전하기 위한 REST API 엔드포인트에는 User-Agent 헤더가 필요합니다. GitHub Enterprise Cloud은(는) 이 헤더가 없는 요청을 거부합니다.

그룹을 프로비전하기 전에 먼저 사용자 프로비전

SCIM 그룹은 대규모로 사용자 액세스를 관리하는 데 효과적입니다. 예를 들어 ID 관리 시스템의 그룹을 사용하여 GitHub Enterprise Cloud에서 팀 및 조직 멤버십을 관리할 수 있습니다.

ID 관리 시스템에서 그룹을 사용하여 팀 멤버십을 관리하려면 다음 단계를 순차적으로 완료해야 합니다.

  1. GitHub Enterprise Cloud의 사용자 계정을 프로비전합니다.
  2. GitHub Enterprise Cloud의 그룹을 프로비전합니다.
  3. ID 관리 시스템에서 그룹의 멤버십을 업데이트합니다.
  4. ID 관리 시스템의 그룹에 매핑된 GitHub Enterprise Cloud에 팀을 만듭니다.

GitHub Enterprise Cloud의 그룹에 대한 액세스 유효성 검사

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

GitHub Enterprise Cloud에 대한 트래픽률 제한 이해

플랫폼의 가용성과 안정성을 보장하기 위해 GitHub은(는) 트래픽률 제한을 구현합니다. 자세한 내용은 "REST API에 대한 트래픽률 제한"을(를) 참조하세요.

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

감사 로그 스트리밍 구성

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

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

REST API를 사용하여 사용자 프로비전

사용자를 프로비전, 나열 또는 관리하려면 다음 REST API 엔드포인트를 요청합니다. REST API 설명서에서 연결된 API 엔드포인트에 대해 참조하고, 코드 예제를 보고, 각 요청과 연결된 감사 로그 이벤트를 검토할 수 있습니다.

ID 관리 시스템에 ID가 있는 사용자가 엔터프라이즈에 로그인하도록 하려면, 먼저 해당 사용자를 생성해야 합니다. 기업이 새 사용자 계정을 프로비전하는 데 라이선스가 필요하지 않습니다.

  • 사용자에게 지원되는 특성에 대한 개요는 REST API 설명서에서 "SCIM"을 참조하세요.
  • GitHub Enterprise Cloud의 웹 UI에서 프로비전된 사용자를 볼 수 있습니다. 자세한 내용은 "Enterprise에서 사용자 보기"을(를) 참조하세요.
작업메서드엔드포인트 및 자세한 정보감사 로그의 이벤트
엔터프라이즈에 대해 프로비전된 모든 사용자를 나열합니다. 여기에는 active을(를) false(으)로 설정하여 소프트 프로비전 해제된 모든 사용자가 포함됩니다.GET/scim/v2/enterprises/{enterprise}/Users해당 없음
사용자를 만듭니다. API의 응답에는 사용자를 고유하게 식별하는 id 필드가 포함됩니다.POST/scim/v2/enterprises/{enterprise}/Users
  • external_identity.provision
  • user.create
  • 요청이 enterprise_owner 역할을 추가하는 경우 business.add_admin
  • 요청이 billing_manager 역할을 추가하는 경우 business.add_billing_manager
사용자를 만들기 위해 보낸 POST 요청의 id 필드를 사용하여 엔터프라이즈의 기존 사용자를 검색합니다.GET/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}해당 없음
사용자를 만들기 위해 보낸 POST 요청의 id 필드를 사용하여 기존 사용자의 모든 특성을 업데이트합니다. active을(를) false(으)로 업데이트하여 사용자를 소프트 프로비전 해제하거나 true(으)로 업데이트하여 사용자를 재활성화합니다. 자세한 내용은 "REST API를 사용하여 사용자 소프트 프로비전 해제" 및 "REST API를 사용하여 사용자 재활성화"를 참조하세요.PUT/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • 소프트 프로비전 해제 또는 다시 프로비전하지 않는 경우 external_identity.update
  • 요청이 enterprise_owner 역할을 추가하는 경우 business.add_admin
  • 요청이 billing_manager을(를) 추가하는 경우 business.add_billing_manager
  • 요청이 enterprise_owner 역할을 제거하는 경우 business.remove_admin
  • 요청이 billing_manager 역할을 제거하는 경우 business.remove_billing_manager
사용자를 만들기 위해 보낸 POST 요청의 id 필드를 사용하여 기존 사용자의 개별 특성을 업데이트합니다. active을(를) false(으)로 업데이트하여 사용자를 소프트 프로비전 해제하거나 true(으)로 업데이트하여 사용자를 재활성화합니다. 자세한 내용은 "REST API를 사용하여 사용자 소프트 프로비전 해제" 및 "REST API를 사용하여 사용자 재활성화"를 참조하세요.PATCH/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • 소프트 프로비전 해제 또는 다시 프로비전하지 않는 경우 external_identity.update
  • 요청이 enterprise_owner 역할을 추가하는 경우 business.add_admin
  • 요청이 billing_manager을(를) 추가하는 경우 business.add_billing_manager
  • 요청이 enterprise_owner 역할을 제거하는 경우 business.remove_admin
  • 요청이 billing_manager 역할을 제거하는 경우 business.remove_billing_manager
기존 사용자를 완전히 삭제하려는 경우, 사용자를 하드 프로비전 해제할 수 있습니다. 하드 프로비전 해제 후에는 사용자를 재활성화할 수 없으며 사용자를 새 사용자로 프로비전해야 합니다. 자세한 내용은 “REST API를 사용하여 사용자 하드 프로비전 해제”를 참조하세요.DELETE/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • external_identity.deprovision
  • user.remove_email

REST API를 사용하여 사용자 소프트 프로비전 해제

사용자가 엔터프라이즈에 액세스하기 위해 로그인하지 못하도록 하려면, PATCH 또는 PUT 요청을 보내 사용자의 active 필드를 false에서 /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}(으)로 업데이트함으로써 사용자를 소프트 프로비전 해제할 수 있습니다. 사용자를 소프트 프로비전 해제하면 GitHub Enterprise Cloud이(가) 사용자 레코드의 login 및 email 필드를 난독 처리하고 사용자가 일시 중단됩니다.

사용자를 소프트 프로비전 해제하면 external_identity.update 이벤트가 감사 로그에 표시되지 않습니다. 다음 이벤트가 감사 로그에 표시됩니다.

  • user.suspend
  • user.remove_email
  • user.rename
  • external_identity.deprovision

엔터프라이즈에 대해 일시 중단된 모든 사용자를 볼 수 있습니다. 자세한 내용은 "Enterprise에서 사용자 보기"을(를) 참조하세요.

REST API를 사용하여 사용자 재활성화

소프트 프로비전 해제된 사용자가 로그인하여 엔터프라이즈에 액세스하도록 허용하려면, PATCH 또는 PUT 요청을 /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}에 보내 사용자의 active 필드를 true(으)로 업데이트합니다.

사용자를 재활성화하면 external_identity.update 이벤트가 감사 로그에 표시되지 않습니다. 다음 이벤트가 감사 로그에 표시됩니다.

  • user.unsuspend
  • user.remove_email
  • user.rename
  • external_identity.provision

REST API를 사용하여 사용자 하드 프로비전 해제

사용자를 완전히 삭제하려면 DELETE 요청을 /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}에 보내 사용자를 하드 프로비전 해제할 수 있습니다. 엔터프라이즈에서는 사용자가 만든 모든 리소스와 주석이 유지됩니다.

사용자를 하드 프로비전 해제하면 다음 이벤트가 발생합니다.

  • 사용자 레코드의 login 및 email 필드가 난독 처리됩니다.
  • 사용자의 표시 이름이 빈 문자열로 설정됩니다.
  • GitHub Enterprise Cloud은(는) 사용자의 SCIM 특성, 이메일, SSH 키, personal access tokens, GPG 키를 모두 삭제합니다.
  • GitHub Enterprise Cloud의 사용자 계정이 일시 중단되고 계정에 로그인하기 위한 인증이 실패합니다.

사용자를 다시 프로비전하려면 POST 메서드를 사용하여 새 사용자를 만들어야 합니다. 새 사용자는 프로비전 해제된 사용자의 login을(를) 재사용할 수 있습니다. 하드 프로비전 해제된 사용자의 이메일 주소와 새 사용자가 일치하는 경우, GitHub Enterprise Cloud은(는) 이메일 주소와 연결된 기존 Git 커밋의 특성을 새 사용자에게 지정합니다. 원래 사용자가 만든 기존 리소스와 주석은 새 사용자와 연결되지 않습니다.

REST API를 사용하여 그룹 프로비전

엔터프라이즈의 리포지토리에 대한 액세스를 제어하려면, ID 관리 시스템의 그룹을 사용하여 엔터프라이즈에서 사용자의 조직 및 팀 멤버십을 제어할 수 있습니다. REST API 설명서에서 연결된 API 엔드포인트에 대해 참조하고, 코드 예제를 보고, 각 요청과 연결된 감사 로그 이벤트를 검토할 수 있습니다.

새 사용자 계정을 프로비전하는 데 사용 가능한 라이선스가 엔터프라이즈에 필요하지는 않지만, 조직에 사용자를 추가하는 그룹을 프로비전하는 경우 해당 사용자에게 사용 가능한 라이선스가 있어야 합니다. 엔터프라이즈에서 GitHub Enterprise이(가) 포함된 Visual Studio 구독만 사용하는 경우 연결된 사용자를 구독자에게 할당되어야 합니다. 자세한 내용은 "GitHub Enterprise가 포함된 Visual Studio 구독 정보"을(를) 참조하세요.

작업메서드엔드포인트 및 자세한 정보감사 로그의 관련 이벤트
엔터프라이즈에 대해 정의된 모든 그룹을 나열합니다.GET/scim/v2/enterprises/{enterprise}/Groups해당 없음
엔터프라이즈의 새 IdP 그룹을 정의하려면 그룹을 만듭니다. API의 응답에는 그룹을 고유하게 식별하는 id 필드가 포함됩니다.POST/scim/v2/enterprises/{enterprise}/Groups
  • external_group.provision
  • external_group.update_display_name
  • 요청에 사용자 목록이 포함된 경우 external_group.add_member
그룹을 만들기 위해 보낸 POST 요청의 id을(를) 사용하여 엔터프라이즈의 기존 그룹을 검색합니다.GET/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}해당 없음
기존 그룹의 모든 특성을 업데이트합니다.PUT/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.update
  • 요청이 그룹의 이름을 업데이트하는 경우 external_group.update_display_name
  • 요청이 그룹에 사용자를 추가하는 경우 external_group.add_member
  • 요청이 그룹에서 사용자를 제거하는 경우 external_group.remove_member
  • 사용자가 IdP 그룹에 연결된 팀에 소속된 조직의 구성원인지 여부에 따라, 감사 로그에 추가 이벤트가 나타날 수 있습니다. 자세한 내용은 "IdP 그룹의 변경 내용에 대한 추가 감사 로그 이벤트"를 참조하세요.
기존 그룹의 개별 특성을 업데이트합니다.PATCH/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.update
  • 요청이 그룹의 이름을 업데이트하는 경우 external_group.update_display_name
  • 요청이 그룹에 사용자를 추가하는 경우 external_group.add_member
  • 요청이 그룹에서 사용자를 제거하는 경우 external_group.remove_member
  • 사용자가 IdP 그룹에 연결된 팀에 소속된 조직의 구성원인지 여부에 따라, 감사 로그에 추가 이벤트가 나타날 수 있습니다. 자세한 내용은 "IdP 그룹의 변경 내용에 대한 추가 감사 로그 이벤트"를 참조하세요.
기존 그룹을 완전히 삭제합니다.DELETE/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.delete
  • 사용자에게 다른 팀 멤버십이 없는 조직의 팀에 연결된 그룹을 삭제하는 요청의 경우 org.remove_member
  • 사용자에게 다른 팀 멤버십이 있는 조직의 팀에 연결된 그룹을 삭제하는 요청의 경우 team.remove_member

IdP 그룹의 변경 내용에 대한 추가 감사 로그 이벤트

/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}에 대한 PUT 또는 PATCH 요청을 사용하여 기존 그룹의 구성원을 업데이트하는 경우, GitHub Enterprise Cloud은(는) 사용자의 현재 조직 멤버십에 따라 조직에 사용자를 추가하거나 조직에서 사용자를 제거할 수 있습니다. 사용자가 이미 조직에서 하나 이상의 팀에 구성원으로 속해 있는 경우 사용자는 조직의 구성원입니다. 사용자가 이미 조직의 어느 팀에도 속해 있지 않은 경우 사용자는 아직 조직의 구성원이 아닐 수도 있습니다.

요청이 사용자가 아직 구성원이 아닌 조직의 팀에 연결된 그룹을 업데이트하는 경우, 감사 로그에 external_group.update 외에 다음 이벤트도 표시됩니다.

  • org.add_member
  • 요청이 사용자가 아직 구성원이 아닌 조직의 팀에 연결된 그룹에 사용자를 추가하는 경우 org.add_member
  • 요청이 조직의 팀에 연결된 그룹에 사용자를 추가하는 경우 team.add_member

요청이 사용자가 구성원으로 속해 있는 조직의 팀에 연결된 그룹을 업데이트하는 경우, 감사 로그에 external_group.update 외에 다음 이벤트도 표시됩니다.

  • 요청이 조직의 팀에 연결된 그룹에서 사용자를 제거하고, 해당 팀이 사용자가 구성원인 조직의 마지막 팀이 아닌 경우 team.remove_member
  • 요청이 조직에서 사용자가 이미 구성원으로 속해 있는 마지막 팀에 연결된 그룹에서 사용자를 제거하는 경우 org.remove_member

새 SCIM 공급자로 마이그레이션

엔터프라이즈에 대한 SCIM 프로비저닝을 구성한 후, 새 SCIM 공급자로 마이그레이션해야 할 수 있습니다. 자세한 내용은 "새 ID 공급자 또는 테넌트로 엔터프라이즈 마이그레이션"을(를) 참조하세요.

SCIM 프로비전 문제 해결

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

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

  • SCIM 요청이 실패했는데 원인을 확인할 수 없는 경우, ID 관리 시스템의 상태 검사 서비스를 사용할 수 있는지 확인합니다. 또한 GitHub의 상태 페이지를 확인합니다. 자세한 내용은 "GitHub 지원 정보"을(를) 참조하세요.

  • 사용자 프로비전 요청이 400 오류로 인해 실패하고 ID 관리 시스템 로그의 오류 메시지가 계정 소유권 또는 사용자 이름 서식에 문제가 있음을 나타내는 경우 "외부 인증에 대한 사용자 이름 고려 사항"을(를) 참조하세요.

  • 인증에 성공하면 GitHub Enterprise Cloud은(는) SCIM에 의해 프로비전된 ID에 인증된 사용자를 연결합니다. 인증 및 프로비저닝에 대한 고유 식별자는 일치해야 합니다. 자세한 내용은 "SCIM용 REST API 엔드포인트"을(를) 참조하세요. GitHub.com에서 이 매핑을 볼 수도 있습니다. "엔터프라이즈에 대한 사용자의 SAML 액세스 보기 및 관리"을(를) 참조하세요.

  • ID 관리 시스템에서 그룹을 사용하여 액세스를 관리하는 경우 GitHub Enterprise Cloud에 대한 REST API 또는 웹 UI를 사용하여 문제를 해결할 수 있습니다.

추가 문제 해결 제안은 "엔터프라이즈의 ID 및 액세스 관리 문제 해결"을(를) 참조하세요.