アクセス制御

Implement authorization to protect player data and game resources.

読み終わるまでの所要時間 7 分

最終更新 1日前

Unity Gaming Services (UGS) のアクセス制御を使用すると、UGS 内のゲームの状態とロジックをチーターやエクスプロイターから保護できます。アクセス制御 (API 承認とも呼ばれます) ではゲームのデータとリソースにアクセス、変更、または削除可能なユーザーを制御し、ゲームへの不正アクセスを防止できるため、重要な機能です。 UGS の API 承認は、認証されたユーザーに実行を許可するアクションを決定するプロセスです。認証では、ユーザーが本当にそのユーザーであるかどうかを検証します。認証と承認を併せて使用することで、API へのアクセスとリソースへのアクセスを確実に制御することができます。UGS は、このドキュメントで説明する API 承認と連携する認証ソリューションを提供しています。認証がなければ、誰でも API にアクセスでき、不正なアクションを実行してしまう可能性があります。例えば、ある API を使用すればユーザーが機密情報の参照やデータの変更を行える場合、認証がなければ、誰でも機密情報にアクセスしたり、許可なく変更したりできます。認証でユーザーの身元を確認し、承認でユーザーに実行を許可するアクションを制御します。認証は、承認が機能するために必要な基盤です。認証は API の扉を開ける鍵のようなものですが、承認はユーザーに立ち入りを許可するかどうか、および入ってからできることを決定します。

アクセス制御のしくみ

UGS のアクセス制御は、リソースポリシーを使用して設定します。UGS サービスでは、これらのサービスにアクセスできるユーザーと、これらのユーザーに実行を許可するアクションを定めたルールを適用します。 UGS サービスにユーザーがアクセスしようとすると、サービスは設定済みのポリシーに照らし合わせてユーザーの身元を確認し、API リクエストを拒否または許可します。リソースポリシーはステートメントのコレクションです。ステートメントでは、ユーザーの身元 (Principal 属性)、対象のアクション (Action 属性)、アクションの制限または許可 (Effect 属性)、およびポリシーを適用するリソース (Resource 属性) について定義します。また、ポリシーでは “Sid” 属性 (ステートメント識別子) も記載します。これは、該当のポリシーに対してユーザーが定義するわかりやすい名前で、英数字とハイフンのみ使用することができます。ポリシーにおいて、リソースは Uniform Resource Name (URN) として定義します。通常は、URN のコンポーネント要素を構成する API パスを指定します。リソースポリシーは、プロジェクトごとまたはプレイヤーごとに設定します。プロジェクトポリシーは、そのプロジェクトで UGS サービスを呼び出すすべてのプリンシパルに対して評価されます。プレイヤーポリシーは、プロジェクトおよび環境のスコープ内の個々のプレイヤーに対してのみ評価されます。以下は、Economy サービスの有効な URN の例です。


urn:ugs:economy:/v2/project/*/player/*/currencies/gold

ここでは、glob パターンを使用して、共通のパターンを持つリソースのセットを検出しています。以下に、この URN の各コンポーネントを示します。

URN コンポーネント	説明
urn:	この文字列が URN であることを示すプレフィックス。
ugs:	URN の名前空間識別子 (NID)。この名前空間の URN の保守を担当する組織またはグループを指定します。この例の “ugs” は、この URN を作成したグループである Unity Gaming Services を表しています。
economy:	名前空間内の特定の命名機関。UGS の特定の領域を指定します。
/v2/project/	URN 固有のセグメント。API のバージョンと URN が適用されるプロジェクトを指定します。
*	すべての文字に一致する最初の glob パターン。この文字は、取り得るすべての値を表すワイルドカードです。この例では、“urn:ugs:economy:/v2/project/” で始まり、その後に任意の文字が続くすべての URN に一致します。
/player/	URN 固有のセグメント。URN が適用されるプレイヤーを指定します。
*	すべての文字に一致する 2 番目の glob パターン。この例では、“urn:ugs:economy:/v2/project/*/player/” で始まり、その後に任意の文字が続くすべての URN に一致します。
/currencies/gold	URN 固有のセグメント。URN が適用される通貨の種類を指定します。

URN の検出に glob パターンを使用しているため、上の URN は以下のように定義することもできます。

urn:ugs:economy:/**/currencies/gold

アクセス制御ポリシーが作成されていない場合、アクセス制御はデフォルトで、認証済みプレイヤーからのすべての認証済み API 呼び出しを許可します。これは、以下のリソースポリシーで記述することもできます。


{	"Sid": "allow-all-ugs",	"Effect": "Allow",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:*"},

以下の例に、認証済みのプレイヤーに対して API 呼び出しを通じた Economy の gold 通貨の読み取りは許可するが、変更 (書き込み) は禁止する有効なポリシーの作成方法を示します。


{	"Sid": "deny-economy-write-access",	"Effect": "Deny",	"Action": ["Write"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/v2/project/*/player/*/currency/gold"},

また、認証済みのプレイヤーに対し、Economy 内のすべての API へのアクセスを完全に拒否する場合に次のように記述します。


{	"Sid": "deny-all-economy-access",	"Effect": "Deny",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:economy:*"},

アクセス制御の使用方法

UGS のリソースポリシーを作成するには、REST API または UGS CLI を使用します。これらのポリシーを作成する必要があるのは一度だけです。作成したポリシーは、認証済み呼び出し元のコンテキスト内で UGS への各 API 呼び出しに対して評価および適用されます。

ポリシーの例

プレイヤーによる Cloud Code スクリプトの実行を禁止する場合、次のように記述します。


{	"Sid": "deny-cloud-code-access",	"Effect": "Deny",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:cloud-code:/v1/projects/*/scripts/*"},

このリソースポリシーは、プレイヤーが認証されるプロジェクトの Cloud Code スクリプトに対するすべてのアクションへのアクセスを拒否します。Cloud Code は “execute” API のみを、この API に対する POST リクエストとして提供します。これは、上のポリシーステートメントの “Write” アクションに分類されます。以下に、Cloud Save のリソースポリシーの例も示します。


{	"Sid": "deny-cloud-save-data-write-access",	"Effect": "Deny",	"Action": ["Write"],	"Principal": "Player",	"Resource": "urn:ugs:cloud-save:/v1/data/projects/*/players/*/items**"},

このリソースポリシーは、プロジェクトのすべての認証済みプレイヤーに対して、すべての Cloud Save データへの書き込みアクセスを拒否します。

Player

識別子を持つユーザーまたはグループの項目下にネストされたすべてのパスおよびサブフォルダーが対象となります。これにより、実質的にはプレイヤーが Cloud Save に直接データを書き込めなくなります。このポリシーと前の Cloud Code 用ポリシーを組み合わせることで、開発者は Cloud Code を通じて Cloud Save にデータを書き込み、Cloud Code 内に追加のゲームロジックを実装することができます。以下に、ポリシーを構成する各コンポーネントとその役割を示します。

ステートメント属性	使用可能な値	説明
Sid	英数字の文字列。例: `^[A-Za-z0-9][A-Za-z0-9_-]{5,59}$`	ステートメント識別子。各ポリシーの環境ごとに一意の値を指定します。人間が判読可能なポリシー名を提供します。値は 5 文字以上 59 文字以下にする必要があります。例えば `deny-cloud-save-data-write-access` などです。
Effect	Allow、Deny	このポリシーで、指定のリソースに対するアクセスを許可または拒否するかを指定します。
アクション	Write、Read、*	許可または拒否するアクセスの種類を指定します。これらのアクションは、UGS の各製品に固有のものです。 Write 値は、通常、UGS サービスに状態の変化を生じさせる操作を指します。このカテゴリには、UGS API の HTTP 動詞である POST、PUT、PATCH、DELETE が含まれます。 Read 値は、通常、UGS サービスから状態をフェッチする操作を指します。このカテゴリには、UGS API の HTTP 動詞である GET が含まれます。 * 値は、許容されるすべてのアクションを指定する省略表現です。
Principal	プレイヤー /Player	ポリシーの適用対象となるユーザーの識別子を指定します。現在、使用可能な値は Player のみです。
Resource	有効な UGS URN	ポリシーを適用するリソースを 1 つまたは複数指定します。例えば、 `urn:ugs:cloud-save:/v1/data/projects//players//items**` のように設定します。この URN では、プロジェクトで認証されたプレイヤーの全 Cloud Save データと一致する glob パターンを使用しており、その対象には項目下にネストされたすべてのパスおよびサプバスが含まれます。

エラー応答

プレイヤーが、適切な権限を持っていないリソースにアクセスしようとすると、403 Forbidden のステータスコードともにエラー応答が返されます。エラー応答の正確な形式は、適用されるアクセス制御の種類によって異なります。プレイヤーがプロジェクトベースのポリシーに基づいてリソースへのアクセスを制限された場合、エラー応答には以下のフィールドが含まれます。


{  "title": "Forbidden",  "detail": "Access has been restricted",  "code": 56,  "status": 403,  "type": "https://services.docs.unity.com/docs/errors/#56"}

プレイヤーがプレイヤーベースのポリシーに基づいてリソースへのアクセスを制限された場合、エラー応答には以下のフィールドが含まれます。


{  "title": "Forbidden",  "detail": "Principal is not authorized to access resource",  "code": 57,  "status": 403,  "type": "https://services.docs.unity.com/docs/errors/#57"}

プレイヤーが一時的にバンされた場合、エラー応答には、以下のようにバンの期間がいつ終了するかを示す

expiresAt

フィールドも含まれます。


{  "title": "Forbidden",  "detail": "Principal is not authorized to access resource",  "code": 57,  "status": 403,  "type": "https://services.docs.unity.com/docs/errors/#57",  "expiresAt": "2023-04-29T18:30:51.243Z"}

プレイヤーが永久的にバンされている場合、エラー応答に

expiresAt

フィールドは含まれません。スムーズなユーザー体験を提供するため、アプリケーションコードでこれらのエラー応答を適切に処理してください。

アクセス制御でのポリシー選択

アクセス制御ポリシーの評価では、最も詳細なルールのみが選ばれ、その効果が適用されます。以下の 3 つのサンプルポリシーがあるとします。


{	"Sid": "deny-all-economy-access",	"Effect": "Deny",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:economy:*"},{	"Sid": "allow-economy-currencies-access",	"Effect": "Allow",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/v2/**/currencies/*"},{	"Sid": "deny-gold-currency-access-economy",	"Effect": "Deny",	"Action": ["Write"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/v2/**/currencies/gold"},

1 番目のルールは、Economy へのすべてのリクエストをまとめて拒否します。
2 番目のルールは、Economy の
```
*/currencies/
```
API へのすべてのリクエストに対する読み取りおよび書き込みアクセスを許可します。
3 番目のルールは、Economy の
```
*/currencies/gold
```
API への書き込みリクエストに対するアクセスを拒否します。

*/currencies/silver

に対してリクエストが行われた場合、2 番目のルール (

/currencies/*

の許可) が適用されます。これは 1 番目のルールより詳細であるためです。

*/currencies/gold

に対してリクエストが行われた場合、3 番目のルール (

*/currencies/gold

の拒否) が適用されます。これは、リクエストに一致するルールのうちで最も詳細であるためです。複数のポリシーでまったく同じ Resource がリストされている場合、常に Deny 効果が優先されます。

ベストプラクティス

デフォルトで拒否

まず、すべてのアクセスを拒否するデフォルトポリシーを作成してから、特定の API またはリソースへのアクセスを明示的に許可します。


{	"Sid": "deny-all-ugs-access",	"Effect": "Deny",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:*:/**"},

最小権限の原則

API またはリソースで必要とされる最小限の権限だけを付与します。


{	"Sid": "allow-cloud-save-read-access",	"Effect": "Allow",	"Action": ["Read"],	"Principal": "Player",	"Resource": "urn:ugs:cloud-save:/v1/data/**/player/*/items**"},

きめ細かいポリシーの定義

ポリシーはすべての API やリソースに対してではなく、特定の API メソッドおよびリソースに対して作成します。


{	"Sid": "allow-economy-silver-readwrite-access",	"Effect": "Allow",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/**/currencies/silver"},{	"Sid": "deny-economy-gold-write-access",	"Effect": "Deny",	"Action": ["Write"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/**/currencies/gold"},

定期的な見直し

API ポリシーを定期的に見直して、ゲームの最新の状態に合わせて更新するとともに、不要な権限を取り除きます。

REST API

アクセス制御 API はウェブエンドポイントを介してアクセス可能であり、つまり REST API です。REST API は柔軟性があり、好みの言語やゲーム開発エンジンを使用してワークフローを自動化することができます。詳細については、アクセス制御 REST API のドキュメントを参照してください。API 呼び出しの認証方法に関する詳細については、サービスアカウント認証のドキュメントを参照してください。以下の例に、REST API で curl ツールを使用しリソースポリシーを設定する方法を示します。


curl -X PATCH https://services.api.unity.com/access/v1/projects/{projectId}/environments/{environmentId}/resource-policy \--header 'Authorization: Basic YOUR_ENCODED_API_KEY' \--header 'Content-Type: application/json' \--data-raw '{     "statements": [    	{            	"Sid": "deny-cloud-save-write-access",            	"Effect": "Deny",            	"Action": ["Write"],            	"Principal": "Player",            	"Resource": "urn:ugs:cloud-save:*"    	}    ]}'

アクセス制御設定のデプロイ

設定を適用するには、Access Control サービスに設定をデプロイする必要があります。

エディターを使用したデプロイ

Unity エディターでアクセス制御設定をデプロイするには、最初に必要なパッケージをインストールし、Unity Gaming Services プロジェクトを Unity エディターにリンクする必要があります。

プロジェクトのリンク

Unity Gaming Services プロジェクトを Unity エディターにリンクします。UGS プロジェクト ID は Unity Dashboard にあります。

Unity エディターで、Edit (編集) > Project Settings (プロジェクト設定) > Services (サービス) の順に選択します。
プロジェクトをリンクします。
- プロジェクトに Unity プロジェクト ID がない場合:
  1. Create a Unity Project ID (Unity プロジェクト ID の作成) > Organizations (組織) の順に選択し、ドロップダウンメニューから組織を選択します。
  2. Create project ID (プロジェクト ID を作成) を選択します。
- 既存の Unity プロジェクト ID がある場合:
  1. Use an existing Unity project ID (既存の Unity プロジェクト ID を使用) を選択します。
  2. ドロップダウンメニューから組織とプロジェクトを選択します。
  3. Link project ID (プロジェクト ID をリンク) を選択します。

Unity プロジェクト ID が表示され、プロジェクトが Unity サービスにリンクされました。また、

UnityEditor.CloudProjectSettings.projectId

を使用して Unity エディタースクリプトのプロジェクト ID にアクセスすることもできます。

必要なパッケージをインストールする

エディター内でアクセス制御設定を作成するには、以下のパッケージをインストールする必要があります。

注

Unity - マニュアル: Package Manager ウィンドウを参照し、Unity Package Manager インターフェースについて理解してください。

これらのパッケージをインストールして、使用可能なパッケージのリストに追加するには、以下を行います。

Unity エディターの Package Manager (パッケージマネージャー) ウィンドウで、+ (add) (+ (追加)) > Add package by name… (名前でパッケージを追加...) を選択します。
```
com.unity.services.deployment
```
を入力します。
Add (追加) を選択します。
これらのステップを
```
com.unity.services.tooling
```
について繰り返します。

設定の作成

アクセス制御設定を作成するには、以下の手順に従います。

Unity エディターで、Project (プロジェクト) ウィンドウを右クリックし、Create (作成) > Services (サービス) > Access Control Configuration (アクセス制御設定) を選択します。
設定に任意の名前を付けます。
Enter を押します。

新しい設定が Project ウィンドウに表示されます。また、Deployment (デプロイ) ウィンドウでは、Window (ウィンドウ) > Deployment (デプロイ) を選択してアクセスできます。

設定の編集

既存のアクセス制御設定を編集する方法は次の 2 つです。

Project (プロジェクト) タブで、既存の設定をダブルクリックする。
Deployment (デプロイ) ウィンドウで、既存のスクリプトを探し、右クリックメニューから Open (開く) を選択する。

CLI を使用したデプロイ

UGS Access Control CLI を使用すると、簡単にアクセス制御設定を管理および自動化できます。

UGS CLI の設定

以下のステップに従って、UGS CLI の使用を準備します。

UGS CLI をインストールします。

プロジェクト ID と環境を以下のように設定します。

ugs config set project-id <your-project-id>

ugs config set environment-name <your-environment-name>

アクセス制御と環境管理に必要なロールでサービスアカウントを設定します。認証の取得を参照してください。

リソースのデプロイ

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

ugs deploy <path-to-access-control-file>

ドキュメント

Development

User Acquisition

Monetization

産業