FieldTwin Collaborate is an optional application that is part of the FieldTwin Enterprise Suite that allows for true collaborative visual workflows between multiple stakeholders. This means that Operators and EPCs work on the same shared data model while ensuring secure granular access and control of users and data for all parties.
Two-Way Real time collaboration
Establishing a two-way secure connection between FieldTwin tenant owners enables you to have a real time collaboration on the same shared data-model. The Collaborate module allows you to connect to external FieldTwin users and securely share your locally stored project data eliminating data loss and duplication of work. The external users can utilise your shared data with the rights you choose to give them. The external party can choose to initiate a collaboration back and you will achieve a two-way real-time collaboration.
Token and Handshake Architecture¶
When it comes to Data Security and Control FieldTwin ensures that all data is stored locally in the respective client tenant database for the collaborators. Furthermore, all data is encrypted both at REST and in TRANSIT meaning that the data is always encrypted when stored (database) and when sent to the other tenant(s) (HTTPS).
To ensure trusted communication between the collaborating parties FieldTwin relies on first establishing a mutual handshake to acknowledge that a collaboration is to be established between two (2) or more tenants.
Thereafter secure tokens (JWT) are generated to verify trust between the collaborative tenant for any and all communication.
Definitions used throughout this document to describe the architecture and process flow:
HOST – This is the account on the tenant that will be hosting the project/sub-project back drop
CLIENT – This is the account on the tenant that will be hosting the project/sub-project where the shared backdrop will be displayed
JWT TOKEN – JWT, or JSON Web Token, is an open standard used to share security information between two parties — a client and a server. Each JWT contains encoded JSON objects, including a set of claims. JWTs are signed using a cryptographic algorithm to ensure that the claims cannot be altered after the token is issued
HANDSHAKE - Handshaking is the connection between the computer and a device. Handshaking is required in order to allow both the computer and device to send protocols to each other. During a handshake, the two devices make sure that they know certain connection requirements of each other.
Set up a Collaboration¶
This section describes the process and flow for establishing a collaboration between two (2) or more tenants.
- To initiate a collaboration with another company, you as the “HOST” must contact your FutureOn Customer Success representative to register the “CLIENT” tenant as a "collaborator” (see COLLABORATION illustration below for reference) in your “HOST” account:
The collaborator created will then contain two (2) essential information attributes namely:
The Account ID for the
CLIENT tenant and the unique URL of the “CLIENT” tenant backend.
- Then in the FT Collaborate application the “HOST” must fill in the required information and then click on the Generate and share token button.
This action will then send a request to the “HOST” BACKEND with the following encrypted information:
- The NAME of the account for the HOST tenant
- The ID of the account of the HOST tenant
- The ID of the project for the "backdrop" sub-project the “HOST” wants to share
- The NAME of the project of the "backdrop" sub-project the “HOST” wants to share
- The ID of the subproject (backdrop) the “HOST” wants to share
- The NAME of the subproject (backdrop) the “HOST” wants to share
- The project CRS (Coordinate Reference System)
- The “CLIENT” name
- The “CLIENT” backend URL
- The “CLIENT” Account ID
- The user role/rights that the “CLIENT” will be granted when accessing the “HOST” backdrop sub-project
The “CLIENT” contact email to whom the activation link/instructions for the collaboration setup will be sent
Using the data provided for step 2 the “HOST” BACKEND will then:
a) Create a SIGNED JWT token (HANDSHAKE_TOKEN) comprised of the following information:
ID - A new and unique ID for this token Content - A new and unique response challenge string for this token AccountID - The ID for the account of the HOST tenant backend - The backend URL for the CLIENT tenant hostAccountID - The ID for the account of the CLIENT tenant
b) This generates a Handshake URL for the CLIENT tenant
This URL is then created using the following pattern:
https://<[baseURL of the CLIENT backend]>/hand-shake/start-redirect/[ID of the CLIENT Account]/[HAND_SHAKE_TOKEN]
c) This URL is then sent by email to the email address provided as contact in step 2
d) When the “CLIENT” clicks on the link in the email they will be redirected to their own FT Collaborate application and asked to login if not already logged in
e) Once logged in, the “CLIENT” FT Collaborate application will make a request to their own backend by sending over their unique “HAND_SHAKE_TOKEN”
f) The “CLIENT” Backend will register the pair of unique content IDs of the
g) The “CLIENT” backend will send a request to the “HOST” backend containing only the ID of the
h) The “HOST” backend then checks if the origin of the request corresponds to the “backend URL” registered in step 2
i) The “HOST” backend makes a request to the “CLIENT” backend URL (as registered in step 2) with the ID of the
j) The “CLIENT” backend then responds with the content of the
k) The “HOST” backend then checks that the response back is the expected one
l) Then a new signed JWT token is created (COLLAB_GENERATOR) with a longer life session period and sends it back with the information needed to access the “HOST” backdrop on the “CLIENT” backend
Collaboration Set up Process Flow¶
The diagram below outlines the collaboration set up including handshake generation and process/data flow between the collaboration tenants:
The last token created (COLLAB_GENERATOR) will only be used to communicate from the “CLIENT” backend tenant to the “HOST” backend tenant. And then only to generate tokens for with short lifespans (< 2 hours) that will allow the users of the “CLIENT” tenant to access the “HOST” tenant backdrop.
Data Access and Permission Flow¶
This diagram outlines the collaboration data access right and permission flow between the tenants: