Document allowing unauthenticated access to specific methods (#1536)

* Document allowing unauthenticated access to specific methods Signed-off-by: Alexandra Tran <[email protected]> * link fixes Signed-off-by: Alexandra Tran <[email protected]> * links Signed-off-by: Alexandra Tran <[email protected]> --------- Signed-off-by: Alexandra Tran <[email protected]>
hyperledger · Mar 11, 2024 · 4959946 · 4959946
1 parent 877f5a9
commit 4959946
Show file tree

Hide file tree

Showing 2 changed files with 126 additions and 18 deletions.
diff --git a/docs/public-networks/how-to/use-besu-api/authenticate.md b/docs/public-networks/how-to/use-besu-api/authenticate.md
@@ -88,9 +88,19 @@ $2a$10$L3Xb5G/AJOsEK5SuOn9uzOhpCCfuVWTajc5hwWerY6N5xBM/xlrMK
 
 ### 2. Enable authentication
 
-To require authentication for the JSON-RPC API, use the [`--rpc-http-authentication-enabled`](../../reference/cli/options.md#rpc-http-authentication-enabled) or [`--rpc-ws-authentication-enabled`](../../reference/cli/options.md#rpc-ws-authentication-enabled) options.
-
-To specify the [credentials file](#1-create-the-credentials-file), use the [`--rpc-http-authentication-credentials-file`](../../reference/cli/options.md#rpc-http-authentication-credentials-file) and [`--rpc-ws-authentication-credentials-file`](../../reference/cli/options.md#rpc-ws-authentication-credentials-file) options.
+Enable authentication for the JSON-RPC API using the
+[`--rpc-http-authentication-enabled`](../../reference/cli/options.md#rpc-http-authentication-enabled)
+or [`--rpc-ws-authentication-enabled`](../../reference/cli/options.md#rpc-ws-authentication-enabled) option.
+
+Specify the [credentials file](#1-create-the-credentials-file) using the
+[`--rpc-http-authentication-credentials-file`](../../reference/cli/options.md#rpc-http-authentication-credentials-file)
+or [`--rpc-ws-authentication-credentials-file`](../../reference/cli/options.md#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`](../../reference/cli/options.md#rpc-http-api-methods-no-auth) or
+[`--rpc-ws-api-methods-no-auth`](../../reference/cli/options.md#rpc-ws-api-methods-no-auth).
+:::
 
 ### 3. Generate an authentication token
 
@@ -148,7 +158,7 @@ Authentication tokens expire five minutes after generation. If you require acces
 
 Enable authentication from the command line and supply the external JWT provider's public key.
 
-:::danger
+:::caution
 
 JWT public authentication disables the Besu `/login` endpoint, meaning [username and password authentication](#username-and-password-authentication) will not work.
 
@@ -223,7 +233,7 @@ Create the JWT using a trusted authentication provider[^1] or [library](https://
 
 See [Java code sample to generate JWT using Vertx](https://github.com/NicolasMassart/java-jwt-sample-generation/) for an example implementation.
 
-:::caution
+:::caution Important
 
 The JWT must use one of the `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, or `ES512` algorithms.
 
@@ -259,9 +269,19 @@ Each payload for the JWT must contain:
 
 ### 3. Enable authentication
 
-To require authentication for the JSON-RPC API, use the [`--rpc-http-authentication-enabled`](../../reference/cli/options.md#rpc-http-authentication-enabled) or [`--rpc-ws-authentication-enabled`](../../reference/cli/options.md#rpc-ws-authentication-enabled) options.
+Enable authentication for the JSON-RPC API using the
+[`--rpc-http-authentication-enabled`](../../reference/cli/options.md#rpc-http-authentication-enabled)
+or [`--rpc-ws-authentication-enabled`](../../reference/cli/options.md#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`](../../reference/cli/options.md#rpc-http-authentication-jwt-public-key-file)
+or [`--rpc-ws-authentication-jwt-public-key-file`](../../reference/cli/options.md#rpc-ws-authentication-jwt-public-key-file) option.
 
-To specify the JWT provider's public key file to use with the externally created JWT, use the [`--rpc-http-authentication-jwt-public-key-file`](../../reference/cli/options.md#rpc-http-authentication-jwt-public-key-file) or [`--rpc-ws-authentication-jwt-public-key-file`](../../reference/cli/options.md#rpc-ws-authentication-jwt-public-key-file) options.
+:::note
+With authentication enabled, you can specify methods that don't require authentication using
+[`--rpc-http-api-methods-no-auth`](../../reference/cli/options.md#rpc-http-api-methods-no-auth) or
+[`--rpc-ws-api-methods-no-auth`](../../reference/cli/options.md#rpc-ws-api-methods-no-auth).
+:::
 
 ## JSON-RPC permissions
 

diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md
@@ -3202,7 +3202,7 @@ Sets a limit on the amount of gas for transaction simulation RPC methods. Its va
 <TabItem value="Syntax" label="Syntax" default>
 
 ```bash
---rpc-http-api=<api name>[,<api name>...]...
+--rpc-http-api=<api name>[,<api name>,...]
 ```
 
 </TabItem>
@@ -3233,14 +3233,58 @@ rpc-http-api=["ETH","NET","WEB3"]
 
 </Tabs>
 
-A comma-separated list of APIs to enable on the HTTP JSON-RPC channel. When you use this option you must also specify the `--rpc-http-enabled` option. The available API options are: `ADMIN`, `CLIQUE`, `DEBUG`, `EEA`, `ETH`, `IBFT`, `MINER`, `NET`, `PERM`, `PLUGINS`, `PRIV`, `QBFT`, `TRACE`, `TXPOOL`, and `WEB3`. The default is: `ETH`, `NET`, `WEB3`.
+A comma-separated list of APIs to enable on the JSON-RPC HTTP channel. When you use this option you must also specify the `--rpc-http-enabled` option. The available API options are: `ADMIN`, `CLIQUE`, `DEBUG`, `EEA`, `ETH`, `IBFT`, `MINER`, `NET`, `PERM`, `PLUGINS`, `PRIV`, `QBFT`, `TRACE`, `TXPOOL`, and `WEB3`. The default is: `ETH`, `NET`, `WEB3`.
 
 :::tip
 
 The singular `--rpc-http-api` and plural `--rpc-http-apis` are available and are two names for the same option.
 
 :::
 
+### `rpc-http-api-methods-no-auth`
+
+<Tabs>
+
+<TabItem value="Syntax" label="Syntax" default>
+
+```bash
+--rpc-http-api-methods-no-auth=<api method>[,<api method>,...]
+```
+
+</TabItem>
+
+<TabItem value="Example" label="Example">
+
+```bash
+--rpc-http-api-methods-no-auth=admin_peers,eth_getWork
+```
+
+</TabItem>
+
+<TabItem value="Environment variable" label="Environment variable">
+
+```bash
+BESU_RPC_HTTP_API_METHODS_NO_AUTH=admin_peers,eth_getWork
+```
+
+</TabItem>
+
+<TabItem value="Configuration file" label="Configuration file">
+
+```bash
+rpc-http-api-methods-no-auth=["admin_peers","eth_getWork"]
+```
+
+</TabItem>
+
+</Tabs>
+
+A comma-separated list of JSON-RPC API methods to exclude from [authentication services](../../how-to/use-besu-api/authenticate.md).
+
+:::note
+You must enable JSON-RPC HTTP authentication using [`--rpc-http-authentication-enabled`](#rpc-http-authentication-enabled).
+:::
+
 ### `rpc-http-authentication-credentials-file`
 
 <Tabs>
@@ -3279,7 +3323,7 @@ rpc-http-authentication-credentials-file="/home/me/me_node/auth.toml"
 
 </Tabs>
 
-The [credentials file](../../how-to/use-besu-api/authenticate.md#credentials-file) for JSON-RPC API [authentication](../../how-to/use-besu-api/authenticate.md).
+The [credentials file](../../how-to/use-besu-api/authenticate.md#1-create-the-credentials-file) for JSON-RPC API [authentication](../../how-to/use-besu-api/authenticate.md).
 
 ### `rpc-http-authentication-enabled`
 
@@ -3359,7 +3403,7 @@ rpc-http-authentication-jwt-algorithm="ES256"
 
 </Tabs>
 
-The [JWT key algorithm](../../how-to/use-besu-api/authenticate#1-generate-a-private-and-public-key-pair)
+The [JWT key algorithm](../../how-to/use-besu-api/authenticate.md#1-generate-a-private-and-public-key-pair)
 used to generate the keypair for JSON-RPC HTTP authentication.
 Possible values are `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, and `ES512`.
 The default is `RS256`.
@@ -3500,7 +3544,7 @@ rpc-http-enabled=true
 
 </Tabs>
 
-Enables or disables the HTTP JSON-RPC service. The default is `false`.
+Enables or disables the JSON-RPC HTTP service. The default is `false`.
 
 ### `rpc-http-host`
 
@@ -3541,7 +3585,7 @@ rpc-http-host="0.0.0.0"
 
 </Tabs>
 
-The host on which HTTP JSON-RPC listens. The default is `127.0.0.1`.
+The host on which JSON-RPC HTTP listens. The default is `127.0.0.1`.
 
 To allow remote connections, set to `0.0.0.0`.
 
@@ -3589,7 +3633,7 @@ rpc-http-max-active-connections=100
 
 </Tabs>
 
-The maximum number of allowed HTTP JSON-RPC connections. Once this limit is reached, incoming connections are rejected. The default is 80.
+The maximum number of allowed JSON-RPC HTTP connections. Once this limit is reached, incoming connections are rejected. The default is 80.
 
 ### `rpc-http-max-request-content-length`
 
@@ -3712,7 +3756,7 @@ rpc-http-port="3435"
 
 </Tabs>
 
-The port (TCP) on which HTTP JSON-RPC listens. The default is `8545`. You must [expose ports appropriately](../../how-to/connect/configure-ports.md).
+The port (TCP) on which JSON-RPC HTTP listens. The default is `8545`. You must [expose ports appropriately](../../how-to/connect/configure-ports.md).
 
 ### `rpc-http-tls-ca-clients-enabled`
 
@@ -4249,6 +4293,50 @@ The singular `--rpc-ws-api` and plural `--rpc-ws-apis` options are available and
 
 :::
 
+### `rpc-ws-api-methods-no-auth`
+
+<Tabs>
+
+<TabItem value="Syntax" label="Syntax" default>
+
+```bash
+--rpc-ws-api-methods-no-auth=<api method>[,<api method>,...]
+```
+
+</TabItem>
+
+<TabItem value="Example" label="Example">
+
+```bash
+--rpc-ws-api-methods-no-auth=admin_peers,eth_getWork
+```
+
+</TabItem>
+
+<TabItem value="Environment variable" label="Environment variable">
+
+```bash
+BESU_RPC_WS_API_METHODS_NO_AUTH=admin_peers,eth_getWork
+```
+
+</TabItem>
+
+<TabItem value="Configuration file" label="Configuration file">
+
+```bash
+rpc-ws-api-methods-no-auth=["admin_peers","eth_getWork"]
+```
+
+</TabItem>
+
+</Tabs>
+
+A comma-separated list of JSON-RPC API methods to exclude from [authentication services](../../how-to/use-besu-api/authenticate.md).
+
+:::note
+You must enable JSON-RPC WebSocket authentication using [`--rpc-ws-authentication-enabled`](#rpc-ws-authentication-enabled).
+:::
+
 ### `rpc-ws-authentication-credentials-file`
 
 <Tabs>
@@ -4287,7 +4375,7 @@ rpc-ws-authentication-credentials-file="/home/me/me_node/auth.toml"
 
 </Tabs>
 
-The path to the [credentials file](../../how-to/use-besu-api/authenticate.md#credentials-file) for JSON-RPC API [authentication](../../how-to/use-besu-api/authenticate.md).
+The path to the [credentials file](../../how-to/use-besu-api/authenticate.md#1-create-the-credentials-file) for JSON-RPC API [authentication](../../how-to/use-besu-api/authenticate.md).
 
 ### `rpc-ws-authentication-enabled`
 
@@ -4373,7 +4461,7 @@ rpc-ws-authentication-jwt-algorithm="ES256"
 
 </Tabs>
 
-The [JWT key algorithm](../../how-to/use-besu-api/authenticate#1-generate-a-private-and-public-key-pair)
+The [JWT key algorithm](../../how-to/use-besu-api/authenticate.md#1-generate-a-private-and-public-key-pair)
 used to generate the keypair for JSON-RPC WebSocket authentication.
 Possible values are `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, and `ES512`.
 The default is `RS256`.
@@ -5553,5 +5641,5 @@ The displayed options are unstable and may change between releases.
 
 <!-- Links -->
 
-[push gateway integration]: ../../how-to/monitor/metrics.md#running-prometheus-with-besu-in-push-mode
+[push gateway integration]: ../../how-to/monitor/metrics.md#run-prometheus-with-besu-in-push-mode
 [JWT provider's public key file]: ../../how-to/use-besu-api/authenticate.md#jwt-public-key-authentication