Skip to content

Latest commit

 

History

History
322 lines (202 loc) · 11.8 KB

authenticate.md

File metadata and controls

322 lines (202 loc) · 11.8 KB
title sidebar_position description tags
Authenticate over JSON-RPC requests
4
Besu authentication and authorization for JSON-RPC
public networks
private networks

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Authenticate and authorize JSON-RPC

Authentication identifies a user, and authorization verifies user access to requested JSON-RPC methods. Besu verifies users using JSON Web Tokens (JWT). JWT is also used in multi-tenancy to verify tenant data access.

Besu supports two mutually exclusive authentication methods:

Besu creates JWT internally with username and password authentication, and externally with JWT public key authentication.

:::info

Using JSON-RPC authentication and authorization with MetaMask is not supported.

:::

:::caution

To prevent interception of authentication credentials and authenticated tokens, make authenticated requests over HTTPS. We recommend running production deployments behind a network layer that provides SSL termination. Besu does not provide a HTTPS connection natively.

:::

Username and password authentication

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 public key authentication disables the /login endpoint.

1. Create the credentials file

The toml credentials file defines user details and the JSON-RPC methods they can access.

[Users.username1]
password = "$2a$10$l3GA7K8g6rJ/Yv.YFSygCuI9byngpEzxgWS9qEg5emYDZomQW7fGC"
permissions=["net:*","eth:blockNumber"]
privacyPublicKey="U7ANiOOd5L9Z/dMxRFjdbhA1Qragw6fLuYgmgCvLoX4="

[Users.username2]
password = "$2b$10$6sHt1J0MVUGIoNKvJiK33uaZzUwNmMmJlaVLkIwinkPiS1UBnAnF2"
permissions=["net:version","admin:*"]
privacyPublicKey="quhb1pQPGN1w8ZSZSyiIfncEAlVY/M/rauSyQ5wVMRE="

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.
  • Hash of the user password. Use the password hash subcommand to generate the hash.
  • JSON-RPC permissions.
  • Optional. The tenant's Tessera public key using privacyPublicKey. Only used for multi-tenancy.
besu password hash --password=MyPassword
$2a$10$L3Xb5G/AJOsEK5SuOn9uzOhpCCfuVWTajc5hwWerY6N5xBM/xlrMK

2. Enable authentication

Enable authentication for the JSON-RPC API using the --rpc-http-authentication-enabled or --rpc-ws-authentication-enabled option.

Specify the credentials file using the --rpc-http-authentication-credentials-file or --rpc-ws-authentication-credentials-file option.

:::note With authentication enabled, you can specify methods that don't require authentication using --rpc-http-api-methods-no-auth or --rpc-ws-api-methods-no-auth. :::

3. Generate an authentication token

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.

curl -X POST --data '{"username":"username1","password":"MyPassword"}' <JSON-RPC-http-hostname:http-port>/login
curl -X POST --data '{"username":"username1","password":"MyPassword"}' http://localhost:8545/login
curl -X POST --data '{"username":"username1","password":"MyPassword"}' <JSON-RPC-ws-hostname:ws-port>/login
curl -X POST --data '{"username":"username1","password":"MyPassword"}' http://localhost:8546/login
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MDYwNCwiZXhwIjoxNTUwNDYwOTA0fQ.l2Ycqzl_AyvReXBeUSayOlOMS_E8-DCuz3q0Db0DKD7mqyl6q-giWoEtfdWzUEvZbRRi2_ecKO3N6JkXq7zMKQAJbVAEzobfbaaXWcQEpHOjtnK4_Yz-UPyKiXtu7HGdcdl5Tfx3dKoksbqkBl3U3vFWxzmFnuu3dAISfVJYUNA"
}

Authentication tokens expire five minutes after generation. If you require access after the token expires, you need to generate a new token.

JWT public key authentication

Enable authentication from the command line and supply the external JWT provider's public key.

:::caution

JWT public authentication disables the Besu /login endpoint, meaning username and password authentication will not work.

:::

1. Generate a private and public key pair

The private and accompanying public key files must be in .pem format.

The key algorithm can be:

  • 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.

The default value for Besu is RS256. When you use a different key algorithm, you must specify the --rcp-http-authentication-jwt-algorithm option and/or the --rcp-ws-authentication-jwt-algorithm option depending on your needs.

  1. Generate the private key:

    openssl genrsa -out privateRSAKey.pem 2048

  2. Generate the public key:

    openssl rsa -pubout -in privateRSAKey.pem -pubout -out publicRSAKey.pem

  1. Generate the private key:

    openssl ecparam -name secp256r1 -genkey -out privateECDSAKey.pem

  2. Generate the public key:

    openssl ec -in privateECDSAKey.pem -pubout -out publicECDSAKey.pem

:::danger 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.

Always keep your private keys safe -- ideally using hardware or vault -- and define a strong security policy and best practices.

Compromised keys can provide attackers access to your node's RPC-API.

:::

2. Create the JWT

Create the JWT using a trusted authentication provider1 or library in your own code.

See Java code sample to generate JWT using Vertx for an example implementation.

:::caution Important

The JWT must use one of the RS256, RS384, RS512, ES256, ES384, or ES512 algorithms.

:::

Each payload for the JWT must contain:

{
  "permissions": ["*:*"],
  "privacyPublicKey": "2UKH3VJThkOoKskrLFpwoxCnnRARyobV1bEdgseFHTs=",
  "exp": 1600899999002
}

Example result

3. Enable authentication

Enable authentication for the JSON-RPC API using the --rpc-http-authentication-enabled or --rpc-ws-authentication-enabled option.

Specify the JWT provider's public key file to use with the externally created JWT, using the --rpc-http-authentication-jwt-public-key-file or --rpc-ws-authentication-jwt-public-key-file option.

:::note With authentication enabled, you can specify methods that don't require authentication using --rpc-http-api-methods-no-auth or --rpc-ws-api-methods-no-auth. :::

JSON-RPC permissions

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.

Use an authentication token to make requests

Specify the authentication token as a Bearer token in the JSON-RPC request header.

Postman

In the Authorization tab in the TYPE drop-down list, select Bearer Token and specify the token (generated either externally or by the login request).

cURL

Specify the Bearer in the header.

curl -X POST -H 'Authorization: Bearer <JWT_TOKEN>' -d '{"jsonrpc":"2.0","method":"<API_METHOD>","params":[],"id":1}' <JSON-RPC-http-hostname:port> -H "Content-Type: application/json"
curl -X POST -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MTQxNiwiZXhwIjoxNTUwNDYxNzE2fQ.WQ1mqpqzRLHaoL8gOSEZPvnRs_qf6j__7A3Sg8vf9RKvWdNTww_vRJF1gjcVy-FFh96AchVnQyXVx0aNUz9O0txt8VN3jqABVWbGMfSk2T_CFdSw5aDjuriCsves9BQpP70Vhj-tseaudg-XU5hCokX0tChbAqd9fB2138zYm5M' -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' http://localhost:8545/ -H "Content-Type: application/json"

Footnotes

  1. for example Auth0 or Keycloak ↩