Skip to main content

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:

NameLanguage
quorum-security-plugin-sdk-goGo

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)
}
FieldDescription
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)
}
FieldDescription
autoIf 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.
certFileLocation to a file storing certificate in PEM format. The default is cert.pem.
keyFileLocation to a file storing private key in PEM format. The default is key.pem.
advancedAdditional TLS configuration.

TLSAdvancedConfiguration

{
"cipherSuites": array
}
FieldDescription
cipherSuitesList 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),
}
FieldDescription
issuersArray of strings specifying approved entities who issue tokens.
cacheConfiguration of a token cache.
introspectConfiguration of how to connect to the introspection API.
jwsConfiguration of how to obtain a JSON Web Keyset to validate a JSON Web Signature.
jwtConfiguration 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
}
FieldDescription
limitMaximum number of items in the cache.
expirationInSecondsExpiration time for a cache item.

IntrospectionConfiguration

{
"endpoint": string,
"authentication": object(AuthenticationConfiguration),
"tlsConnection": object(TLSConnectionConfiguration)
}
FieldDescription
endpointIntrospection API endpoint.
authenticationConfiguration of how to authenticate when invoking endpoint.
tlsConnectionConfiguration of TLS when connecting to endpoint.

AuthenticationConfiguration

{
"method": string,
"credentials": map(string->EnvironmentAwaredValue)
}
FieldDescription
methodDefines an authentication mechanism. Supported values are:
  • client_secret_basic: basic authentication
  • client_secret_form: form authentication
  • private_key: mutual TLS authentication
credentialsDefines the key value pair used for method. See the following table for the supported keys.
MethodKeys
client_secret_basicclientId, clientSecret
client_secret_formclientId, clientSecret
private_keycertFile, keyFile

TLSConnectionConfiguration

{
"insecureSkipVerify": bool,
"certFile": EnvironmentAwaredValue,
"caFile": EnvironmentAwaredValue
}
FieldDescription
insecureSkipVerifyIf true, GoQuorum doesn't verify the server TLS certificate.
certFileLocation to a file storing the server certificate in PEM format. The default is server.crt.
caFileLocation to a file storing the server CA certificate in PEM format. The default is server.ca.cert.

JWSConfiguration

{
"endpoint": string,
"tlsConnection": object(TLSConnectionConfiguration)
}
FieldDescription
endpointAPI endpoint to obtain a JSON Web Keyset.
tlsConnectionConfiguration of TLS when connecting to endpoint.

JWTConfiguration

{
"authorizationField": string,
"preferIntrospection": bool
}
FieldDescription
authorizationFieldClaim field name that is used to extract scopes for authorization. The default is scope.
preferIntrospectionIf 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
ScopeDescription
rpc://web3.clientVersionAllow 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.