Dependencies

• Familiarity with Runtime Options - To configure new User Roles, you need to edit your project's runtime options. Check out Working with Runtime Options for more information.
• Familiarity with the LiveOps Dashboard HTTP API - Although not necessary to understand Permissions, this page explains how they interact with the Dashboard's HTTP API. If you want to understand it better, take a look at Working with the LiveOps Dashboard HTTP API.

Key Concepts

• Permissions grant access to LiveOps Dashboard actions or features. One Permission may allow you to view a player's details while another may allow you to send in-game mail to a player. Permissions are granted to users through User Roles.

• User Roles are groups of Permissions you can assign to individual users.

Overview

While managing your game, you might not want to grant everyone that has access to the LiveOps Dashboard the same capabilities. You can do the by assigning users with Roles, that in turn grant them Permissions to access specific features on the dashboard. The Metaplay SDK ships with a set of default User Roles, but you can also create your own in your project's runtime options. It is also possible to test that the assigned Roles are working correctly by disabling Auth and using the Assume Roles feature.

Permissions

The server validates Permissions in several places:

• The LiveOps Dashboard uses Permissions to decide which features a user can access. Sometimes a button may appear greyed out in the LiveOps Dashboard, indicating that the current user does not have the required Permission to perform the action. Other times, entire pages or features may be greyed out. Whenever you see a button or page that is disabled in this way, you can float your mouse cursor over the feature to see a tooltip that describes the required Permission.

• The HTTP API uses Permissions to decide whether an endpoint can be called or not. When the LiveOps Dashboard authenticates a user it receives a signed token from the authentication server. The LiveOps Dashboard sends this token along with every call to the HTTP API. The HTTP API validates the token by verifying its signature, then checks the contents to decide whether the user can call the requested endpoint or not. If the user lacks the proper permission, the request is blocked. Even if a malicious user manages to bypass the LiveOps Dashboard Permission checking, they will not be able to call HTTP API endpoints that they do not have permission to use.
• Inside the game server code, each HTTP API endpoint can be tagged with the Permission required to activate it. By default, we add fine-grained Permissions to nearly all API endpoints in the game server. This ensures that we can control exactly which users can perform which actions. We only leave a couple of endpoints unprotected by Permissions- just enough that the Dashboard can query basic information about the game server, such as how to authenticate a User.

Note that we don't assign Permissions directly to users, instead we group a them together as roles and assign those to the user. Which brings us to:

Creating Custom Permissions

Start with adding the permission by modifying (or creating) the GamePermissions.cs file in Backend/Server/AdminApi/

GamePermissions.cs

[AdminApiPermissionGroup("Game-specific permissions")] // Human readable group name for the permissions.
public static class GamePermissions
{
  [MetaDescription("Grant rewards to players with an admin action in the LiveOps Dashboard.")] // Human readable description of the permission.
  [Permission(isDashboardOnly: false, isDynamicallyChecked: false, DefaultRole.GameAdmin)] // Default role that has this permission. Game admins generally should have all permissions and are a safe pick.
  public const string GrantReward = "api.players.grant_reward";
}

If your permission is only used on the dashboard or dynamically checked, then you should set isDashboardOnly or isDynamicallyChecked respectively to true. The server will otherwise detect that the permission is unused and refuse to start to prevent you from being locked out of these actions.

If you have overriden roles in your runtime options then you'll also need to add an entry for the new permission in there. This will look similar to:

api.players.grant_reward: [ game-admin, customer-support-senior, customer-support-agent ]

Now that you have a new permission, you can require it in the API controller. Using the RequirePermission attribute you can specify the required permission for an API endpoint:

AdminApi.cs

[RequirePermission(GamePermissions.GrantReward)]
public async Task GrantReward(string playerIdStr) { }

User Roles

Roles are simply a list of Permissions. When a Role is assigned to a user, that user automatically gains all of the Permissions of that Role. If the Role is removed from the user, so are the Permissions.

Metaplay ships with a few pre-defined Roles for each of your deployments:

• Game Admin - Full access to the dashboard.
• Game Viewer - View access to everything in the Dashboard.
• Customer Support Senior - Has access to manage individual players, but cannot make changes to the game server.
• Customer Support Agent - Similar to Customer Support Senior, but is unable to make drastic changes to players and access some additional types of player data.

If you want to define a different set of roles, you can do this in your game server’s runtime options. It most likely makes sense to configure this inside the base options file: Options.base.yaml. Inside the AdminApi section you can define your roles with:

## AdminApi:

AdminApi:
  Roles:
    # Choose which built-in roles are enabled for the game.
    # You'll always need to enable at least game-admin here.
    - game-admin
    # Specify a game-specific example role
    - my-custom-role
  Permissions:
    # Define all other permissions..
    api.players.unlock_producer: [ game-admin, customer-support-senior, customer-support-agent, my-custom-role ]

Pro tip

A user can have multiple Roles assigned to them, and they will gain Permissions from all attached Roles. You could choose to define Roles on a more granular level than we have, eg: one Role to view players, one to edit players with non-destructive actions, and another for destructive player actions. You would then assign sets of Roles to users based on their required capabilities. We believe that it is best to manage users by having a few well-defined Roles, and then applying a single Role to each user. This is how we have configured the Roles to work by default.

Development and Testing with Permissions

We won't talk about how to add new Permissions to your code in this page, as that's covered by Working with the LiveOps Dashboard HTTP API, but we will talk a little about a powerful feature that helps you to check that your Roles and Permissions are correctly configured: the Assume Roles feature.

Assuming Roles

If you disable Auth, every user gets given a default role. You can easily use this to test that your Roles and Permissions are correctly configured by running the game server locally with Auth disabled. You can then use the Assume Roles feature to pretend that your user has different Roles than the default value.

The Assume Roles feature can be found on the user profile page, which can be accessed by clicking on your username in the top right corner of any page on the LiveOps Dashboard.

To assume a different Role, tick the box next to its name in the Assume Roles box. If you tick multiple boxes then you gain the combined permissions of all selected roles. When this feature is active, it will be clearly indicated on the sidebar of every page in the LiveOps Dashboard.

Security first

The Assume Roles feature is great for development and testing, but it's also a potential security risk that could be abused. For this reason, the feature is only available when Auth is turned off. When Auth is turned on, the Assume Roles code is completely removed from the game server's authentication and authorization code paths and there is no way for users to change, spoof or assume different Roles.

Pro tip

The Assume Roles feature works by adding a special HTTP header field to each API request. The value of this header is remembered per browser tab, not globally. This means that you can test a Role in your browser without affecting anyone else - or you can use it to see how the LiveOps Dashboard would look to different users by assuming different Roles in multiple different tabs.