Security plugins

For developers

You can develop new security plugins to customize protection of the JSON-RPC server.

security plugins must follow the gRPC API interface requirements.

To simplify the development of new security plugins the following security plugin SDKs are available:

Name	Language
quorum-security-plugin-sdk-go	Go

For users

GoQuorum provides an official plugin implementation that:

• Provides TLS configuration to HTTP and WS transports.
• Enables the geth JSON-RPC (HTTP/WS) server to be an OAuth2-compliant resource server.

See how to use the security plugin.

Configuration

One of the following blocks must be configured:

{
    "tls": object(TLSConfiguration),
    "tokenValidation": object(TokenValidationConfiguration)
}

Field	Description
tls	(Optional) The TLS configuration.
tokenValidation	(Optional) Configuration to verify access token and extract granted authorities from the token.

TLSConfiguration

{
    "auto": bool,
    "certFile": EnvironmentAwaredValue,
    "keyFile": EnvironmentAwaredValue,
    "advanced": object(TLSAdvancedConfiguration)
}

Field	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. The default is cert.pem.
keyFile	Location to a file storing private key in PEM format. The default is key.pem.
advanced	Additional TLS configuration.

TLSAdvancedConfiguration

{
    "cipherSuites": array
}

Field	Description
cipherSuites	List of cipher suites to be enforced. The default is: 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 View the list of supported cipher suites.

TokenValidationConfiguration

{
    "issuers": array,
    "cache": object(CacheConfiguration),
    "introspect": object(IntrospectionConfiguration),
    "jws": object(JWSConfiguration),
    "jwt": object(JWTConfiguration),
}

Field	Description
issuers	Array of strings specifying approved entities who issue tokens.
cache	Configuration of a token cache.
introspect	Configuration of how to connect to the introspection API.
jws	Configuration of how to obtain a JSON Web Keyset to validate a JSON Web Signature.
jwt	Configuration of how to handle a JSON Web Token.

CacheConfiguration

An LRU cache that checks for expiration before returning the value. If not specified, the default configuration is as follows:

{
  "limit": 80,
  "expirationInSeconds": 3600
}

Field	Description
limit	Maximum number of items in the cache.
expirationInSeconds	Expiration time for a cache item.

IntrospectionConfiguration

{
    "endpoint": string,
    "authentication": object(AuthenticationConfiguration),
    "tlsConnection": object(TLSConnectionConfiguration)
}

Field	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)
}

Field	Description
method	Defines an authentication mechanism. Supported values are: client_secret_basic: basic authentication client_secret_form: form authentication private_key: mutual TLS authentication
credentials	Defines the key value pair used for method. See the following table 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
}

Field	Description
insecureSkipVerify	If true, GoQuorum doesn't verify the server TLS certificate.
certFile	Location to a file storing the server certificate in PEM format. The default is server.crt.
caFile	Location to a file storing the server CA certificate in PEM format. The default is server.ca.cert.

JWSConfiguration

{
    "endpoint": string,
    "tlsConnection": object(TLSConnectionConfiguration)
}

Field	Description
endpoint	API endpoint to obtain a JSON Web Keyset.
tlsConnection	Configuration of TLS when connecting to endpoint.

JWTConfiguration

{
    "authorizationField": string,
    "preferIntrospection": bool
}

Field	Description
authorizationField	Claim field name that is used to extract scopes for authorization. The default is scope.
preferIntrospection	If true, the introspection result (if defined) is used.

EnvironmentAwaredValue

A regular string that allows values to be read from environment variables by specifying a URI with env scheme. For example, env://MY_VAR returns the value from the 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

You can view examples on how to integrate Quorum Security Plugin with an OAuth2 Authorization Server.

OAuth2 Scopes

Scope is a mechanism to limit a client's access to protected resources in a GoQuorum client RPC server. A client can request one or more scopes from a token endpoint of an OAuth2 Provider. The access token issued to the client is limited to the scopes granted.

The scope syntax is as follows:

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

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

service-name := string

delimiter := "." or "_"

method-name := string

Example scopes: Protecting APIs

Scope	Description
rpc://web3.clientVersion	Allow access to the web3_clientVersion API.
rpc://eth_* or rpc://eth_	Allow access to all APIs under the eth namespace.
rpc://*_version or rpc://_version	Allow access to the version method of all namespaces. For example, net_version, ssh_version.