Skip to main content

Configure GoQuorum qlight

A qlight client node requires a full node configured to act as a qlight server. The server node is usually set up to support multiple private states (MPS), with the qlight client set up to use a private state identifier (PSI) which is managed by the server node.


Setting up a server node to support MPS is not required, for example, when setting up a qlight client for offloading processing from a full node.

Configure qlight client

Configure the qlight client using the --qlight.client.* command line options.

If the server node has the RPC API secured using TLS, then you must set the --qlight.client.rpc.tls.* command line options.

If you stop the qlight client node, on restart it resyncs with any blocks it missed when it was not running.

Configure server node

Configure the qlight server using the --qlight.server.* command line options.

Network IP restriction

This restricts communication to specified IP networks (CIDR masks). Specify the network mask on the qlight server using --qlight.server.p2p.netrestrict.

File based permissioning

File based permissioning allows you to check qlight clients against a permissioned list and a disallowed list. Enable file based permissioning on the server node using --qlight.server.p2p.permissioning.

The default files are permissioned-nodes.json and disallowed-nodes.json. You can specify a file prefix using --qlight.server.p2p.permissioning.prefix.

Configure enterprise authorization

The enterprise authorization protocol integration only allows authenticated clients to connect to the server.

When using JSON-RPC security you must provide an access token to communicate to the qlight server.

Enable auth tokens in the qlight client using --qlight.client.token.enabled.

Once enabled, specify an initial value using --qlight.client.token.value.

Specify a refresh mechanism for the token using

Configure TLS for P2P communication

You can add an encryption layer on the qlight client-server communication. Configure the encryption layer using the qlight.tls.* command line options.

Configure the client-security-plugin mode

In this mode, the configured Go-Quorum plugin is called when the token expiry is reached. You can configure and even develop your own implementation of this plugin.

The plugins are in the ConsenSys repository and are downloaded automatically to the plugins directory.

You can provide your own plugin implementation. Refer to the use of plugin with the hello world tutorial and follow the same steps with the following projects:

You can refer to the QLight Client with Token Manager Plugin Docker-compose file in the GoQuorum examples.


  1. Configure the plugins (plugins/geth-plugin-settings.json)

    "baseDir": "./plugins",
    "providers": {
    "qlighttokenmanager": {
    "name": "quorum-plugin-qlight-token-manager",
    "version": "1.0.0",
    "config": "file://./plugins/qlight-token-manager-plugin-config.json"
    "helloworld": {
    "name": "quorum-plugin-hello-world",
    "version": "1.0.0",
    "config": "file://./plugins/hello-world-plugin-config.json"
  2. Configure the qlight token manager (plugins/qlight-token-manager-plugin-config.json)

    "url": "https://multi-tenancy-oauth2-server:4444/oauth2/token",
    "method": "POST",
    "parameters": {
    "grant_type": "client_credentials",
    "client_id": "${PSI}",
    "client_secret": "foofoo",
    "scope": "rpc://eth_* p2p://qlight rpc://admin_* rpc://personal_* rpc://quorumExtension_* rpc://rpc_modules psi://${PSI}?self.eoa=0x0&node.eoa=0x0",
    "audience": "Node1"
  3. Enable the plugins configuration in the geth arguments

    Add the flag --plugins file://./plugins/geth-plugin-settings.json --plugins.skipverify so GoQuorum enables them.

    (skipverify will skip the verification of the plugins integrity)