Installation and usage of the platform

Precise platform configuration: gRPC and REST API authorization

Authorization is necessary to provide access to the gRPC and REST API tools of a node. For this purpose, the Waves Enterprise blockchain platform supports two types of authorization:

  • api-key string hash authorization;

  • JWT token (oAuth 2) authorization.

Attention

Authorization by api-key hash is a simple means of accessing a node, but the security level of this authorization method is relatively low. An intruder can gain access to a node if the string api-key reaches him. If you want to improve security of your network, we recommend using JWT token authentication via an authorization service.

The auth section of the node configuration file is used to configure authorization.

type = "api-key"

Authorization by hash of the key string api-key is used in the default node. When selecting the authorization method by hash of the key string api-key the auth section contains the following parameters:

auth {
  type = "api-key"

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

  # Hash of API key string for PrivacyApi routes
  privacy-api-key-hash = "G3PZAsY6EA8esgpKxB2UYTQJZJPzc14gLnNbm2xvcDf6"
}

  • api-key-hash - hash from the REST API access key string.

  • privacy-api-key-hash - hash from the key string to access privacy methods.

To fill in these parameters you will need the ApiKeyHash utility from the generator-x.x.x.jar package, which you can download from the official Waves Enterprise repository on GitHub, selecting the platform version you use.

Place this file in the root folder of the platform and also create a file api-key-hash.conf:

apikeyhash-generator {
  crypto {
    type = WAVES
  }
  api-key = "some string for api-key"
  file = ${user.home}"/apikeyhash.out"
}

In this file, enter the string that you want to hash and use for authorization in the api-key parameter.

You can use the ‘’file’’ parameter to specify the name of the file to which the hash will be saved. The parameter is optional. If it is not specified, the hash is output to the console.

Note

The waves-crypto field with yes and no values is still supported, but it will be deprecated in the platform future versions. Instead, use the type field in the crypto section.

Enter the prepared api-key-hash.conf file as an argument when you run the ApiKeyHash utility from the generator package:

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

Output example:

Api key: some string for api-key
Api key hash: G3PZAsY6EA8esgpKxB2UYTQJZJPzc14gLnNbm2xvcDf6

2021-02-11 16:31:21,586 INFO  [main] c.w.g.ApiKeyHashGenerator$ - Generator done

Specify the resulting Api key hash value in the api-key-hash and privacy-api-key-hash parameters in the auth section of the node configuration file as indicated above.

type = "oauth2"

When selecting authorization by JWT-token, the auth section of the node configuration file looks like this:

auth {
  type: "oauth2"
  public-key: "AuthorizationServicePublicKeyInBase64"
}

The public key for oAuth is generated during the initial deployment of the node. It is located in the file ./auth-service-keys/jwtRS256.key.pub. Copy the line between -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- and paste it as the public-key parameter of the auth section of the node configuration file.

Hint

The REST API and gRPC interfaces use the same api-key for authorization by key string and public-key for authorization by JWT-token.

See also