Roles

Overview

The Roles and Permission offers a solution to your distinctive needs in managing your resources especially when you have a large number of users with various levels of roles. As a publisher, this feature allows you to design a better service roadmap by implementing the role and permission mechanism from the general user level to the top admin level. You can start by defining a role and giving the role a collection of permissions to access certain resources.

Now the role can be assigned to your users by using the role manager and the roles member concept:

  • Role Manager manages and assigns roles to role members. This role has a privilege on controlling which roles are going to be attached to which role members as well as revoking the permission from a role member from a specific role.
  • Role Member is a member of a role that is managed by a role manager.

Tutorials

Create a New Role

Create a New Role Using the API Gateway

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

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

  2. Fill out the Request Body.

    a. Set the Admin Role value to determine whether or not a role will have admin privileges. Set the value to true if the role will be an admin role and false if the role will not be an admin role.

    b. Define who will be the manager of the role.

    • Input the Namespace with the publisher namespace.
    • Input the Display Name of the user who will be the role manager.
    • Input the User ID of the user who will be the role manager.
    • Input the Display Name of the user who will be the role member.

    c. Define who will be a member of the role.

    • Input the Namespace with the publisher namespace.
    • Input the User ID of the user who will be the role member.

    d. Set the Permissions

    • Input the Action needed for the newly created role. The action values are listed in the table below:

      ValueAction
      1Create
      2Read
      4Update
      8Delete
    • Input the resource you want to access. Note that the Resource parameter has its own formatting requirements, listed below:

      • Variable placeholders should be wrapped with {}
      • Only uppercase letters and numbers can be used, except in the variable section
      • Uppercase and lowercase letters are both allowed for the variable placeholder
      • Variable placeholders can be replaced with * as the value or alphanumeric only string
      • Sections are separated by a colon (:)
      • Cannot end with colon (:)
      • Spaces cannot be used

      Below are some examples of how to fill in the Resource parameter:

      • NAMESPACE:game:USER:{userId} Replace userId with the ID of the user you’re creating the permissions for. This allows the user to access any data related to their account in game.
      • NAMESPACE:{namespace}:USER:{userId} Replace namespace and userId with the desired client and user. This allows the user to access their account data in whatever client they’re logged into.
      • ADMIN:NAMESPACE:USER: This permission allows admins to access all namespaces and all user IDs.

    e. The following parameters are optional; they can be used to schedule permissions that are granted on a temporary basis.

    • Input the desired action value into the SchedAction field.
    • For recurring permissions, input the desired string or date range in UTC into the SchedCron field.
    • Input the start and end dates for the permission into the SchedRange field.

    f. Set the Role Name

    • The role name determines what the role is called. The role name should make it clear what the role does.

Create a New Role Using the Admin Portal

  1. In the Admin Portal, go to the Platform Configurations section, then click the Roles menu.

    roles-management

  2. Click the Create New button.

    roles-management

  3. Fill in the required fields

  • Input the Role Name.

  • Select the Set as Admin Role checkbox if you want your new role to have admin privileges.

    roles-management

Add a Role Member

You must be a role manager to add role members.

Add a Role Member Using the API Gateway

You can add a role member by following the steps below.

  1. Use the Roles: Add Role Members - POST /iam/v3/admin/roles/{roleId}/members endpoint.

  2. Input the Role ID to which you want to add more members.

  3. Fill in the Request Body.

    • The Member field defines who will be a member of the role. To add a new member, fill out these fields:
      • Input the Display Name of the user who will be the role member.
      • Input the User ID of the user you’re adding as a role member.
      • Input the Namespace with the publisher namespace.

Upon successful request, the selected user will be a member of the chosen role.

Add a Role Member Through the Admin Portal

You must be a role manager to add role members.

  1. On the Roles page of the Admin Portal, choose the desired roles and click View.

    roles-management

  2. In the role details, go to the Role Members section and click the Add button.

    roles-management

  3. Fill in the required fields

    roles-management

    • Input the User ID or Email of the new role member, then click Add.
    • The user’s ID and display name will appear. Click Add again to add the user as a member of the role.

Add a Role Manager

You should be a role manager to be able to appoint another user to be a role manager.

Add a Role Manager Using the API

Follow the following steps below to add a new permission to add a role manager.

  1. Use the Roles: Add Role Managers - POST /iam/v3/admin/roles/{roleId}/managers endpoint.
  2. Input the Role ID to which you want to add a manager.
  3. Fill in the Request Body.
    • The Managers field defines who will be a manager of the role. To add a new manager, fill out these fields:
      • Input the Display Name of the user who will be the role manager.
      • Input the Namespace to which the particular user belongs.
      • Input the User ID of the user you’re adding as the role manager.

Upon successful request, the selected user will be a manager of the chosen role.

Add a Role Manager Through the Admin Portal

The procedure is similar to the procedure to add a role member.

  1. Go to the Role Manager panel in the Admin Portal and click Add.

    roles-management

  2. Fill in the required fields.

    roles-management

    • Input the User ID or Email of the new role manager, then click Add.
    • The user’s ID and display name will appear. Click Add again to add the user as a manager of the role.

Add a New Permission to a Role

Add a New Permission to a Role in the API Gateway

Follow the following steps below to add a new permission to a role.

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

  2. Input the Role ID of the role to which you want to add permissions.

  3. Fill in the Request Body.

    • Input the Action needed for the newly created role. The following parameters are optional; they can be used to schedule permissions that are granted on a temporary basis.
    • Input the Resource you want to access with the appropriate format.
    • Input the desired action value into the SchedAction field.
    • For recurring permissions, input the desired string or date range in UTC into the SchedCron field.
    • Input the start and end dates for the permission into the SchedRange field.

Upon successful request, the new permission will be added to the role.

Add a New Permission to a Role in the Admin Portal

  1. In the Role Details window of the Admin Portal, go to the User Permissions section and click the Add button.

    roles-management

  2. Fill in the required fields.

    • Input the needed information into the Resource field, with the appropriate format. e.g. PERMISSION:{variable}:NAMESPACE:AccelByte:RESOURCE:*
    • Select the desired Action. You can select more than one.

    roles-management

  3. Click the Confirm button when you're done. The new permission will be added to the list.