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"
}
api-key-hash
– hash from the REST API access key string;privacy-api-key-hash
– the hash from the access key string to the REST methods for handling confidential data and obtaining information about access groups (privacy) and similar gRPC methods;confidential-contracts-api-key-hash
– the hash from the access key string to the REST methods of handling confidential smart contracts and similar gRPC 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. Generators are described in more detail in the Generators section.
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.