Integrate with your system via USIP

Overview

In fact, Univer’s backend service does not integrate an account system (and shouldn’t integrate). By default, Univer’s backend service does not authenticate visitors, meaning that all users can access all resources.

If you need to authenticate users before they can access, you must implement your own account system. You can configure Univer server to interact with your system, and Univer server will call your system to complete authentication when it needs.

In order to achieve this type of interaction, Univer has designed the Univer Server Integration Protocol (USIP). USIP is essentially a kind of SPI (Service Provider Interface), which is defined by Univer and then implemented by your system. Univer has defined some USIP interfaces according to the potential needs of customers. You can choose to implement some interfaces to change the process of Univer handling certain user requests, such as user authentication and permission verification. If the existing USIP interfaces cannot meet your needs, you can give us suggestions.

USIP interface description

Currently, Univer defines two groups of USIP interfaces for different scenarios.

1. Account group

• User authentication
• User information acquisition

2. Permission group

• permission role: Obtain the user’s permission role on a document
• list collaborators: Get the list of collaborators of a document

Below are detailed descriptions of each interface

User authentication

Call scene

Every interact with the Univer backend should be authenticated, so the authentication SPI will be called every time.

Interaction flow

Protocol definition

Request parameters

No request parameter

Response data

sample response data:

{
  "user": {
    "userID": "ace55655ceabd55g",
    "name": "alice",
    "avatar": "https://image.xx/acde55acb45bbead55"
  }
}

Get user information in batches

Call scene

When multiple people collaborate, display the profile photo and name of the current collaborator; when viewing the comment list in the document, display the profile photo and name of the commenting user.

Interaction flow

Protocol definition

Request parameters

sample request data:

{
  "userIDs": [ "user_id1", "user_id2", "user_id3" ]
}

Response data

sample response:

{
"users": [
    {"userID": "user_id1", "name":"name1", "avatar":"https://xxxx"},
    {"userID": "user_id2", "name":"name2", "avatar":"https://xxxx"},
    {"userID": "user_id3", "name":"name3", "avatar":"https://xxxx"}
  ]
}

User permission role acquisition

Call scene

When a user reads or edits a unit, gets the user’s permission role to determine whether there is permission for the corresponding operation.

Interaction flow

Protocol definition

Request parameters

sample request:

curl -X GET "http://sample.univer.ai/role?unitID=acff-adebc125e45b&userID=acd5455e44fc5bb55"

Response data

sample response data:

{
  "userID": "acd5455e44fc5bb55",
  "role": "editor"
}

list collaborators of the unit

Call scene

When setting the collaborators of a protected area or sub-table(only the collaborators of this unit can be set as readable/editable users of the sub-table and protected area).

Interaction flow

Protocol definition

Request parameters

sample request:

{
  "unitIDs": [
    "unit_id1",
    "unit_id2",
    "unit_id3"
  ]
}

Response data

sample response data:

{
  "collaborators": [
    {
      "unitID":"unit_id1",
      "subjects": [
        {
          "subject": {
            "id": "1abcdef777",
            "name": "alice",
            "avatar": "https://image.ai/36554",
            "type": "user"
          },
          "role":"owner"
        },
        {
          "subject": {
            "id": "1abcdef779",
            "name": "bob",
            "avatar": "https://image.ai/36559",
            "type": "user"
          },
          "role":"editor"
        },
      ]
    }
  ]
}

Configure to integrate via USIP

How to configure Univer backend services to enable user authentication and permission verification?

When deploying using Docker Compose, add the following configuration to the custom configuration file .env.custom:

# usip about
USIP_ENBALED=true  # Set true to enable USIP
USIP_URI_CREDENTIAL=https://your-domain/usip/credential # the implementation URL of USIP API user authentication
USIP_URI_USERINFO=https://your-domain/usip/userinfo     # the implementation URL of USIP API get user information
USIP_URI_ROLE=https://your-domain/usip/role             # the implementation URL of USIP API get user role
USIP_URI_COLLABORATORS=https://your-domain/usip/collaborators # the implementation URL of USIP API list collaborators
  
# auth about
AUTH_PERMISSION_ENABLE_OBJ_INHERIT=false  # See permission design instructions below
AUTH_PERMISSION_CUSTOMER_STRATEGIES=      # See permission design instructions below

When deploying with k8s, edit your custom values.yaml and add the following configuration:

universer:
  config:
    usip:
      enabled: true  # Set true to enable USIP
      uri:
        userinfo: "https://your-domain/usip/userinfo" # the implementation URL of USIP API get user information
        collaborators: "https://your-domain/usip/collaborators" # the implementation URL of USIP API list collaborators
        role: "https://your-domain/usip/role"                   # the implementation URL of USIP API get user role
        credential: "https://your-domain/usip/credential"       # the implementation URL of USIP API user authentication
    auth:
      permission:
        enableObjInherit: false  # See permission design instructions below
        customerStrategies: ""   # See permission design instructions below

Please note that once you configure to enable USIP, the URLs of all four USIP APIs mentioned above need to be configured and your service needs to implement them correctly. For how to apply these configurations during deployment, please refer to [Production Deployment(/guides/sheets/pro-features/server/deploy).

permission management design of Univer

Univer’s permission control uses the RBAC model. Currently, there are three fixed roles: owner, editor, and reader. The editor role has the permissions of the reader role, and the owner role has the permissions of the editor and reader roles. Custom roles are not currently available, but users can configure the minimum role required for each action. Univer has a default configuration that takes effect. If you don’t need it, you can do nothing. If necessary, you can configure it to cover the minimum role requirements for some actions.

The default actions and their required minimum roles built into Univer are as follows:

If you want to modify the minimum roles required for some of the actions, such as setting that only the unit’s owner (role = 2) can copy content (action = 6) and print (action = 3), you can configure it as follows:

When deploying using Docker Compose, add the following configuration to the custom configuration file .env.custom:

AUTH_PERMISSION_CUSTOMER_STRATEGIES=[{"action": 3, "role": 2}, {"action": 6, "role": 2}]

When deploying with k8s, edit your custom values.yaml and add the following configuration:

universer:
  config:
    auth:
      permission:
        customerStrategies: '[ {"action": 3, "role": 2}, {"action": 6, "role": 2} ]'

It can be seen that the configured value is a JSON object array, and the action of the object is the enumeration value of the action in the above list, and the role is the enumeration value corresponding to the lowest role required by the action.

There is another point to pay attention to in the design of Univer permission management.

Univer not only controls permissions at the entire document level, but also controls permissions on protected areas/sub-tables under the unit, all of which have independent authorized user management. For example, if user A is the editor of the entire unit, but not the editor or owner of a protected area/sub-table in this unit, then user A cannot edit this protected area/sub-table. Under Univer’s default configuration, even if user A is the owner of the unit, he cannot manage protected areas/sub-tables created by other users on this unit unless other users have added permissions to him. If you want to configure the owner of the unit to unconditionally have the owner role of all objects in the unit, you can modify the configuration as follows:

When deploying using Docker Compose, add the following configuration to the custom configuration file .env.custom:

AUTH_PERMISSION_ENABLE_OBJ_INHERIT=true

When deploying with k8s, edit your custom values.yaml and add the following configuration:

universer:
  config:
    auth:
      permission:
        enableObjInherit: true

USIP client system implementation example

Refer to our USIP example source code