Multi-tenant Nodes

Kaleido provides a multi-tenant node offering, to allow a Network Operator to manage a node that is shared securely between a number of participants in the business network.

To understand this feature, let us first consider the make up of Modern Business Networks and where this feature fits into the participation model.

Participation Levels in Modern Business Networks

Modern Business Networks built on blockchain commonly have multiple tiers of participation:

The Network Operator

  • Responsible for the process of on-boarding new members into the business network
  • Develops common components of the decentralized application stack run by the participants
  • Coordinates upgrades and technical collaboration between the participants
  • Helps ensure all levels of participation in the business network have the infrastructure required to participate

In Kaleido this member has a Kaleido account, with one or more memberships to perform on-boarding and management. Depending on the business network, the network operator might own one or more blockchain signing nodes or non-signing nodes themselves. These could represent the network operator directly in the business network, or be run on behalf of others in order to support lower tiers of participation in the network.

While not all business networks have a network operator, it has been established as a common pattern for successfully fostering new ecosystems.

Block Signers with Dedicated Infrastructure

  • Key stakeholders in the business network
  • Take on responsibility for running block signing nodes (or "validators" in IBFT terminology)
  • Run their own copy of the decentralized application
  • Decentralize the network by taking direct ownership of their keys, data and operations

In Kaleido these members have their own Kaleido account, with their own membership and their own signing node.

In some business networks the network operator starts as the first member, and decentralization occurs over time. In these cases the Kaleido Public Ethereum Tether service can be helpful to demonstrate a high level of immutability in early phases where the network operator manages a high proportion of the infrastructure directly.

Additional Members with Dedicated Infrastructure

  • Transact in the business network, as part of their core business operations
  • Have their own replicated copy of the blockchain, for fast access from their core systems to transactions and events
  • Might run a copy of the application, or use a dedicated copy of the application hosted by the network operator

In Kaleido these members could have their own Kaleido account, or connect to a dedicated node that is operated for them by the network owner as a proxy. In either case they a membership visible to other parties in the network and their own non-signing node.

For some networks, all members with dedicated infrastructure wish to have signing nodes. However, the limits of enterprise byzantine fault-tolerant consensus algorithms such as IBFT are considered as barriers to allowing all members to run the own signing node. In these cases the Kaleido Rotating Block Signers service can be helpful to provide efficient operation of the network, allowing signing responsibilities to be shared across hundreds of members.

Observers

  • Do not directly participate in transactions, but fulfill some regulatory or audit function for the business network
  • Run their own signing or non-signing node to increase trust and transparency in the network

In Kaleido these members have their own Kaleido account, with their own membership and their own signing node or non-signing node.

Additional Members sharing Multi-tenant Infrastructure

  • Transact in the business network
  • Need access to a node to submit transactions, and consume events
  • Are willing to share a replicated copy of the ledger with other participants
  • Do not wish to take on the responsibility of owning their own node
  • Require isolation of their data and transactions from other members
  • Might run a copy of the application, or use a multi-tenant copy of the application hosted by the network operator

In Kaleido these members are modeled as a tenant underneath a membership owned by the network operator, and are provided secure application credentials to a shared signing node or non-signing node operated for them by the network operator.

Multi-tenant Node Configuration

The multi-tenant node feature must be enabled for your network operator account before you can use it. Please contact us for more information.

  • Create a membership that will represent the shared access to the platform from all tenants that share a node
  • Choose a tag to group your tenants onto a node - a simple string from 1-48 characters (a-z0-9-_. characters allowed)
  • Create a tenant via the REST API for each tenant that will share a node, referencing that tag
  • Configure the Blockchain Application Firewall of the node to dynamically generate a policy for the tagged set of Tenants

Tenant Properties

The properties underneath a tenant are a set of string to string key/value pairs that can be used within templated Blockchain Application Firewall rules to authenticate those tenants.

Dynamic Blockchain Application Firewall Re-configuration

Whenever you add/remove/update tenants underneath a tag, all multi-tenant nodes with a Blockchain Application Firewall configuration will dynamically update without requiring a restart.

REST API Gateway and JSON/RPC Support

The multi-tenancy feature and Blockchain Application Firewall support:

  • JSON/RPC connections over HTTPS
  • JSON/RPC connections over Web Sockets
  • REST API connections via the Kaleido REST API Gateway

Example using JWT Tokens (inc. OAuth 2.0 + OpenID Connect)

In a modern web and mobile application it is likely you are using JWT tokens to authorize access to the platform:

  • Directly issued by the multi-tenant application tier hosted by the network operator
  • Issued via an OAuth 2.0 flow with an Authentication Server as OpenID Connect Identity Tokens

In order to connect your Kaleido tenant with the organizational or user identity of the application tenant, you need to ensure the JWT token contains a unique identifier for the tenant in the claims within that JWT token.

For example, if the JWT token issues contain claims like:

{
  "uid": "a9435f19-2919-46f0-bf2d-330673edd311",
  "email": "example-user@kaleido.io",
  "iat": 1581960466,
  "exp": 1581960526
}

You might configure a tenant in Kaleido as follows:

{
    "tag": "tenants-for-node-x",
    "properties": {
        "name": "example-user@kaleido.io",
        "uid": "a9435f19-2919-46f0-bf2d-330673edd311"
    }
}

Then in your BAF policy configuration, you would use the uid to map that unique user in your JWT issuing application security tier to a set of access permissions on the node. In the following example the JWT is supplied via a bearer token.

{
    "tenants_tag": "tenants-for-node-x",
    "jwt": {
        "enabled": true,
        "bearer": true,
        "mappings": [{
            "ruleset": "access-for-authorized-tenants",
            "templated": true,
            "claims": {
                "uid": "{{.uid}}"
            }
        }]
    }
    // ... other blockchain application firewall configuration
}

This templated rule in the BAF policy configuration, will evaluate a uid against each tenant definition tagged with tenants-for-node-x. The rule updates automatically without any downtime/restart when you add/remove additional tenants.

The {{.uid}} syntax is a handlebar template syntax, where uid could be changed to any field in your tenant properties. For example {{.email}} would match the email property of the tenants properties.

Example using App Credentials

You can also use HTTPS with Basic access authentication to create a strong generated credential for each tenant that accesses the node, which is a mechanism supported by a wide range of web3 libraries.

First generate a new Application Credential that will be used only by that tenant of the node.

For this example, say we generated a new Application Credential as follows:

  • Username (id): e0uog765lx
  • Password (secret): Dkwn_UN9K84MUrE5QqD9nZ1OJLz7v-BCucPYOPkv0Mc

Then you might configure a tenant in Kaleido as follows:

{
    "tag": "tenants-for-node-x",
    "properties": {
        "name": "example-user@kaleido.io",
        "accesskey1": "e0uog765lx"
    }
}

Then in your BAF policy configuration, you would use the keyid to map that unique user in your JWT issuing application security tier to a set of access permissions on the node.

{
    "tenants_tag": "tenants-for-node-x",
    "appcreds": {
        "basicAuth": true,
        "mappings": [{
            "ruleset": "access-for-authorized-tenants",
            "templated": true,
            "claims": {
                "id": "{{.accesskey1}}"
            }
        }]
    }
    // ... other blockchain application firewall configuration
}

The secret part of the strong generated Application Credential should never appear in your configuration.