Master Permissions

Last updated on August 9, 2023
note

AGS Starter ではまだ権限を利用できません。まもなく公開します！

概要​

権限とは、AccelByte Gaming Service (AGS) を使用したいユーザーとアプリケーションに特定のアクセス権利を付与する手段のことです。

これは、2 つの個別の部分を含む承認システム全体の基礎となります。

  1. 権限の要件：ほとんどの AGS API エンドポイントは、特定の必要な権限によって保護されています。

    注記

    当社の API エンドポイントドキュメント に、各エンドポイントに必要な権限を記載しています。

  2. 権限の付与：管理者ポータルを使用して、必要な権限を (IAM クライアントを介して) アプリケーションに、(ロールを介して) ユーザーに割り当てることができます。

目標​

このトピックの目的は次のとおりです。

  • 権限とは何か、どのように使用されているかを理解します。
  • IAM クライアントで使用されている権限と、ユーザーアカウントに割り当てられているロールについて説明する関連ガイドへリンクします。

前提条件​

RESTful API 設計に精通している必要があります。

構文​

権限は_permission resource_と_permission action_で構成されます。

権限リソース​

AccelByte Gaming Services (AGS) のRESTful API 設計を使用しています。RESTful API, では、プライマリデータ表現を_resource_と呼びます。

AGS では、権限リソースはコロンで区切られた複数のトークンを含む文字列です。これには、権限を適用する名前空間やユーザー、また保護されたオブジェクトの名前といった詳細を含めることができます。

権限アクション​

権限アクションでは、ユーザーやアプリケーションが権限によってリソースで実行できることを説明します。サポートされているアクションは、Create (作成)、Read (読み取り)、Update (更新)、Delete (削除)です。

権限の要件​

必要な権限を AGS エンドポイントに定義する場合は、上記の一般的な構文に従ってください。例として、4 つの個別のトークンを含む、AGS エンドポイントに定義した権限の要件のテンプレートを以下に示します。

[ADMIN:][NAMESPACE:<namespace>:][USER:<userId>:]<OBJECTNAME>

  • ADMIN:はオプションであり、権限が管理リソースを対象としていることを示しています。これは、ADMIN エンドポイントに関連付けられた権限においてのみプレフィックスとして使用する必要があり、次の 2 つのシナリオで使用することが意図されています。

    1.AGSと、IAM クライアントを介して承認されたアプリケーション間で、信頼できる内部 API 呼び出しを行う場合。 1.適切なロールを持つ管理者ユーザーが、管理者ポータル (またはその他の適切な外部ツール) を使用して呼び出しを行う場合。

    たとえば、ロール情報の検索に使用するエンドポイントには、管理者権限が必要です。

    エンドポイント権限説明
    GET /iam/v3/admin/rolesADMIN:ROLE <READ>ロールはプラットフォームレベルのオブジェクトであり、名前空間やユーザーに属していないため、必要なアクセス許可で定義されている名前空間:{namespace}またはユーザー:{userId}はありません。
    • 非 ADMIN 権限は、常に公開エンドポイントに関連付けられます。これらのエンドポイントは、有効なアクセストークンを使用して、任意の承認されたユーザーアカウントから呼び出せます。

  • NAMESPACE:{namespace}はオプションであり、リソースが IAM クライアント、ストア、その他のリソースで必要とされる名前空間レベルにある場合にのみ使用します。これは権限が適用される名前空間がどれかを示しています。構文は、リテラル文字列 NAMESPACE:に名前空間名プレースホルダー{namespace}が続きます。たとえば、特定の名前空間内で IAM クライアントを作成するために使用するエンドポイントには、管理者権限が必要です。

    エンドポイント権限説明
    POST /iam/v3/admin/namespaces/{namespace}/clientsADMIN:NAMESPACE:{namespace}:CLIENT <CREATE>リクエストティアがPOST /iam/v3/admin/namespaces/accelbyte/clientsを介してリソースにアクセスする場合、実際に必要な権限はADMIN:NAMESPACE:accelbyte:CLIENT [CREATE]です。IAM クライアントが名前空間レベルの下にあり、しかしユーザー固有のリソースではない場合、必要な権限に User:userId は定義されていません。

  • USER:{userId}はオプションであり、ユーザー固有のリソースにのみ使用します。これはNAMESPACE:{namespace part}と似ていて、権限を適用するユーザーを表しています。構文は、リテラル文字列 USER: にユーザー ID プレースホルダー{userId}が続きます。たとえば、これは特定の名前空間内における特定のユーザーに属するエンタイトルメントを検索する場合に、エンドポイントに必要になる管理者権限です。

    エンドポイント権限説明
    GET /admin/namespaces/{namespace}/users/{userId}/entitlementsDMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENT <READ>リクエストティアがGET <code>/admin/namespaces/accelbyte/users/1234/entitlementsを介してリソースにアクセスする場合、実際に必要な権限はADMIN:NAMESPACE:accelbyte:USER:1234:ENTITLEMENT <READ>

  • OBJECTNAME は必須であり、このトークンはプロファイルや通貨など、保護されたリソースオブジェクトを表しています。たとえば、これは特定の名前空間で通貨を検索する場合に、エンドポイントに必要になる管理者権限です。

    エンドポイント権限説明
    GET /admin/namespace/{namespace}/currenciesADMIN:NAMESPACE:{namespace}:CURRENCY <READ>権限リソースには、コロンで区切られた複数のオブジェクト名を含めることができます。が、それはほとんどの場合、推奨しません。

権限の付与​

ユーザーまたはアプリケーションに権限を付与する場合は、上記の一般的な構文にも従う必要があります。

ここに挙げるのは付与された権限のテンプレートです。4 つの個別のトークンも含まれています。

[ADMIN:][NAMESPACE:<namespace>:][USER:<userId>:]<OBJECTNAME>

  • ADMIN は ADMIN エンドポイントで定義されている権限の要件と同じです。これは、管理リソースの権限にプレフィックスとして付ける必要があります。たとえば、ロールの CRUD (作成、読み取り、更新、削除) のために付与された管理者権限だとこのようになります。

    権限説明
    ADMIN:ROLE <CREATE>|<READ>|<UPDATE>|<DELETE>アクション間のロジックは Bitwise または(|)です。

  • NAMESPACE:<namespace> はオプションであり、リソースが名前空間レベルにある場合にのみ使用します。

    構文は、リテラル文字列 NAMESPACE: に名前空間名プレースホルダー{namespace}、* (ワイルドカード)、または特定の名前空間名が続きます。

    • {namespace}：この値は、ユーザーまたはアプリケーションから付与された名前空間にそれを動的に解決するよう、バックエンドに指示します。これは、特定の名前空間に対応する権限を付与されたクライアントとユーザーが、その名前空間内のリソースのみを使用できることを意味します。たとえば、これはユーザーアカウント/アプリケーションに付与された特定の名前空間で、IAM クライアントを作成するためのアクセスを許可する権限です。
    権限説明
    ADMIN:NAMESPACE:{namespace}:CLIENT <CREATE>アスタリスク("*")はワイルドカードとして解釈され、すべての名前空間でそのリソースへのアクセスを許可します。たとえば、これはいずれかの名前空間で、IAM クライアントを作成するためのアクセスを許可する権限です。ADMIN:NAMESPACE:*:CLIENT <CREATE>

  • 特定の名前空間の名前：特定の名前空間が指定されている場合(たとえばNAMESPACE:namespace_A)、その特定の名前空間内に存在するリソースに対してのみ権限が付与されます。これはスーパー管理者が使用できます。特定のゲームの名前空間内に存在するリソースのみに対する制限付きの管理者アクセスを、カスタマーサポートユーザーに許可する方法を提供します。

    権限説明
    ADMIN:NAMESPACE:namespace_A:CLIENT <CREATE>この権限は、特定の名前空間 (namespace_A) でのみ、IAM クライアント作成のためのアクセスを許可します。

  • USER:userId はオプションであり、ユーザー固有のリソースにのみ使用します。

    構文は、リテラル文字列 USER: にユーザー ID プレースホルダー{userId}、またはワイルドカードアスタリスクのいずれかが続きます。

    • {userId}：この値は、ログインしているユーザーの ID に動的にバインドし、{userId}をユーザーの実際の ID で置き換えるよう、バックエンドに指示します。これは、特定のユーザーに対応する権限を付与されたクライアントとユーザーが、そのユーザーに属するリソースのみを使用できることを意味します。たとえば、これは任意の名前空間でログインしているユーザーが、エンタイトルメントを検索するためのアクセスを許可する権限です。
    権限説明
    ADMIN:NAMESPACE:*:USER:{userId}:ENTITLEMENT <READ>アスタリスクはワイルドカードとして解釈され、任意のユーザーに属するそのリソースへのアクセスを許可します。たとえば、これは任意の名前空間にいるユーザーが、エンタイトルメントを検索するためのアクセスを許可する権限です。ADMIN:NAMESPACE:*:USER:*:ENTITLEMENT <READ>

  • OBJECTNAME は、ADMIN エンドポイントで定義されている権限の要件とほぼ同じです。ここでの構文には、特定のオブジェクト名またはワイルドカードアスタリスクのいずれかを使用します。

  • 特定のオブジェクト名は、保護されたリソースオブジェクトを表します。たとえば、これは特定の名前空間内に存在する特定のユーザーに属するプロファイルを検索するための、アクセスを許可する権限です。

    権限説明
    ADMIN:NAMESPACE:{namespace}:USER:{userId}:PROFILE <READ>全リソースオブジェクトにアクセスを許可する場合は、オブジェクト名をワイルドカードのアスタリスクに置き換えます。たとえば、これは任意の名前空間にログインしているユーザーが、何らかの検索をするためのアクセスを許可する権限です。ADMIN:NAMESPACE:*:USER:{userid}:* <READ>

##トラブルシューティング

このセクションには、サービス使用時に発生しうる一般的なエラーや問題、およびそれらを解決する方法についての推奨事項を記載しています。

###各 AGS エンドポイントに必要な権限を見つける方法

API エンドポイントドキュメント を検索すると、各エンドポイントに必要な権限が一覧表示されます。

###権限に関するエラーを解決する方法

ナレッジベース でエラーと例外について確認します。

##次のステップ

ユーザーアカウントとアプリケーションに権限を付与する方法の確認を続けるには、他のガイドを参照してください。

に最終更新

On this page