Authenticate
KalyChain authentication and authorization for JSON-RPC
Last updated
KalyChain authentication and authorization for JSON-RPC
Last updated
Authentication identifies a user, and authorization verifies user access to requested JSON-RPC methods. KalyChain verifies users using .
Kaly supports two mutually exclusive authentication methods:
.
Kaly creates JWT internally with , and externally with .
Using JSON-RPC authentication and authorization with is not supported.
Enable authentication from the command line. Supply the credentials file and send a request to the /login
endpoint using the username and password. The /login
endpoint creates a JWT for making permitted JSON-RPC requests.
Using disables the /login
endpoint.
The toml
credentials file defines user details and the JSON-RPC methods they can access.
!!! example "Sample auth.toml
credentials file"
Each user requiring JSON-RPC access the configuration file lists the:
Username. Users.
is mandatory and followed by the username. That is, replace <username>
in [Users.<username>]
with the username.
!!! example "Password hash subcommand"
To generate an authentication token, make a request to the /login
endpoint with your username and password. Specify the HTTP port or the WS port to generate a token to authenticate over HTTP or WS respectively. HTTP and WS requires a different token.
!!! example
Authentication tokens expire five minutes after generation. If you require access after the token expires, you need to generate a new token.
Enable authentication from the command line and supply the external JWT provider's public key.
The private and accompanying public key files must be in .pem
format.
RSA with private key length of at least 2048 bits using algorithm RS256
, RS384
or RS512
.
ECDSA private key, using ES256
(secp256r1
or secp256k1
), ES384
or ES512
.
Kaly default is RS256
.
!!! example "Example of key generation using OpenSSL"
!!! critical "Private key security" The private key must be kept secret. Never share private keys publicly or on a Web site, even if advertised as secure.
!!! important The JWT must use one of the RS256
, RS384
, RS512
, ES256
, ES384
, or ES512
algorithms.
Each payload for the JWT must contain:
!!! example "JWT generation example"
Each user has a list of permissions strings defining the methods they can access. To give access to:
All API methods, specify ["*:*"]
.
All API methods in an API group, specify ["<api_group>:*"]
. For example, ["eth:*"]
.
Specific API methods, specify ["<api_group>:<method_name>"]
. For example, ["admin:peers"]
.
With authentication enabled, to explicitly specify a user cannot access any methods, include the user with an empty permissions list ([]
). Users with an empty permissions list and users not included in the credentials file cannot access any JSON-RPC methods.
Specify the authentication token as a Bearer
token in the JSON-RPC request header.
Specify the Bearer
in the header.
!!! example
Hash of the user password. Use the subcommand to generate the hash.
.
To require authentication for the JSON-RPC API, use the or options.
To specify the , use the and options.
!!! important JWT public authentication disables the Kaly /login
endpoint, meaning will not work.
The can be:
Create the JWT using a trusted authentication or in your own code.
See for an example implementation.
To require authentication for the JSON-RPC API, use the or options.
To specify the JWT provider's public key file to use with the externally created JWT, use the or options.
In the Authorization tab in the TYPE drop-down list, select Bearer Token and specify the token (generated either or by the ).