Remote Services API¶

Idea¶

Remote Services provide APIs that facilitate secure connectivity to devices on the shopfloor for remote technicians and experts by means of Fine Grained Authorization Control (FGAC). These APIs allow modelling isolated organization structures in user-defined tree like structures, where the devices to be accessed form the leaves of the tree. In addition to modelling organization structures, these APIs allow privileged users to provide grants to other users to have access to certain parts of the organization structure.

Access¶

For accessing this service, you need to have the the following Insights Hub roles:

mdsp:core:vpnrts.serviceowner
mdsp:core:vpnrts.orguser

Service Owner¶

Service owner is the role that allows tenant-wide operations such as creating isolated organizations, so that data privacy across different organizations can be achieved. The purpose of the service owner role is to facilitate initiation and supporting of organizations. This role is only given to a user that resides in the organization which is the owner of the tenant.

Organization User¶

Organization user (orguser) is the role that regular users should have in order to be able to access the Remote Services APIs. This role provides all the necessary access rights for the users to model an organization and perform all other organization level functionalities.

Remote Services endpoints¶

Remote Services endpoints that belong to users or devices need internet connectivity that allows them to access Remote Services APIs using the HTTPS protocol.

Basics¶

Organizations¶

By default, a tenant is pre-initialized with a single organization called "Service Provider Organization". This is a special organization that every tenant has and all the service owners are automatically onboarded to.

In addition, a service owner may decide to introduce additional organizations into their tenant depending on their needs. A typical scenario is that a service provider has a business relationship with another physical organization and they would like to onboard this 3^rd party business as an isolated organization. Initially, as the creator of the organization, the service owner will have access to it and may help create the organization structure. New users can be onboarded to the new organization and they may be given access rights to the organization. Typically, the organization is eventually handed over to its owner and the access from Service Provider Organization is only granted via the means of external users.

Organization Owner¶

Organizations have an internal organization owner role. By default, the service owner who creates the organization is automatically given organization ownership so that they can perform all the necessary operations across the organization.

Organization owners can add or remove other organization owners, and sometimes even themselves.

Service Provider Organization¶

Service Provider Organization is a special organization in a tenant. It cannot be deleted. All the service owners are automatically onboarded to this organization. External users can only be referred from the service provider organization.

If an already existing user who was onboarded to a different organization is given the Insights Hub role for service owner, this is considered an erroneous situation since the users can only have a single home organization. For this user, the access to the Service Provider Organization is not given and the associated Insights Hub role is automatically removed.

External Users¶

External users of an organization are external to the organization. External users may only be originating from the Service Provider Organization. External users are typically experts who provide assistance in maintaining a device on the shopfloor.

A newly created organization typically has no users of its own. The only user who will have access to it is the service owner who created it. But, this access is given via the external user status of the service owner as the creator of the organization. This access is given automatically as part of organization creation functionality.

External users are referred to an organization by a service owner. Once they are referred, an organization owner in the respective organization may do one of the following:

Admit this referred external user, which enables others in the organization to allow access to this external user.
Alternatively, an organization owner may reject the external user, which causes the referral to be terminated. In this case, the external user will not be available in the organization. Service owner may refer the same user again in future, if necessary.
Another alternative for organization owners is to revoke an admitted external user. All the access granted to this external user will be removed while preserving their role as an external user, so that the same user can be admitted again in the future. Hence, revoking does not require referral by the service owner. An external user with revoked access can be re-admitted.

Lastly, a service owner may at any point rescind referral of an external user which results in the removal of the external user status of the user as well as all the access granted in the organization.

Users¶

In contrast to external users, organizations also have their own users. Every user in the system belongs to a particular organization. Privileged users may add new users to an organization. Upon onboarding to an organization, users are automatically given orguser role in Insights Hub, which allows them to access the Remote Services APIs.

User Roles¶

Users assume different roles, which are determined by the grants and access rights that are given to them by the privileged users. A user may have the following roles:

Organization Owner: Organization ownership allows users to perform organization level operations. There are mainly two categories of functionality that requires organization ownership role: external user management and organization management. Organization owner role is provided to users by means of making them organization owners (by other organization owners).
Organization Admin: Organization admin role is given via an FGAC mechanism called grants. Once a user is given an organization admin grant, they will have this role in the organization. This role allows users to perform administration tasks within the organization including multiple categories of functionalities such as user management, user group management, grant management, connector management, product, node and site management, etc.

With tasks pertaining to organization structure, users with organization admin grant will be limited to those portions of the organization that relevant grant allows them access to.

Site Owner: Site owner role is also given via the grants mechanism. A user with a site owner grant will have the site owner role in the organization. Site owners are typically responsible for administrative tasks in a site as well as providing temporary access to devices in the site by remote technicians.
Remote User: Remote user role is given via the grants mechanism. Remote users are allowed to establish connections to devices that reside in remote sites. Just like in other cases, the provided grants determine the level of access for the given remote user.

Account Status¶

Users have an associated account status information stored alongside their data. The account status for a user is typically set to ACTIVE which signifies that the user is able to access the Remote Services functionalities in accordance with the level of access granted to them by privileged users. However, there are additional status values possible:

SUSPENDED: A privileged user (organization admin) may suspend a user's account to prevent further access by the respective user. Once a user is suspended, the account status must be explicitly modified by an organization admin to later make the user active again.
EXPIRED: Typically, the users will not have accounts that expire. However, it is possible for organization admins to activate users while also setting an expiration date for the future. The respective user will have to be ACTIVE until the expiration date, and then their account status will be set as EXPIRED, which will prevent them from accessing the system. An organization admin may re-activate this user at this point.
RESTRICTED: Account status for a user will be set to RESTRICTED upon detection that the user has lost their Insights Hub roles for Remote Services, which would prevent them from using the Remote Services APIs. This situation may occur if a tenant admin removes all necessary roles. In this case, the user can be re-activated by an organization admin or by re-assigning the necessary Insights Hub role to the user.

User Groups¶

User groups allow simplifying management of user rights for organization admins. Organization admins may introduce new user groups and assign users to these user groups. It is possible to provide grants to user groups which automatically allows users within to acquire these grants.

Products¶

Each organization has a product hierarchy defined by the organization admin. Products are means to define device types and families in Remote Services. Each product may have its descendants represented by child products. Products are used as part of the grants, to further restrict the given access to a particular product family or device type.

Products have an identifier information and each product has its parentID.

Nodes¶

Each organization has a node hierarchy defined by the organization admin. Nodes are organized in a tree like structure and each node may have multiple children. The way the organization needs to be structured is completely determined by the organization admins. Any logical tree-like structuring is possible by using nodes. A node may contain other nodes or sites underneath.

The nodes have an identifier information and each node has its parentID.

Sites¶

Sites would correspond to the structural element in organizations that are connected to nodes, and they would house the devices. Sites can only have devices in them, hence it is not possible to create other sites or nodes under a given site. In the tree-like organization structure, they are the level immediately above the leaf level (device level).

The site is actually a special kind of a node. Sites have an identifier information, which corresponds to their ID as node. Instead of a parentID, sites have the nodeID information which corresponds to the node contains the site.

Connectors¶

Connectors define the actual connection details. Connectors are defined by organization admins. Once a connector is defined, then it is available for the entire organization. Any organization admin may assign this connector to a device they have access to. Assignment of a connector to a device enables remote users to establish connections using this connector on the device.

At its core, a connector definition contains information about the TCP ports that should be used for the tunnels, in addition to some properties of the underlying protocol.

Depending on the type of the connector, the required information varies. The available connector types are as below:

DTT: This is the most generic connector type that allows tunneling of TCP traffic originating from service endpoint towards a device where the connector is assigned to.
RDP: This is a connector type that builds on top of DTT to provide additional convenience to users by providing RDP related properties such as domain name, user name, resolution, etc.
VNC: This is a connector type that builds on top of DTT to provide additional convenience to users by providing VNC related properties.
SSH: This is a connector type that builds on top of DTT to provide additional convenience to users by providing SSH related properties.
Proxy Unaware (PU): This is a connector type that allows clients to connect to remote devices seamlessly even if the clients cannot cope with intermediate proxies.
DTT-R: This is similar to DTT. However, the goal is to provide device to device tunneling. DTT-R stands for DTT-Reverse.
Web Application: This connector type allows tunneling HTTP based applications to be accessed by remote users.

User Grants¶

Grants allow the users to have access to parts of the organization while also specifying the kind of access. User grants are the kind of grants that are directly given to individual users. A user grant contains the following:

userID: This specifies the user to which this grant is given to.
role: The access right given to the user with this grant. Alternative roles that can be given are:
- REMOTE_USER
- SITE_OWNER (Site owner grant can only be given to a site)
- ORGANIZATION_ADMIN
nodeID: The node at which the user is given the grant. If there are any children nodes, the user will also have access to those as well. This may either be a node or a site.
productID: The product hierarchy level the user is allowed access to. This will specify which kind of devices in the organization structure the user will have access to.

User Group Grants¶

Similar to user grants, user group grants allow access to parts of the organization, but for user groups. User group grants are inherited by the users assigned to the respective user group. The pieces of information for a user group grant are as below:

userGroupID: which specifies the user group to which this grant is given to.
role: access right given to the user group with this grant. Alternative roles that can be given are:
- REMOTE_USER
- SITE_OWNER (Site owner grant can only be given to a site)
- ORGANIZATION_ADMIN
nodeID: The node at which the user group is given the grant. If there are any children nodes, the user group will also have access to those as well. Note that this may either be a node or a site.
productID: The product hierarchy level the user group is allowed access to. This will specify which kind of devices in the organization structure the user group will have access to.

Features¶

Organization management
User management
External user management
User groups
Product management
Node management
Site management
Connector management
User grant management
User group grant management
Session management
Parameter management

*[FGAC]:Fine Grained Authorization Control is a security approach that provides detailed and specific permissions to users based on their roles, attributes, or contextual factors. Unlike coarse-grained control, which typically offers broad access permissions (e.g., "admin" or "user"), fine-grained control allows for more precise and nuanced access management.