Access control

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

Read time 3 minutes

Last updated a day ago

You can control access Unity Gaming Services (UGS) including Cloud Code via the Access Control service. Using Access Control enables you to create rules to restrict access to service APIs that should not be made available to players.

Note

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

Control player access to Cloud Code modules example

The example below demonstrates how you can create a project-based policy that denies access to the Cloud Code service APIs. You can wire a Cloud Code C# module to a trigger while denying direct requests from players, increasing the security of your game. You are able to create access policies with the UGS CLI tool.

Prerequisites

First, you need to create a service account with required access roles and configure the UGS CLI.

Authenticate using a Service Account

Before you can call the Scheduling and Triggers services, you need to use a service account to authenticate.

In the Unity Dashboard, open the Account menu and select Manage organization.
In the Administration menu, select Service Accounts.
Select the New button and enter a name and description for the Service Account.
Select Create.

Add Product roles and create a key:

Select Manage product roles.
Add the following roles to the Service Account:

From the LiveOps dropdown, select Triggers Configuration Editor, Triggers Configuration Viewer, Scheduler Configuration Editor and Scheduler Configuration Viewer .
From the Admin dropdown, select Unity Environments Viewer, Project Resource Policy Editor and Project Resource Policy Reader.

Select Save.
Select Add Key.
Encode the Key ID and Secret key using base64 encoding. The format is “key_id:secret_key”. Note this value down.

For more information, refer to Authentication.

Configure the UGS CLI

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

Install the UGS CLI.

Use the following to configure your Project ID and Environment:

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

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

Authenticate using the service account you created earlier. For more information, refer to Get Authenticated.

Create a module endpoint

Create a Cloud Code module that broadcasts a message to all connected players in the project. Refer to send push messages for more information.


using Microsoft.Extensions.DependencyInjection;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.Apis;namespace HelloWorld{    public class HelloWorld    {        [CloudCodeFunction("SendProjectMessage")]        public async Task SendProjectMessage(IExecutionContext context, IPushClient pushClient, string message, string messageType)        {            await pushClient.SendProjectMessageAsync(context, message, messageType);        }    }    public class ModuleConfig : ICloudCodeSetup    {        public void Setup(ICloudCodeConfig config)        {            config.Dependencies.AddSingleton<IPushClient>(PushClient.Create());        }    }}

Deploy the module. Refer to Deploying Hello World to learn how to deploy a module.

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 module endpoint.


{  "statements": [    {      "Sid": "DenyPlayerAccessForSendingMessageToProject",      "Resource": "urn:ugs:cloud-code:/v1/projects/*/modules/HelloWorld/SendProjectMessage",      "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

SendProjectMessage

module endpoint when authenticated as a player.


curl 'https://cloud-code.services.api.unity.com/v1/projects/<PROJECT_ID>/players/<PLAYER_ID>/modules/HelloWorld/SendProjectMessage' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer <BEARER_TOKEN>' \--data '{"params": {"message": "hello"}}'

If the policy is 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}

Test that the Cloud Code module is able to execute when authenticated with a service account with the same request. To continue, you need to obtain a stateless token and use it as a Bearer token in the request. Refer to Cloud Code Client API Bearer Authentication for more information.


curl 'https://cloud-code.services.api.unity.com/v1/projects/<PROJECT_ID>/modules/HelloWorld/SendProjectMessage' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer <BEARER_TOKEN>' \--data '{"params": {"message": "hello"}}'

If the request is successful, Cloud Code should respond with a

HTTP status code.


{  "output": null}

Set up Scheduling and Triggers

You can set up a schedule and trigger to invoke the

SendProjectMessage

module endpoint.

Create a schedule configuration

Run the

new-file

command to create a schedule configuration locally:


ugs scheduler new-file schedule-config

Update the

schedule-config.sched

file with the following configuration:


{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/schedules.schema.json",  "Configs": {    "send-project-message": {      "EventName": "announcement",      "Type": "one-time",      "Schedule": "2024-08-28T00:00:00Z",      "PayloadVersion": 1,      "Payload": "{\"message\": \"hello\"}"    }  }}

Note

Make sure the

schedule

timestamp is in the future.

Create a trigger configuration

Run the

new-file

command to create a trigger configuration locally:


ugs triggers new-file triggers-config

To create a trigger that invokes the

SendProjectMessage

module endpoint when the

announcement

event fires, update the

triggers-config.tr

file with the following configuration:


{  "$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",  "Configs": [    {      "Name": "announcement-trigger",      "EventType": "com.unity.services.scheduler.announcement.v1",      "ActionUrn": "urn:ugs:cloud-code:HelloWorld/SendProjectMessage",      "ActionType": "cloud-code"    }  ]}

Deploy the configurations

Deploy the files using the UGS CLI tool:


ugs deploy <path-to-config-files>

If configured correctly, the trigger should invoke the

SendProjectMessage