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

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

この記事の内容

Note

GitHub Enterprise Server の SCIM は現在公開用ベータ版であり、変更される可能性があります。 GitHub では、最初にステージング インスタンスを使用したテストをお勧めします。 「ステージングインスタンスのセットアップ」をご覧ください。

GitHub Enterprise Server の SCIM プロビジョニングについて

SCIM を使用してユーザー アカウントをプロビジョニングおよび管理するには、ID 管理システムで次の機能を提供する必要があります:

  • Security Assertion Markup Language (SAML) 2.0 を実装するシングル サインオン認証
  • クロス ドメイン ID 管理システム(SCIM)でユーザー ライフサイクル管理

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

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

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

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

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

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

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

前提条件

REST API を使用して SCIM を実装するには、GitHub Enterprise Server で SCIM を使用するための一般的な前提条件が適用されます。 「Provisioning users and groups with SCIM using the REST API」の「前提条件」セクションをご覧ください。

さらに、次の前提条件を検討してください:

  • 「Provisioning users and groups with SCIM using the REST API」の手順 1 から 3 を完了している必要があります。

    • ビルトイン セットアップ ユーザー用に作成された personal access token (classic) を使用して、REST API への要求を認証する必要があります。

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

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

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

ID 管理システムを構成してGitHub Enterprise Serverにユーザーまたはユーザーのグループをプロビジョニングするとき、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 Serverは、このヘッダーがない要求を拒否します。

グループをプロビジョニングする前にユーザーをプロビジョニングする

SCIM グループは、大規模なユーザー アクセスの管理に効果的です。 たとえば、ID 管理システムのグループを使用し、GitHub Enterprise Serverのチームと組織のメンバーシップを管理できます。

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

  1. GitHub Enterprise Serverのユーザー アカウントをプロビジョニングします。
  2. GitHub Enterprise Serverにグループをプロビジョニングします。
  3. ID 管理システムのグループのメンバーシップを更新します。
  4. ID 管理システムのグループにマッピングされたチームをGitHub Enterprise Serverに作成します。

GitHub のグループにアクセスを検証する

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

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

サイト管理者がインスタンスのレート制限を有効にしている場合、ユーザーを初めてプロビジョニングするときにエラーが発生する可能性があります。 試した SCIM プロビジョニングまたはプッシュ操作がレート制限エラーに起因して失敗したかは IdP ログで確認できます。 プロビジョニング失敗に対する反応は IdP によって異なります。

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

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

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

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

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

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

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

  • ユーザーに対してサポートされている属性の概要については、REST API ドキュメントの「SCIM」を参照してください。
  • GitHub Enterprise Server のプロビジョニングされたユーザーを Web UI で表示できます。 詳しくは、「Enterprise の人を表示する」を参照してください。
アクションメソッドエンドポイントとその他の情報監査ログのイベント
Enterprise のプロビジョニングされたすべてのユーザーをリストし、これには“active“を“false“に設定して論理的にプロビジョニング解除されたすべてのユーザーが含まれます。GET/scim/v2/Users該当なし
ユーザーを作成します。 API の応答には、ユーザーを一意に識別するために id フィールドが含まれています。POST/scim/v2/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/Users/{scim_user_id}該当なし
ユーザーを作成するために送信した POST 要求の id フィールドを使用し、既存ユーザーのすべての属性を更新します。 “active“を“false“に更新してユーザーを論理的にプロビジョニング解除するか、“true“に更新してユーザーを再度有効にします。 詳細については、「REST API でユーザーを論理的にプロビジョニング解除する」と「REST API でユーザーを再度有効にする」を参照してください。PUT/scim/v2/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/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/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/Users/{scim_user_id} に対して送信してユーザーの“active“フィールドを“false“に更新することにより、ユーザーを論理的にプロビジョニング解除できます。 ユーザーを論理的にプロビジョニング解除すると、GitHub Enterprise Serverはユーザー レコードの“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/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/Users/{scim_user_id} に対して“DELETE“要求を送信してユーザーをハードウェア上でプロビジョニング解除できます。 Enterprise は、ユーザーが作成したすべてのリソースとコメントを保持します。

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

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

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

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

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

エンタープライズでは、新しいユーザー アカウントをプロビジョニングするために使用可能なライセンスは必要ありませんが、組織にユーザーが追加されるグループをプロビジョニングする場合は、それらのユーザーに対して使用可能なライセンスが必要です。

アクションメソッドエンドポイントとその他の情報監査ログの関連イベント
Enterprise に定義されたすべてのグループをリストします。GET/scim/v2/Groups該当なし
Enterprise に新しい IdP グループを定義するには、グループを作成します。 API の応答には、グループを一意に識別する id フィールドが含まれています。POST/scim/v2/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/Groups/{scim_group_id}該当なし
既存グループのすべての属性を更新します。PUT/scim/v2/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/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/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/Groups/{scim_group_id} に更新する場合、ユーザーの現在の組織メンバーシップに応じて、GitHub Enterprise Serverは組織にユーザーを追加したり、組織からユーザーを削除したりする場合があります。 ユーザーが既に組織内で少なくとも 1 つのチームのメンバーである場合、そのユーザーは組織のメンバーです。 ユーザーが組織内のチームのメンバーではない場合、そのユーザーはまだ組織のメンバーでもない可能性があります。

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

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

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

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

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

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

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

  • SCIM 要求が失敗して原因を特定できない場合、ID 管理システムの状態をチェックしてサービスが利用可能だったことを確認します。

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

  • 認証が成功すると、GitHub Enterprise Server は、SCIM によってプロビジョニングされた ID に認証されたユーザーをリンクします。 認証とプロビジョニングの一意の識別子が一致している必要があります。 詳細については、「SCIM の REST API エンドポイント」を参照してください。

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

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