OneSpan Sign Developers: Account Role – Part 1

Duo Liang, September 8, 2021

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.

9-8-1

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:

Sender Admin Permissions

Event Notification

sender_admin.event_notification

Custom Fields

sender_admin.custom_fields

Subscription account billing details

sender_admin.subscription

Reports

sender_admin.reports

User Management

sender_admin.users

Roles

sender_admin.role

Security Settings

sender_admin.security_settings

Customization

sender_admin.customization

Notary

sender_admin.notary

API Access

sender_admin.api_access

Data Management

sender_admin.data_management

Sub Account Management

sender_admin.sub_account_management

Group Permissions

Group Signing Management (Sender UI Email Groups)

groups.group_signing_management

Template and Layout Permissions

Share Template

templates_layouts.share_templates

Share Layout

templates_layouts.share_layouts

Transaction Permissions

Transaction

transaction.transaction

Change Signer Option

transaction.change_signer

Transaction visibility for delegates

transaction.delegation_visibility

In Person Signing

transaction.in_person

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!