mirror of https://github.com/hyperledger/besu
An enterprise-grade Java-based, Apache 2.0 licensed Ethereum client https://wiki.hyperledger.org/display/besu
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
117 lines
5.9 KiB
117 lines
5.9 KiB
# Authentication and Authorization for JSON-RPC
|
|
|
|
Authentication identifies a user based on a username and password. Authorization verifies whether the user has
|
|
access to the JSON-RPC method they are requesting.
|
|
|
|
Pantheon uses the username and password to authenticate users and [JWT tokens](https://jwt.io/introduction/) to authorize JSON-RPC requests.
|
|
|
|
!!! important
|
|
To prevent interception of authentication credentials and authenticated tokens, make authenticated requests over HTTPS.
|
|
We recommended production deployments are run behind a network layer that provides SSL termination.
|
|
Pantheon does not provide a HTTPS connection natively.
|
|
|
|
## Credentials File
|
|
|
|
The credentials file is a `toml` file defining user details and the JSON-RPC methods to which they have access.
|
|
|
|
!!! example "Example Credentials File"
|
|
```toml
|
|
[Users.username1]
|
|
password = "$2a$10$l3GA7K8g6rJ/Yv.YFSygCuI9byngpEzxgWS9qEg5emYDZomQW7fGC"
|
|
permissions=["net:*","eth:blockNumber"]
|
|
|
|
[Users.username2]
|
|
password = "$2b$10$6sHt1J0MVUGIoNKvJiK33uaZzUwNmMmJlaVLkIwinkPiS1UBnAnF2"
|
|
permissions=["net:version","admin:*"]
|
|
```
|
|
|
|
Each user requiring JSON-RPC access is listed with:
|
|
|
|
* Username. `Users.` is mandatory and followed by the username. That is, replace `<username>` in `[Users.<username>]` with the username being defined.
|
|
* Hash of the user password. Use the [`password hash`](../Reference/Pantheon-CLI-Syntax.md#password) subcommand to generate the hash.
|
|
* JSON-RPC permissions.
|
|
|
|
!!! example "password hash Subcommand"
|
|
```bash
|
|
pantheon password hash --password=pegasys
|
|
```
|
|
|
|
## 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"]`.
|
|
|
|
If authentication is 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.
|
|
|
|
## Enabling Authentication
|
|
|
|
Use the [` --rpc-http-authentication-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-enabled) or
|
|
[`--rpc-ws-authentication-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-enabled)
|
|
options to require authentication for the JSON-RPC API.
|
|
|
|
Use the [`--rpc-http-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-credentials-file)
|
|
and [`--rpc-ws-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-credentials-file)
|
|
options to specify the [credentials file](#credentials-file).
|
|
|
|
!!!note
|
|
The [`--rpc-http-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-credentials-file)
|
|
and [`--rpc-ws-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-credentials-file)
|
|
options are not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md).
|
|
Use a bind mount to [specify a credentials file with Docker](../Getting-Started/Run-Docker-Image.md#credentials-files).
|
|
|
|
## Obtaining an Authentication Token
|
|
|
|
To obtain an authentication token, make a request to the `/login` endpoint with your username and password. Specify the
|
|
HTTP port or the WS port to obtain a token to authenticate over HTTP or WS respectively. A different token is required
|
|
for HTTP and WS.
|
|
|
|
!!! example
|
|
```bash tab="Obtain Token for HTTP"
|
|
curl -X POST --data '{"username":"username1","password":"pegasys"}' <JSON-RPC-http-hostname:http-port>/login
|
|
```
|
|
|
|
```bash tab="Example for HTTP"
|
|
curl -X POST --data '{"username":"username1","password":"pegasys"}' http://localhost:8545/login
|
|
```
|
|
|
|
```bash tab="Obtain Token for WS"
|
|
curl -X POST --data '{"username":"username1","password":"pegasys"}' <JSON-RPC-ws-hostname:ws-port>/login
|
|
```
|
|
|
|
```bash tab="Example for WS"
|
|
curl -X POST --data '{"username":"username1","password":"pegasys"}' http://localhost:8546/login
|
|
```
|
|
|
|
```json tab="JSON result"
|
|
{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MDYwNCwiZXhwIjoxNTUwNDYwOTA0fQ.l2Ycqzl_AyvReXBeUSayOlOMS_E8-DCuz3q0Db0DKD7mqyl6q-giWoEtfdWzUEvZbRRi2_ecKO3N6JkXq7zMKQAJbVAEzobfbaaXWcQEpHOjtnK4_Yz-UPyKiXtu7HGdcdl5Tfx3dKoksbqkBl3U3vFWxzmFnuu3dAISfVJYUNA"}
|
|
```
|
|
|
|
Authentication tokens expire 5 minutes after being generated. It is necessary to generate a new authentication
|
|
token if access is required after token expiration.
|
|
|
|
## Using 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 by the [`login` request](#obtaining-an-authentication-token).
|
|
|
|
### Curl
|
|
|
|
Specify the `Bearer` in the header.
|
|
|
|
!!! example
|
|
```bash tab="curl Request with Authentication Placeholders"
|
|
curl -X POST -H 'Authorization: Bearer <JWT_TOKEN>' -d '{"jsonrpc":"2.0","method":"<API_METHOD>","params":[],"id":1}' <JSON-RPC-http-hostname:port>
|
|
```
|
|
|
|
```bash tab="curl Request with Authentication"
|
|
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
|
|
``` |