Authorisation Model

The Authorisation Model exposes entry point to verify a user’s access privileges by looking up a configurable, granular, group-based authorisation model. The model is used for defining a fine-grained authorisation protocol to various IPF components through the IPF Operational Dashboard. The above-mentioned authorisation model currently covers the HTM Service endpoints in the IPF Dashboard. It is intended to be rolled out to further IPF components in the near future.

Granular, Group-based Authorisation Protocol

The granular, group-based authorisation model provides the ability to define fine-grained access to HTM tasks, as permissions are calculated by taking into account not only roles, but also system-specific contexts. This enables clients to configure such type of authorisation model, which gives limited access to tasks filtered by specific properties to different teams in the business.

Example Configuration

Below you can see an example for a finely-tuned authorisaton model for access to HTM endpoints.

ipf.authorisation {
  processing-entities = [
    {
      name: "BANK_ENTITY_1",
      code: "BE1"
    },
    {
      name: "BANK_ENTITY_2",
      code: "BE2"
    },
  ]
  groups = [
    {
      name: "ADMIN_GROUP",
      bankEntities: {
        "BANK_ENTITY_1": ["ROLE_1", "ROLE_2", "ROLE_3", "ROLE_4"],
        "BANK_ENTITY_2": ["ROLE_1", "ROLE_2", "ROLE_3", "ROLE_4"],
      }
    },
    {
      name: "GROUP_1",
      bankEntities: {
        "BANK_ENTITY_1": ["ROLE_1", "ROLE_3"]
      },
    },
    {
      name: "GROUP_2",
      bankEntities: {
        "BANK_ENTITY_2": ["ROLE_2", "ROLE_4"]
      }
    }
  ],
  roles = [
    {
      role: "ROLE_1",
      permissions: [
        {
          system: "System1",
          actions: ["VIEW"]
          context: {
            "taskType": ["REPAIR"],
            "metaData": ["CURRENCY:USD"]
          }
        }
      ]
    },
    {
      role: "ROLE_2",
      permissions: [
        {
          system: "System2",
          actions: ["VIEW"]
          context: {
            "taskType": "REPAIR"
          }
        }
      ]
    },
    {
      role: "ROLE_3",
      permissions: [
        {
          system: "System1",
          actions: ["CREATE"]
        }
      ]
    }
    {
      role: "ROLE_4",
      permissions: [
        {
          system: "System1",
          actions: ["CREATE", "UPDATE", "CANCEL", "VIEW"]
          context: {
            "taskType": "REPAIR",
            "metaData": ["CURRENCY:GBP"]
          }
        }
      ]
    }
  ]
}

Key Concepts in Granular Authorisation Model

processing-entities: This entry contains a list of ProcessingEntity objects. ProcessingEntity (not to be confused with the more widely used ProcessingEntity object across IPF) has two properties: name and code.

groups: A list of Group objects. It contains a Map of processing entities with grouped roles.

roles: A list of roles defined with respective applicable permissions.

permissions: A list of permissions per system associated with a role.

Let’s go through a permission 's main parts to understand how we can leverage it to achieve granular authorisation.

system: Compulsory attribute. Defines which system the permissions pertain to. Currently, only HTM endpoints are integrated with the new authorisation approach. So, system is set to "HTM".

actions: Compulsory attribute. A list of String values which are in line with enum values of programmatically defined HTMAction.

context: Optional attribute. It is a Map of <String, Object> pairs which makes permissions granular based on task properties. HTM endpoints in dashboard service automatically pass on 2 different filters, if provided, to be forwarded onto the HTM Service calls. These are taskType and metaData.

Let’s review how including these attributes in a context affects what type of tasks the configured permissions can be applied to. The options below are described from least restrictive to the most restrictive access privilege.

Context Type 1

Context is omitted within the role definition. This guarantees admin privilege to the user to execute any of the actions specified within permissions on all tasks.

E.g.: ROLE_3 in Example Configuration has an admin privilege, as system specific context is not defined for this role.

Context Type 2

Only taskType is configured in the context. Task type has to be configured as a <String, String> key - value pair. Consequently, specifying multiple values to a taskType is prohibited.

E.g.: ROLE_2 role in Example Configuration. This role specifies "taskType": "REPAIR". A user who might hold this role (within the associated group), can only view, and update such tasks which have property taskType of REPAIR.

Context Type 3

Both taskType and metaData are defined in the context. This indicates the most restricted access to tasks as a result of filters applied.

E.g.: ROLE_1 role in Example Configuration. A user who might hold this role (within the associated group), can only view such tasks on the screen which have taskType of REPAIR and attached metaDataTags of "CURRENCY:USD".

Registering a System with the Permissions Model

A SystemDefinition is required to be registered for the given system which implements granular authorisation model, which consequently defines the support Actions and an optional ContextAdapter.

Rules to follow to correctly override config:

Client implementation must override ipf.authorisation.conf if they wish to leverage granular authorisation.

Make sure list of permissions are correctly defined. Firstly, all the values have to be the String representations of HTMAction enums. Secondly, view is the minimum privilege a role must hold to have access to further actions. If a role is permitted to further actions which modify the task in any way, one must make sure VIEW permission is still included in the list. This is to ensure that the given task is returned to the user in the initial search query upon log in.
To reiterate, a taskType in a context must only hold a single String value.
A Group might hold different Roles with vastly different contexts. Permissions as well as contexts are additive. In the scenario of determining authorised scope of a user to view tasks, all the taskTypes as well as metaData tags defined in respective roles are used as filters in the query. Be aware, in case of roles with admin privileges override contexts attached to other roles.
- To demonstrate the additive nature of permissions, let’s take a look at Configuration Layout of a highly granular Authorisation Model in the Appendix. Let’s assume there is a user who is in group SANCTIONS. This group encompasses SANCTIONS_EXECUTE and SANCTIONS_APPROVE roles (see roles in example config above). Consequently, the user can view, assign, execute, approve and reject any tasks which have type COMPLIANCE and metaDataTags COMPLIANCETYPE:SANCTIONS.

Authorisation Service

It exposes overloaded the method of isPermitted function:

public <X extends Action, T extends AggregatedPermissionContext> PermittedResult<T> isPermitted(String processingEntityName, List<String> groupNames, SystemDefinition<?, X> system, X action

Controllers in the dashboard service interact with this single function to determine whether a given user can access to the requested resource, identified by the system and an action.

Appendix

1. Section

1.1. Current Authorisation Protocol Used To Access API Endpoints on the Dashboard

To be noted, currently all the endpoints in the service, be that ODS, or CSM Reachability, use role-based authorisation model. From this point onwards, we proceed to use HTM APIs to illustrate the current authorisation model’s usage. A user is assigned to one or more of the following roles to gain access to HTM Tasks on the dashboard:

ROLE_HTM_VIEWER
ROLE_HTM_EXECUTE
ROLE_HTM_APPROVER

Depending on which one or more of the roles the user is assigned to, the user is authorised to view and possibly execute various further actions on tasks. This approach provides unlimited access to the user to access all tasks, as long as they are authorised to do so.

2. Section

2.1. Backward-compatible Default Config

ipf.authorisation {
  processing-entities = [
    {
      name: "BANK_ENTITY_1",
      code: "BE1"
    },
    {
      name: "BANK_ENTITY_2",
      code: "BE2"
    },
    {
      name: "BANK_ENTITY_3",
      code: "BE3"
    },
  ]
  groups = [
    // Groups to ensure backward compatibility using current role definitions
    {
      name: "ROLE_HTM_VIEWER",
      bankEntities: {
        "BANK_ENTITY_1": ["ROLE_HTM_VIEW"],
        "BANK_ENTITY_2": ["ROLE_HTM_VIEW"],
        "BANK_ENTITY_3": ["ROLE_HTM_VIEW"],
      }
    },
    {
      name: "ROLE_HTM_EXECUTE",
      bankEntities: {
        "BANK_ENTITY_1": ["ROLE_HTM_EXECUTE_AND_ASSIGN"],
        "BANK_ENTITY_2": ["ROLE_HTM_EXECUTE_AND_ASSIGN"],
        "BANK_ENTITY_3": ["ROLE_HTM_EXECUTE_AND_ASSIGN"],
      }
    },
    {
      name: "ROLE_HTM_APPROVER",
      bankEntities: {
        "BANK_ENTITY_1": ["ROLE_HTM_APPROVE_AND_REJECT"],
        "BANK_ENTITY_2": ["ROLE_HTM_APPROVE_AND_REJECT"],
        "BANK_ENTITY_3": ["ROLE_HTM_APPROVE_AND_REJECT"],
      }
    },
  ],
  roles = [
    {
      role: "ROLE_HTM_VIEW",
      permissions: [
        {
          system: "HTM",
          actions: ["VIEW"]
        }
      ]
    },
    {
      role: "ROLE_HTM_EXECUTE_AND_ASSIGN",
      permissions: [
        {
          system: "HTM",
          actions: ["VIEW", "ASSIGN", "EXECUTE"]
        }
      ]
    },
    {
      role: "ROLE_HTM_APPROVE_AND_REJECT",
      permissions: [
        {
          system: "HTM",
          actions: ["VIEW", "APPROVE", "REJECT"]
        }
      ]
    },
  ]
}

Default config ensures that current users retain the same access privileges as they had with the old approach.

2.2. Configuration Layout of a highly granular Authorisation Model

Below you can see an example for a finely-tuned authorisaton model for access to HTM endpoints.

ipf.authorisation {
  processing-entities = [
    {
      name: "BANK_ENTITY_1",
      code: "BE1"
    },
    {
      name: "BANK_ENTITY_2",
      code: "BE2"
    },
    {
      name: "BANK_ENTITY_3",
      code: "BE3"
    },
  ]
groups = [
  {
    name: "HTM_ADMIN_GROUP",
    bankEntities: {
      "BANK_ENTITY_1": ["ADMIN_TEAM", "SANCTIONS_EXECUTE"],
      "BANK_ENTITY_2": ["ADMIN_TEAM"],
    }
  },
  {
    name: "HTM_OPERATOR_GROUP_1",
    bankEntities: {
      "BANK_ENTITY_1": ["GB_ACCOUNTS_TEAM", "ACCOUNTS_SYSTEM_A_APPROVE"],
      "BANK_ENTITY_2": ["GB_ACCOUNTS_TEAM", "ACCOUNTS_ADMIN_TEAM"]
    },
  },
  {
    name: "HTM_OPERATOR_GROUP_2",
    bankEntities: {
      "BANK_ENTITY_1": ["US_ACCOUNTS_TEAM", "ACCOUNTS_SYSTEM_A_EXECUTE"]
      "BANK_ENTITY_2": ["US_ACCOUNTS_TEAM", "FRAUD_APPROVE"]
    }
  },
],
roles = [
  {
    role: "US_ACCOUNTS_TEAM",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW"]
        context: {
          "taskType": "REPAIR",
          "metaData": ["CURRENCY:USD"]
        }
      }
    ]
  },
  {
    role: "GB_ACCOUNTS_TEAM",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW"]
        context: {
          "taskType": "REPAIR"
          "metaData": ["CURRENCY:GBP"]
        }
      }
    ]
  },
  {
    role: "ACCOUNTS_SYSTEM_A_EXECUTE",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW", "ASSIGN", "EXECUTE"]
        context: {
          "taskType": "REPAIR"
          "metaData": ["ACCOUNTSYSTEM:A"]
        }
      }
    ]
  },
  {
    role: "ACCOUNTS_SYSTEM_A_APPROVE",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW","APPROVE", "REJECT"]
        context: {
          "taskType": "REPAIR"
          "metaData": ["ACCOUNTSYSTEM:A"]
        }
      }
    ]
  },
  {
    role: "ACCOUNTS_SYSTEM_B_APPROVE",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW", "ASSIGN", "EXECUTE", "APPROVE", "REJECT"]
        context: {
          "taskType": "REPAIR"
          "metaData": ["ACCOUNTSYSTEM:B"]
        }
      }
    ]
  },
  {
    role: "SANCTIONS_EXECUTE",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW", "ASSIGN", "EXECUTE"]
        context: {
          "taskType": "COMPLIANCE"
          "metaData": ["COMPLIANCETYPE:SANCTIONS"]
        }
      }
    ]
  },

  {
    role: "SANCTIONS_APPROVE",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW", "APPROVE", "REJECT"]
        context: {
          "taskType": "COMPLIANCE"
          "metaData": ["COMPLIANCETYPE:SANCTIONS"]
        }
      }
    ]
  },
  {
    role: "FRAUD_EXECUTE",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW", "ASSIGN", "EXECUTE"]
        context: {
          "taskType": "COMPLIANCE"
          "metaData": ["COMPLIANCETYPE:FRAUD"]
        }
      }
    ]
  },
  {
    role: "FRAUD_APPROVE",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW", "APPROVE", "REJECT"]
        context: {
          "taskType": "COMPLIANCE"
          "metaData": ["COMPLIANCETYPE:FRAUD"]
        }
      }
    ]
  },

  {
    role: "ACCOUNTS_ADMIN_TEAM",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW", "APPROVE", "REJECT"]
        context: {
          "taskType": "REPAIR"
        }
      }
    ]
  },
  {
    role: "ADMIN_TEAM",
    permissions: [
      {
        system: "HTM",
        actions: ["VIEW", "ASSIGN", "EXECUTE", "APPROVE", "REJECT"]
      }
    ]
  },
]
}