User Permissions

The PayRun.io API supports two flavors of authentication; OAuth 1.0 (signed requests using consumer keys and secrets) and Auth 2.0 (using JWT and remote authorisation services).

OAuth 1.0 authentication supports a single level of permission globally per application. This is ideal when a single tenet exists within the application and there is no need to restrict access to any particular resources.

OAuth 2.0 authentication allows for user centric authorisation. Using a combination of remote authentication service, user name and resource permission specification, it is possible to define which resources a particular user can access.

Authorization Header

API requests can be authorised (on a per user basis) by specifying a valid base64 encoded JWT access token under the HTTP Authorization request header. The JWT access token should be pre-fixed with the "Bearer" indicator.

Example Authorization Header

  • Authorization Bearer ##Base64EncodedAccessToken##

Remote Authentication Service

The PayRun.io API makes use of external services to ensure received authentication values are valid. The remote signing authority provides public information that allows the API to validate the received JWT is correctly signed and has not been tampered with.

Once the JWT has been validated, the token values are combined to form a unique user identifier value.

User Identifier

The user identifier is a combination of issuing authority and user name. This value is used to uniquely identify a user record within the API.

Example User Identifier Pattern

(Issuer Url)(Separator)(User Name)
https://example.authentication.service.com/AuthPoolId~~UserName001

Example Access Token Payload

{
  "sub": "54e9896e-e345-439c-aaca-b19ce7c19628",
  "event_id": "d53acb39-5966-44c4-abe4-3d9687879221",
  "token_use": "access",
  "scope": "example.scope",
  "auth_time": 1628502322,
  "iss": "https://example.authentication.service.com/eu-west-2_ORmRwH6w4",
  "exp": 1628505922,
  "iat": 1628502322,
  "jti": "9756631e-9292-4acc-aa92-b889d1becef3",
  "client_id": "7fcn2acebkq0ajpt3e97dprjvb",
  "username": "test_sign_in_user"
}

Results In User Identifier

  • "iss" + ~~ + "username"
  • https://example.authentication.service.com/eu-west-2_ORmRwH6w4~~test_sign_in_user

Object Hierarchy

The following diagram displays the user permission object hierarchy under the application root.

Users

User records are stored within the PayRun.io API just like any other resource, accessed and managed using a combination of HTTP [GET], [PUT], [POST] and [DELETE].

The purpose of a User record is to relate the user identifier to a particular application and associate them with a list of roles and permission links.

User Record User Identifier Property

User records are matched to the received JWT authorisation headers using the User Identifier compound key value. The user record identifier value (set on the User record) must exactly match the User Identifier that generated from the received JWT access token header value.

User Roles

The User record entity includes support for an optional list of roles. The role values are unrestrained strings that can be used to store additional role based information against a user record. They are not used within the API for any other authorisation purposes.

Permissions are associated to User records using a Link. A single User record can be associated with any number of Permissions.

Permissions

Much like user records, Permissions are stored and controlled within the API just like any other resource. A single Permission defines an access policy for resources. This policy can either allow or deny: read, write or delete access to resources within the associated application.

Permission Policy

A Permission can be defined to either allow or deny actions against a set of API resources matching the expression.

Permission Verbs

The Permission can be applied to certain actions. You can specify any combination of Read, Write, or Delete verbs when defining permissions or use the All verb as a shortcut for all actions. A Permission that has only the Delete verb value will be considered only when the user attempts to perform a deletion. Conversely, a Permission with the all verb will be considered for any resource request action.

Permission Expressions

The resources covered by a Permission are identified using an expression value. The Permission is matched to the resource by comparing the expression to the resource location path. Expressions can optionally include wildcard (*) characters in order to match multiple resources.

Available Resources Locations:

  • /Employer/ER001
  • /Employer/ER001/Employee/EE001
  • /Employer/ER002
  • /Employer/ER002/Employee/EE001

Explicit Expression Example

  • /Employer/ER001

Matched Resources:

  • /Employer/ER001

Wildcard (*) Expression Example

  • /Employer/ER001*

Matched Resources:

  • /Employer/ER001
  • /Employer/ER001/Employee/EE001

Permission Priority

When multiple contradictory permissions match a given URL, which permission takes priority is determined using the following set of rules.

  1. Explicit paths trump wildcard paths
  2. More complex expressions have a higher priority.
  3. Deny trumps Allow

Expression Complexity
The complexity of an expression is determined by the number of sub sections. Sub sections are declared using a forward slash /.

Expression: /Employer/ER001/Employee/EE001
is more complex than /Employer/ER001/Employees because it has an additional sub section.

User Permission Process Flow

The user permission authentication and authorisation process flow is described in the following diagram.

Default Permissions

The API will automatically supply a default set of permissions within every application instance. There are also default permissions generated when a new employer record is added.

Existing permissions can be found using the following API request:

curl -X GET \
  'https://api.test.payrun.io/Permissions' \
  -H 'Accept: application/xml' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/xml'
curl -X GET \
  'https://api.test.payrun.io/Permissions' \
  -H 'Accept: application/json' \
  -H 'Api-Version: default' \
  -H 'Authorization: {OAuthHeader}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-type: application/json'

Default Application Level Permissions

The following list details the permission objects created by default with every application instance.

Name Description Expression Policy Verbs
AllowAll Allow read, write, delete access to all resources * Allow All
DenyAll Deny read, write, delete, access to all resources * Deny All
EmployersAllowAll Allow read, write, delete access to all employers /Employer* Allow All
EmployersDenyAll Deny read, write, delete access to all employers /Employer* Deny All
ReportDefinitionsAllowAll Allow read, write, delete access to all Report Definitions /ReportDefinition* Allow All
ReportDefinitionsDenyAll Deny read, write, delete access to all Report Definitions /ReportDefinition* Deny All
TransformDefinitionsAllowAll Allow read, write, delete access to all Transform Definitions /TransformDefinition* Allow All
TransformDefinitionsDenyAll Deny read, write, delete access to all Transform Definitions /TransformDefinition* Deny All
TemplateJournalInstructionsAllowAll Allow read, write, delete access to all Template Journal Instructions /JournalInstruction* Allow All
TemplateJournalInstructionsDenyAll Deny read, write, delete access to all Template Journal Instructions /JournalInstruction* Deny All
PermissionsAllowAll Allow read, write, delete access to all Permissions /Permission* Allow All
PermissionsDenyAll Deny read, write, delete access to all Permissions /Permission* Deny All
UserAllowAll Allow read, write, delete access to all Users /User* Allow All
UserDenyAll Deny read, write, delete access to all Users /User* Deny All

The below list details the permissions automatically generated when a new Employer record is created.

[EmployerKey] will be replaced with the unique key value of the newly created employer record.
E.g. Employer unique key ER001 will result in permission ER001AllowAll

Name Description Expression Policy Verbs
[EmployerKey]AllowAll Allow read, write, delete access to employer [EmployerKey] and all descendants /Employer/[EmployerKey]* Allow All
[EmployerKey]DenyAll Deny read, write, delete access to employer [EmployerKey] and all descendants /Employer/[EmployerKey]* Deny All