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.

Things to Know

  • Make sure you are authorized to perform any requests.

Tutorials

Create a New Role

Create a New Role Using the API Gateway

Use the Roles: Create Role - POST /iam/v3/admin/roles endpoint and fill out the request body. Follow these steps to make the request:

Step 1: Set the Admin Role Value

Use the adminRole parameter to determine whether or not a role will have admin privileges.

  • Set the value to true if the role will be an admin role.
  • Set the value to false if the role will not be an admin role.
Step 2: Set a Manager

This field is used to define who will be the manager of the role.

  1. Input the Display Name of the user who will be the role manager.
  2. Input the Namespace to which the user belongs.
  3. Input the User ID of the user who will be the role manager.
Step 3: Set a Member

This field is used to define who will be a member of the role.

  1. Input the Display Name of the user who will be the role member.
  2. Input the Namespace to which the particular user belongs.
  3. Input the User ID of the user who will be the role member.
Step 4: Set the Permissions
  1. Input the Action needed for the newly created role. The action values are listed in the table below:

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

    • Only uppercase letters and numbers can be used, except in the variable section
    • Variable placeholders should be wrapped with {}
    • 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 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.

    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.
Step 5: Set the Role Name

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

Step 6: Try it out!

When you’re done, click Try it out! Upon successful request, the new role will be created.

Create a New Role Using the Admin Portal

  1. Login to the Admin Portal with your valid credentials.
  2. Go to the Platform Configurations section, then click the Roles menu.

roles-management

  1. Click the Create New button.

roles-management

  1. Input the Role Name.

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

roles-management

  1. Click the Add button, and this page will appear:

roles-management

  1. Now you can set up your role. If you want to change an existing role to be an admin role, you can click the Enable button in the Role section.

Adding a Role Member

You must be a role manager to add role members.

Adding a Role Member Using the API Gateway

Use the Roles: Add Role Members - POST /iam/v3/admin/roles/{roleId}/members endpoint. Follow these steps to make the request:

  1. Input the Role ID to which you want to add more members.
  2. 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 Namespace to which the particular user belongs.
    • Input the User ID of the user you’re adding as a role member.
  3. Click Try it out!

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

Adding a Role Member Through the Admin Portal

You must be an admin to add role members.

  1. Go to Platform Configuration and click the Roles menu.

roles-management

  1. Choose the desired Role Name and click View. The page below will appear.

roles-management

  1. Go to the Role Members section and click the Add button.

roles-management

  1. Type 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.

roles-management

  1. Upon successful request the user will be added as a role member.

Adding a Role Manager

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

Adding a Role Manager Using the API Gateway

Use the Roles: Add Role Managers - POST /iam/v3/admin/roles/{roleId}/managers endpoint.

  1. Input the Role ID to which you want to add more members.
  2. 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.
  3. Click Try it out!

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

Adding a Role Manager Through the Admin Portal

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

  1. Go to Role Managers and click Add. The below field will appear.

roles-management

  1. Type 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.

roles-management

  1. Upon successful request the user will be added as a role manager.

Adding a New Permission to a Role

Adding a New Permission to a Role in the API Gateway

To attach new permissions to a role, use the Roles: Add Role Permissions - POST /iam/v3/admin/roles/{roleId}/permissions endpoint.

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

  2. Fill in the Request Body:

    • Input the Action needed for the newly created role.
    • Input the resource you want to access into the Resource parameter. Note that the Resource parameter has its own formatting requirements, listed below:
      • Only uppercase letters and numbers can be used, except in the variable section
      • Variable placeholders should be wrapped with {}
      • 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 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.

    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.
  3. Click Try it out!

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

Adding a New Permission to a Role in the Admin Portal

  1. Go to Platform Configuration, and click the Roles menu.

roles-management

  1. Find the desired role and click View. The below page will appear.

roles-management

  1. Go to User Permissions and click Add.
    • 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

  1. Click the Confirm button when you're done.

What’s Next?

  • Check out the API Reference for more information about Roles Management.