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.

security Plugins: For users

GoQuorum offers an official plugin implementation providing the following enterprise features to geth JSON RPC server:

  • Providing TLS configuration to HTTP and WS transports
  • Enabling geth JSON RPC (HTTP/WS) server to be an OAuth2-compliant resource server

Configuration

One of the below blocks must be configured:

{
    "tls": object(TLSConfiguration),
    "tokenValidation": object(TokenValidationConfiguration)
}
Fields Description
tls (Optional) Serve the TLS configuration. See TLSConfiguration for more details
tokenValidation (Optional) Configuration to verify access token and extract granted authorities from the token. See TokenValidationConfiguration for more details

TLSConfiguration

{
    "auto": bool,
    "certFile": EnvironmentAwaredValue,
    "keyFile": EnvironmentAwaredValue,
    "advanced": object(TLSAdvancedConfiguration)
}
Fields Description
auto If true, generate a self-signed TLS certificate. Then save the generated certificate and private key in PEM format in certFile and keyFile respectively
If false, use values from certFile and keyFile
certFile Location to a file storing certificate in PEM format. Default is cert.pem
keyFile Location to a file storing private key in PEM format. Default is key.pem
advanced Additional TLS configuration

TLSAdvancedConfiguration

{
    "cipherSuites": array,
}
Fields Description
cipherSuites List of cipher suites to be enforced. Default to
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
Go here to view all supported cipher suites

TokenValidationConfiguration

{
    "issuers": array,
    "cache": object(CacheConfiguration),
    "introspect": object(IntrospectionConfiguration),
    "jws": object(JWSConfiguration),
    "jwt": object(JWTConfiguration),
}
Fields Description
issuers Array of strings specifying approved entities who issue tokens
cache Configuration of a token cache
introspect Configuration of how to connect to introspection API
jws Configuration of how to obtain JSON Web Keyset in order to validate JSON Web Signature
jwt Configuration of how to handle JSON Web Token

CacheConfiguration

An LRU cache which also checks for expiration before returning the value. Below is the default configuration if not specified

{
    "limit": 80,
    "expirationInSeconds": 3600
}
Fields Description
limit Max number of items in the cache
expirationInSeconds Expiry time for a cache item

IntrospectionConfiguration

{
    "endpoint": string,
    "authentication": object(AuthenticationConfiguration),
    "tlsConnection": object(TLSConnectionConfiguration)
}
Fields Description
endpoint Introspection API endpoint
authentication Configuration of how to authenticate when invoking endpoint
tlsConnection Configuration of TLS when connecting to endpoint

AuthenticationConfiguration

{
    "method": string,
    "credentials": map(string->EnvironmentAwaredValue)
}
Fields Description
method Defines authentication mechanism. Supported values are
  • client_secret_basic: basic authentication
  • client_secret_form: form authentication
  • private_key: mutual TLS authentication
credentials Defines key value pair used for the given authentication mechanism above. See below for the supported keys
Method Keys
client_secret_basic clientId, clientSecret
client_secret_form clientId, clientSecret
private_key certFile, keyFile

TLSConnectionConfiguration

{
    "insecureSkipVerify": bool,
    "certFile": EnvironmentAwaredValue,
    "caFile": EnvironmentAwaredValue
}
Fields Description
insecureSkipVerify If true, do not verify server TLS certificate
certFile Location to a file storing server certificate in PEM format. Default is server.crt
caFile Location to a file storing server CA certificate in PEM format. Default is server.ca.cert

JWSConfiguration

{
    "endpoint": string,
    "tlsConnection": object(TLSConnectionConfiguration)
}
Fields Description
endpoint API endpoint to obtain JSON Web Keyset
tlsConnection Configuration of TLS when connecting to endpoint

JWTConfiguration

{
    "authorizationField": string,
    "preferIntrospection": bool
}
Fields Description
authorizationField Claim field name that is used to extract scopes for authorization. Default to scope
preferIntrospection If true, introspection (if defined) result is used

EnvironmentAwaredValue

A regular string which allows value being read from an environment variable by specifying an URI with env scheme. For example: env://MY_VAR will return value from MY_VAR environment variable.

Supported Cipher Suites

  • TLS_RSA_WITH_RC4_128_SHA
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_RSA_WITH_RC4_128_SHA
  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
  • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

OAuth2 Authz Server Integration

Examples on how to integrate Quorum Security Plugin with an OAuth2 Authorization Server are here.

OAuth2 Scopes

Scope is a mechanism to limit a client’s access to protected resources in Quorum Client RPC server. A client can request one ore more scopes from a token endpoint of an OAuth2 Provider. The access token issued to the client will be limited to the scopes granted.

The scope syntax is as follow:

    scope := "rpc://"rpc-string

    rpc-string := service-name delimiter method-name

    service-name := string

    delimiter := "." or "_"

    method-name := string

Examples

Protecting APIs

Scope Description
rpc://web3.clientVersion Allow access to web3_clientVersion API
rpc://eth_*
or rpc://eth_
Allow access to all APIs under eth namespace
rpc://*_version
or rpc://_version
Allow access to version method of all namespaces.
E.g.: net_version, ssh_version
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