Access control

Control access to Unity Gaming Services by creating rules to restrict service APIs you want to protect.

Read time 4 minutes

Last updated 25 days ago

You can control access to Unity Gaming Services (UGS) including Cloud Code via the Access Control service.

Access Control enables you to create rules to restrict access to service APIs that you don't want to make available to players. An example of a access control policy to stop writes to common LiveOps services can be viewed on the Control Access to Services page.

Note

If you allow player access to modules, you reduce the security of your game. For more information, refer to Server authority.

Control player economies with Cloud Code example

The example below demonstrates how you can create a project-based policy that denies access to the Economy service increment/decrement APIs. As players are unable to manipulate their own balances directly, you can create a Cloud Code module that makes these requests as a trusted client on the player's behalf.

You can apply access policies with the UGS CLI tool.

Prerequisites

Ensure you have the following prerequisites for your project before you continue with the example:

Have a published currency in the Economy service.
Have the UGS CLI set up to run commands. For more information, refer to the Get started guide.
Have the project-level Project Resource Policy Editor, Project Resource Policy Reader, and Unity Environments Viewer roles granted to the Service Account you use to authenticate with the CLI tool.

Create an Access Control project policy to restrict access

Create a

project-policy.json

file with the following content to create a policy that denies players direct access to the increment and decrement APIs in the Economy service.


{  "statements": [    {      "Sid": "DenyPlayerAccessForEconomyIncrementAndDecrement",      "Resource": "urn:ugs:economy:/*/*crement",      "Principal": "Player",      "Action": ["*"],      "Effect": "Deny"    }  ]}

Use the UGS CLI tool to apply this policy to your project:


ugs access upsert-project-policy project-policy.json

Test that the policy has successfully denied players from making requests directly to the

increment

API endpoint when authenticated as a player.


curl 'https://economy.services.api.unity.com/v2/projects/<PROJECT_ID>/players/<PLAYER_ID>/currencies/<CURRENCY_ID>/increment' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer <BEARER_TOKEN>' \--data '{    "amount": 10}'

If the policy has been successfully applied, this request should return a response with a

HTTP status code:


{  "status": 403,  "title": "Forbidden",  "type": "https://services.docs.unity.com/docs/errors/#56",  "requestId": "b815d154-91f5-470e-a8ef-76c3c8ec7c13",  "detail": "Access has been restricted",  "code": 56}

Create a module endpoint

Create a Cloud Code module that includes the latest Economy SDK version to make the increment balance request. The module function takes the

currencyId

as a parameter to define which currency to apply the balance update to. Ensure this matches the resource ID in your Economy currency configuration.


using System;using System.Threading.Tasks;using Unity.Services.CloudCode.Apis;using Unity.Services.CloudCode.Apis.Extensions;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Shared;using Unity.Services.Economy.Model;namespace Sample;public class EconomySample{    [CloudCodeFunction("IncrementBalance")]    public async Task<ApiResponse<CurrencyBalanceResponse>> IncrementPlayerBalance(IExecutionContext ctx,        IGameApiClient gameApiClient, string currencyId)    {        try        {            return await gameApiClient.EconomyCurrencies.IncrementPlayerCurrencyBalanceAsync(ctx, ctx.ServiceToken,                ctx.ProjectId, ctx.PlayerId, currencyId, new CurrencyModifyBalanceRequest(currencyId, 10));        }        catch (ApiException ex)        {            throw new Exception($"Failed to get increment {currencyId} currency for player: {ctx.PlayerId}. Error: {ex.Message}");        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.AddGameApiClient();        }    }}

Note

In the

Unity.Services.CloudCode.Apis.Extensions

namespace,

config.AddGameApiClient()

is available from

com.unity.services.cloudcode.core

version 0.0.4 and

com.unity.services.cloudcode.apis

version 0.0.24.

In earlier versions, do the following to register the client manually:


config.Dependencies.AddSingleton<IGameApiClient>(GameApiClient.Create());

Important

The Economy SDK default authentication uses the Cloud Code service account from version 2.4+. It authenticates as the player when using version 2.3 and below.

Test that the Cloud Code module is able to increment the balance when authenticated as a player.


curl --request POST 'https://cloud-code.services.api.unity.com/v1/projects/<PROJECT_ID>/modules/<MODULE_NAME>/<FUNCTION_NAME>' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer <BEARER_TOKEN>' \--data '{	"params": {		"currencyId": "<CURRENCY_ID>"	}}'

If the balance update request was successful, Cloud Code should respond with a

HTTP status code and the result of the increment request containing the new balance value.


{  "result": {    "balance": 10,    "created": {      "date": "2023-06-30T09:12:54Z"    },    "currencyId": "GOLD",    "modified": {      "date": "2023-06-30T09:12:54Z"    },    "writeLock": "1"  }}

Validating the module

You can confirm the player currency balance in the Unity Dashboard using Player Management or by requesting the balance through the Economy service API:


curl 'https://economy.services.api.unity.com/v2/projects/<PROJECT_ID>/players/<PLAYER_ID>/currencies' \--header 'Authorization: Bearer <BEARER_TOKEN>'

With Cloud Code successfully set up to control player balances, you can insert additional logic to ensure that a player's balance is updated only when it is expected.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Cloud Code

Scripting API

Services C# SDKs

Services JavaScript SDKs

Admin REST API

Client REST API

Scheduler Admin REST API

Observability REST API