Introduction

The purpose of this guide is to give an understanding of permission-based security mechanism that provides various options of controlling how users with different security levels will access the system as well as perform different tasks.

Intended Audience

This guide will be useful for administrative users that want to know how to manage security policy within the system at all levels.

Security Mechanism Overview

Within the system, the privileges, permissions and access levels. — Data access - deals with data that a user has access to, for example, data associated with a particular merchant, reseller, etc. This is controlled by data access policy. — Functions - deals with functions that a user can fulfill within the various business processes implemented in the system. This is controlled by function policy." >security mechanism is organized in the following way:
The security mechanism is needed to control the access to various system resources and functionalities that a user has within the system. User access is regulated in three ways:

• Actions that a user can perform within the system. For example, access different perspectives and forms and perform tasks within these forms. This is controlled by privileges, permissions and access levels.
• Data that a user has access to, for example, data associated with a particular merchant, reseller, etc. This is controlled by data access policy.
• Functions that a user can fulfill within the various business processes implemented in the system. This is controlled by function policy.

There are two types of users – human and service. Which user should be created depends on the needs of a user within the system.

Users

A human user is a specific person or entity within the system. This type of a user has access to the user interface only. A human user cannot be created with a generic name (for example, admin) because generic names do not represent a specific known individual. Therefore, the most common generic usernames are rejected by the system. The system allows only one user session to be active at a time. It means that if the user is logged in to the system, its username and password cannot be used in another browser or computer. If there another user session for the active user is attempted, the user receives a corresponding error (to learn more about possible login errors, review login error response codes.

A service user is a specific software unit within the system. This type of a user has access to the API only. The name of a service user should correspond to the following convention: api-{nameofasoftware}. In the name, api is a fixed value required for distinguishing between service and human users and nameofasoftware is a variable value, which is highly recommended to be a name of a software. Depending on the API, service users submit requests to the following end-points:


By default, both human and service users can fail to log in up to 5 times. This parameter can be modified by a gateway administrator via the User Failed Login Limit setting on the Settings form. After the user exceeds the limit of the available count of login attempts, the user gets deactivated in the gateway. The gateway administrator can reactivate the user by resetting login attempts count value and setting the user as active via the Service User Details form.

When a user's password is about to expire, a respective email notification is received. For human users, the notification comes five days prior to the expiration date. For service users, it comes 30 days prior to the expiration date. The password for both types of users can be reset via either the User perspective or the logon page. When resetting a password on the User perspective, the old password for both service and human user is no longer active and only a new password can be used. The same rule works for the human user password reset via the logon page. However, when resetting a password of the service user via the logon page, both old and new passwords are supported by the date when the old password gets expired.

It is highly recommended to associate a particular service user with only one integrated system. If the service user must be used for two different integrations (for example, for real-time transactions sent via API and for terminal transactions), separate service users with separate passwords should be created. This is done to avoid authentication problems related to the password rotation process when the password that needs to be updated is not changed in both systems. To meet PCI requirements, it is necessary to change a service user's password every 90 days. The password of this service user should be stored in a single place as well. Note that a password must be stored encrypted and cannot be hardcoded in the source code. To learn how to change a password for a service user, review How to reset your password tutorial.

A service user can log in to the system in two ways:

• with a permanent password assigned to a user; generally received by email;
• with a session password, which is a temporary password that can be used only once. To generate a session one-time password, authentication operation is used.

To select whether a user should access API using a permanent password or a temporary one, the Authentication Mode setting on the Service User Details form should be configured.

The following time periods are used for user password expiration by default: human users - 90 days, service users - 180 days of a user being inactive. After that period, a user is not able to log in to the application. Once the account is expired, the user needs to reactivate its account by addressing the issue to the gateway support. If necessary, these periods can be modified by a gateway administrator via the User Password Expiration Period setting on the Settings form.

What level and/or component of the system is available for any of these users is regulated by privileges and permissions.

Privileges

Privilege represents a user’s ability to access a part of the system - API or user interface. For example, a human user can view, modify or access different forms and do different actions within the user interface and Management API, while a service user can submit API calls, having a set of privileges assigned. There are seven privileges in the gateway:

• User Interface – allows a user to access functionality of the user interface. By default, this privilege is assigned to human users only.
• Processing API - allows a user to access functionality related to transaction processing. This privilege can be assigned to the service users only.
• Management API - allows a user to access functionality related to the settings setup of merchants, portfolios, etc. This privilege can be assigned to the service users only. In addition, along with this privilege, a permissions that are frequently granted to users collectively. Thus, when a user is created a particular role can be assigned instead of a large number of individual permissions. In the gateway system, there are twelve security roles that belong to four groups (System, Portfolio, Reseller, Merchant, Customer). Security roles are organized hierarchically from System 2 (the highest security level with the largest number of permissions) to Customer 1 (the least number of permissions). To learn more about permissions based security mechanism, review this guide." >security role must be set up.
• Billing API - allows a user to access functionality related to recurring billing. This privilege can be assigned to the service users only.
• Onboarding API - allows a user to access functionality related to the onboarding application. This privilege can be assigned to the service users only and is available only to the users that have access to Processing API.
• TMS API - allows a user to access functionality related to the terminal management system via the specific API. The functionality includes configuration changes, activation of the terminals, parameters setup, etc. This privilege can be assigned to the service users only.
• Reporting API - allows a user to access functionality related to the reports generation via the specific API. This privilege can be assigned to the service users only.

As stated above, human users have only one privilege within the system - user interface access. Service users do not have access to the user interface. However, it is possible to grant them access to all types of APIs within the system.

Permissions

To control what actions are available for a user on a more fine-grained level, both within the UI and APIs, permissions are used. The permission represents a user’s ability to perform a particular action within the system. A user can view or modify the elements of the system, or access different forms and do different actions within these forms. They are assigned to various elements of the user interface, defining what permissions will be necessary for a user to have access to the forms and be able to execute the actions on the user interface or within the API.

Types of permissions, that regulate certain user's actions within the system, are the following:

• access permissions are used to control access to a particular element of the user interface that does not correspond to a business entity (customer, merchant, transaction, etc); for example, perspective or form.
• modify permissions are used to control access to view and modify options within a particular element of the user interface that corresponds to a respective business entity (customer, merchant, transaction, etc).
• view permissions are used to control access to view and search options within a particular element of the user interface that corresponds to a respective business entity (customer, merchant, transaction, etc).
• inherit permissions are used to overwrite permissions of a higher level by permissions of a lower level. For example, permissions denied at the Portfolio level can be allowed at the Reseller level by enabling inherit permissions . At the Portfolio level, they remain denied.

@{API name of a field} permissions are used to control access to a particular field of a business entity on a more granular level (for example, to credit card number or social security number of a customer). Name of the permission consists of two parts: @ (constant) - indicates the type of permission, and {API name of a field} (variable value) - indicates API name of the field that can be viewed and modified by a user.

You can review the whole list of permissions and their availability for every security role here. To verify the link between the permission and a component on the user interface, follow this link - https://sandbox-portal.tidypay.com/?permissions.

So, the privileges control the access to particular places in the system, while permissions control the access to particular actions within these places. To simplify the process of permission setting for a particular user, certain masks are available within the system. These masks are called access levels.

Access levels

Access level is a security role which is basically a combination of permissions. The permission system is represented as a hierarchy. The number of permissions accessible to a user of the lower security level is available for a user that has a higher security level in the system.
The system allows customizing permissions for a particular user. With the help of access policy management, it is possible to add or remove permissions without changing the actual role of the user. When a user with a low-level security role is created, this user has limited permissions by default.
You can see the hierarchy of the access levels available within the gateway in the diagram below:

• System 1/2 – grants the access to the whole system, allowing to perform all kinds of tasks – from merchant to administrative;
• Portfolio 1/2 – grants the access to the forms and actions used by business-oriented administrators of the system. It allows managing the setup of various system-wide settings, information about resellers, merchants, documentation, etc;
• Reseller 1/2 – grants the access to the functions needed for the management of resellers;
• Merchant 1/2/3 – grants the access to the most common merchant tasks, including making payments, refunds, managing recurring billing, etc;
• Customer 1/2/3 – grants the access to the self-service portal that allows managing a customer’s account information, including payments, contracts, account management, etc.

As it is shown in the diagram, the highest level within the system is System 2; a user with this level has system-wide access to all forms and actions. On the contrary, the lowest security level is Customer 1 with the most limited access to the gateway.
It is possible to modify low-level security roles on the perspectives of higher level allowing to enable or disable particular actions. For example, if a user with a Reseller 1/2 security level wants to change the common behavior of all users with Merchant 1/2/3 security level, their permissions can be simply modified on Merchant perspective.

Data access policy

Access policy regulates access levels within the system. Every security level has a certain number of permissions that define what information is available for a particular user to view and access, as well as what actions are available to perform within the forms and perspectives. On the one side, permissions are connected to the security roles, allowing to control the access level of a particular user, and on the other side - to various elements of the user interface and APIs, assigning what is available for a user. The system of permissions allows to differentiate what users are allowed or denied to do within the gateway.
Along with the System 1/2 security level, that has access to the whole system, there are levels that correspond to the particular elements, represented by portfolios, resellers and merchants. Thus, Portfolio 1/2 level corresponds to portfolios, Reseller 1/2 level corresponds to resellers, and Merchant 1/2/3 level corresponds to merchants present in the gateway. At the same time, every lower element belongs to the respective element of the higher level.

All merchants created under particular resellers together with resellers are automatically associated with the portfolio they belong to. Identically, customers, associated with a particular merchant, are automatically linked to the reseller and portfolio this merchant belongs to. For example, there is a portfolio (Portfolio A) that has resellers (Reseller A, Reseller B) assigned; Merchant A, Merchant B and Merchant C are assigned to the Reseller A; Merchant D and Merchant E are assigned to the Reseller B. In this case, if a user is granted with access to the portfolio, access to the Merchants A, B, C, D, and E is granted as well. However, if a user has access only to Reseller A, there will only be access to Merchants A, B and C.

In addition, the system assigns the owner to every newly created user. Thus, users belong to the perspective they were created on. For example, if a user is created on Portfolio perspective, the owner is a current portfolio. If a user is created on Merchant perspective, the owner is a current merchant.
This mechanism allows to create a fully operating security role for a short period of time to avoid separately attaching all the resellers or merchants that the user needs access to. If a user is created on Reseller perspective, the user will be connected to the current reseller and to all the merchants associated with this reseller. Also, users created on Fulfillment perspective will have and access only to this perspective and associated orders.

Function Policy

In addition to security level which determines which actions are allowed, a user can fulfill a particular function defining for what business process a user is responsible. Function defines what role can be played by a user within a particular business context. For example, in a context of chargeback managing, a user can be allowed to be responsible for handling a particular chargeback, or responsible for handling a particular customer account. All functions are controlled by function policy.

Function, assigned to a user, can be the following:

• Chargeback manager - chargeback cases can be assigned to a user (a user will be present in the respective chargeback case combo box).
• Collections agent - customers' accounts can be assigned to a user (a user will be associated with particular customers within the system to manage their records including debts control).

Raw Account Data Processing

For data submission, two end-points can be used: the gateway and the data filter. When there is no sensitive information in the submitted data, both of them can be used. If sensitive data is included, it can be submitted to the data filter only, as it serves as proxy-filter for data sanitization.

Additionally, you can control whether sensitive data can be submitted by a particular user, and how it is allowed to be submitted. For this purpose, Raw Account Data Mode setting within the User Details form on the User perspective is used.

For service users, three options are available:

• HPP usage: disallowed, API usage: disallowed - sensitive data cannot be submitted. You can submit only tokenized/encrypted data via both API and HPP;
• HPP usage: allowed, API usage: disallowed - sensitive data can be submitted only via HPP. Via HPP, you can submit either sensitive or tokenized/encrypted data. Via API, you can submit only tokenized/encrypted data;
• HPP usage: allowed, API usage: allowed - sensitive data can be submitted via either HPP or the API. You can submit either sensitive or tokenized/encrypted data via both API and HPP.

For human users, two options are available:

• UI usage: disallowed - tokenized or encrypted data is entered on the user interface and forwarded to a processor; raw account data submission is prohibited. In this case, the submitted token or data, encrypted by a processor’s key, cannot be decrypted while processing through the gateway end-point;
• UI usage: allowed - raw account data is entered on the user interface and processed by the data filter. In this case, the entered data is subsequently proxynized by the data filter.

Use Cases

Modifying access policy for a user

As an example, let’s review a situation when it is necessary to provide a user with access to the merchant’s payments collected from the customers. At the same time, a user must have no access to other functionality associated with payments (such as voids, refunds, chargebacks, etc).

In this case, the scenario of actions will look as follows:
1. Review permissions assigned to Transaction form available for Merchant 1/2/3 role.
2. A user has to be assigned with a particular role, for example, Merchant 1, to be distinguished from the other roles.
3. Check the settings on Access Policy form. In transaction section of this form, it is possible to change permissions for all roles; you have to allow only a view permission and deny every other permission for this section. To learn how to do it, review a respective tutorial.

Modifying access policy for an access level

Let’s review a situation when it is needed for all users with Merchant 2 access level to be able to modify information associated with the customers, except for billings and collections.

In this case, the scenario of actions will look as follows:
1. Review security settings related to the access policy.
2. Select a Merchant 2 access level on Access Policy form and review its permissions associated with customers group.
3. Deny a modify permission for billing information and collections information.

Changing owner of a user

Let’s review a situation when a user has an access to several portfolios (and their merchants and resellers correspondingly), but it is needed to provide this user with access to merchants and resellers under one particular portfolio.
Note: If a user has Portfolio access level and was created on User perspective, the user's owner is System and this user has an access to all portfolios within the gateway.

In this case, the scenario of actions will look as follows:
1. Access Users perspective and find a respective user in the top section of the screen.
2. Open User Details form. On this form, the owner can be changed from System to Portfolio, and specific portfolio can be chosen as an owner.
3. After the owner has been changed, merchant(s) that a user has to have access to should be assigned to this user. It can be done on Merchants List form on Users perspective.

If there is a user that has an access to several resellers, but it is needed to provide this user with access to only one particular reseller, the scenario of actions will be similar. You only need to do it on Reseller perspective.