Blog

Latest news and updates from the PlayFab developers

by ZachStone 2016-11-21

Introducing API Permission Policies

We are pleased to announce PlayFab API permission policies. These allow you to enforce fine grained control over which API calls are forbidden and which are allowed. This is a powerful tool to help you prevent hacking and cheating for your game by disabling or restricting APIs which are unneeded.

Note: The system as launched today is quite basic. Several fields support only one possible value. This is a new system, and we have planned ahead for future expansion. We will be adding new features in coming months.

Permission Policies

Starting today, all titles now have a permission policy which governs which entities are allowed to call which PlayFab APIs. The policy is a list of statements, each of which describes a single permission rule.

Statements might look like:

{
    "Resource":"pfrn:api--*",
    "Principal":"*",
    "Effect":"Allow",
    "Action":"*",
    "Comment":"This will allow anyone to call anything"
}

Or

{
    "Resource":"pfrn:api--/Client/ConfirmPurchase",
    "Principal":"*",
    "Effect":"Allow",
    "Action":"*",
    "Comment":"This will allow anyone to call ConfirmPurchase"
}

Policy Statements

Statements include the following fields:

  • Resource. The API being acted on. For now, only client API methods are controlled by policies. In the future we will expand to all APIs. API paths must be prefixed with ‘pfrn:api–’. Failing to include this prefix will cause an error when you try to upload the statement. The API path can include the wildcard ‘*’, but it does not support partial matching. This effectively means you need to either allow all APIs, or enable them one-by-one..
  • Action. For now, this can only be the wildcard ‘*’. In the future, this will support more detailed actions like POST vs GET, or READ vs WRITE.
  • Principal. For now, this can only be the wildcard ‘*’. In the future, this will describe the actor, giving you permission to limit different classes of callers.
  • Effect. For now, this can only be ‘Allow’. In the future, this will also support ‘Deny’ so you can selectively disable sets of APIs.
  • Comment. You can set to whatever text you wish to help with future debugging or maintenance.

An empty policy means ‘deny all’. In other words, all apis are disabled unless they are explicitly enabled. Consequently, all titles going forward come with an ‘Allow All’ statement by default.

Note: PlayFab also has other API permissions configurable in the game manager via Settings -> API Features. We will eventually migrate this feature over to new permission policy system, but for now, both still apply. An API request is only valid if both permission sets allow it.

Getting and Setting Policies

For now, you can only update your title’s policy using the /Admin/UpdatePolicy API call, and retrieve the current policy using /Admin/GetPolicy. Later we will provide UI support for this in the Game Manager.

After updating a new policy, it may take up to 30 seconds for the update to propagate. Once the policy takes effect, calls to any restricted APIs will return an HTTP 403 error.

Today you may only have a single policy, called “ApiPolicy”. In the future we will support multiple policies.

Creating Your First Policy

To create a policy, we recommend making a list of all PlayFab API calls your game client uses, then set up a policy that enables these and only these APIs. By disabling unused API calls you limit the ability for other players to create mischief.

For example, here is a link to a sample policy statement for our Unicorn Battle demo game. You may use this as the basis for your own policy.

To summarize the current system limitations (as of early November 2016):

  1. The only supported action is *.
  2. The only supported principal is *.
  3. The service only applies to the client API.
  4. There is only one policy, called ApiPolicy.
  5. The ApiPolicy only applies to the Client API.
  6. Wildcards do not support partial matching.
  7. The only supported effect is “Allow”. Practically, that means you use the policy to enable API methods, not to disable them.
  8. These permissions are not configurable from game manager. Configuration must be done through the Admin API.