# AppURP or URP (User, Role, Permission) for Application
## Basic Concept
URP stands for user, role and permission (also called authority). It is a basic module which controls all kinds of system accesses and permissions. It is vitally important for different users to perform security control and isolation.
Our URP module allows the system administrator to configure all relevant permissions via default URP UI and provides APIs for front-end applications to call and control corresponding accesses. We support to configure not only the menu-related permissions, but data and API-related permissions.
Please note that everything in this document is related to AppUrp which is URP for application usage. It's not about insureMO portal URP usage.
## User Scenario
For anybody who wants to use our platform to develop an application with proper control over the permissions of each login user.
## Composition of URP
The URP module includes the following aspects:
* ***User***, the login account, including basic name, password and other additional attributes.
* ***Role***, a set of permissions which reflect business operation units.
* ***Permission***, a unit of permissions checking which the system will take for validation.
note
One user can have multiple roles and one role can contain multiple permissions.
Once a user logs in to the system, the system will obtain all permissions for users and check the permissions accordingly.
For the permission, its code is the unique identifier which can be further divided into two user scenarios:
* Standalone as a ***Non-UI Permission***, which can control the backend behavior, like API authority.
* Linked to UI as a ***UI Permission***, which can control the UI behavior, like UI menu or button.
The UI permission can be made up of two parts:
* ***Menu Permission***, which can control the display of UI menu in the left side.
* ***UI Element Permission***, which can control the display of specific UI components, like button or link.
Besides API authority, a non-UI permission can also be defined as a ***Row-Level Data Permission***, which describes the data scope a user can operate on. For details, see section **Basic UI Operation > 6. Data Permission**.
We can even define a global whitelist of API permissions in our URP module according to business requirements.
### Role Management Mechanism
Logically, there are two methods of achieving the relationship between the permission and user for a role:
* Role as a group
It is the most common system design. With this approach, users will obtain roles only through role association. Any change in the permission under a role will be automatically applied to all users.
* Role as a template
It is a more complex scenario. With this approach, users will obtain permissions to copy directly from roles. Any change in a permission under a role will not be applied to all users unless it is intentionally synchronized. Also, when a permission needs to be added for a user, it can be added directly, bypassing the role.
Now the system normally treats a role as a group. In our architectural design, however, we can support the role as a template design. If our users do have such a business scenario, they can contact the insureMO team to jointly observe how to achieve it.
### Complex Business Permission Extension
In some complex business scenarios, a business department may require multi-layered permission structure, for example, to check claim authorities based on product line, product, task and authority amount.
For such scenarios, it is impossible to come up with a standard URP module without much customization from the platform. In other words, our permission structure cannot meet the requirements of these scenarios. Yet, we recommend that the business module implement its own authorities and attach the results to our permissions.
Logically, it will turn our permission into another authority group and the detailed system logic will be implemented through the business authority.
Here is an example of the UI that implements Claim Authority.
### Import/Export
Configuration data is allowed to be defined in our master configuration (MC) portal and deployed to other environments. For the URP side:
* Users normally use instance data which is configured directly in runtime environment.
* Permission allows configuration data to be defined in MC, which are deployed in runtime environment.
* Role/Branch is in a grey area as some users might treat it as the definition data or instance data.
To dig into this topic, please read Scenario Part 1 to better grasp on how to build an initial database (DB) on our platform.
## Basic UI Operation
note
**Permission definition needs to be performed in either runtime environment or MC portal, and it is not allowed in other environments unless for troubleshooting purposes. Role management can be performed in either MC portal or runtime environment, but be sure to select only one of them.**
### 1. Create New User
**User Management > Add User > Save**
* **User Name**: The primary key to a user, it should be unique. When logging in, input the user name.
* **Real Name**: The real name of user.
* **Email**: The email of user.
* **Mobile**: The mobile number of user.
* **Status**: If a user is set to be **Inactive**, the user cannot log in to the system.
* **User Type**: It is a business extension field without specific platform system action on this field.
* **Organization Name**: Data source is a part of Branch. If the data is empty, we need to add the value in the Branch menu.
* **Position**:
- **Super Administrator**: The user can perform almost everything and the system will not check menu or API authority for it.
- **Authorized Administrator**: Menu operation permission depends on the permission granted by Administrator. With the URP permission, the user can perform any operation related to URP-authorized permissions.
- **Branch Administrator**: Similar to the authorized administrator but it can only view or edit users who belong to their own branches or sub-ordinate branches.
- **Ordinary User**: Menu operation permission depends on the permission granted by Administrator. Even with the URP permission, the user can only check the information but cannot perform any operations related to URP-authorized permissions.
* **Default Language**: The default UI language when users log in.
* **Supervisor**: Supervisor of a user. Any workflow task that needs approving, it should be sent to the Supervisor.
* **Expired Time**: The container can practically control whether the user takes effect.
- To avoid the confusion caused by the users' inactive status in the container and the active status still displayed in the general insurance (GI), GI adds the Expired Time to control the display of the users' status.
- If the Expired Time is greater than the current time, this user status displays inactive, but whether the user can log in primarily determines the users' status in the container.
* **Party Code**: Reference value, it's used to indicate the user party identification such as employee, sales channel or customer code.
### 2. Create New Role
Role works as a bundle of permissions. To create a role, we just need to group some permissions to a bundle.
There's a dropdown list of role category which user need to pay special attention:
1. Standard Role - This is just standard role and there will be no specific system action on it.
2. Common Role - Once a role is defined as common, it will be always applied to all users. It's very useful to apply when there's some whitelist APIs at tenant level to configure.
3. Default Role - Once a role is defined as default, it will be automatically added to the user during his first login.
Also, users need to pay attention to role level whether it's platform/baseline or tenant. Users are freely to change tenant role but platform/baseline role users can only use but not change them.
**Role Management > Add Role > Select Subsystem and permission code > Save**
Select **Subsystem**, and then select the **permission code** for the role. If you need to remove any permission, just de-select it.
### 3. Grant Role to Existing User
For role is a bundle of permissions, granting a role to a user will actually mean grant a bundle of all permissions under the role to a user.
**User Management > Search the Existing User > Edit > Add the Role**
### 4. Create New Permission
caution
- Before **add node**, please click the **parent node** that you want to add a child node to. The **Permission Group ID** will be automatically populated, or otherwise, it will be empty.
- Only when **Menu Type** is with value **Folder**, **Menu**, the child node can be added.
**Permission Management > Select Subsystem > Search > Add Node > Input permission related information > Save**
Input permission related information, and click **Save**.
| Field Name | Description |
| -------------------- | ------------------------------------------------------------ |
| Menu Type | Folder/Menu/Element/API Permission/Data. Different levels of the menus have different types of functions. **Folder** is only for root node; **Menu** is for function menus to show; **Element** for UI element authority on the page; **API ** for API authority only without UI; **Data** for row-level data authority (see section 6 Data Permission). |
| Permission Name | User input. |
| Permission Code | User input and Uniqueness. |
| Permission Group Id | Auto generated, for example YYYYMMDDXX 2021041200. It is the same from level 1 to level N in the same menu. |
| Permission Type | **Folder** is a default set for root node. **Portal Permission** is a default set for level 1 menus, and **Standard Permission** is a default set for sub menus. Others are for special function. |
| Function Description | Business description. |
| Entrance URL | The URL of the primary menu, for example `/ui/urp/`, where URP is the name of your UI project. The URLs of the other menus (of the relative path) need to notice. If there is no three-level menu, fill in the secondary menu path (entranceurl) with the relative path corresponding to the menu. If there is a three-level menu, the second level of menu path will not be filled in. Otherwise, for the third level menu path (entranceurl), fill in the relative path corresponding to the menu. |
| DOC URL | If it is filled in, there will be a question mark appended in the upper left menu. Users can click to open a new page to view the corresponding document. |
| Is Latest | Whether it is a new function. If it is not selected, the default is N; if it is selected, the left menu will indicate it's a new menu. |
| Is Visible | Whether the menu is visible. If it is not selected, it is visible by default. This is to hide menus not to be used. |
| Icon | The small icon of the menu. The name is fixed in the rainbow component library. For example "rainbow Document16". |
| I18N Group | If it is not selected, system takes it as the group **Menu** of the UI Label. For i18n Group, see [i18n](https://docs.insuremo.com/ics/app_framework/i18n). |
| I18N Code | The key of i18n. For i18n Code, see [i18n](https://docs.insuremo.com/ics/app_framework/i18n). |
| Display Index | The order of the menu. |
| Is Hyperlink | If it's defined as Yes, the menu will pop up as a new window. |
### 5. API Authority
Before APIs authority are configured, we need to differentiate two scenarios first, whether the APIs should be applicable for all users without any specific permissions or APIs should be only applicable for certain permissions.
* If it is API applicable to all, like fetching code table definition data or personal center, it should be configured as a common whitelist API.
* If it is API relevant to the business transaction, like policy issuance or payment collection, it should be configured in the specific permission.
Also, except most of the scenarios that API authority needs to be checked, there are some other specific scenarios which API authority can be bypassed:
* A user is a super administrator.
- To facilitate environment operation, by current system logic, we will not check API authority for super administrator.
* Register API into container.
- The API authority check then will be imposed at container side. This is the suggested approach if the API is for integration with third party application.
* Exclude special environment.
- Now portal/MC environment is specifically excluded for check as it's meant for configuration only. For private cloud, there might be more environment to exclude.
* Exclude special tenant.
- This is just for few special case and up to platform team to decide. If you feel API authority is a burden instead of plus for your tenant, you can contact insureMO team for support.
| Field Name | Description |
| ---------------- | ------------------------------------------------------------ |
| Order | System auto generate. |
| Request Rest URL | The API to be authorized. The URL format is always the "`/{appname}/{path}`". No server domain URL is needed. |
| Match Type | If there is no request parameter for the API, it should be **String Matching**, or otherwise it should be **Wildcard Matching**. |
| Key API | Deprecate, the flag to label the API is imported. |
| Write API | Deprecate, the flag to label the API is to write data to the system. Please select **Yes** if the API execute update/delete/insert, or select **No**. |
| Maintained By | System auto generate. |
Take an API for example "https://tenantcode***.insuremo.com/api/platform/dd/public/code/mgmt/v1/dataTable/byName?dataTableName=XXX". If users want to configure the "Request Rest URL", there are two parts that users don't need to configure:
1. URL/Server Domain: https://tenantcode***.insuremo.com/api/platform
2. Request Parameter: ?dataTableName=XXX
So users only need to configure "`/dd/public/code/mgmt/v1/dataTable/byName`" in the API authority.
#### Match Type
**String Matching** is the exact matching. In order to get authority, API URL must be exactly the same as what's configured.
**Wildcard Matching** is the fuzzing matching. Possible scenarios can be:
- Header parameter. For example, a URL - `/urp/updateUser/abc`, since abc is dynamically changed, users can configure as `/urp/updateUser/` then use wildcard matching.
- One configuration for all. For example, if it's a URP management screen and user don't want to update API authority every time, user can configure as `/urp/**`, then use wildcard matching.
##### Example A: String Matching
* UserName: [`xxxx.xxx`]
* PermissionCode: [ED50]
* API: [`/attachment-core/attachFileLog/v1/getAtta`]
**Permission Management > Select Subsystem > Search > Add > Save**
##### Example B: Wildcard Matching
* UserName: [`xxxx.xxx`]
* PermissionCode: [ED50]
* API: [`/attachment-core/attachAuth/v1/666`]
**Permission Management > Select Subsystem > Search > Add > Save**
#### Common API Allowlist
##### Tenant Level
During role creation, there's a specific role category called "**Common Permissions**". Once this category is selected, all API permissions belonging to the mentioned role will be automatically applicable to all users.
##### Platform Level
By default, there's a list of APIs that don't need to conduct an API authority check. All APIs are maintained in the menu **"URP" -> "Common API Allowlist"** and the tenant can only view but not make any modification.
### 6. Data Permission
Data permission (row-level data authority) is the third permission dimension besides menu permission and API authority. Menu permission controls which UI a user can see; API authority controls which backend APIs a user can call; data permission controls **on which data rows** the user can operate. Typical scenarios:
* Users of a TPA can only operate the claims handled by their own TPA.
* A coverage team can operate the claims of the products it is responsible for.
* An audit role can read the claims of all TPAs but cannot modify them.
A data permission is still a normal permission code in URP and reuses the whole RBAC chain: define the permission code in Permission Management, mount the code to a role, then grant the role to users. The differences are:
1. The **Menu Type** of the permission is **Data**.
2. Besides the common permission fields, it carries a structured data scope definition:
* **Domain** — the business object the scope talks about, for example `Urp`.
* **Criteria** — a condition tree describing "which rows" by field / operator / value, combined by AND / OR groups. The root of the tree also carries an **Access** array (for example READ / WRITE) telling which operations the criteria applies to.
* **Explicit Items** — row-level overrides on top of the criteria: an explicit ALLOW or DENY list of concrete keys, for example deny one specific claim number.
note
URP only defines, stores and serves the data permission definitions. The final judgment — scope union of multiple permissions, DENY takes precedence, fail-closed when no definition matches and the derivation of "unrestricted" — is implemented by the consumer module (for example Claim). URP does not interpret the business meaning of the field values.
At runtime, the consumer module calls the URP API `GET /public/dataPermission/v1/loadUserDataPermissions` with userId + permissionCode + domain and receives the structured definitions of the data permissions the user holds. The consumer module is suggested to cache the result locally (for example 7 days TTI) and refresh it on role change events.
#### Ownership: Who Configures What
Attribute-based data permission on insureMO involves three parties:
| Party | Responsibility |
| -------------------------------- | ------------------------------------------------------------ |
| Customer | Defines the business, operations, support and security roles, the data scopes and the approved access rules. |
| insureMO URP | Maintains domains, criteria and explicit exceptions. Assigns the policies to roles and exposes the policy retrieval APIs. |
| Business APIs (consumer modules) | Evaluate the policies against trusted business attributes. Enforce record access and field restrictions. |
In other words: the customer decides **who may operate on which data**, URP stores and serves that decision as structured permission definitions, and each business API turns the definitions into an actual permit / deny decision at runtime.
A configured rule in business form, for example:
```
WRITE: BranchCode IN {10001, 10002} AND ChannelCode IN {C10001, C1002}
```
is exactly one data permission in URP: the root **Access** is `WRITE`, the group combines by AND, and `BranchCode IN {...}` and `ChannelCode IN {...}` are two conditions of the criteria tree.
#### Prerequisites: Domain and Field Configuration
Before creating data permissions in the UI, the domain metadata needs to be prepared on the platform configuration side first. The field list of a data permission is not maintained in URP — it comes from the data dictionary (DD):
1. In the data dictionary, under model **DataPermissionDomain**, create one object per domain (for example `Urp`). The object name is the domain code shown in the UI dropdown, and the fields of the object are the selectable business fields, for example `BranchCode`, `ThirdPartyCode`.
2. The parent object **DataPermissionBaseDomain** predefines the three reserved fields **PermissionAccess**, **PermissionLogic** and **PermissionOperator**. They are backed by code tables of the same name and drive the Access / AND-OR / operator options in the UI.
Each business field supports the following attributes, maintained in the data dictionary:
| Attribute | Description |
| --------------- | ------------------------------------------------------------ |
| Label | The display name of the field in the dropdown. |
| DataType | INTEGER / DOUBLE / STRING / DATE. It decides the value shape validation and which operators are available. |
| Max Length | The maximum length of a single value. Longer values are rejected on save. |
| Code Table Name | If maintained, the field becomes a dropdown field and every value must exactly match a code of this code table. |
The code tables behind the reserved fields:
| Code Table | Values (example) | Usage |
| ------------------ | ---------------------------------------------------- | ------------------------------------------------------------ |
| PermissionAccess | READ / WRITE / ALLOW / DENY | The Access options of the criteria root and of the explicit items. |
| PermissionLogic | AND / OR | The combination logic inside each group. |
| PermissionOperator | EQ / NE / IN / NOT_IN / LIKE / IS_NULL / IS_NOT_NULL | The operator options, filtered by the field's DataType through the condition column of the code table. |
caution
* Values of a code-table-bound field are validated as **exact code matches** on save. LIKE wildcards (for example `%SH%`) must be placed on fields without a code table binding.
* Fields with the `_CodeDesc` suffix are description derivatives generated by the data dictionary and are not selectable in the UI.
#### Create a Data Permission
**Permission Management > Select Subsystem > click the parent node > Add Node > Menu Type = Data > input permission info and data scope > Save**
Besides the common fields (see section 4 Create New Permission), a data permission provides the following dedicated fields:
| Field Name | Description |
| -------------- | ------------------------------------------------------------ |
| Menu Type | Select **Data**. The row is then identified as a data permission: no UI menu, no API list, and the Criteria / Explicit Items editors show up. |
| Domain | Required. The business object the scope talks about, from the DD configuration above. Changing the domain resets Criteria and Explicit Items, because the field metadata is domain-bound. |
| Criteria | The condition tree. See below. |
| Explicit Items | Row-level ALLOW / DENY overrides. See below. |
##### Criteria
The criteria area edits a condition tree. A **group** is a set of conditions combined by AND / OR. A group can contain conditions (leaves) and sub-groups, up to 3 levels of nesting recommended.
Each group renders a one-line header:
| Element | Description |
| ------------------ | ------------------------------------------------------------ |
| ▾ / ▸ | Collapse / expand the group. A collapsed group shows a one-line summary of its first conditions. |
| AND / OR | The combination logic of the conditions inside the group. |
| n Conditions | How many conditions (leaves and sub-groups) the group contains. |
| Access (root only) | Multi-select of the operations (for example READ / WRITE) the criteria applies to. Values come from the PermissionAccess code table. |
| Add Condition | Append a condition row into the group. |
| Add Group | Append a sub-group into the group. |
| Delete | Remove the group (not shown on the root group). |
Each condition row is a single line of four controls:
| Control | Description |
| -------- | ------------------------------------------------------------ |
| Field | The business field the condition talks about, from the domain's DD fields. |
| Operator | Depends on the field's DataType, from the PermissionOperator code table. Scalar operators (EQ / NE / LIKE ...) take exactly one value; IN / NOT_IN take one or more; IS NULL / IS NOT NULL take no value. |
| Value | The value editor depends on the field: a code-table-bound field renders a filterable multi-select (picking more than one value automatically upgrades the operator to IN); a numeric field renders a number input; otherwise a text input. For IN / NOT_IN on free fields, values can be typed in batch, separated by comma or new line. |
| Delete | Remove the condition. |
Nesting levels are told apart by the depth of the left rail color — the deeper, the darker. When the nesting reaches 3 levels a warning is shown; deeper trees are still accepted by the backend but are not recommended for readability.
##### Explicit Items
Explicit items describe row-level overrides outside the criteria tree, for example "deny this specific claim" or "allow this specific branch even though the criteria does not cover it". Each item is a single row:
| Control | Description |
| ------- | ------------------------------------------------------------ |
| Field | The business field the item keys on, from the domain's DD fields. |
| Access | ALLOW or DENY. |
| Values | One or more keys. Code-table-bound fields render a multi-select; free fields accept batch input. |
| Delete | Remove the item. |
The same field may appear in both an ALLOW item and a DENY item. How the overrides combine with the criteria (typically DENY first) is decided by the consumer module.
##### Validation on Save
| Error Code | Scenario |
| ---------- | ------------------------------------------------------------ |
| B0091 | Domain is empty, or the row is not maintained as a data permission (for example Functioned = Yes). |
| B0094 | Invalid criteria: unknown field or operator, wrong value shape, a scalar operator with multiple values, a value exceeding Max Length, or a value not existing in the bound code table. The error message carries the detail of the rejected node. |
| B0095 | Invalid explicit items: the same family of problems on the item list. |
| B0013 | The permission code is still mounted by roles when deleting. Unmount it from the roles first. |
#### Grant and Consume
Granting a data permission to users works the same as any other permission:
**Role Management > Add/Edit Role > select the data permission code > Save**, then grant the role to users (see sections 2 and 3).
One user can hold multiple data permissions of the same domain; the consumer module merges them (scope union, DENY first). Whether a user holding no data permission of a code means "no data" or "unrestricted" is derived by the consumer module — if the fail-closed behavior matters to the business, define an explicit restricted role instead of relying on the absence of definitions.
#### Enforcement in the Business API
Taking WRITE access as an example, a business API enforces data permission in five steps:
1. **API request** — the user submits a business operation, for example updating policy P-1001 as user U-101.
2. **Resolve context** — the API resolves which domain (for example `Policy`) and which operation (for example `WRITE`) the request belongs to.
3. **Load URP policies** — the API calls `GET /public/dataPermission/v1/loadUserDataPermissions` for the user, the permission code and the domain, and receives the user's data permission definitions.
4. **Evaluate in the API** — the API matches the operation and the trusted business attributes of the target record (for example BranchCode = 10001, ChannelCode = C10001) against the criteria, then applies the explicit exceptions.
5. **Enforce the decision** — permit means executing within the granted scope; deny means rejecting the operation.
The attributes used in the evaluation come from the **trusted business data** of the record itself — the branch that serves the policy, the channel it was sold through, the TPA handling the claim — not from the request, so a requester cannot widen the scope by claiming attributes.
The consumer module applies three rules when evaluating:
* **DENY overrides ALLOW.** An explicit deny always wins, no matter how many allows match.
* **No applicable grant means no access.** When no definition grants the operation, the operation is rejected (fail-closed).
* **Lists and exports use the same authorized scope.** Query, list and export endpoints filter rows with the same evaluation, so a denied row never leaks through a listing screen or a downloaded file.
Example evaluation against the WRITE scope `BranchCode IN {10001, 10002} AND ChannelCode IN {C10001, C1002}`:
| Target Record | BranchCode | ChannelCode | Additional Rule | Result |
| ----------------- | ---------- | ----------- | ----------------------------------------------------- | ----------- |
| PolicyNo P-1001 | 10001 | C10001 | No exception | ALLOW WRITE |
| PolicyNo P-1002 | 10001 | C90001 | Channel outside scope | DENY WRITE |
| PolicyNo P-1003 | 10002 | C1002 | Explicit item denies PolicyNo P-1003 | DENY WRITE |
| ProposalNo Q-2001 | 10002 | C1002 | The user holds only a READ grant for this record type | DENY WRITE |
### 7. Some Specific Permission Scenarios
#### Entrance URL and DOC URL
"Entrance URL" field is super important to control which UI to navigate for the system menu.
Let's assume our tenant code is abc and URL is https://tenantcode***.insuremo.com/:
##### UI Within One UI Project
Suppose there's a 1st level and 2nd level menu. For the 1st menu, it can be configured as the 1st page URL while for the second, the system will automatically append the 1st URL and thus there is no need to configure again. For example:
1st Menu: `/ui/nb/`
The system will take https://tenantcode***.insuremo.com/ui/nb/ to navigate. The 'nb' here must be coded in the UI project package.json file and with attribute defined as 'name'. For example, if "name" is "`abc-nb-ui`", the system will remove tenant code and UI at both sides and take `/ui/nb` to navigate.
2nd Menu: `/workList`
The system will automatically append `/ui/nb/` together and take https://tenantcode***.insuremo.com/ui/nb/#/worklist to navigate. The 'worklist' must be coded in the 'Route Path' inside UI project and there will be a "#" to separate two pieces of URL.
##### UI NOT Within one UI Project - `$originalUrlPlaceholder$`
Suppose there's a 1st level and 2nd level menu, while the 2nd menu is not in the same UI project as 1st Menu and in a separate project. For example:
1st Menu: `/ui/nb/`
The system will take https://tenantcode***.insuremo.com/ui/nb/ to navigate.
2nd Menu: `$originalUrlPlaceholder$/ui/commission/`
By having `$originalUrlPlaceholder$`, the system will notice there's a need to have a new and independent URL, and the system will actually take https://tenantcode***.insuremo.com/ui/commission/ to navigate.
##### Third Party System - `$tenant.targetURL$`
In some cases, there's a need for the system to navigate to other systems via menu. Generally, all systems will have different environments to separate activities like DEV/TEST/PROD and third-party systems may also have different URLs corresponding to our system for navigation. Thus, a special place holder is required to cater for such a case.
The following is an example of such a case. You can see that there's a special place holder `$tenant.targetURL$` put at front.
`$tenant.targetURL$/login.do?lsForwordPath=/arap/cash/ctrl/banktransfer/manual/ManualMatchingAction.do?current_module_id=1000000257$needToken$`
Once it's configured, the system will NOT bring https://tenantcode***.insuremo.com/ and instead will take abc.targetURL in config-parameter to navigate. Here abc.targetURL will definitely not be https://tenantcode***.insuremo.com/ but can be whatever a third-party value like https://tenantcode***.insuremo.com/. Users need to put a request to insureMO platform team to set up the config-parameter value for each environment.
##### Exchange Token - $needToken$
If there's a need to achieve SSO between a third party system and our system, we would suggest using exchange token for authentication.
See the example below. When there's `$needToken$` appended at the end, system will append exchange token at the end and bring it to third party system.
`$tenant.targetURL$/login.do?lsForwordPath=/arap/cash/ctrl/banktransfer/manual/ManualMatchingAction.do?current_module_id=1000000257$needToken$`
##### DOC URL
Our DOC URL navigation rule will share the same configuration pattern as entrance URL.
If users are using default insureMO document guide framework, then you can directly specify format like `/common-doc/bcp/easy_bcp` for navigation.
#### Hide Specific Menu or Permission Code
In some cases, the platform provides some permission codes that you do not want to expose to your administrators to avoid the possibility that your administrators grant them incorrectly, which may lead to business errors.
The platform now allows hiding these permission codes. The list of excluded permission codes can be configured through the global parameter table **SystemConfigTable**, and both platform permission codes and tenant permission codes can be configured.
After configuration, these permission codes will not be displayed in the permission tree for Permission Management and Role Management. If the code contains child nodes, they will also be hidden.
For example:
If you want to hide "Endorsement Management" and "Micro Insurance Management" in the **Policy Admin** subsystem,
* The "Endorsement Management" permission code is "PA-POLICY-ENDO", and the "Micro Insurance Management" permission code is "PA-POLICY-PADD".
* You can go to **Public Setting > Global Parameter > SystemConfigTable > Key**: excludePermissionCodes > Value: PA-POLICY-ENDO, PA-POLICY-PADD > Note that multiple data here is separated by commas and the system will take both the platform owned and the tenant owned parameter to exclude.
* The change will take effect automatically after 30 minutes. If it needs to take effect immediately, manually clear URP cache.
* Check if these two types of data are hidden in Permission Management and Role Management.
**Global Parameter SystemConfigTable**:
Clear the URP cache.
Comparison of the value before and after Permission Code Modification in Permission Management and Role Management.
#### Reading and Writing Separate Permission on UI
If you have any specific authority control on specific UI element, you can configure the permission code mapped to page element and use the API to control its display.
There's a default attribute provided together with Rainbow UI framework to facilitate the permission code usage.
1. Add the writing permission for page element. For more details, see [create new permission](https://docs.insuremo.com/iam/urp#4-create-new-permission).
The image below shows the writing permission for data table, just for reference.
note
- Page element must be configured under the menu tree node.
- API authority must be adjusted accordingly (menu must normally have only read authority while write action can have more authorities).
- No requirement to configure "Element Sign" as it meant to be for old version.
2. Add the configuration item below in **/src/config/config.js**.
`DEFINE_PERMISSION_URL: 'urp/public/authorities/v1/loadUnauthorizedPageElementPermissionCode',`
3. Add the element properties "**permissionCode**", and set the value to be the permission code added.
Example code is as below:
```js
```
Then on UI, if users only have Data Table menu permission, the **Add** button will not show up on UI. If users need to add authority, please grant the permission to user-related roles.
#### Special Treatment If Tenant to Re-write Platform UI
In some cases, if the business side finds any of default platform UI behavior doesn't support business requirements, there's still the possibility for business side to take over platform UI and customize. Basically, it will involve the following steps to be performed:
1. Contact SiteOps
A formal request should be put forward to SiteOps to ask for source code for specific UI. Then SiteOps will set up the code base as well as CICD for the tenant.
2. Change on package.json
To customize the platform sales channel UI, the key file is package.json in the UI project.
There's a name attribute. By default, after setup, platform sales channel UI will display like "`tenantCode-saleschannel-ui`", which will then translate into URL like "`tenantURL/saleschannel`". If this is not changed, the system will be confused on whether to route to platform sales channel UI or tenant sales channel UI.
Thus, project team members need to modify it into another name, say "`tenantCode-sc-ui`" to avoid such a conflict.
3. Duplicate sales channel menu in the environment
After you deploy new sales channels, there will be two sales channel UI in the platform and it might cause confusion for testers and later for one end user which menu authority to grant.
It's suggested to follow guidance in the "Hide Specific Menu or Permission Code" topic to go to “global parameter” to exclude platform permission code to hide platform menu.
### 8. Synchronize User Default Information
Sometimes, because of the training or enablement requirement, all users in one tenant might need to have some default authority upon login.
This can be achieved by our global parameter configuration: **Global Configuration > Global Parameter > SystemConfigTable**.
- Parameter Value
| Seq | Function | Parameter Name | Value (Example) |
| ---- | ------------------------------------------------------------ | ----------------- | ------------------------------------------------------------ |
| 1 | Assign default role permissions to users who log in for the first time. | defaultRoleNames. | RoleA,RoleB,RoleC. |
| 2 | Synchronize users for the first time and assign default values to users. | defaultUserInfo. | DefaultLanguage:en_US,OrgCode:001,OrgId:-10,Position:1,RealName:GIMO,Status:Y,UserType:1. |
Cache effectiveness: The system will automatically clear the cache in 30 minutes. If users want to take effect immediately, they need to manually clear the cache in **URP > URP**.
- Default User Attribute Description (Value):
| Seq | Attribute Name | Key | Default Value | Reference Information |
| ---- | ---------------------- | ---------------- | --------------------- | ------------------------------------------------------------ |
| 1 | User default Language. | DefaultLanguage. | en_US. | en_US : English.
ja_JP : Japanese. |
| 2 | User Branch Code. | OrgCode. | -1 | |
| 3 | User Branch Id. | OrgId. | -1 | |
| 4 | User Position. | Position. | 1 | 1 : Ordinary user.
60 : Authorized administrator.
99 : Super administrator. |
| 5 | User Real Name. | RealName. | RealName or UserName. | |
| 6 | User Status. | Status. | Y | Y : Active user.
N : Invalid user. |
| 7 | User Type. | UserType. | 1 | 1 : Employees.
2 : Individual Customers.
3 : Corporate Customers.
6 : Institutional Staff.
13 : Personal agent.
99 : Super user. |
### 9. Export and Check in
#### Role Management
note
If `T_PUB_USER_AUZ_ROLE.csv` (dirty data) is included in the folder, please delete it manually in git.
#### Permission Management
#### SystemConfigTable
If you use the Hide part permission code function, you need to export **SystemConfigTable**.
If you use the Hide part permission code function, you need to check in **SystemConfigTable**.
### 10. Upload User and Grant Role
#### Download Excel Template
**User Management > Select User Record > Download**
#### Assembly Data
**Field Description**
* USER_NAME: user name
* REAL_NAME: real name
* ORG_NAME: organization name
* ORG_CODE: organization code
* DEFAULT_LANG: default language
* USER_TYPE: user type
* MOBILE: mobile
* EMAIL: email
* STATUS: user status
* POSITION: user position
* PARTY_CODE: party code
#### Upload File
**User Management > Upload**
note
* Uploading in excel format supports two cases:
- Uploading users only
- Uploading users and granting roles
* If the user does not exist, it will be created. Otherwise, it will be updated.
* For the granted roles of users, only new roles are added, and the original one are not deleted.
## URP Audit
Once any URP-related data is updated, the system will record it as audit log.
To view audit log of URP, please open the container by click **Public Setting > insureMO Container**.
More operation on container, see [Container Audit](https://docs.insuremo.com/non_insurance_service/docs/md/insureMO_Audit_Service#4-data-retrieval).
## URP API Development
To adopt URP API, users can have two ways:
1. For Vela SDK, users can import below into your code:
```
com.ebao.vela
vela-urpmgmt
```
2. For insureMO SDK, users can visit [Welcome to InsureMo SDK for Java](https://docs.insuremo.com/sdk_for_java/sdk/insuremo_sdk_java_welcome).
Basically, there are two kinds of APIs:
1. Get current user information or authority from user token
* /urp/public/authorities/v1/current/roles
* /urp/public/authorities/v1/current/hasrole
* /urp/public/authorities/v1/current/permissions
* /urp/public/authorities/v1/current/permissioncodes
* /urp/public/authorities/v1/current/haspermission
These APIs will not have security issues because they can only get information from the current user.
2. Get authority or user information across user
Please use such API carefully. Usually, if there's branch structure involved, users need to develop and grant authority only to new BFF API which wraps URP API.
## Common Scenarios and Q&A
### How to make the initial DB?
First, we need to differentiate two scenarios:
* System configuration data
* Initial DB
The key difference between them is that system data will always exist, while the initial DB will only be refreshed once after go-live.
For example, when we add users to the initial DB, it will be deployed during system launch. However, for subsequent deployments, any user changes will not be deployed but updated directly in production. Thus, users represent a typical type of initial data.
Permission, on the other hand, is a typical system configuration data type. It works like a program code which needs to be maintained in MC and deployed together with the system program code. It is not one-time production update, nor something that needs to be maintained continuously after go-live.
Role/Branch are tricky part. In some cases, it can be considered as a production update while in some as an MC update. So we support both scenarios:
* If it is treated as configuration data preparation like permission or role, it is simple and follows our common data import/export process. Configuring file needs to be exported from the MC environment and checked in the source code and then it can be deployed to all environments being used.
* If the data is treated as initial data preparation, it is more complex and might require more efforts to extract the DB scripts separately and execute during production launch. If the volume is not large, we suggest creating them manually one by one after the production launch. And if you are supporting a large case with a large volume, you can contact the insureMO team to see how it works for it.
At either option, please make sure not check in part of the data while configuring part of data in runtime environment which might cause data distortion.
### API authority is required along with *Ordinary User*. This user ID will be used by the front-end application to call different backend for frontend API. How is it configured?
Take the snapshot below as an example, where only the API is provided, without UI pages. Just add a permission menu for it and the relevant APIs under it.
Then create a role with the added permission, or add the permission to an existing role.
Finally, create a user with the relevant role or add an existing user to the relevant role.
### API authority is not required along with *Ordinary Users*. These users just need to have an Easy PA access to view policies or pass endorsements. How is it configured?
* If the Easy PA UI that needs to be authorized to a user is a new UI page.
1. Add a menu permission for it. For details, see [create new permission](https://docs.insuremo.com/iam/urp#4-create-new-permission).
2. Add the relevant APIs (called on the UI pages) under it.
For details, see [add api auth under permission](https://docs.insuremo.com/iam/urp#5-api-authority).
3. Create a role with the permission or add the permission to an existing role.
For details, see [create role](https://docs.insuremo.com/iam/urp#2-create-new-role).
4. Grant the user with the role added/updated with the permission.
For details, see [grant role](https://docs.insuremo.com/iam/urp#3-grant-role-to-existing-user).
* If the page menu permission exists already, it just missed some APIs or had some newly added APIs called by the UI. When the UI loads, some errors will pop up:
```
{"timestamp":"2021-10-26T16:56:06",
"timestampServer":"2021-10-26T08:56:06.274",
"traceId":"4bxxxxxxxxxdad",
"traceIdContainer":null,
"code":"EBAO-PLATFORM-GW-B0000",
"message":"Current user can't have the api authority. userName[internal], permissionCode[PMCommon], api[/product/prd/v1/filterProductList]"}
```
It means that the API `/product/prd/v1/filterProductList` is not mapped to the permission **PMCommon**.
Then refer to the [link](https://docs.insuremo.com/iam/urp#common-api-allowlist) to add the API under the permission.
### How can I achieve SSO with my existing system?
Our platform supports single sign-on methods in most industries, such as integration with third-party authentication systems (e.g. Okta) or in-house HR systems.
As SSO depends heavily on the tenant's own system behavior and settings, if you have such a requirement, please contact the insureMO Operation team for further information and discussion.
If different systems are involved, we also support user synchronization integration to have consistent user settings across different systems.
### I have found ADMIN user being a super user has too much authority. How can I treat it for my production?
To avoid security issues, for production setup, our recommendation is:
1. Set up environment, create an ADMIN user, and perform environment sanity testing.
2. Create business admin user held by client by tagging position as "Authorized Administrator".
3. Disable ADMIN.
4. Create all business users for business operation-related menu by tagging position as “Ordinary User” by business admin user held by the client.
5. Create system maintenance users for troubleshooting-related menu by tagging position as "Ordinary User" by business admin user held by the client.
Then the users should be of different categories like:
- Authorized administrator – URP menu only
- Business Operation User – PA operation
- System Maintenance User – Product, Rating, Rule, DD, Batch etc in read-only mode
- Prohibited – Super ADMIN & Product, Rating, Rule, DD, Batch etc in editable mode
### If I want to extend new field in user management UI, how can I achieve it?
It's very common that different client want to display different field in the user management UI. Some client might only display branch while some client might want to display branch with department together. It's impossible to have one set of user management UI catered for all business cases.
So if user find that our platform default UI cannot meet your client requirement, you can contact insureMO support team to give you a copy of user management UI source code to customize. (Detailed guideance in [Tenant to Re-write Platform UI](https://docs.insuremo.com/iam/urp#special-treatment-if-tenant-to-re-write-platform-ui))
For the backend, if you find current fields are not enough to use, you can pass dynamic fields to achieve save and load feature.
```
{
"@pk": 10000017976847,
"AllowOperation": true,
"AllowResetPassword": false,
"AuthenticationFlag": "Y",
"AutoCreate": false,
"DefaultLanguage": "en_US",
"Email": "abc@insuremo.com",
"InvalidLogin": 0,
"IsCallGateway": true,
"IsDomainAccount": false,
"NeedChangePassword": false,
"OrgCode": "ABC",
"OrgId": 10000017976846,
"PasswordChangeDate": "2025-06-27T04:15:14",
"Position": 99,
"RealName": "abc",
"Status": "Y",
"Sync2ContainerFlag": false,
"UserCheckFlag": false,
"UserId": 10000017976847,
"UserName": "abc",
"UserType": 1,
"TempData": {
"Mask-Email": "f1hjKCd+8SOoiDwxh4D3tblrDj7vmP8zmiaUCX6x+rU=",
"MaskAfter-Email": "abc@insuremo.com"
},
"DynamicFields":"{\"Fieldx\":\"001001\"}"
}
```
### User Separation Mode and Non Separation Mode
1. **Configuration center configuration parameters**
*tenant. urp. syncUser2Container. include*, where the tenant name is configured for user non separation mode
2. **User not separated mode**
User management is mainly based on container, with user synchronization mode:
- Pull mode, authenticated users request GI services. If the user does not exist in GI, the user is actively synchronized to GI URP from Container. For domain accounts, the portal environment defaults to the super administrator role, while other environments default to the normal user role.
- Push mode, when GI URP creates or updates user information, GI URP actively synchronizes user information to the Container .
3. **User Separation Mode**
User management is separate ,with user synchronization mode:
- Pull mode, authenticated users request GI services. If the user does not exist in GI, the user is actively synchronized to GI URP from Container. The portal environment is assigned the super administrator role by default, while other environments are assigned the normal user role by default
4. **Manual synchronization function**
Administrators can choose to manually synchronize GI URP users to the Container in the User Management menu.
5. **Cas Login Mode**
When CAS login, the user separation mode have a parameter 'user_source_id=platform',while the user non separation mode does not have this parameter or 'user_source_id=mo'
### User API Permission Management Mechanism
#### Permission Acquisition Methods
User API permissions can be obtained through the following methods:
- Super Admin - Default has all permissions
- Common Api AllowList
- Common Role permissions assignment
- Standard Role permissions assignment
#### Permission Verification Scenarios
##### UI Request Scenario
UI requests will carry the corresponding permissionCode in the request header (x-mo-module-permission-code). In this scenario, permission validation works as follows:
1. Super Admin has permissions by default
2. If the API is configured in Common API AllowList, the user is considered to have access to this API
3. If any Common Role contains this API under any permissionCode, the user has access to this API
4. If any of the user's Standard Roles has this permissionCode, and that permissionCode includes this API, then the user has access to this API
##### Non-UI End Requests
For non-UI end requests or any requests that do not specify permissionCode in the RequestHeader, permissions will be verified as follows:
1. Super Admin has permissions by default
2. If the API is configured in Common API AllowList, the user is considered to have access to this API
3. If any Common Role contains this API under any permissionCode, the user has access to this API
4. If any permissionCode under any of the user's Standard Roles contains this API, then the user has access to this API
### Password Encryption Method
**Encryption Algorithm Characteristics**
- *One-Way Hash (SHA-512) Encryption*: This is an irreversible hash encryption method
- *Salted Hash*: Uses a fixed salt value "UNICORN" to enhance security
**Encryption Parameter Composition**
1. *Username as Dynamic Salt*: UserName- Uses username as a variable factor
2. *Fixed Salt Value*: "UNICORN" - System preset static salt value
3. *Original Password*: Plaintext password to be encrypted
**Security Features**
- *Protection Against Rainbow Table Attacks*: By combining username and fixed salt values, the difficulty of cracking is increased
- *Irreversibility*: Due to being a one-way hash, original password cannot be reverse-engineered from the hash value
- *Consistent Verification*: Same input always produces the same hash value, which can be used for password verification
### Extended DB Operation
Once a user is created, we do not allow deletion of that user in principle. However, it is possible that an incorrect operation has been performed and the client is adamant that it is deleted to avoid audit issues.
If that is the case, we can also apply some DB scripts to achieve it, especially for private clouds. For public clouds, please contact the insureMO team first and do not perform it by yourself.
note
* Please run the following scripts in the corresponding pub database.
* If you delete the user and role at the same time, please delete the role first, and then the user.
#### Delete User
Example: Delete User A and User B
```sql
DELETE FROM T_PUB_USER_AUZ_ROLE
WHERE user_id IN
(
SELECT user_id FROM t_pub_user
WHERE user_name IN (
'userA',
'userB'
)
)
;
Delete FROM t_pub_user_role
WHERE USER_ID IN
(
SELECT user_id FROM t_pub_user
WHERE user_name IN (
'userA',
'userB'
)
);
Delete FROM t_pub_user_password
WHERE USER_ID IN
(
SELECT user_id FROM t_pub_user
WHERE user_name IN (
'userA',
'userB'
)
);
Delete FROM t_pub_user_preference
WHERE USER_ID IN
(
SELECT user_id FROM t_pub_user
WHERE user_name IN (
'userA',
'userB'
)
);
DELETE FROM t_pub_user
WHERE user_name IN (
'userA',
'userB'
);
```
#### Delete Role
Example: Delete URPRoleForTest and TestForUrp.
```sql
DELETE FROM t_pub_user_role
WHERE role_id IN (
SELECT role_id FROM T_PUB_ROLE WHERE NAME IN ('URPRoleForTest', 'TestForUrp')
);
DELETE FROM t_pub_user_role WHERE role_temp IN (
SELECT role_id FROM T_PUB_ROLE WHERE NAME IN ('URPRoleForTest', 'TestForUrp')
);
DELETE FROM T_PUB_ROLE_PERMISSION WHERE role_id in (
SELECT role_id FROM T_PUB_ROLE WHERE NAME IN (
'URPRoleForTest',
'TestForUrp'
)
);
Delete FROM t_pub_user_auz_role WHERE role_id IN (
SELECT role_id FROM T_PUB_ROLE WHERE NAME IN (
'URPRoleForTest',
'TestForUrp'
)
);
DELETE FROM T_PUB_ROLE WHERE NAME IN (
'URPRoleForTest',
'TestForUrp'
);
```
## FAQ
#### General Concepts and Usage
**Q: What is the URP module and how does it work?**
A: URP stands for User, Role, and Permission, controlling system access and permissions. It allows administrators to configure permissions via UI or APIs, covering menu, data, and API permissions. Roles can be managed as groups or templates, with roles as groups being the default.
**Q: What is the Branch module used for?**
A: The Branch module manages organizational hierarchies and relationships, enabling proper authority settings for different entities within a client’s system.
#### User and Role Management
**Q: Can I hide specific permission codes?**
A: Yes, you can hide permission codes by configuring the **excludePermissionCodes** in **SystemConfigTable**. Changes take effect after 30 minutes or by clearing URP cache.
**Q: How do I assign roles to users?**
A: Go to **User Management > Search User > Edit > Add Role**. Roles are bundles of permissions, and assigning a role grants all permissions under that role to the user.
**Q: What are the different types of roles?**
A: There are standard roles, common roles (always applied to all users), and default roles (automatically added to users on first login). Roles can be categorized as platform/baseline or tenant-specific.
#### Permission Configuration
**Q: How do I create a new permission?**
A: Navigate to **Permission Management > Select Subsystem > Search > Add Node> Input Details > Save**. Define the permission type, name, code, and other attributes.
**Q: How do I configure API permissions?**
A: Determine if the API should be accessible to all users or specific roles. Configure common whitelist APIs for universal access or specific permission APIs for restricted access. Use string or wildcard matching based on API requirements.
**Q: Can I bypass API authority checks?**
A: Yes, API authority checks can be bypassed for super administrators, registered APIs in the container, or specific environments and tenants.
#### Advanced Scenarios
**Q: How do I handle complex business permission structures?**
A: Implement custom authorities within the business module and attach them to URP permissions. This allows for multi-layered permission structures tailored to specific business needs.
**Q: How do I integrate with third-party systems?**
A: Use placeholders like `$tenant.targetURL$` and `$needToken$` in the DOC URL and Entrance URL fields to navigate to third-party systems and enable SSO.
**Q: How do I manage user and role data across environments?**
A: Ensure consistency by either defining roles and permissions in the MC portal for deployment or managing them individually in each runtime environment. Avoid mixing configurations to prevent data distortion.
#### Development and Integration
**Q: How do I integrate URP APIs into my application?**
A: Use Vela SDK or insureMO SDK to integrate URP APIs. Refer to the documentation for specific dependency imports and API usage guidelines.
**Q: Can I customize the user management UI?**
A: Yes, contact the insureMO support team to obtain the source code for customization. Pass dynamic fields to achieve extended functionality.
**Q: How do I handle branch configuration data?**
A: Branches can be configured in the MC portal for deployment or individually in each runtime environment. Use the provided API for branch data retrieval and integration into front-end applications.
#### Troubleshooting and Maintenance
**Q: Why am I getting an 'API permission check failed' error?**
A: Ensure the correct PermissionCode is bound to the frontend menu through the RequestHeader *x-mo-module-permission-code*. Verify if the user has the specified permissionCode and if there are API permissions under it.
**Q: How do I remove a branch?**
A: Call the branch deletion API with the appropriate party ID. Capture the party ID using Chrome Developer Tools.