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

注:

GitHubのパブリック SCIM スキーマを使用したユーザーにプロビジョニングのサポートはパブリックベータ版であり、変更される場合があります。
GitHub では、IdP と GitHub.com 上の運用データから分離された環境でプロビジョニングをテストすることをお勧めします。

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 プロバイダーの使用
他の ID 管理システムの使用

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

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

認証とプロビジョニングの両方に 1 つのパートナー IdP を使用するとき、GitHubは、パートナー IdP でアプリケーションにサポートに加え、GitHub Enterprise Cloudで IdP の統合を提供します。

パートナー IdP を使用して SCIM プロビジョニングの構成の詳細については、「エンタープライズマネージドユーザーの SCIM プロビジョニングの構成」を参照してください。

他の 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 の認証を構成する」を参照してください。
GitHubの REST API でユーザーとグループをプロビジョニングするには、ID 管理システムが SCIM 2.0 規格をサポートしている必要があります。詳細については、IETF Web サイトにある次の RFC を参照してください
Enterprise にオープンの SCIM 構成を有効にする必要があります。詳しくは、「エンタープライズマネージドユーザーの SCIM プロビジョニングの構成」を参照してください。
SCIM の REST API エンドポイントに要求を認証するには、Enterprise の設定ユーザーに関連付けられたpersonal access token (classic)を使用する必要があります。トークンには admin:enterprise スコープが必要です。 GitHubは、トークンに有効期限を構成しないことをお勧めします。詳しくは、「エンタープライズマネージドユーザーの SCIM プロビジョニングの構成」を参照してください。
認証とプロビジョニングに使用するシステムのユーザーレコードは、一意の識別子を共有し、GitHub の一致条件を満たす必要があります。詳しくは、REST API ドキュメントの「SCIM の REST API エンドポイント」をご覧ください。

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

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

ID 管理システムが書き込み操作の唯一のソースであることを確認する
REST API エンドポイントに有効な要求を送信する
グループをプロビジョニングする前にユーザーをプロビジョニングする
GitHub Enterprise Cloudのグループにアクセスを検証する
GitHub Enterprise Cloudのレート制限を理解する
監査ログストリーミングを構成する

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 管理システムでグループを持ったチームメンバーシップを管理するには、順序に従って次の手順を完了する必要があります。

GitHub Enterprise Cloudのユーザーアカウントをプロビジョニングします。
GitHub Enterprise Cloudにグループをプロビジョニングします。
ID 管理システムのグループのメンバーシップを更新します。
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 のレート制限を超えないようにするには、IdP アプリケーションに 1 時間あたり 1,000 人を超えるユーザーを割り当てないでください。グループを使って IdP アプリケーションにユーザーを割り当てる場合、1 時間あたり 1,000 人を超えるユーザーを各グループに追加しないでください。これらのしきい値を超えると、ユーザーをプロビジョニングしようとすると、"レート制限" エラーが発生して失敗する可能性があります。試した SCIM プロビジョニングまたはプッシュ操作がレート制限エラーに起因して失敗したかは IdP ログで確認できます。プロビジョニング失敗に対する反応は IdP によって異なります。

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

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

このログのイベント量により、GitHub ではデータを 180 日間保持します。監査ログデータを失わないようにするため、また監査ログ内のアクティビティをより詳細に表示するには、GitHub で監査ログストリーミングを構成することをお勧めします。監査ログをストリーミングするとき、SCIM プロビジョニングの REST API エンドポイントへの要求など、必要に応じて API 要求のイベントをストリーミングできます。詳しくは、「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`
ユーザーを作成するために送信した `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`
ユーザーを作成するために送信した `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 でユーザーの論理的なプロビジョニング解除

ユーザーがログインして 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

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

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 ドキュメントを参照してコード例を確認してください。また、各要求に関連付けられた監査ログイベントも確認できます。

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

グループでサポートされている属性の概要については、REST API ドキュメントの「SCIM」を参照してください。
グループに関連する監査ログイベントの概要については、「エンタープライズの監査ログイベント」を参照してください。
GitHub Enterprise Cloud のプロビジョニングされたグループを Web UI で表示できます。詳しくは、「ID プロバイダーグループを使用したチームメンバーシップの管理」を参照してください。

アクション	メソッド	エンドポイントとその他の情報	監査ログの関連イベント
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`
グループを作成するために送信した `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` ユーザーが既に 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 グループへの変更に関する追加の監査ログイベント

“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 プロビジョニングのトラブルシューティング

GitHub が REST API への要求のレート制限を行っている場合は、「GitHub Enterprise Cloud のレート制限について」で詳細を確認できます。
API 要求の監査ログストリーミングとストリームイベントを有効にした場合、EnterpriseUsersScim または EnterpriseGroupsScim コントローラでイベントをフィルター処理し、SCIM プロビジョニングのために REST API エンドポイントへの要求を確認できます。
SCIM 要求が失敗して原因を特定できない場合、ID 管理システムの状態をチェックしてサービスが利用可能だったことを確認します。さらに、GitHubの状態ページをチェックします。詳しくは、「GitHub Supportについて」を参照してください。
ユーザーをプロビジョニングする要求が 400 エラーで失敗し、ID 管理システムのログのエラーメッセージにアカウントの所有権またはユーザー名の書式設定に関する問題が示されている場合、「外部認証のユーザー名に関する考慮事項」を確認してください。
認証が成功すると、GitHub Enterprise Cloud は、SCIM によってプロビジョニングされた ID に認証されたユーザーをリンクします。認証とプロビジョニングの一意の識別子が一致している必要があります。詳しくは、「SCIM の REST API エンドポイント」を参照してください。このマッピングは、GitHub.comで表示できます。「Enterprise へのユーザの SAML アクセスの表示および管理」をご覧ください。
ID 管理システムのグループを使用してアクセスを管理している場合は、REST API または Web UI を使用して GitHub Enterprise Cloud のトラブルシューティングを行うことができます。
- REST API を使用し、ID 管理システムのグループメンバーシップをGitHubのそれらのグループに対する解釈と比較できます。「外部グループの REST API エンドポイント」と「チームの REST API エンドポイント」を参照してください。
- Web UI を使用したトラブルシューティングの詳細については、「ID プロバイダーグループを使用したチームメンバーシップのトラブルシューティング」を参照してください。

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