Last Updated: 9/6/2021, 8:19:04 AM

# Roles

# Overview

Roles are used to allow central management of user permissions as well as define whether a user can access the Admin Portal. A role is an association between a list of permissions and a list of users. As permissions cannot be directly defined on a user account, roles provide the mechanism for assigning permissions to a user. When a user signs into the platform, the user inherits the permissions granted by all roles assigned to that user.

Roles can be configured to allow access to all namespaces, which means that any user assigned to that role will have the permissions granted by that role in any namespace the user signs into. If a role is not configured to allow access to all namespaces, you must choose which namespaces the role will be applied in for each user that is assigned to the role.

INFO

Role ID is a universally unique identifier (UUID) that is automatically generated when the role is created and can never be changed.

# Prerequisites

# Permissions

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage roles in the Admin Portal. For a full list of permissions that impact roles management, see the IAM tab of the permissions reference.

Usage Resource Action
Create Role ADMIN:ROLE Create
Add Role Permissions ADMIN:ROLE Update
Invite User Admin ADMIN:NAMESPACE:{namespace}:USER:INVITE Create
Admin Add User’s Role ADMIN:NAMESPACE:{namespace}:ROLE:USER:* Update

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# Default Roles

When a new publisher environment is created, it will contain the following roles by default:

Role Admin Description
User No A user that signs into the backend normally through the launcher, game client, or player portal. The user role is automatically applied to user accounts when they are created.
View Only Yes Read-only admin access to the Admin Portal. Has access to all namespaces.
Game Admin Yes Full control, admin access to the Admin Portal. Has access to specific game namespaces only.
Super Admin Yes Full control, admin access to the Admin Portal. Has access to all namespaces.

# Managing Roles in the Admin Portal

# Create a New Role

  1. In the Admin Portal, open the Platform Configurations dropdown in the top-right corner of the page and select the Roles menu.

    roles

  2. On the Roles page, click the Create New button.

    roles

  3. The Create New Role form appears. Fill in the fields with the following information:

    • Enter a name for the role in the Role Name field.
    • Select the Allow Access to All Namespace checkbox if you want your role to be able to access all namespaces.
    • Select the Set as Admin Role checkbox if you want your new role to have access to the Admin Portal.

    roles

  4. When you’re finished, click the Add button. The new role will be created.

# Add Permissions to a Role

After you create a role, you can add permissions to the role by following the steps below.

  1. In the Admin Portal, open the Platform Configurations dropdown in the top-right corner of the page and select the Roles menu.

    roles

  2. Click View next to the role that you want to add permissions to.

roles

  1. In the Permissions section of the Role page, click the Add Permission button.

roles

  1. The Add Role Permission form appears. Fill in the fields with the following information:

    • Enter a permission tag into the Resource field. A permission tag is a string containing multiple tokens that is used to grant access to specific resources. For more information, see the Permissions documentation or the permissions reference
    • Select the action or actions the permission requires in the Action field. These are also listed in the permissions reference (opens new window).

    roles

  2. When you’re done, click Confirm. The permission will be added to the role.

# Assign a Role to a User

You can assign a role to the user from either the Users Management page or the Roles page in the Admin Portal.

# Assign a Role from the Role Page

  1. In the Admin Portal, open the Platform Configurations dropdown in the top-right corner of the page and select the Roles menu.

    roles

  2. Click View next to the role that you want to assign users to.

    roles

  3. Click the Assign Role button in the Assigned Users section of the page.

    roles

  4. The Assign User Role form appears. Fill in the fields with the following information to add the role to the selected user:

    • In the User ID or Email Address field, enter the user ID or email address of the user you want to assign to the role to.
    • If the role has not been configured to allow access to all namespaces, the Select Namespace field will appear, where you can choose one or more namespaces. These namespaces will be the only namespaces in which the user will be given this role. This allows you to create one role that can be used for multiple games.

    roles

  5. When you’re done, click Add. The user will be assigned to the selected role.

# Assign a Role from the User Management Page

  1. In the Admin Portal, click Users in the User Management section of the left navigation bar.

    roles

  2. Select the search filter from the dropdown menu in the Search User panel that corresponds to the user’s account information that you have on hand. Then type that information in the text box and press Enter to search.

    roles

  3. The results of your search will appear. Browse the list to find the account you’re looking for and click View in the Action column of the account listing to open it.

    roles

  4. The User Overview will appear. From here, open the Roles tab from the ribbon at the top of the page.

    roles

  5. On the Roles page, click the Add Role button.

    roles

  6. The Add Role form appears. Fill in the fields with the following information:

    • Select the role you want to assign to the user from the Roles dropdown menu.
    • Enter the namespace where the user should have this role in the Namespace field. You can enter more than one namespace.

    roles

  7. When you’re done, click the Add button. The role will be added to the user.

# Managing Roles Using API

You can also use our API endpoints to manage roles.

# Create a New Role

You can create a new role by following the steps below.

  1. Use the Create Role endpoint: POST - /iam/v4/admin/roles

  2. Fill out the Request Body.

    • Type a name for the role in the roleName field. Role names can only contain alphanumeric characters.
    • For the adminRole field, specify true if users assigned to the role should be allowed to access the Admin Portal. The default value is false.
    • For the isWildcard field, specify true if the role should allow access to all namespaces. The default value is false.

The request is successful if the new role is created. Here is an example response for a successful request:

# Add a Permission to a Role

You can add a permission to a role by following the steps below.

  1. Use the Add Role Permissions endpoint: POST - /iam/v4/admin/roles/{roleId}/permissions .

  2. In the roleId field, specify the autogenerated role ID of the role you want to add the permission to.

  3. Fill out the Request Body with the permission you want to grant:

    • In the Action field, enter the number that corresponds to the bitmask of actions that you want to grant to the role:
    Action Number Description
    1 Create
    2 Read
    3 Create, Read
    4 Update
    5 Update, Create
    6 Update, Read
    7 Update, Read, Create
    8 Delete
    9 Delete, Create
    10 Delete, Read
    11 Delete, Read, Create
    12 Delete, Update
    13 Delete, Update, Create
    14 Delete, Update, Read
    15 Delete, Update, Read, Create
     
    • Enter the permission tag for any endpoint the role will need to access in the Resource field. See the permission reference for a full list.

Upon a successful request, the permission you defined will be assigned to the role. Here is an example response for a successful request:

# Assign a Role to a User

You can assign a role to an existing user by following the steps below.

  1. Use the Assign User To Role endpoint: POST - /iam/v4/admin/namespaces/{namespace}/users/{userId}/roles

  2. In the Namespace field, specify the name of the namespace that the user was created within.

  3. Enter the user’s User ID into the userId field.

  4. Fill out the Request Body:

    • The assignedNamespaces should be populated with the namespaces in which you want the user to be given this role. This is only relevant if the role has not been configured to allow access to all namespaces.
    • In the roleId field, specify the role ID of the role that you want to assign to the user.

Upon a successful request, the new role will be assigned to the specified user. Here is the response example of the successful request:

  • To learn more about permissions, see our Permissions documentation or permissions reference that includes a complete list of all permission tags for all endpoints.
  • See our Accounts documentation for more information about how to create and manage user accounts.
  • Before integrating our services into your game, see our Authorization & Authentication documentation.