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 makeup 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 onboarding 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 onboarding 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 to support lower tiers of participation.

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 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.

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
- See api.kaleido.io for technical information
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, you are likely 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

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 tenants' properties' email property`.

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.