セキュリティアセスメントのためにエンドポイントを準備する

Last updated on September 18, 2026

注釈：本資料はAI技術を用いて翻訳されています。

Overview

テストしたい各エンドポイントについて、Extend セキュリティアセスメントはそのエンドポイントが認証を必要とするかどうか、およびどのIAM権限を適用するかを知る必要があります。実行中のExtendアプリを呼び出すことでこれを自動的に検出するため、エンドポイントごとに手動で入力する必要はありません。ただし、これはアプリが権限を読み取れる形式で宣言している場合にのみ機能します。

要件：到達可能なOpenAPI仕様

Extend Service Extension アプリは、到達可能なSwagger v2（OpenAPI 2.0）仕様を公開している必要があります。これは通常、<YourServiceURL>/apidocs/api.jsonで提供されます。これは、AccelByteのservice extensionテンプレートから構築されたアプリのデフォルトです。これは必須要件です。Extend セキュリティアセスメントが仕様を取得できない場合、エンドポイントを一覧表示することも、リクエストを受け付けることも一切できません。

この仕様の詳細については、Extend App UI: Codegenの仕様を参照してください。

権限が検出される順序

OpenAPIのx-required-permission拡張。 保護された各オペレーションについて、Extend セキュリティアセスメントはそのオペレーションのカスタムOpenAPI拡張フィールドを探します。
```
"x-required-permission": "ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE]"
```
サービスがAccelByteのService Extensionテンプレート（Go、C#、Java、Pythonに対応）のいずれかから構築されている場合、.protoファイル内のRPCで権限を宣言するだけで、この設定を自動的に得られます。どのテンプレートも同じgRPC protoの定義を共有しているため、使用した言語のテンプレートに関わらず、protoc-gen-openapiv2が権限を生成されたSwagger仕様に自動的に組み込みます。
```
rpc CreateOrUpdateGuildProgress (CreateOrUpdateGuildProgressRequest) returns (CreateOrUpdateGuildProgressResponse) {
  option (permission.action)   = CREATE;
  option (permission.resource) = "ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD";
  option (google.api.http) = {
    post: "/v1/admin/namespace/{namespace}/progress"
    body: "*"
  };
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
    security: { security_requirement: { key: "Bearer" value: {} } }
    extensions: {
      key: "x-required-permission"
      value { string_value: "ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE]" }
    }
  };
}
```
これらのテンプレートを使用していない場合は、OpenAPI仕様を生成するツールの該当するオペレーションにx-required-permission拡張を追加してください。形式はRESOURCE [ACTION]です（例：ADMIN:NAMESPACE:{namespace}:SEASON [UPDATE]）。
gRPCサーバーリフレクション。 Extend セキュリティアセスメントは、アプリのgRPCサーバーリフレクションサービスにも独立してクエリを実行し、protoメソッドから直接permission.resource・permission.actionメソッドオプション（上記のスニペットに示されているのと同じオプション）を読み取ります。これは、サービスでリフレクションが登録されている場合にのみ機能します（AccelByteのService Extensionテンプレートはデフォルトでこれを登録します）。登録されていない場合、このソースなしで単純に処理を続行します。
優先順位。 Extend セキュリティアセスメントは各エンドポイントについて両方のソースを読み取ります。エンドポイントの権限が両方の場所で宣言されている場合、OpenAPIのx-required-permissionの値が優先されます。gRPCリフレクションの値は、OpenAPI仕様がそのオペレーションの権限を宣言していない場合にのみ有効になります。どちらのソースもエンドポイントの権限を宣言しておらず、かつ仕様とgRPCリフレクションの両方に正常に到達できた場合、そのエンドポイントを意図的に未認証であるものとして扱います。プロンプトや警告は表示されません。
手動での上書き。 権限が本当に検出できない場合（gRPCリフレクションがなく、仕様にもx-required-permissionがない場合）、リクエストのエンドポイントを選択する際に権限文字列を自分で入力できます。Extend セキュリティアセスメントは形式を検証します（namespaceスコープである必要があり、ワイルドカードは使用できません）が、その値がアプリが実行時に実際に適用している内容と一致するかどうかは検証できません。値が誤っていると、テストケースがチェックする範囲が狭すぎたり広すぎたりする可能性があるため、慎重に入力してください。

ヒント

手動での上書きに頼るのではなく、権限はコード側で修正してください。x-required-permission（または同等のprotoオプション）を保護されたエンドポイントに宣言するのは一度きりの変更です。一度コードに反映すれば、そのエンドポイントの権限は今後のすべてのセキュリティアセスメントで自動的かつ正しく検出されます。

Overview​

要件：到達可能なOpenAPI仕様​

権限が検出される順序​

Overview

要件：到達可能なOpenAPI仕様

権限が検出される順序