Extend App UI のトラブルシューティング

Last updated on July 14, 2026

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

Overview​

このページでは、Extend App UI が AccelByte Gaming Services (AGS) Admin Portal から Extend Service Extension または Event Handler を呼び出す際に発生しやすい問題について説明します。最も多く発生するのは認証に関する問題です。サービスが Authorization ヘッダーのみを読み取る場合、Admin Portal からのリクエストは access_token クッキーで認証されるため、401 エラーで失敗します。

Admin Portal から Extend サービスを呼び出す際の権限エラー​

症状​

App UI から Extend サービスへの呼び出しが HTTP 401 と authorization header is missing のようなメッセージで失敗します。同じエンドポイントを Swagger、Postman、または Bearer トークンを使ったローカルテストから直接呼び出すと正常に動作します。

原因​

Admin Portal が App UI を埋め込む際、ブラウザは Authorization ヘッダーではなく access_token という名前のクッキーを使って認証します。これは、gRPC の上に REST エンドポイントを公開するサービスに対して gRPC-Gateway がブラウザベースの認証を処理する方法です。サービスの gRPC 認証インターセプターが Authorization ヘッダーのみを検査する場合、Admin Portal からのクッキー認証済みリクエストはすべて拒否されます。

ローカル開発でもこの問題が発生します。devProxyPlugin はクッキーを Authorization ヘッダーに変換しません。想定されるネームスペースのサブドメインからリクエストが来たように見せるため、Referer を書き換えるだけです。クッキーはそのままサービスに転送されます。プラグインが処理する内容と処理しない内容については、devProxyPlugin を参照してください。この修正はサービス側で行う必要があります。インターセプターがクッキーを直接受け入れるようにする必要があります。

修正方法​

この修正を適用する前に、Extend SDK を最新バージョンに更新してください。必要なクッキー処理 API が古いリリースには含まれていない場合があります。

Authorization ヘッダーが存在しない場合に cookie メタデータにフォールバックするように、gRPC 認証インターセプターを更新します。クッキー文字列から access_token=... の値を取り出し、Bearer トークンを検証する場合と同じ方法で検証します。トークンからネームスペース、ユーザー ID、またはユーザー名を読み取るヘルパーにも同じフォールバックを適用します。

以下の Go の例は、Extend Tournament System テンプレートからスキャフォールドされたサービスに適用されたパターンを示しています。同じロジックは、言語を問わず任意の Extend サービスに適用できます。Authorization が存在しない場合、cookie メタデータから access_token を取り出します。このスニペットの正確なファイルパス、構造体名、ヘルパー関数は Extend の実装によって異なります。プロジェクトの構造に合わせて調整してください。

ヘッダーを手動で分割する代わりに、net/http を使ってクッキーを解析します。各 cookie メタデータエントリを最小限の http.Request でラップすることで、標準ライブラリのクッキー解析を再利用でき、引用符、スペース、複数のクッキーヘッダーに関するエッジケースを回避できます。

// pkg/common/auth_interceptors.go

// extractTokenFromCookieMetadata parses the "cookie" metadata key and
// returns the access_token value if present.
func extractTokenFromCookieMetadata(meta metadata.MD) string {
	for _, cookieHeader := range meta.Get("cookie") {
		req := &http.Request{Header: http.Header{"Cookie": {cookieHeader}}}
		if cookie, err := req.Cookie("access_token"); err == nil {
			return cookie.Value
		}
	}
	return ""
}

func (t *TournamentAuthInterceptor) CheckTournamentPermission(
	ctx context.Context,
	requiredPermission string,
	namespace string,
) error {
	meta, ok := metadata.FromIncomingContext(ctx)
	if !ok {
		return status.Error(codes.Unauthenticated, "missing metadata")
	}

	// Existing checks for Authorization header and service tokens go here.
	// ...

	// Check for token in cookies (browser-based authentication via gRPC-Gateway).
	if token := extractTokenFromCookieMetadata(meta); token != "" {
		return t.validateToken(ctx, token, requiredPermission, namespace)
	}

	return status.Error(codes.Unauthenticated, "authorization header or cookie is missing")
}

トークンからクレームを抽出するすべてのコンテキストヘルパーに、同じフォールバックを適用します。パターンは常に、まず Authorization を試し、次に extractTokenFromCookieMetadata(meta) にフォールバックするというものです。たとえば、GetContextUserID、GetContextUsername、GetContextNamespace はいずれも、JWT をデコードして関連するクレームを返す前に同じルックアップを再利用します。

修正の確認​

  1. Extend サービスを再デプロイします。
  2. App UI を開きます。Admin Portal から行う場合は、Extend > My Extend Apps > App UI に移動し、対象アプリの行で Open UI をクリックします。または、npm run dev を実行した後に http://localhost:5173 のローカル開発サーバーから開くこともできます。
  3. 以前に 401 を返していたリクエストを実行します。今回は成功するはずです。
  4. サービスのログを確認し、リクエストがクッキー経由で認証され、インターセプターで拒否されていないことを確認します。

ネームスペースコンテキストの取得時に発生する 403 insufficient-permission エラー​

注記

この問題は AGS Private Cloud デプロイメントにのみ適用されます。AGS Public Cloud では、スタジオ管理者およびゲーム管理者は Publisher ネームスペースにアクセスできないため、この競合は発生しません。

症状​

ローカル検証中に、Extend サービスが次のようなエラーをログに記録します。

failed to fetch namespace context. [GET /basic/v1/admin/namespaces/{namespace}/context][403] getNamespaceContextForbidden {"devStackTrace":"require permission: Permission(resource=ADMIN:NAMESPACE:{namespace}:NAMESPACE, action=2)","errorCode":20013,"errorMessage":"insufficient permission","requiredPermission":{"action":2,"resource":"ADMIN:NAMESPACE:{namespace}:NAMESPACE"}}

原因​

Extend サービスが、デプロイされているゲームネームスペースではなく Publisher ネームスペースを呼び出しています。通常、Extend サービスはデプロイ先のゲームネームスペースのみを呼び出す必要があります。Publisher ネームスペースの呼び出しが適切なのは、サービスの設計上明示的に必要な場合に限られます。

Public Cloud では、スタジオ管理者およびゲーム管理者は Publisher ネームスペースにアクセスできないため、このエラーは発生しません。

修正方法​

Extend サービスのネームスペースロジックを確認し、それが属するゲームネームスペースのみを対象にしていることを確認します。サービスの設計上 Publisher ネームスペースへのアクセスが明示的に必要でない限り、ネームスペースを対象とするすべての API 呼び出しは、Publisher ネームスペースではなくゲームネームスペースを使用する必要があります。

に最終更新
On this page