REST を使用して認証する

このページでは、Google API に REST リクエストを送信するときの認証方法について説明します。

Google クライアント ライブラリを使用する際の認証方法については、クライアント ライブラリを使用した認証をご覧ください。

準備

このページのサンプルを実行するには、次の手順を完了させます。

1. Install the Google Cloud CLI.

2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

gcloud CLI を使用しない場合は、この手順をスキップして、サービス アカウントの権限借用またはメタデータ サーバーを使用してトークンを生成できます。

認証情報の種類

REST 呼び出しの認証に使用できる認証情報は次のとおりです。

• gcloud CLI 認証情報

  これは、ローカル開発環境で REST メソッドに認証情報を渡すための最も簡単で安全な方法です。呼び出すメソッドに対して必要な Identity and Access Management（IAM）権限がユーザー アカウントに付与されている場合は、この方法をおすすめします。

  gcloud 認証情報は、gcloud CLI を使用して ADC に指定する認証情報とは異なります。詳細については、gcloud CLI 認証構成と ADC 構成をご覧ください。

• アプリケーションのデフォルト認証情報（ADC）に指定する認証情報。

  ADC は、コードが実行されているリソース（Compute Engine 仮想マシンなど）から認証情報を検索します。このため、本番環境での REST 呼び出しの認証方法としては、これを推奨します。ローカル開発環境での認証に ADC を使用することも可能です。その場合は、gcloud CLI を使用して、認証情報を含むファイルをローカル ファイル システム内に作成します。

• サービス アカウントの権限を借用して指定する認証情報。

  この方法では追加の設定が必要です。別のサービス アカウント用の有効期間が短い認証情報を取得するために既存の認証情報を使用する場合（例: サービス アカウントを使ってローカルでテストを行う場合や、一時的な権限昇格をリクエストする場合）は、この方法を使用します。

• メタデータ サーバーから返される認証情報。

  この方法は、メタデータ サーバーにアクセスできる環境でのみ機能します。メタデータ サーバーから返される認証情報は、関連付けられているサービス アカウントを使用してアプリケーションのデフォルト認証情報により検出される認証情報と同じですが、メタデータ サーバーにアクセス トークンを明示的にリクエストすると、REST リクエストで指定できます。メタデータ サーバーに認証情報をクエリするには、HTTP GET リクエストが必要です。この方法では、Google Cloud CLI を使用しません。

• API キー

  REST リクエストで API キーを使用できるのは、API キーを受け取る API の場合のみです。また、API キーは、API での使用を阻むような制限がされていない必要があります。

gcloud CLI 認証情報

次の例を実行するには、プロジェクトに対する resourcemanager.projects.get 権限が必要です。resourcemanager.projects.get 権限は、閲覧者のロール（roles/browser）など、さまざまなロールに含まれています。

1. ユーザーの認証情報から生成されたアクセス トークンを挿入するには、gcloud auth print-access-token コマンドを使用します。

   次の例では、指定したプロジェクトの詳細を取得します。どの REST リクエストに対しても、同じパターンを使用できます。

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

   • PROJECT_ID: Google Cloud プロジェクト ID または名前。

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

   curl

   次のコマンドを実行します。

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   次のコマンドを実行します。

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   プロジェクトの詳細が返されます。

割り当てプロジェクトが必要な API の場合は、リクエストのために明示的に設定する必要があります。詳細については、このページの REST リクエストを使用して割り当てプロジェクトを設定するをご覧ください。

アプリケーションのデフォルト認証情報

以下の例を実行するには、ADC に指定する認証情報に関連付けられているプリンシパルに、プロジェクトに対する resourcemanager.projects.get 権限が必要です。resourcemanager.projects.get 権限は、閲覧者のロール（roles/browser）など、さまざまなロールに含まれています。

1. ADC に認証情報を指定します。

   Google Cloud コンピューティング リソースで実行する場合は、ADC にユーザー認証情報を指定しないでください。代わりに、関連付けられているサービス アカウントを使用して認証情報を指定します。詳細については、サービス アカウントが関連付けられているリソースに ADC を設定するをご覧ください。

2. gcloud auth application-default print-access-token コマンドを使用して、ADC から返されたアクセス トークンを REST リクエストに挿入します。

   次の例では、指定したプロジェクトの詳細を取得します。どの REST リクエストに対しても、同じパターンを使用できます。

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

   • PROJECT_ID: Google Cloud プロジェクト ID または名前。

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

   curl

   次のコマンドを実行します。

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   次のコマンドを実行します。

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   プロジェクトの詳細が返されます。

   この API が対応していないエンドユーザー認証情報に関するエラー メッセージがリクエストから返された場合は、このページの REST リクエストを使用して割り当てプロジェクトを設定するをご覧ください。

権限の借用元であるサービス アカウント

サービス アカウントの権限を借用してアクセス トークンを生成する最も簡単な方法は、gcloud CLI を使用することです。ただし、トークンをプログラムで生成する必要がある場合や、gcloud CLI の使用を避ける場合は、権限借用を使用して有効期間の短いトークンを生成できます。

サービス アカウントの権限の借用について詳しくは、サービス アカウントの権限借用を使用するをご覧ください。

1. 必要な権限を確認します。

   • 権限の借用に使用するプリンシパルには、権限の借用元であるサービス アカウント（権限を保持するサービス アカウント）に対する iam.serviceAccounts.getAccessToken 権限が必要です。iam.serviceAccounts.getAccessToken 権限は、サービス アカウント トークン作成者のロール（roles/iam.serviceAccountTokenCreator）に含まれています。ユーザー アカウントを使用している場合は、プロジェクトに対するオーナーロール（roles/owner）がある場合でも、この権限を追加する必要があります。詳細については、必要な権限の設定をご覧ください。

2. 権限を保持するサービス アカウント（権限の借用元であるサービス アカウント）を特定または作成します。

   権限を保持するサービス アカウントには、API メソッドの呼び出しに必要な権限が付与されている必要があります。

gcloud

1. --impersonate-service-account フラグを指定して gcloud auth print-access-token コマンドを使用し、権限を保持するサービス アカウントのアクセス トークンを REST リクエストに挿入します。

次の例では、指定したプロジェクトの詳細を取得します。どの REST リクエストに対しても、同じパターンを使用できます。

この例を実行するには、権限の借用元であるサービス アカウントに resourcemanager.projects.get 権限が必要です。resourcemanager.projects.get 権限は、閲覧者のロール（roles/browser）など、さまざまなロールに含まれています。

次の項目を置き換えます。

• PRIV_SA: 権限を保持するサービス アカウントのメールアドレス。例: [e-mail]

• PROJECT_ID: Google Cloud プロジェクト ID または名前。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

有効期間の短いトークン

サービス アカウントの権限を借用して有効期間の短いトークンを生成するには、有効期間の短いアクセス トークンを作成するの手順に沿って操作します。

メタデータ サーバー

メタデータ サーバーからアクセス トークンを取得するには、メタデータ サーバーにアクセスできるサービスのいずれかを使用して REST 呼び出しを行う必要があります。

• Compute Engine
• App Engine スタンダード環境
• App Engine フレキシブル環境
• Cloud Run functions
• Cloud Run
• Google Kubernetes Engine
• Cloud Build

curl などのコマンドライン ツールを使用してアクセス トークンを取得し、REST リクエストに挿入します。

1. メタデータ サーバーに対してクエリを行い、アクセス トークンを取得します。

   curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
       -H "Metadata-Flavor: Google"
   

   このリクエストにより、次の例に似たレスポンスが返されます。

   {
         "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
         "expires_in":3599,
         "token_type":"Bearer"
    }
   

2. アクセス トークンを REST リクエストに挿入して、次の項目を置き換えます。

   • ACCESS_TOKEN: 前の手順で返されたアクセス トークン。
   • PROJECT_ID: Google Cloud プロジェクト ID または名前。

   curl -X GET \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

API キー

REST API 呼び出しに API キーを含めるには、次の例に示すように x-goog-api-key HTTP ヘッダーを使用します。

curl -X POST \
    -H "X-goog-api-key: API_KEY" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://translation.googleapis.com/language/translate/v2"

HTTP ヘッダーを使用できない場合は、key クエリ パラメータを使用できます。ただし、この方法では API キーが URL に含まれるため、URL スキャンによってキーが盗難に遭う可能性があります。

次の例は、documents.analyzeEntities の Cloud Natural Language API リクエストで key クエリ パラメータを使用する方法を示しています。API_KEY は、API キーのキー文字列に置き換えます。

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

REST リクエストで割り当てプロジェクトを設定する

ユーザー認証情報を使用して API を呼び出す場合、使用量に応じて課金され、割り当ての追跡に使用されるプロジェクを設定する必要があります。API 呼び出しでユーザー認証情報に対応していないことや、割り当てプロジェクトが設定されていないことを通知するエラー メッセージが返された場合は、リクエストのために割り当てプロジェクトを明示的に設定する必要があります。割り当てプロジェクトを設定するには、リクエストに x-goog-user-project ヘッダーを含めます。

この問題が発生した場合は、ユーザー認証情報が機能しないをご覧ください。

プロジェクトを請求先プロジェクトとして指定するには、serviceusage.services.use IAM 権限が必要です。serviceusage.services.use 権限は、Service Usage ユーザーの IAM ロールに含まれています。プロジェクトに対する serviceusage.services.use 権限がない場合は、セキュリティ管理者か、プロジェクトの Service Usage ユーザーのロールを付与できるプロジェクト オーナーに連絡します。

次の例では、Cloud Translation API を使用して「hello」という単語をスペイン語に翻訳します。Cloud Translation API は、割り当てプロジェクトの指定が必要な API です。サンプルを実行するには、リクエスト本文を含む request.json という名前のファイルを作成します。

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

• PROJECT_ID: 課金プロジェクトとして使用する Google Cloud プロジェクトの ID または名前。

リクエストの本文（JSON）:

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

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

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/language/translate/v2"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

翻訳リクエストは成功します。x-goog-user-project HTTP ヘッダーのないコマンドを使用してみると、課金プロジェクトを指定しないとどうなるか確認できます。

次のステップ

• 認証の概要を確認する。
• クライアント ライブラリで認証する方法を学習する。
• gcloud CLI 認証構成と ADC 構成について理解する。