Skip to content

Concepts

TRUST-TOKENS

Fully control your application's authorization flows using open, industry standard JSON Web Tokens (JWT) for representing claims securely between parties.

Trusted access is the most important and core feature of dataBridges. Applications should be able to trust the source of the messages it receives and at the same time trust that the messages it sends is only delivered to trusted participants. This trust is delivered using trust-tokens.

To understand trust-tokens, we need to 1st know main players in the dataBridges network.

dataBridges Router (dBR)

A dataBridges router is a high performance, in-memory, zero-logger, messaging web socket server.

The dataBridges network is based on client server architecture, where the dBR is the main routing server and applications using dataBridges library connect to the routing server and establishes full duplex, bi-directional, low latency connection.

Databridges app key

An app needs a valid application key (app.key) to connect to dataBridges network.

  • An app.key is part of an Application.
  • A dataBridges application can have multiple application keys (app.keys).
  • Lets take an example of an application - realtime.dashboard and we have 4 different programs participating in this application namely data.source app (python application), web dashboard (standard HTML, JS browser app), android app and iOS app. we can create 4 separate app.keys for each type of programs. This allows us to control and manage app.keys in much controlled manner.
    • So we end up having 4 separate app.keys linked to the same app realtime.dashboard
  • Using the app.key, the application will connect to the dataBridges router.

Connection session

Each authenticated connection to the dataBridges network is assigned a unique session-ID.

  • Once an application / device connects to dataBridges network, it is assigned a session-ID unique across the dataBridges network.
  • The dataBridges router creates a global routing map (dBridge routing fence) and links all the connected session-ID belonging to the same application.
  • These sessions can now communicate with each other using public channels and consume public RPC's.

Applications authenticated using valid app.key are automatically authorized to communicate over public channels, public RPC.

Note: dataBridges allows you to disable publish-to-public-channel grant against a key.

Trust-Tokens

Trust-token is a JWT based authorization key required to be submitted by application, device to connect to access controlled private, presence, system channel and RPC functions

Continuing our example of realtime.dashboard, let us take a use case where based on the employee designation, the dashboard would like to display different sets of information.

Let us consider the dashboard caters to the following hierarchy in the company

  • L1 - Executive Director or CEO
  • L2 - President and Vice-President
  • L3 - Department directors
  • L4 - Managers
  • L5 - Supervisors
  • L6 - Employees

The dashboard data-source program

We have the main Dashboard data-source program (Python application) responsible to publish dashboard data (json format). This main Data-source-program uses the following channels [pvt:L1, pvt:L2, pvt:L3, pvt:L4, pvt:L5, pvt:L6 ].

The dashboard data-source program publishes Real-time messages to all these 6 private channels. The core idea here is only authorised employee will be able to access only channels based on their user hierarchy.

The dashboard application [web, mobile client]

  • The dashboard web and mobile application as standard app that authenticates against the company's existing authentication system.
  • Once the authentication is successful, the dashboard app connects to dataBridges network using dataBridges app.key and get a unique session-ID.
  • The dashboard application passes the session-ID to company's authorization server and gets back a prs:Channel name and associated trust-token.
  • Using this trust-token, the dashboard application will subscribe to the dataBridges channel.
  • The dataBridges router will allow the subscription only if the JWT is validated.

How a trust-token is created?

The company authorisation server has the following piece of information

  • User hierarchy
  • The session ID

Based on the the user hierarchy, the authorization server creates a trust-token JWT which indicates allow $session-ID access to Channel name = $Channel.Name and i have signed this JWT using the secret key associated with app.key = $app.key

How a trust-token is validated?

  • The dashboard app (web, mobile) submits the following subscription message grant me subscription to channel = $Channel Name and here is the JWT trust-token
  • The dataBridges router receives the subscription request and validates the trust-token.
  • It retrieves the session-ID from the connected socket
  • It already knows which app.key was used by this authenticated session.id
  • using the above information the dataBridges router validates the JWT trust-token.
  • If the JWT trust-token is validated, the dataBridges router will allow the session to subscribe to the channel it asked.

This trust-token process greatly simplifies the security authorisation process by moving all the complexity to the dataBridges router and the company's existing authentication and authorisation services. This leaves the product designer extreme flexibility to deliver brilliant real-time features based on trusted access and without breaking the existing company's authorization processes and system.