Installation and usage of the platform

Precise platform configuration: gRPC and REST API authorization

Authorization is required to provide access to the gRPC and REST node API tools.

The Waves Enterprise blockchain platform supports two types of authorization for gRPC and REST APIs:

  • 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 attacker may gain access to a node if the api-key string is exposed. If you want to improve security on your network, we recommend using JWT token authentication via authorization service.

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

Hint

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

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"

  # Hash of API key string for Сonfidential Smart Contracts API
  confidential-contracts-api-key-hash = "G3PZAsY6EA8esgpKxB2UYTQJZJPzc14gLnNbm2xvcDf6"
}

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, privacy-api-key-hash and confidential-contracts-api-key-hash parameters in the auth section of the node configuration file as indicated above.

type = "oauth2"

When you select authorization by JWT-token, the auth section of the node configuration file looks as follows:

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

The public key for oAuth is generated during the initial deployment of the node. The key is located in the ./auth-service-keys/jwtRS256.key.pub file.

Copy the line between -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- and paste it as the public-key parameter in the auth section of the node configuration file.

OAuth2 authorization roles

A number of REST API methods and gRPC API methods can only be invoked by users with specific authorization roles.

When registering a new user in Waves Enterprise Client the user is assigned the user role. Further the administrator of the authorization service can change the list of roles assigned to the user.

The user role is encrypted in the JWT token.

The tables below show the methods and the roles required to invoke them that are used in the Waves Enterprise Mainnet blockchain network.

The list of REST methods and the roles that have access to them in Mainnet

REST methods group

REST method

No role

user

admin

privacy

ConfidentialContractUser

activation

*

*

*

*

addresses

*

*

*

*

alias

*

*

*

*

anchoring

*

*

*

*

assets

*

*

*

*

blocks

*

*

*

*

consensus

*

*

*

*

/consensus/algo is not available for user role

*

contracts

*

*

*

*

confidential-contracts

*

*

crypto

*

*

*

*

debug

/debug/validate

*

*

*

*

/debug/blocks/{howMany}

*

/debug/cleanState

*

/debug/configInfo

*

/debug/createGrpcAuth

*

/debug/freeze

*

/debug/historyInfo

*

/debug/info

*

/debug/minerInfo

*

/debug/portfolios/{address}

*

/debug/print

*

/debug/rollback

*

/debug/rollback-to/{signature}

*

/debug/state

*

/debug/stateWE/{height}

*

/debug/threadDump

*

/debug/utx-rebroadcast

*

leasing

*

*

*

*

node

/node/status

*

*

*

*

*

/node/version

*

*

*

*

*

/node/healthcheck

*

*

*

*

*

/node/owner

*

*

*

*

/node/config

*

*

*

*

get /node/logging

*

*

*

*

get /node/metrics

*

*

*

*

/node/stop

*

post /node/logging

*

post /node/metrics

*

peers

/peers/all

*

*

*

*

/peers/connected

*

*

*

*

/peers/suspended

*

*

*

*

/peers/allowedNodes

*

/peers/connect

*

/peers/hostname/{address}

*

permissions

*

*

*

*

privacy

/privacy/{policyId}/recipients

*

*

*

*

/privacy/{policyId}/owners

*

*

*

*

/privacy/{policyId}/hashes

*

*

*

*

/privacy/{policyId}/transactions

*

*

*

*

/privacy/{policyId}/ getData/{policyItemHash}

*

/privacy/{policyId}/ getLargeData/{policyItemHash}

*

/privacy/{policyId}/ getInfo/{policyItemHash}

*

/privacy/getInfos

*

/privacy/sendData

*

/privacy/sendDataV2

*

/privacy/sendLargeData

*

/privacy/forceSync

*

transactions

*

*

*

*

snapshot

/snapshot/status

*

*

*

*

/snapshot/genesisConfig

*

*

*

*

/snapshot/swapState

*

utils

*

*

*

*
The list of gRPC methods and the roles that have access to them in Mainnet

gRPC service

gRPC method

No role

user

admin

privacy

ConfidentialContractUser

TransactionPublicService

grpc-tx

*

*

*

*

UtxInfo

*

*

*

*

*

TransactionInfo

*

*

*

*

BlockchainEventsService

SubscribeOn

*

*

*

*

PrivacyEventsService

SubscribeOn

*

*

*

*

PrivacyPublicService

GetPolicyItemData

*

GetPolicyItemInfo

*

PolicyItemDataExists

*

SendData

*

ContractStatusService

ContractExecutionStatuses

*

*

*

*

ContractsExecutionEvents

*

*

*

*

NodeInfoService

NodeConfig

*

*

*

*

*

ContractPublicService

ConfidentialCall

*
See also