Entra ID 認証は、Admin、Server、および一部の entity API 呼び出しのための開発者シークレット キーの代替手段です。プレイヤー向けの Client と entity API では、引き続きプレイヤー サインインで取得したセッション チケットと entity トークンを使用します。Entra ID で利用できるのは、title entity トークンで呼び出し可能な entity API のみです。シークレット キーの詳細については、Secret key management を参照してください。
Entra ID 認証を使用する理由
開発者シークレット キーはシンプルで使いやすいですが、Entra ID 認証にはいくつかの利点があります。- 共有シークレットなし — パブリック クライアント フローではクライアント シークレットは不要です。トークンは短命で、サインインしたユーザーに限定されます。
- 個別の説明責任 — 各 API 呼び出しが特定のユーザー ID に紐付けられ、誰が何をしたかを容易に監査できます。
- 条件付きアクセス — 組織は IP 制限、多要素認証 (MFA)、デバイス コンプライアンス チェックなどの Entra ID ポリシーを適用できます。
Entra ID 認証の仕組み
Microsoft Entra ID を扱ったことがない方のために説明すると、これは Microsoft のクラウド ID サービスであり、Microsoft 365、XBOX 開発者アカウント、Azure を支えている ID システムと同じものです。PlayFab がスタジオに長期間有効なシークレット キーを発行する代わりに、ツールが Entra ID に開発者のサインインを依頼し、短命の アクセス トークン を返してもらいます。PlayFab は、スタジオのメンバーであるユーザー向けに Entra ID が発行するトークンを信頼します。 3 つの当事者が関わります。- 開発者。 Microsoft アカウント (個人) または職場/学校アカウント (Entra ID) でサインインしているあなたです。
- Entra ID のアプリ登録。 PlayFab を呼び出すツール - CLI、ビルド スクリプト、社内ダッシュボードなど - を表します。「このアプリはサインイン ユーザーに代わって PlayFab のアクセス トークンを要求できます」と Entra ID に伝えます。
- PlayFab サービス。 PlayFab はアプリケーション ID
448adbda-b8d8-4f33-a1b0-ac58cf44d4c1の下で Entra ID に登録されており、pluginという委任アクセス許可を公開します。コードがスコープ448adbda-b8d8-4f33-a1b0-ac58cf44d4c1/pluginを要求すると、Entra ID は PlayFab が受け入れるトークンを発行します。
- コードは Microsoft Authentication Library (MSAL) を使用してサインインを開始します。通常はブラウザーのポップアップまたはデバイス コード プロンプトです。
- ユーザーは Microsoft ID でサインインし、アプリが自分の代わりに PlayFab を呼び出すことに同意します。
- MSAL はアクセス トークン (JWT) を返し、リフレッシュ トークンをキャッシュするため、以後の呼び出しではプロンプトをスキップできます。
- コードは各 PlayFab リクエストに
Authorization: Bearer <token>ヘッダーとしてトークンを送信します。 - PlayFab はトークンを検証し、一致するスタジオ ユーザーにマッピングし、そのユーザーのロールに基づいて呼び出しを認可します。
前提条件
- Entra ID がバックエンドの Microsoft アカウント (職場または学校アカウント) または個人の Microsoft アカウント (MSA)。
- PlayFab タイトル。詳細については、PlayFab アカウントを作成する を参照してください。
- Microsoft Entra ID テナントでアプリケーションを登録する権限。
- 呼び出し側のユーザーは PlayFab スタジオに追加され、タイトル管理者として割り当てられている必要があります。ロールの詳細については、PlayFab ユーザー ロール を参照してください。
Entra ID にパブリック クライアント アプリケーションを登録する
サインインしたユーザーに代わってコードが委任トークンを要求できるように、Entra ID テナントにアプリケーションを登録する必要があります。パブリック クライアント フロー (SPA、デバイス コード、暗黙的) では、クライアント シークレットは必要ありません。- Azure Portal にサインインします。
- App registrations を検索して選択し、New registration を選択します。
-
アプリケーションの名前を入力します (例:
PlayFab API Client)。 - Supported account types で、組織の要件に一致するオプションを選択します。最大の柔軟性を得るには、Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts を選択します。このオプションは、任意の Microsoft アカウントによる認証を許可します。
-
アプリケーションのタイプに基づいて Redirect URI を構成します。
- シングル ページ アプリケーション (SPA) の場合、Single-page application (SPA) を選択し、リダイレクト URI を入力します (たとえば、
http://localhost:3000)。 - デバイス コード フローを使用するネイティブまたはコンソール アプリケーションの場合、Public client/native (mobile & desktop) を選択し、
http://localhostを入力します。
- シングル ページ アプリケーション (SPA) の場合、Single-page application (SPA) を選択し、リダイレクト URI を入力します (たとえば、
- Register を選択します。概要ページで、Application (client) ID をメモします。この値はトークンを要求する際に必要になります。
-
アプリ登録に PlayFab API アクセス許可を追加します。
- Azure Portal でアプリ登録に移動し、API permissions を選択します。
- Add a permission > APIs my organization uses を選択します。
- PlayFab アプリケーション ID
448adbda-b8d8-4f33-a1b0-ac58cf44d4c1を検索して選択します。 - Delegated permissions を選択し、plugin アクセス許可をオンにして、Add permissions を選択します。
シナリオで機密 (Web アプリ) クライアントが必要な場合は、Certificates & secrets の下でクライアント シークレットも作成する必要があります。この記事はシークレットを必要としないパブリック クライアント フローに焦点を当てています。機密クライアント フローの詳細については、Microsoft ID プラットフォームと OAuth 2.0 認可コード フロー を参照してください。
PlayFab スタジオ アクセスをセットアップする
PlayFab は、スタジオ メンバーシップに対して Entra ID トークンを検証します。呼び出し元のユーザーは PlayFab スタジオに追加され、適切なロールを付与されている必要があります。- スタジオ管理者に Game Manager にサインインしてもらいます。
- スタジオの Users セクションに移動します。
- Add User を選択し、API アクセスが必要な開発者の Microsoft アカウントのメール アドレスを入力します。
- 認証プロバイダーとして Microsoft を選択します。
- Admin または Server API アクセスを含むロールをユーザーに割り当てます。少なくとも、API を呼び出す必要があるタイトルの title admin である必要があります。
- Add user を選択して招待を送信します。
アクセス トークンを取得する
アプリケーションは、ユーザーをサインインし、Entra ID から委任アクセス トークンを取得する責任を負います。以下の例は、一般的なパブリック クライアント フローを示しています。対話型ブラウザー フロー (デスクトップおよびコンソール アプリに推奨)
対話型ブラウザー フローは、サインインのためにシステム ブラウザー ウィンドウを開きます。デスクトップ アプリケーションとローカル開発ツールに推奨されるオプションです。PKCE を伴う認可コード (SPA に推奨)
Proof Key for Code Exchange (PKCE) を伴う認可コード フローは、シングル ページ アプリケーションに推奨されるアプローチです。次の JavaScript の例では、Microsoft Authentication Library (MSAL) を使用します。アクセス トークンで PlayFab API を呼び出す
X-SecretKey ヘッダーを使用する代わりに、PlayFab API リクエストの Authorization ヘッダーに Bearer トークンとして Entra ID アクセス トークンを含めます。
リクエスト例
同じリクエストで
X-SecretKey と Authorization: Bearer の両方を使用することはできません。呼び出しごとに 1 つの認証方法を使用してください。C# の例
以下の例では、Microsoft Authentication Library (MSAL) を使用してトークンを取得し、Server/GetTime API を呼び出します。your-client-id をアプリ登録の Application (client) ID に置き換えてください。
Node.js の例
以下の例では、@azure/msal-node ライブラリを使用してトークンを取得し、Server/GetTime API を呼び出します。your-client-id をアプリ登録の Application (client) ID に置き換えてください。
トークンのリフレッシュ
Entra ID アクセス トークンは短命 (通常 60〜90 分) です。MSAL を使用している場合、各リクエストの前にAcquireTokenSilent (C#) を呼び出すか、トークン キャッシュを確認してください。キャッシュされたリフレッシュ トークンが利用可能な場合、MSAL は自動的にリフレッシュを処理します。
手動でトークンを管理している場合は、現在のトークンが期限切れになる前に同じサインイン フローを使用して新しいトークンを要求してください。
使用中にトークンが期限切れになった場合、PlayFab は
401 Unauthorized の応答を返します。アプリケーションは、このエラーを処理して新しいトークンを要求し、呼び出しを再試行する必要があります。トラブルシューティング
エラー応答の例
Bearer トークンが不足、不正、または期限切れの場合の PlayFab からの401 Unauthorized は次のようになります。
403 Forbidden は次のようになります。
制限事項
現在、PlayFab SDK は Entra ID 認証をサポートしていません。現時点で Entra ID トークンで PlayFab API を呼び出すには、C# および Node.js の例に示すように、直接 HTTP 呼び出しを使用し、自分でAuthorization: Bearer <token> ヘッダーを設定してください。SDK のサポートは今後のリリースで予定されています。
