Access Control

Access Control for Unity Gaming Services (UGS) allows you to defend your game state and logic in UGS from cheaters and exploiters. Access Control (also known as API Authorization) is important as it lets you control who can access, modify, or delete game data and resources in order to protect the game from unauthorized access.

API authorization for UGS is the process of determining what actions a user is allowed to perform once they have been authenticated. Authentication verifies that a user is who they claim to be. Together, authentication and authorization provide a secure way to control access to APIs and access to resources. UGS provides an Authentication solution that works with API authorization described in this documentation.

Without authentication, anyone can access the API and potentially perform unauthorized actions. For example, if an API allows users to view sensitive information or make changes to data, and there is no authentication in place, anyone can access that information or make changes without permission.

Authentication establishes the identity of the user, and authorization controls what actions they are allowed to perform. Authentication provides the necessary foundation for authorization to work. It’s like a key that unlocks the door of the API, but the authorization decides if the user is allowed to enter, and what they can do once they are in.

How Access Control works

Access Control in UGS is configured using resource policies. UGS services enforce rules for who can access those services and what actions they are allowed to perform.

When a user attempts to access a UGS service, the service checks the user's identity against the configured policies and either denies or allows an API request.

A resource policy is a collection of statements. The statements are defined in terms of the user’s identity (the Principal attribute), what actions (the Action attribute) are restricted or allowed (the Effect attribute), and the resource the policy applies to (the Resource attribute). A policy also contains a “Sid” attribute (Statement Identifier), a user-defined descriptive name for the given policy which can only contain alphanumeric characters and hyphens.

The resources in the policies are defined as Uniform Resource Names (URNs), which typically end in API paths that make up the component parts of the URN.

Resource policies are configured on a per-project or per-player basis. A project policy is evaluated for all Principals that call UGS services for that project. A player policy is only evaluated for an individual player within the scope of a project and environment.

Here is an example of a valid URN in the Economy service:

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

It uses a glob pattern to match a set of resources that share a common pattern. Below are the different components of this URN.

URN component	Description
urn:	The prefix that indicates that the string is a URN.
ugs:	The namespace identifier (NID) of the URN, which identifies the organization or group responsible for maintaining the URNs in this namespace. In this case, "ugs" stands for Unity Gaming Services, which is the group that created this URN.
economy:	The specific naming authority within the namespace, identifying the specific area of UGS.
/v2/project/	A specific segment of the URN that identifies the version of the API and the project that the URN applies to.
*	The first glob pattern that matches any characters. This is a wildcard that represents any possible value. In this case, it would match any URN that starts with "urn:ugs:economy:/v2/project/" and is followed by any characters.
/player/	A specific segment of the URN that identifies the player that the URN applies to.
*	The second glob pattern that matches any characters. In this case, it would match any URN that starts with "urn:ugs:economy:/v2/project/*/player/" and is followed by any characters.
/currencies/gold	This is the specific segment of the URN that identifies the specific type of currency that the URN applies to.

Because URN matching uses glob patterns, the above URN can also be defined as the following.

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

When no Access Control policies are created, Access Control defaults to allowing all authenticated API calls from authenticated players. That could be described using the following resource policy.

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

The following example shows how to create a valid policy to allow authenticated players to read, but not change (write), the gold currency in Economy via an API call.

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

Alternatively, to completely deny access to authenticated players to all APIs within Economy:

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

How to use Access Control

Use the REST API or the UGS CLI to create resource policies for UGS. These policies only need to be created once and are evaluated and enforced for each API call to UGS within the context of the authenticated caller.

Example policies

Do not allow Players to execute any Cloud Code scripts:

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

This resource policy denies access to all actions on cloud code scripts in the project that a Player is authenticated for. Cloud Code only provides an “execute” API as a POST request to that API, which falls under the “Write” Action in the above policy statement.

Below is another example of what a resource policy for Cloud Save could be:

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

This resource policy denies write access to all the cloud save data for any authenticated player for the project, including all nested paths and subfolders under items for a user or group with a Player identity. This effectively prevents Players from directly writing data to Cloud Save. Combining this policy with the previous policy for Cloud Code, means a developer could write data to Cloud Save via Cloud Code and implement any additional game logic within Cloud Code.

Below are the different components that make up a policy and what they do.

Statement Attribute	Acceptable Values	Description
Sid	Alphanumeric string, e.g., `^[A-Za-z0-9][A-Za-z0-9_-]{5,59}$`	The Statement Identifier. Unique per environment for this policy, used to provide a human-readable name for the policy. Valid values must contain between 5 and 59 characters. For example, `deny-cloud-save-data-write-access`.
Effect	Allow, Deny	Used to specify whether this policy allows or denies access to the specified resource.
Action	Write, Read, *	Used to specify the type of access that is allowed or denied. These actions are specific to the various products in UGS. The Write value typically refers to operations that would result in a change of the state in UGS services. POST, PUT, PATCH, DELETE HTTP verbs for UGS APIs fall into this category. The Read value typically refers to operations that would fetch state from UGS services. The GET HTTP verb for UGS APIs falls into this category. The * value is shorthand for including all acceptable actions.
Principal	Player	Used to specify the identity of the user the policy applies to. Player is currently the only accepted value.
Resource	A valid UGS URN	Used to specify the resource or resources the policy applies to. For example, the resource could be set to `urn:ugs:cloud-save:/v1/data/projects//players//items**`, which is a URN with glob pattern that matches any Cloud Save data for any player authenticated for a project, including all nested paths and subpaths under items.

Error responses

When a player attempts to access a resource for which they don't have appropriate permissions, an error response is returned with a status code of 403 Forbidden. The exact format of the error response depends on the type of access control policy in place.

If a player is restricted from accessing a resource based on a project-based policy, the error response includes the following fields:

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

If a player is restricted from accessing a resource based on a player-based policy, the error response includes the following fields:

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

If the player is temporarily banned, the error response also includes an expiresAt field which indicates when the ban expires:

{
  "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"
}

If the player is permanently banned, the error response doesn't include an expiresAt field. You should handle these error responses appropriately in your application code to ensure a smooth user experience.

Policy selection in Access Control

When Access Control policies are evaluated, only the most specific rule wins and its effect is applied.

Below are three example policies.

{
	"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"
},

The first rule is a generic deny for all requests to Economy
The second rule allows read and write access for all requests to the */currencies/ API in Economy
The third rule specifically denies access for write requests to the */currencies/gold API in Economy

If a request is made to */currencies/silver, the second rule, allow /currencies/*, is applied because it is more specific than the first rule.

If a request is made to */currencies/gold, the third rule, deny */currencies/gold, is applied because it is the most specific rule that matches the request.

If there are multiple policies that list the exact same Resource, then the Deny Effect always takes precedence.

Best practices

Deny by default

Start with a default policy of denying all access and explicitly grant access to specific APIs or resources.

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

Least privilege principle

Grant only the minimum permissions required for an API or resource.

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

Define fine-grained policies

Create policies for specific API methods and resources, rather than for all APIs and resources.

{
	"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"
},

Regular review

Regularly review and update API policies to ensure they reflect the current state of the game and to remove unnecessary permissions.

REST API

The Access Control APIs are accessible via web endpoints, or REST APIs. REST APIs provide flexibility to automate your workflows using your favorite language and game development engine.

Refer to the Access Control REST API documentation for more information. Refer to the Service Account Authentication documentation for more information on how to authenticate your API calls.

The following example shows how to set a resource policy using the REST APIs with the cURL tool.

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:*"
    	}
    ]
}'

CLI

Use the UGS Access Control CLI for simpler management and automation of your Access Control configuration.

Deploy an Access Control configuration

To apply your configuration, you must deploy the configuration to the Access Control service.

Configure the UGS CLI

Follow the steps below to get stated with the UGS CLI:

Install the UGS CLI.
Configure your Project ID and Environment as such:
ugs config set project-id <your-project-id>
ugs config set environment-name <your-environment-name>
Configure a Service Account with the required roles for Access Control and environments management. Refer to Get Authenticated.

Deploy the resource

Run the following command:

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

Access Control#

How Access Control works#

How to use Access Control#

Example policies#

Error responses#

Policy selection in Access Control#

Best practices#

Deny by default#

Least privilege principle#

Define fine-grained policies#

Regular review#

REST API#

CLI#

Deploy an Access Control configuration#

Configure the UGS CLI#

Deploy the resource#