アドミッションコントロール

はじめに

このページでは、Service Control API v2 を使用して、Service Infrastructure と統合されているマネージドサービスのアドミッションコントロールを行う方法について説明します。このチュートリアルは、サービスを Google Cloud に深く統合したいと考えているサービスプロデューサーを対象としています。

Service Infrastructure は、デベロッパーが API とサービスを作成、管理、保護、使用するための基盤となるプラットフォームです。シンプルで一般的なサービス使用モデルを使用し、ユーザーはプロデューサーが管理するサービスを消費します。すべての Google API とGoogle Cloud APIは Service Infrastructure の上に構築されているため、このモデルを使用します。

クライアントがサービスにアクセスすると、一般に、コンシューマー、サービス、プロデューサー、ユーザー、アプリケーション、ネットワーク、リソースなど、アクセスに関与するすべてのエンティティがステータスとポリシーのチェックを必要とします。Service Infrastructure では、このプロセスはアドミッションコントロールと呼ばれ、認証、承認、監査、レート制限などが含まれます。

Service Control API v2

Service Control API v2 は、Service Infrastructure と統合されたすべてのサービスにアドミッションコントロールを提供するシンプルな services.check メソッドを提供します。このメソッドを使用すると、1 回のメソッド呼び出しで次のことを行うことができます。

ステータスチェック
- 不正使用ステータス
- 課金ステータス
- コンシューマーのステータス
- サービスのステータス
- サービスの使用開始
認証
- GoogleOAuth アクセストークン
- Google サービスアカウントの署名された JWT
承認
- Identity and Access Management（IAM）
監査
- Cloud Audit Logging監査ログは、サービス「externalaudit.googleapis.com」に関連付けられます。

サービスが Service Control API を呼び出すとき、プロデューサーは Service Control API のコンシューマーでもあります。したがって、services.check メソッドは、Service Control API の呼び出しでアドミッションコントロールも実行します。

サービスが Service Control API を呼び出すには、プロデューサープロジェクトで Service Control API を有効にし、サービスに対する適切な権限を持っている必要があります。詳細については、Cloud API のスタートガイドと Service Control の Access Control をご覧ください。

リクエストの属性

クライアントがサービスにアクセスするとき、サービスはアドミッションコントロールでチェックできる 1 つ以上の API リクエストへのアクセスを抽象化する必要があります。ほとんどの場合、そのようなアクセスは実際に本物の API リクエストです。それ以外の場合には、アクセスは複雑なデータインポートジョブまたは SQL クエリであり、サービスは一連の仮想 API リクエストの観点からアクセスをモデル化し、各リクエストでアドミッションコントロールを実行する必要があります。

Service Control API を使用してアドミッションコントロールを実行するには、サービスが必要なリクエストの属性を指定して services.check メソッドを呼び出す必要があります。次の表に、アドミッションコントロールに必要な属性を示します。詳細な仕様については、AttributeContextをご覧ください。

属性	説明	例
`origin.ip`	発信者の IP アドレス。	"1.2.3.4"
`api.service`	API サービスの名前	"endpointsapis.appspot.com"
`api.operation`	API メソッドの名前	"google.example.hello.v1.HelloService.GetHello"
`api.version`	API バージョンの文字列	"v1"
`api.protocol`	API プロトコルの名前	"https"
`request.id`	一意のリクエスト ID	"123e4567-e89b-12d3-a456-426655440000"
`request.time`	リクエストの時刻	"2019-07-31T05:20:00Z"
`request.method`	HTTP メソッドの名前	"POST"
`request.scheme`	URL スキーム	"https"
`request.host`	HTTP ホストヘッダー	"endpointsapis.appspot.com"
`request.path`	URL パス	"/v1/hello"
`request.headers`	HTTP リクエストヘッダー必要なヘッダーは、"authorization"、"user-agent", "origin"、"referer"です。
`resource.name`	ターゲットリソース名。	"projects/123/topics/news-feed"

リソースの属性

クライアントがサービスにアクセスするとき、アクセスには、サービス内の 1 つ以上のリソース（オブジェクトの読み取りや VM インスタンスの作成など）が含まれる場合があります。サービスは、Service Infrastructure アドミッション制御を使用して、IAMとCloud 監査ログでサポートされるリソースのアクセス制御を行うことができます。サービスがアクセスコントロールを必要としない場合は、このセクションをスキップできます。

アクセスコントロールでは、サービスはリクエストの属性とともにリソースの属性を services.check メソッドに渡す必要があります。次の表は、アクセス制御に必要なリソースの属性を示しています。

属性	説明	例
`name`	リソース名。	"projects/123/locations/global/instances/instance-1"
`type`	リソースの型。形式は ”{service}/{Kind}” です。	"endpointsapis.appspot.com/Instance"
`permission`	リソースのアクセス許可。形式は ”{service}/{kinds}.{verb}” です。	"endpointsapis.appspot.com/instances.get"

パフォーマンスと効率性に関して、services.check メソッドを使用すると、1 回の呼び出しで 1 つのリソースに対する複数の権限を確認できます。

アドミッションコントロールの実行

サービス構成を Service Management API にデプロイし、サービスがクライアントからのリクエストを処理する準備ができたら、デプロイされたサービスの services.check の呼び出しを開始できます。サービスがリクエストを受信するたびに、services.check を呼び出してアドミッションコントロールを実行する必要があります。

gcurl コマンドを使用して services.check メソッドを呼び出すと、アドミッションコントロールをすばやく試せます。初期設定手順については、Service Control API スタートガイドをご覧ください。

次の例は、gcurl コマンドを使用して HTTP 経由で services.check を呼び出す方法を示しています。

gcurl -d '{
  "service_config_id": "latest",
  "attributes": {
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation", "google.example.hello.v1.HelloService.GetHello",
      "version": "v1",
      "protocol": "https"
    }
  },
  "request": {
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "time": "2019-07-31T05:20:00Z",
    "scheme": "https",
    "host": "endpointsapis.appspot.com"
    "headers": {
      "authorization": "Bearer xxx",
      "user-agent": "curl/1.0"
    }
  },
  "resources": [
  ]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check
{
}

services.check メソッドからのレスポンスは、アドミッションコントロールが成功したかどうかを示します。成功した場合、応答は空になります。失敗した場合、レスポンスの status には、サービスがクライアントに返す必要があるエラー情報が含まれます。多くの場合、サービスはエラー情報を独自の形式に変換する必要があります。このサービスでは、ロギングやモニタリングの目的でこの情報を使用することもできます。

本番環境サービスの場合、Google が提供するクライアントライブラリのいずれかを使用して Service Control API を呼び出す必要があります。このようなライブラリは、優れたユーザビリティを提供し、認証などの一般的な機能を自動的に処理します。詳しくはクライアントライブラリの説明をご覧ください。