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 hash 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 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
```

5.1 KiB Raw Blame History