OneSpan Sign Developers: Account Role – Part 1

With the new Roles & Permissions feature in OneSpan Sign, admin users now have more granular control over their sender users’ access permissions. By creating a customized Account Role with a set of permissions and assigning the role to a user, you can determine the actions available to the user and easily manage the access rights of a large number of users without having to change their respective permissions.

In this blog, we will begin with a brief introduction to the Roles & Permissions feature, then dive into the available system permissions as well as how to create an account role via RESTful API and SDK code. Without further delay, let’s get started!

Feature Overview

Without access to this feature, admin users were only able to specify two static role types: Sender and Manager. This functionality struggles to scale as the number of senders grows and senders warrant different access to resources based on their role. In order to alleviate this pain point, the Roles & Permissions feature has been introduced to provide more flexible and secure sender management capabilities to your OneSpan Sign account.

The feature will be turned off by default, admin users can contact our support team to arrange setting up your account. Thereafter under your sender portal “Admin” menu, you will find a new UI option “Roles” which allows you to manage your account roles.  Ad-hoc users can also check our “Managing Roles” guide for more detailed instructions.

Available Permissions

With a Role-based Access Control model, you can categorize your users with similar needs and group them into a Role, then grant a set of permissions to the role, so that it determines which resources or actions these users can perform. As the first step, it’s important to be aware all the available permissions and their descriptions. You can also refer to the table below to match the permissions with their IDs, which will later be used to uniquely identify the permissions:

Note: Depending on whether the feature has been turned on in your account, not all of above options may be available for your account role. Also, the permissions list is subject to change as new releases comes out.

Create an Account Role

OneSpan Sign offers three out-of-the-box roles with their pre-configured permission sets: Admin, Manager, and Sender. If you require customized roles, for RESTful API users, use below API:

HTTP Request

POST /api/account/roles

HTTP Headers

Authorization: Basic {your_api_key}
Content-Type: application/json
Accept: application/json

Example Payload

{
  "name": "Regional Manager",
  "enabled": true,
  "description": "Customized Role for Regional Manager",
  "permissions": [
    "transaction.transaction",
    "transaction.in_person"
    ......
  ]
}

From response, an account role ID formatted in UUID will be returned. Store the ID to your local, and we will reference this ID later. 

Similarly for SDK users, make sure your SDK is equal or greater than version 11.35, and use the code snippets below:

Java SDK

AccountRole accountRole = AccountRoleBuilder.newAccountRole()
    .withName("Regional Manager")
    .withPermissions(Arrays.asList("transaction.transaction", "transaction.in_person"))
    .withDescription("Customized Role for Regional Manager")
    .withEnabled(true)
    .build();

eslClient.getAccountService().addAccountRole(accountRole);

Looking Forward to Future Installation

There it is. Through today’s blog, you can now get started with the Roles & Permissions feature. In the next blog, we will continue to showcase the other relative APIs regarding to account roles. Stay tuned!  

If you have any questions regarding this blog or anything else concerning the integration of OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!