a95229daba
* fixes PIE-1374 add placeholders system to have global variables in markdown
implement and configure a first batch of variables for versions to be changeable
in only one place and change in the whole doc.
available placeholders are :
{{ versions.pantheon_stable }} -> the latest stable release
{{ versions.quickstart }} -> the latest quickstart release whicjh is currently
pointing to the same value as Pantheon as QS and Pantheon releases are in sync
but I still keep two separated values to make it clear.
Also includes few fixes like removing $ in front of bash commands and changed an
info block syntax
Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
5.1 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 to authorize JSON-RPC 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 hashsubcommand 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 or
--rpc-ws-authentication-enabled
options to require authentication for the JSON-RPC API.
Use the --rpc-http-authentication-credentials-file
and --rpc-ws-authentication-credentials-file
options to specify the credentials file.
!!!note
The --rpc-http-authentication-credentials-file
and --rpc-ws-authentication-credentials-file
options are not used when running Pantheon from the Docker image.
Use a bind mount to specify a credentials file with Docker.
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.
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
```