This repository has been archived by the owner on Sep 26, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 130
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
257cddf
commit c925a10
Showing
11 changed files
with
293 additions
and
136 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.