REST API を使用した SCIM でユーザーとグループのプロビジョニング

GitHub の クロスドメイン ID 管理システム (SCIM) 用 REST API を使用して、お使いの ID プロバイダー (IdP) のユーザー アカウントのライフサイクルを管理します。

この機能を使用できるユーザーについて

GitHub Enterprise Cloud で Enterprise Managed Users を使用するエンタープライズ アカウントで使用できます。 「Enterprise Managed Users について」をご覧ください。

この記事の内容

Note

GitHub では、IdP と GitHub 上の運用データから分離された環境でプロビジョニングをテストすることをお勧めします。

Enterprise Managed Users用 IAM について

GitHubの Enterprise がEnterprise Managed Users用に作成された場合、ユーザー アカウントをプロビジョニングして管理するため、外部 ID 管理システムを構成する必要があります。 ID 管理システムは、次の機能を提供する必要があります。

  • 次の 2 つあるシングル サインオン (SSO) 規格のいずれかを実装したシングル サインオン認証
    • Security Assertion Markup Language(SAML)2.0
    • OpenID Connect(OIDC)は、Microsoft Entra ID(旧称 Azure AD)を使用した場合にのみサポートされます。
  • クロス ドメイン ID 管理システム(SCIM)でユーザー ライフサイクル管理

Enterprise の認証とプロビジョニングを構成するとき、パートナー IdP を使用するか、ID 管理システムの別の組み合わせを使用できます。

パートナー ID プロバイダーの使用

各パートナー IdP は、SSO とユーザー ライフサイクル管理の両方を実装する"舗装されたパス"アプリケーションを提供します。 構成を簡略化するには、GitHub は認証とプロビジョニングの両方にパートナー IdP のアプリケーションを使用することをお勧めします。 パートナー IdPs リストと詳細については、「Enterprise Managed Users について」 を参照してください。

パートナー IdP を使用して SCIM プロビジョニングの構成の詳細については、「Provisioning users and groups with SCIM using the REST API」を参照してください。

他の ID 管理システムの使用

移行のオーバーヘッド、ライセンス コスト、組織の慣性が原因で認証とプロビジョニングの両方にパートナー IdP を使用できない場合、別の ID 管理システムまたはシステムの組み合わせを使用できます。 システムは、SAML を使用した認証と SCIM を使用したユーザー ライフサイクル管理を提供し、GitHubの統合ガイドラインに従う必要があります。

GitHubは、すべての ID 管理システムとの統合をテストしていません。 Enterprise Managed Users との統合は可能ですが、GitHubのサポート チームはこれらのシステムに関連する問題を支援できない場合があります。 パートナー IdP ではない ID 管理システムに関するヘルプが必要な場合、または SAML 認証にのみパートナー IdP を使用する場合、システムのドキュメント、サポート チーム、その他のリソースを利用する必要があります。

前提条件

  • GitHub Enterprise Cloudの使用を開始したとき、マネージド ユーザーを含む Enterpriseを作成することを選択している必要があります。 詳しくは、「GitHub Enterprise Cloud の Enterprise の種類の選択」を参照してください。

  • プロビジョンニングを構成する前に、ユーザーに認証を構成する必要があります。 この構成は、ID 管理システムとGitHub Enterprise Cloudの両方でセットアップする必要があります。 詳しくは、「Enterprise Managed User の認証を構成する」を参照してください。

  • Enterprise にオープンの SCIM 構成を有効にする必要があります。 詳しくは、「Provisioning users and groups with SCIM using the REST API」を参照してください。

  • SCIM の REST API エンドポイントに要求を認証するには、Enterprise の設定ユーザーに関連付けられたpersonal access token (classic)を使用する必要があります。 トークンには scim:enterprise スコープが必要です。 GitHubは、トークンに有効期限を構成しないことをお勧めします。 「Enterprise Managed Users の概要」を参照してください。

  • GitHubの REST API でユーザーとグループをプロビジョニングするには、ID 管理システムが SCIM 2.0 規格をサポートしている必要があります。 詳細については、IETF Web サイトにある次の RFC を参照してください

  • 認証とプロビジョニングに使用するシステムのユーザー レコードは、一意の識別子を共有し、GitHub の一致条件を満たす必要があります。 詳しくは、REST API ドキュメントの「SCIM の REST API エンドポイント」をご覧ください。

GitHubの REST API で SCIM プロビジョニングのベスト プラクティス

ID 管理システムを構成してGitHub Enterprise Cloudにユーザーまたはユーザーのグループをプロビジョニングするとき、GitHubは次のガイドラインに従うことを強くお勧めします。

ID 管理システムが書き込み操作の唯一のソースであることを確認する

環境に信頼できる唯一の情報源があることを確認するには、ID 管理システムから SCIM プロビジョニング用に REST API にのみプログラムで書き込む必要があります。 GitHubは、1 つのシステムのみが API に“POST“、“PUT“、“PATCH“、“DELETE“要求を送信することを強くお勧めします。

ただし、スクリプトの“GET“要求または Enterprise 所有者によるアドホック要求を使用し、GitHubの API から、情報を安全に取得できます。

警告: SCIM プロビジョニングにパートナー IdP を使用する場合、IDP のアプリケーションが API への書き込み要求を行う唯一のシステムである必要があります。 “POST“、“PUT“、“PATCH“、“DELETE“メソッドを使用してアドホック要求を行った場合、後続の同期試行は失敗してプロビジョニングが Enterprise に対して正しく機能しません。

REST API エンドポイントに有効な要求を送信する

SCIM でユーザーをプロビジョニングするGitHubの REST API エンドポイントには、適格な要求が必要です。 次のガイドラインに注意してください。

  • REST 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 のグループにアクセスを検証する

ID 管理システムのグループを使用してアクセスを管理している場合、任意でユーザーが必要なアクセス権を取得することを検証できます。 REST API を使用し、システムのグループ メンバーシップをGitHubがそれらのグループに対する解釈と比較できます。 詳しくは、「外部グループの REST API エンドポイント」および REST API のドキュメントの「チームの REST API エンドポイント」を参照してください。

GitHub のレート制限を理解する

プラットフォームの可用性と信頼性を確保するため、GitHubはレート制限を実装します。

レート制限を考慮ない場合、初めてEnterprise Managed Usersで大企業のオンボーディングすると制限を超える可能性があります。 GitHub Enterprise Cloud のレート制限を超えないようにするには、IdP の SCIM 統合に 1 時間あたり 1,000 人を超えるユーザーを割り当てないでください。 グループを使って IdP アプリケーションにユーザーを割り当てる場合、1 時間あたり 1,000 人を超えるユーザーを各グループに追加しないでください。 これらのしきい値を超えると、ユーザーをプロビジョニングしようとすると、"レート制限" エラーが発生して失敗する可能性があります。 試した SCIM プロビジョニングまたはプッシュ操作がレート制限エラーに起因して失敗したかは IdP ログで確認できます。 プロビジョニング失敗に対する反応は IdP によって異なります。

詳しくは、「REST API のレート制限」を参照してください。

監査ログ ストリーミングを構成する

エンタープライズの監査ログには、エンタープライズでのアクティビティに関する詳細が表示されます。 監査ログを使用して、SCIM の構成をサポートできます。 詳しくは、「企業の監査ログについて」を参照してください。

このログのイベント量により、GitHub ではデータを 180 日間保持します。 監査ログ データを失わないようにするため、また監査ログ内のアクティビティをより詳細に表示するには、GitHub で監査ログ ストリーミングを構成することをお勧めします。 監査ログをストリーミングするとき、SCIM プロビジョニングの REST API エンドポイントへの要求など、必要に応じて API 要求のイベントをストリーミングできます。 詳しくは、「Enterprise の監査ログのストリーミング」を参照してください。

SCIM トークンのスコープを制限する

セキュリティ態勢を向上させるために、SCIM 呼び出しを行うために必要な REST API エンドポイントへのトークンのアクセスを制限するには、scim:enterprise スコープのみを持つ personal access token (classic) を使用することをお勧めします。

現在、admin:enterprise スコープのトークンを使用している場合は、このトークンが Enterprise 上のすべてのアクションへのアクセス権を付与していることに注意してください。 中断することなく、scim:enterprise スコープだけでトークンを新しいトークンにスワップできます。

REST API でユーザーのプロビジョニング

ユーザーをプロビジョニング、リスト、管理するには、次の REST API エンドポイントに要求を行います。 関連付けられた API エンドポイントについては、REST API ドキュメントを参照してコード例を確認してください。また、各要求に関連付けられた監査ログ イベントも確認できます。

ID 管理システム上の ID を持つユーザーが企業にサインインできるようにするには、対応するユーザーを作成する必要があります。 Enterprise は、新規のユーザー アカウントをプロビジョニングするために利用可能なライセンスは必要ありません。

  • ユーザーに対してサポートされている属性の概要については、REST API ドキュメントの「SCIM」を参照してください。
  • GitHub Enterprise Cloud のプロビジョニングされたユーザーを Web UI で表示できます。 詳しくは、「Enterprise の人を表示する」を参照してください。
アクションメソッドエンドポイントとその他の情報監査ログのイベント
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
  • 要求が成功した場合、external_identity.scim_api_success
  • 要求が失敗した場合、external_identity.scim_api_failure
ユーザーを作成するために送信した POST 要求の id フィールドを使用し、Enterprise の既存ユーザーを回収します。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
  • 要求が成功した場合、external_identity.scim_api_success
  • 要求が失敗した場合、external_identity.scim_api_failure
ユーザーを作成するために送信した 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
  • 要求が成功した場合、external_identity.scim_api_success
  • 要求が失敗した場合、external_identity.scim_api_failure
既存ユーザーを完全に削除するには、ユーザーをハードウェア上のプロビジョニング解除できます。 ハードウエア上のプロビジョニング解除後、ユーザーを再度有効にすることはできません。ユーザーを新規ユーザーとしてプロビジョニングする必要があります。 詳細については、「REST API でハードウェア上のプロビジョニング解除」を参照してください。DELETE/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • external_identity.deprovision
  • user.remove_email
  • 要求が成功した場合、external_identity.scim_api_success
  • 要求が失敗した場合、external_identity.scim_api_failure

REST API でユーザーの論理的なプロビジョニング解除

ユーザーがログインして Enterprise にアクセスすることを防止するには、“PUT“または“PATCH“要求を /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} に対して送信してユーザーの“active“フィールドを“false“に更新することにより、ユーザーを論理的にプロビジョニング解除できます。 ユーザーを論理的にプロビジョニング解除すると、GitHub Enterprise Cloudはユーザー レコードの“login“と“email“フィールドを難読化し、ユーザーが保留になります。

ユーザーを論理的にプロビジョニング解除すると、external_identity.update イベントは監査ログに表示されません。 次のイベントは監査ログに表示されます。

  • user.suspend
  • user.remove_email
  • user.rename
  • external_identity.deprovision
  • この要求が成功した場合、external_identity.scim_api_success
  • 要求が失敗した場合、external_identity.scim_api_failure

Enterprise の保留にされたすべてのユーザーを表示できます。 詳細については、「Enterprise の人を表示する」を参照してください。

REST API でユーザーを再度有効にする

論理的にプロビジョニング解除されたユーザーがログインして Enterprise にアクセスできるようにするには、ユーザーの“active“フィールドを“true“に更新する /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} に対して“PUT“または“PATCH“要求を送信し、ユーザーを保留解除します。

ユーザーを再度有効にすると、external_identity.update イベントは監査ログに表示されません。 次のイベントは監査ログに表示されます。

  • user.unsuspend
  • user.remove_email
  • user.rename
  • external_identity.provision
  • この要求が成功した場合、external_identity.scim_api_success
  • 要求が失敗した場合、external_identity.scim_api_failure

REST API でユーザーをハードウェア上のプロビジョニング解除する

ユーザーを完全に削除するには、/scim/v2/enterprises/{enterprise}/Users/{scim_user_id} に対して“DELETE“要求を送信してユーザーをハードウェア上でプロビジョニング解除できます。 Enterprise は、ユーザーが作成したすべてのリソースとコメントを保持します。

ユーザーをハードウェア上でプロビジョニング解除すると、次のイベントが発生します。

  • ユーザー レコードの“login“と“email“フィールドが難読化されます。
  • ユーザーの表示名は空の文字列に設定されます。
  • GitHub Enterprise Cloudは、ユーザーのすべての SCIM 属性、電子メール、SSH キー、personal access tokens、GPG キーを削除します。
  • GitHub Enterprise Cloudのユーザーのアカウントは保留にされ、アカウントにログインするための認証が失敗します。

ユーザーを再プロビジョニングするには、“POST“メソッドを使用して新規ユーザーを作成する必要があります。 新規ユーザーは、プロビジョニング解除されたユーザーの login を再利用できます。 ハードウェア上のプロビジョニング解除されたユーザーのメール アドレスと新規ユーザーが一致する場合、GitHub Enterprise Cloudはメール アドレスに関連付けられた既存の Git コミットを新規ユーザーに属性付けします。 元のユーザーが作成した既存のリソースとコメントは、新規ユーザーには関連付けされません。

REST API でグループのプロビジョニング

Enterprise のリポジトリへのアクセスを管理するには、ID 管理システムのグループを使用して Enterprise のユーザーに対して組織とチームのメンバーシップを管理できます。 関連付けられた API エンドポイントについては、REST API ドキュメントを参照してコード例を確認してください。また、各要求に関連付けられた監査ログ イベントも確認できます。

エンタープライズでは、新しいユーザー アカウントをプロビジョニングするために使用可能なライセンスは必要ありませんが、組織にユーザーが追加されるグループをプロビジョニングする場合は、それらのユーザーに対して使用可能なライセンスが必要です。 エンタープライズで GitHub Enterprise を持つ Visual Studio サブスクリプション のみを使用している場合は、関連付けられているユーザーをサブスクライバーに割り当てる必要があります。 詳しくは、「Visual Studio subscriptions with GitHub Enterpriseについて」をご覧ください。

アクションメソッドエンドポイントとその他の情報監査ログの関連イベント
Enterprise に定義されたすべてのグループをリストします。GET/scim/v2/enterprises/{enterprise}/Groups該当なし
Enterprise に新しい IdP グループを定義するには、グループを作成します。 API の応答には、グループを一意に識別する id フィールドが含まれています。POST/scim/v2/enterprises/{enterprise}/Groups
  • external_group.provision
  • external_group.update_display_name
  • 要求にユーザーのリストが含まれている場合、external_group.add_member
  • 要求が成功した場合、external_group.scim_api_success
  • 要求が失敗した場合、external_group.scim_api_failure
グループを作成するために送信した POST 要求の id を使用し、Enterprise の既存グループを回収します。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
  • 要求が成功した場合、external_group.scim_api_success
  • 要求が失敗した場合、external_group.scim_api_failure
  • ユーザーが既に 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
  • 要求が成功した場合、external_group.scim_api_success
  • 要求が失敗した場合、external_group.scim_api_failure
  • ユーザーが既に IdP グループにリンクしたチームの組織メンバーであるかどうかに応じて、監査ログに追加のイベントが表示される場合があります。 詳細については、「IdP グループへの変更に関する追加の監査ログ イベント」を参照してください。
既存グループを完全に削除します。DELETE/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.delete
  • 要求は、ユーザーが他のチームメンバーシップがない組織のチームにリンクされたグループを削除した場合、org.remove_member
  • 要求は、ユーザーが他のチームメンバーシップがある組織のチームにリンクされたグループを削除した場合、team.remove_member
  • 要求が成功した場合、external_group.scim_api_success
  • 要求が失敗した場合、external_group.scim_api_failure

IdP グループへの変更に関する追加の監査ログ イベント

“PUT“または“PATCH“要求を使用して既存グループのメンバーを /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id} に更新する場合、ユーザーの現在の組織メンバーシップに応じて、GitHub Enterprise Cloudは組織にユーザーを追加したり、組織からユーザーを削除したりする場合があります。 ユーザーが既に組織内で少なくとも 1 つのチームのメンバーである場合、そのユーザーは組織のメンバーです。 ユーザーが組織内のチームのメンバーではない場合、そのユーザーはまだ組織のメンバーでもない可能性があります。

要求は、ユーザーがまだメンバーではない組織のチームにリンクされたグループを更新した場合、external_group.update に加えて、次のイベントが監査ログに表示されます。

  • org.add_member
  • 要求は、ユーザーがまだメンバーではない組織のチームにリンクされたグループにユーザーを追加した場合、org.add_member
  • 要求が、組織のチームにリンクされたグループにユーザーを追加した場合、team.add_member

要求は、ユーザーが既にメンバーである組織のチームにリンクされたグループを更新した場合、external_group.update に加えて、次のイベントが監査ログに表示されます。

  • 要求は、組織のチームにリンクされたグループからユーザーを削除し、当該チームが、ユーザーがメンバーである組織の最後のチームではない場合、team.remove_member
  • 要求は、ユーザーが既にメンバーである組織の最後のチームにリンクされたグループからユーザーを削除した場合、org.remove_member

新しい SCIM プロバイダーへの移行

Enterprise の SCIM プロビジョニングを構成した後、新しい SCIM プロバイダーへの移行が必要になる場合があります。 詳しくは、「新しい ID プロバイダーまたはテナントへの Enterprise の移行」を参照してください。

SCIM プロビジョニングのトラブルシューティング

  • REST API への要求がレート制限されている場合は、「GitHub でのレート制限を理解する」を参照してください。

  • API 要求の監査ログ ストリーミングとストリーム イベントを有効にした場合、EnterpriseUsersScim または EnterpriseGroupsScim コントローラでイベントをフィルター処理し、SCIM プロビジョニングのために REST API エンドポイントへの要求を確認できます。

  • SCIM 要求が失敗して原因を特定できない場合、ID 管理システムの状態をチェックしてサービスが利用可能だったことを確認します。 さらに、GitHub の状態ページを確認します。 詳しくは、「GitHub Supportについて」をご覧ください。

  • ユーザーをプロビジョニングする要求が 400 エラーで失敗し、ID 管理システムのログのエラー メッセージにアカウントの所有権またはユーザー名の書式設定に関する問題が示されている場合、「外部認証のユーザー名に関する考慮事項」を確認してください。

  • 認証が成功すると、GitHub Enterprise Cloud は、SCIM によってプロビジョニングされた ID に認証されたユーザーをリンクします。 認証とプロビジョニングの一意の識別子が一致している必要があります。 詳細については、「SCIM の REST API エンドポイント」を参照してください。 このマッピングは、GitHub で表示することもできます。 「Enterprise へのユーザの SAML アクセスの表示および管理」を参照してください。

  • ID 管理システムのグループを使用してアクセスを管理している場合は、REST API または Web UI を使用して GitHub Enterprise Cloud のトラブルシューティングを行うことができます。

その他のトラブルシューティングのお勧めについては、「Enterprise のアイデンティティおよびアクセス管理のトラブルシューティング」を参照してください。