Skip to content
You are reading GoQuorum development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Updated on April 12, 2021

Multi-tenancy

In a typical network, each participant (tenant) uses its own GoQuorum and Tessera node. Tessera can be configured to manage multiple key pairs which are owned by one tenant. This model is costly to run and scale as more tenants join the network.

Multi-tenancy allows multiple tenants to use the same GoQuorum node, with access controls ensuring isolation of tenant data. Tenants can only perform actions on data within their scope. Operators who access the GoQuorum node using an IPC socket have access to all states, and are not restricted by any scope. Accessing a node using HTTP/HTTPS/WS/WSS requires scoped access tokens.

State Isolation

Only private states are logically isolated whereas the public state is publicly available to all tenants.

uml diagram

In this scenario, an organization represents a tenant with multiple departments, and users within the departments. Each user owns one or more privacy manager key pairs. A network operator administers entitlements for each organization using the Authorization Server.

JSON RPC security features are used to manage the authorization flow in which multi-tenancy checks are performed on pre-authenticated access tokens with the authorized scope.

Enable multi-tenancy

Important

Multi-tenancy requires Tessera version 20.10.2 or later.

To enable multi-tenancy, configure the JSON RPC Security plugin and start GoQuorum with the --multitenancy command line option:

geth <other parameters> \
    --multitenancy \
    --plugins file:///<path>/<to>/plugins.json

In the command, plugins.json is the plugin settings file that contains the JSON RPC Security plugin definition. View the security plugins documentation for more information about how to configure the JSON RPC Security plugin.

Example

If quorum-security-plugin-enterprise is used, plugins.json will look like the below

{
    "providers": {
        "security": {
            "name":"quorum-security-plugin-enterprise",
            "version":"0.1.1",
            "config": "/path/to/config.json"
        }
    }
}

Access Token Scope

The JSON RPC Security plugin enables the geth JSON RPC API server to be an OAuth2-compliant resource server. A client must first obtain a pre-authenticated access token from an authorization server, then present the access token (using an Authorization HTTP request header) when calling an API.

The value of the scope encoded in an access token (in case of JWT), or introspection response (in the case of the OAuth2 Token Introspection API) contains the RPC scope and tenant scope which has the following URL-based syntax:

    "private://0x0/_/contracts?owned.eoa=0x0&from.tm=[tm-pubkey]"

In the syntax, tm-pubkey is the URL-encoded value of the Privacy Manager public key.

For example, for a client that owns two Privacy Manager public keys PUBKEY1 and PUBKEY2, an authorization server operator would setup and grant the following scopes to the client:

    private://0x0/_/contracts?owned.eoa=0x0&from.tm=PUBKEY1
    private://0x0/_/contracts?owned.eoa=0x0&from.tm=PUBKEY2

A client presenting an access token containing the above scopes has full access (read/write/create) to private contracts in which PUBKEY1 and PUBKEY2 are participants.

ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can discuss issues and obtain free support on GoQuorum Slack channel.
For paid professional support by ConsenSys, contact us at quorum@consensys.net