1  # JWT Token Authentication via URL Query Parameters
  2  
  3  This document describes the enhanced JWT authentication functionality that allows passing JWT tokens via URL query parameters in addition to the traditional Authorization header method.
  4  
  5  ## Overview
  6  
  7  The proxy now supports multiple methods for JWT token authentication:
  8  
  9  1. **Authorization Header** (existing method)
 10  2. **URL Query Parameters** (new method)
 11  
 12  Both methods can be used interchangeably and provide the same level of security and functionality.
 13  
 14  ## Supported Authentication Methods
 15  
 16  ### 1. Authorization Header (Existing)
 17  
 18  ```bash
 19  curl -X POST "http://proxy-url/ethereum/mainnet" \
 20    -H "Content-Type: application/json" \
 21    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
 22    -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
 23  ```
 24  
 25  ### 2. URL Query Parameters (New)
 26  
 27  The following query parameter names are supported for JWT token authentication:
 28  
 29  #### Using `token` parameter:
 30  ```bash
 31  curl -X POST "http://proxy-url/ethereum/mainnet?token=YOUR_JWT_TOKEN" \
 32    -H "Content-Type: application/json" \
 33    -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
 34  ```
 35  
 36  #### Using `jwt` parameter:
 37  ```bash
 38  curl -X POST "http://proxy-url/ethereum/mainnet?jwt=YOUR_JWT_TOKEN" \
 39    -H "Content-Type: application/json" \
 40    -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
 41  ```
 42  
 43  #### Using `access_token` parameter:
 44  ```bash
 45  curl -X POST "http://proxy-url/ethereum/mainnet?access_token=YOUR_JWT_TOKEN" \
 46    -H "Content-Type: application/json" \
 47    -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
 48  ```
 49  
 50  ## Security Features
 51  
 52  ### Automatic Parameter Sanitization
 53  
 54  When JWT tokens are passed via query parameters, the proxy automatically:
 55  
 56  1. **Extracts** the JWT token from the query parameters
 57  2. **Validates** the token using the same validation logic as header-based authentication
 58  3. **Removes all query parameters** from the request before forwarding to blockchain providers (since no other query parameters are expected for RPC calls)
 59  
 60  Example:
 61  ```bash
 62  # Original request
 63  GET /ethereum/mainnet?token=jwt123
 64  
 65  # Forwarded to provider (all query params removed)
 66  GET /ethereum/mainnet
 67  ```
 68  
 69  ### Token Priority
 70  
 71  If both Authorization header and query parameters are present, the system follows this priority:
 72  
 73  1. **Authorization Header** - checked first
 74  2. **Query Parameters** - checked if no valid Authorization header found
 75     - `token` parameter
 76     - `jwt` parameter  
 77     - `access_token` parameter
 78  
 79  ## Getting JWT Tokens
 80  
 81  To obtain JWT tokens for authentication, use the provided script:
 82  
 83  ```bash
 84  ./go-auth-service/get_proxy_token.sh [environment]
 85  ```
 86  
 87  Available environments:
 88  - `local` (default) - http://localhost:8081
 89  - `test` - https://test.eth-rpc.status.im  
 90  - `prod` - https://prod.eth-rpc.status.im
 91  
 92  Example:
 93  ```bash
 94  # Get token for local development
 95  ./go-auth-service/get_proxy_token.sh local
 96  
 97  # Get token for test environment
 98  ./go-auth-service/get_proxy_token.sh test
 99  ```
100  
101  ## Rate Limiting
102  
103  Rate limiting works identically for both authentication methods:
104  - Same token = same rate limit counter
105  - Rate limits are applied per token, regardless of how the token was provided
106  - Headers `X-RateLimit-Limit` and `X-RateLimit-Remaining` are set for both methods
107  
108  ## Caching
109  
110  JWT token validation caching works the same for both methods:
111  - Tokens are cached after successful validation
112  - Cache keys are based on the token value, not the source method
113  - `X-Cache-Status` header indicates cache hit/miss status
114  
115  ## Testing
116  
117  Use the provided test script to verify functionality:
118  
119  ```bash
120  ./test_jwt_url_auth.sh
121  ```
122  
123  The test script verifies:
124  - Authorization header method still works
125  - All query parameter methods work
126  - Parameter sanitization works correctly
127  - Requests without authentication are properly rejected
128  
129  ## Error Handling
130  
131  Authentication errors are handled identically for both methods:
132  - `401 Unauthorized` for invalid or missing tokens
133  - `429 Too Many Requests` for rate limit violations
134  - Same error response format and status codes