Authorization type configuration for the REST API and gRPC access

The Waves Enterprise blockchain platform supports the following two types of authorization for the node’s REST API/gRPC access:

  • api-key string hash authorization;

  • authorization using the JWT token.

api-key string hash authorization type is a simple method of the access management to a node with a low level security. If the api-key hash is leaking out to the attacker, he is getting the full access to the node. When you utilize the separate authorization service with access tokens, you increase the security level of your blockchain network to the high level. You can read more information about the authorization service in the Authorization service section.

api section of the node configuration file

api section contains authorization settings and REST API/gRPC interfaces.

api {
rest {
  # Enable/disable REST API
  enable = yes

  # Network address to bind to
  bind-address = "0.0.0.0"

  # Port to listen to REST API requests
  port = 6862

  # Enable/disable TLS for REST
  tls = no

  # Enable/disable CORS support
  cors = yes

  # Max number of transactions
  # returned by /transactions/address/{address}/limit/{limit}
  transactions-by-address-limit = 10000

  distribution-address-limit = 1000
}

grpc {
  # Enable/disable gRPC API
  enable = yes

  # Network address to bind to
  bind-address = "0.0.0.0"

  # Port to listen to gRPC API requests
  port = 6865

  # Enable/disable TLS for GRPC
  tls = no

  # Akka HTTP settings for gRPC server
  akka-http-settings {
    akka {
      http.server.idle-timeout = infinite

      # Uncomment these settings if you want detailed logging for gRPC calls
      # loggers = ["akka.event.slf4j.Slf4jLogger"]
      # loglevel = "DEBUG"
      # logging-filter = "akka.event.slf4j.Slf4jLoggingFilter"
      # stdout-loglevel = "DEBUG"
      # log-dead-letters = 10
      # log-dead-letters-during-shutdown = on
      #
      # actor {
      #   debug {
      #     # enable function of LoggingReceive, which is to log any received message at
      #     # DEBUG level
      #     receive = on
      #     # enable DEBUG logging of all AutoReceiveMessages (Kill, PoisonPill etc.)
      #     autoreceive = on
      #     # enable DEBUG logging of actor lifecycle changes
      #     lifecycle = on
      #     # enable DEBUG logging of unhandled messages
      #     unhandled = on
      #     # enable DEBUG logging of subscription changes on the eventStream
      #     event-stream = on
      #     # enable DEBUG logging of all LoggingFSMs for events, transitions and timers
      #     fsm = on
      #   }
      # }
      #
      # io.tcp.trace-logging = on
      # http.server.http2.log-frames = yes
    }
  }
}

# Authorization strategy should be either 'oauth2' or 'api-key', default is 'api-key'
auth {
  type = "api-key"

  # Hash of API key string
  api-key-hash = "H6nsiifwYKYEx6YzYD7woP1XCn72RVvx6tC1zjjLXqsu"

  # Hash of API key string for PrivacyApi routes
  privacy-api-key-hash = "H6nsiifwYKYEx6YzYD7woP1XCn72RVvx6tC1zjjLXqsu"
}
# For OAuth2:
# auth {
#   type: "oauth2"

#   # OAuth2 service public key to verify auth tokens
#   public-key: "AuthorizationServicePublicKeyInBase64"

# }
}

api.rest parameters description

  • enable - REST API option activation.

  • bind-address - a network address to bind the REST API interface.

  • port - a port to listen to REST API requests.

  • tls - enable/disable TLS for REST API requests.

  • cors - enable/disable CORS support.

  • transactions-by-address-limit - a maximum number of transactions returned by /transactions/address/{address}/limit/{limit} method.

  • distribution-address-limit - GET ​/assets​/{assetId}​/distribution​/{height}​/limit​/{limit}.

api.grpc parameters description

  • enable - gRPC interface activation.

  • bind-address - a network address to bind the gRPC interface.

  • port - a port to listen to gRPC requests.

  • tls - enable/disable TLS for gRPC requests.

auth section for the api-key type

  • type - the authorization type, specify the api-key value - the string hash authorization.

  • api-key-hash- a hash of API key string.

  • privacy-api-key-hash - a hash of API key string for privacy methods.

auth section for the oauth2 type

  • type - the authorization type, specify the oauth2 value - the token authorization.

  • public-key - a public key of the authorization service.

The REST API and gRPC interfaces use the same api-key and JWT-token values.

Key string authorization usage

Specify the api-key value for the auth-type parameter. Create the api-key-hash for the REST API access by using the generators-x.x.x.jar utility. To run the utility, you need to specify the api-key-hash.conf file as one of the parameters, which defines the parameters of creating the api-key-hash. Use the following command to run the generator:

java -jar generators-x.x.x.jar ApiKeyHash api-key-hash.conf

Specify the value obtained as a result of the utility execution in the parameter api-key-hash in the node configuration file.

Create the privacy-api-key-hash by the same way as the api-key-hash to get the privacy methods access. Specify the value obtained as a result of the utility execution in the parameter privacy-api-key-hash in the node configuration file.

Token authorization usage

Specify the oauth2 value for the auth-type parameter, write the public key of the authorization service into the public-key parameter.