Cloud OAuth API を使用してユーザー情報を取得する

このガイドでは、Cloud OAuth API（cloudoauth.googleapis.com）の /userinfo エンドポイントを使用して、認証済みの従業員ユーザーの OpenID Connect（OIDC）標準クレーム、カスタム ディレクトリ クレーム、グループ メンバーシップを取得する方法について説明します。

始める前に

  1. Workforce Identity プールとプロバイダを構成します。詳細については、Workforce Identity 連携を構成するをご覧ください。
  2. OAuth クライアントを登録し、認証コードをアクセス トークンと交換します。詳細については、Cloud OAuth API でトークンを交換するをご覧ください。
  3. アクセス トークンに openid スコープが含まれていることを確認します。

  4. Cloud OAuth API を有効にします。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。

    API の有効化

組織スコープのエンドポイント

Cloud OAuth API は、クライアント アプリケーションとリソースが特定のGoogle Cloud 組織に制限されている場合に使用できる組織スコープ（シングルテナント）エンドポイントを提供します。

Cloud OAuth API の organizations.userinfo メソッドは、特定の組織で認証されたユーザーの OpenID Connect（OIDC）標準クレーム、カスタム クレーム、グループ メンバーシップを取得します。

リクエストのデータを使用する前に、次のように置き換えます。

  • TOKEN: トークン交換エンドポイントから取得した有効期間の短い OAuth 2.0 アクセス トークン。
  • ORGANIZATION_ID: 実際の数値 Google Cloud の組織 ID

HTTP メソッドと URL:

GET https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/userinfo

リクエストを送信するには、次のいずれかのオプションを展開します。

SCIM プロビジョニングが有効になっていない Workforce Identity プールの場合、エンドポイントはプロファイル属性、カスタム クレーム、グループ メンバーシップをインラインで返します。

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

ユーザー クレームと SCIM 分散グループ

リクエストが成功すると、/userinfo エンドポイントは HTTP 200 OK ステータスと、認証されたユーザーのクレームを含む JSON オブジェクトを返します。

クレームの形式は、Workforce Identity プール プロバイダが SCIM プロビジョニングを使用するかどうかによって異なります。

インライン クレーム（非 SCIM ID プール）

SCIM プロビジョニングが有効になっていない Workforce Identity プールの場合、エンドポイントはプロファイル属性、カスタム クレーム、グループ メンバーシップをインラインで返します。

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

分散クレーム（SCIM 対応の ID プール）

SCIM プロビジョニングが有効になっている Workforce Identity プールの場合、グループ メンバーシップは分散クレームとして返されます。レスポンスには、/groups エンドポイントを参照する _claim_names と _claim_sources が含まれます。

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "name": "Jane Doe",
  "email": "user@example.com",
  "_claim_names": {
    "groups": "src1"
  },
  "_claim_sources": {
    "src1": {
      "endpoint": "https://cloudoauth.googleapis.com/v1/common/groups"
    }
  }
}

クレーム フィールド

レスポンスには、次の標準クレーム フィールドと分散クレーム フィールドが含まれます。

フィールド タイプ 説明
sub string Workforce Identity プール内の認証済みユーザーの固有のプリンシパル ID。
name string ID プロバイダから取得できる場合は、ユーザーのフルネーム。
email string 認証済みユーザーのメールアドレス。
groups array of strings （SCIM 以外の場合のみ）ユーザーのエンタープライズ グループ メンバーシップのリスト。
_claim_names object （SCIM 対応のみ）分散クレーム名（groups など）を _claim_sources のソース識別子にマッピングする JSON オブジェクト。
_claim_sources object （SCIM 対応のみ）分散クレーム識別子ごとにソース エンドポイントを定義する JSON オブジェクト。

/userinfo エンドポイントから返されるエラー レスポンスについては、Cloud OAuth ユーザー情報とグループのエラーをご覧ください。

次のステップ