mirror of https://github.com/hyperledger/besu
MadelineMurray
6 years ago
committed by
GitHub
parent
2de26d69c1
commit
9f597293cf
@ -0,0 +1,96 @@ |
||||
# Authentication and Authorization |
||||
|
||||
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 API requests. |
||||
|
||||
!!! important |
||||
Authenticated requests must be made over HTTPS. HTTPS is encrypted which prevents eavesdropping on the connection |
||||
to obtain the JWT token from the requests. |
||||
|
||||
## 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). |
||||
|
||||
## Obtaining an Authentication Token |
||||
|
||||
To obtain an authentication token, make a request to the `/login` endpoint with your username and password. |
||||
|
||||
!!! example |
||||
```bash tab="curl HTTPS request" |
||||
$ curl -X POST --data '{"username":"username1","password":"pegasys"}' <JSON-RPC-https-endpoint:port>/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-https-endpoint: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}' https://localhost:8545 |
||||
``` |
||||
@ -0,0 +1,19 @@ |
||||
description: Pantheon JSON-RPC API reference |
||||
<!--- END of page meta data --> |
||||
|
||||
# JSON-RPC API Overview |
||||
|
||||
The Pantheon JSON-RPC API uses the [JSON-RPC v2.0](https://www.jsonrpc.org/specification) specification of the JSON-RPC protocol. |
||||
|
||||
The [JSON](http://json.org/) (RFC 4627) format which represents |
||||
objects and data fields as collections of name/value pairs, in a readable, hierarchical form. |
||||
Values have specific data types such as quantities (decimal integers, hexadecimal numbers, strings) and |
||||
unformatted data (byte arrays, account addresses, hashes, and bytecode arrays). |
||||
|
||||
RPC is the remote procedure call protocol (RFC 1831). The protocol is stateless and transport agnostic in that the concepts |
||||
can be used within the same process, over sockets, over HTTP, or in various message passing environments. |
||||
|
||||
* [Using the Pantheon JSON-RPC API](Using-JSON-RPC-API.md) |
||||
* [Authentication](Authentication.md) |
||||
* [JSON-RPC API Methods](../Reference/JSON-RPC-API-Methods.md) |
||||
* [JSON-RPC API Objects](../Reference/JSON-RPC-API-Objects.md) |
||||
@ -1,12 +0,0 @@ |
||||
description: Pantheon JSON-RPC API reference |
||||
<!--- END of page meta data --> |
||||
|
||||
# JSON-RPC API overview |
||||
|
||||
The Pantheon JSON-RPC API uses the [JSON](http://json.org/) (RFC 4627) data format, which can represent objects and data fields as collections of name/value pairs, in a relatively readable, hierarchical form. Values have specific data types such as QUANTITIES (decimal integers, hexadecimal numbers, strings) and UNFORMATTED DATA (byte arrays, account addresses, hashes, and bytecode arrays). |
||||
|
||||
RPC is the remote procedure call protocol (RFC 1831), which is stateless and transport agnostic in that the concepts can be used within the same process, over sockets, over HTTP, or in many various message passing environments. |
||||
|
||||
* [Using the Pantheon JSON-RPC API](Using-JSON-RPC-API.md) |
||||
* [JSON-RPC API Methods](JSON-RPC-API-Methods.md) |
||||
* [JSON-RPC API Objects](JSON-RPC-API-Objects.md) |
||||
Loading…
Reference in new issue