Skip to content

Commit 4a04e3a

Browse files
stevehustevehu
committed
fixes #9 add several documents for concern
1 parent 8cdba02 commit 4a04e3a

20 files changed

Lines changed: 1808 additions & 73 deletions

‎src/SUMMARY.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@
1414
- [Path Resource](./concern/handler/path-resource.md)
1515
- [Virtual Host](./concern/handler/virtual-host.md)
1616
- [Middleware Handler](./concern/middleware-handler.md)
17+
- [API Key](./concern/middleware/api-key.md)
18+
- [Audit Handler](./concern/middleware/audit-handler.md)
19+
- [Basic Auth](./concern/middleware/basic-auth.md)
20+
- [Body Handler](./concern/middleware/body-handler.md)
1721
- [Header Handler](./concern/middleware/header-handler.md)
1822
- [IP Whitelist](./concern/middleware/ip-whitelist.md)
1923
- [Rate Limit](./concern/middleware/rate-limit.md)
@@ -28,11 +32,23 @@
2832
- [Request Transformer](./concern/interceptor/request-transformer.md)
2933
- [Response Transformer](./concern/interceptor/response-transformer.md)
3034
- [Admin Endpoint](./concern/admin-endpoint.md)
35+
- [Cache Explorer](./concern/admin/cache-explorer.md)
36+
- [Config Reload](./concern/admin/config-reload.md)
3137
- [Server Info](./concern/admin/server-info.md)
3238
- [Logger Handler](./concern/admin/logger-handler.md)
3339
- [Utility](./concern/utility/utility.md)
3440
- [Ldap Utility](./concern/utility/ladp-util.md)
3541
- [Module](./concern/module/module.md)
42+
- [Load Balance](./concern/module/load-balance.md)
43+
- [Cluster](./concern/module/cluster.md)
44+
- [Switch](./concern/module/switch.md)
45+
- [Consul Registry](./concern/module/consul-registry.md)
46+
- [Config](./concern/module/config.md)
47+
- [Cache Manager](./concern/module/cache-manager.md)
48+
- [Data Source](./concern/module/data-source.md)
49+
- [DB Provider](./concern/module/db-provider.md)
50+
- [Decryptor](./concern/module/decryptor.md)
51+
- [Http2 Client](./concern/module/http2-client.md)
3652
- [Monard Result](./concern/module/monard-result.md)
3753
- [Data Mask](./concern/module/data-mask.md)
3854
- [Portal Registry](./concern/module/portal-registry.md)

‎src/concern/admin/cache-explorer.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Cache Explorer
2+
3+
The `CacheExplorerHandler` is an admin endpoint that allows developers and operators to inspect the contents of the application's internal caches. It is particularly useful for debugging and verifying that data (such as JWKs, ensuring config reloading, etc.) is correctly cached.
4+
5+
## Overview
6+
7+
- **Type**: Admin Handler
8+
- **Class**: `com.networknt.cache.CacheExplorerHandler`
9+
- **Source**: `light-4j/cache-explorer`
10+
11+
## Usage
12+
13+
The handler operates by retrieving a specific cache by name via the `CacheManager` singleton.
14+
15+
### Endpoint
16+
17+
The endpoint is typically accessible via the admin port (default 8473) if configured using the [admin-endpoint][] module.
18+
19+
**Method**: `GET`
20+
**Path**: `/adm/cache` (or as configured in `handler.yml`)
21+
22+
### Parameters
23+
24+
| Parameter | Type | Required | Description |
25+
| :--- | :--- | :--- | :--- |
26+
| `name` | Query | Yes | The name of the cache to inspect (e.g., `jwk`, `jwt`, `myCache`). |
27+
28+
### Examples
29+
30+
#### Inspect JWK Cache
31+
32+
The `jwk` cache has special handling to format the output as a simple JSON map of strings.
33+
34+
Request:
35+
```
36+
GET /adm/cache?name=jwk
37+
```
38+
39+
Response:
40+
```json
41+
{
42+
"key1": "value1",
43+
"key2": "value2"
44+
}
45+
```
46+
47+
#### Inspect Generic Cache
48+
49+
For other caches, it returns the JSON representation of the cache's key-value pairs.
50+
51+
Request:
52+
```
53+
GET /adm/cache?name=myCache
54+
```
55+
56+
Response:
57+
```json
58+
{
59+
"user123": {
60+
"name": "John",
61+
"role": "admin"
62+
}
63+
}
64+
```
65+
66+
## Configuration
67+
68+
This module does not have a specific configuration file (e.g., `cache-explorer.yml`). It relies on the `CacheManager` being available and populated.
69+
70+
To use it, you must register the handler in `handler.yml` and add it to the admin chain (or another chain).
71+
72+
### `handler.yml` Registration
73+
74+
```yaml
75+
handler.handlers:
76+
# ... other handlers ...
77+
- com.networknt.cache.CacheExplorerHandler@cache_explorer
78+
79+
handler.chains.default:
80+
# ...
81+
- cache_explorer
82+
```
83+
84+
**Note**: In most standard `light-4j` templates, if you are using the unified `admin-endpoint`, this handler might not be wired by default and needs explicit registration if you want it exposed on the main port, or it might be auto-wired in the admin chain if the dependency is present (depending on the chassis version).
85+
86+
[admin-endpoint]: /concern/admin-endpoint/

‎src/concern/admin/config-reload.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Config Reload
2+
3+
The `config-reload` module provides admin endpoints to reload configuration files for specific modules or plugins at runtime without restarting the server. This is particularly useful in shared environments like a gateway where restarting would impact multiple services, or for dynamic updates to policies and rules.
4+
5+
## Endpoints
6+
7+
The module typically exposes two operations on the same path (e.g., `/adm/modules`).
8+
9+
### Get Registered Modules
10+
11+
- **Path**: `/adm/modules`
12+
- **Method**: `GET`
13+
- **Description**: Returns a list of all registered modules and plugins capable of being reloaded.
14+
- **Response**: A JSON array of class names (Strings).
15+
16+
### Trigger Config Reload
17+
18+
- **Path**: `/adm/modules`
19+
- **Method**: `POST`
20+
- **Description**: Triggers a config reload for the specified list of modules or plugins.
21+
- **Request Body**: A JSON array of class names (Strings) to reload. If the list is empty or contains "ALL", it attempts to reload all registered modules.
22+
- **Response**: A JSON array of the class names that were successfully reloaded.
23+
24+
## Configuration
25+
26+
### Module Configuration (`configreload.yml`)
27+
28+
The module itself is configured via `configReload.yml` (or `configReload.yaml`/`json`).
29+
30+
| Property | Description | Default |
31+
| :--- | :--- | :--- |
32+
| `enabled` | Enable or disable the config reload endpoints. | `true` |
33+
34+
### Handler Configuration (`handler.yml`)
35+
36+
To expose the endpoints, you need to configure them in your `handler.yml`.
37+
38+
```yaml
39+
paths:
40+
- path: '/adm/modules'
41+
method: 'get'
42+
exec:
43+
- admin
44+
- modules
45+
- path: '/adm/modules'
46+
method: 'post'
47+
exec:
48+
- admin
49+
- configReload
50+
```
51+
52+
And in `values.yml` (if using aliases):
53+
54+
```yaml
55+
handler.handlers:
56+
- com.networknt.config.reload.handler.ModuleRegistryGetHandler@modules
57+
- com.networknt.config.reload.handler.ConfigReloadHandler@configReload
58+
```
59+
60+
## Security
61+
62+
These are sensitive admin endpoints. They should be protected by OAuth 2.0 (requiring a specific scope like `admin` or `${serviceId}/admin`) or restricted by IP whitelist in a sidecar/gateway deployment.
63+
64+
## Dependency
65+
66+
Add the following dependency to your `pom.xml`:
67+
68+
```xml
69+
<dependency>
70+
<groupId>com.networknt</groupId>
71+
<artifactId>config-reload</artifactId>
72+
<version>${version.light-4j}</version>
73+
</dependency>
74+
```
75+
76+
## Usage Examples
77+
78+
### List Modules
79+
80+
```bash
81+
curl -k https://localhost:8443/adm/modules
82+
```
83+
84+
**Response:**
85+
```json
86+
[
87+
"com.networknt.limit.LimitHandler",
88+
"com.networknt.audit.AuditHandler",
89+
"com.networknt.router.middleware.PathPrefixServiceHandler",
90+
...
91+
]
92+
```
93+
94+
### Reload Config
95+
96+
Reload configuration for the Limit Handler and Path Prefix Handler.
97+
98+
```bash
99+
curl -k -X POST https://localhost:8443/adm/modules \
100+
-H 'Content-Type: application/json' \
101+
-d '[
102+
"com.networknt.limit.LimitHandler",
103+
"com.networknt.router.middleware.PathPrefixServiceHandler"
104+
]'
105+
```
106+
107+
**Response:**
108+
```json
109+
[
110+
"com.networknt.limit.LimitHandler",
111+
"com.networknt.router.middleware.PathPrefixServiceHandler"
112+
]
113+
```

‎src/concern/middleware/api-key.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# API Key Handler
2+
3+
For some legacy applications to migrate from a monolithic gateway to the light-gateway without changing any code on the consumer application, we need to support the API Key authentication on the light-gateway (LG) or client-proxy (LCP). The consumer application sends the API key in a header to authenticate itself on the light-gateway. Then the light-gateway will retrieve a JWT token to access the downstream API.
4+
5+
Only specific paths will have API Key set up, and the header name for each application might be different. To support all use cases, we add a list of maps to the configuration `apikey.yml` to `pathPrefixAuths` property.
6+
7+
Each config item will have `pathPrefix`, `headerName`, and `apiKey`. The handler will try to match the path prefix first and then get the input API Key from the header. After comparing with the configured API Key, the handler will return either `ERR10075` API_KEY_MISMATCH or pass the control to the next handler in the chain.
8+
9+
## Configuration
10+
11+
The configuration is managed by `ApiKeyConfig` and corresponds to `apikey.yml` (or `apikey.json`/`apikey.properties`).
12+
13+
### Configuration Properties
14+
15+
| Property | Type | Default | Description |
16+
| :--- | :--- | :--- | :--- |
17+
| `enabled` | boolean | `false` | Enable ApiKey Authentication Handler. |
18+
| `hashEnabled` | boolean | `false` | If API key hash is enabled. The API key will be hashed with PBKDF2WithHmacSHA1 before it is stored in the config file. It is more secure than putting the clear text key into the config file. |
19+
| `pathPrefixAuths` | list | `null` | A list of mappings between path prefix and the api key parameters. |
20+
21+
### Configuration Example (apikey.yml)
22+
23+
```yaml
24+
# ApiKey Authentication Security Configuration for light-4j
25+
# Enable ApiKey Authentication Handler, default is false.
26+
enabled: ${apikey.enabled:false}
27+
28+
# If API key hash is enabled. The API key will be hashed with PBKDF2WithHmacSHA1 before it is
29+
# stored in the config file. It is more secure than put the encrypted key into the config file.
30+
# The default value is false. If you want to enable it, you need to use the light-hash command line tool.
31+
hashEnabled: ${apikey.hashEnabled:false}
32+
33+
# path prefix to the api key mapping. It is a list of map between the path prefix and the api key
34+
# for apikey authentication. In the handler, it loops through the list and find the matching path
35+
# prefix. Once found, it will check if the apikey is equal to allow the access or return an error.
36+
pathPrefixAuths: ${apikey.pathPrefixAuths:}
37+
```
38+
39+
### Values Example (values.yml)
40+
41+
To enable the handler and configure paths, add the following to your `values.yml`:
42+
43+
```yaml
44+
# apikey.yml
45+
apikey.enabled: true
46+
apikey.pathPrefixAuths:
47+
- pathPrefix: /test1
48+
headerName: x-gateway-apikey
49+
apiKey: abcdefg
50+
- pathPrefix: /test2
51+
headerName: x-apikey
52+
apiKey: mykey
53+
```
54+
55+
JSON format example for `pathPrefixAuths` (useful for config server):
56+
57+
```json
58+
[{"pathPrefix":"/test1","headerName":"x-gateway-apikey","apiKey":"abcdefg"},{"pathPrefix":"/test2","headerName":"x-apikey","apiKey":"mykey"}]
59+
```
60+
61+
### Multiple Consumers for Same Path
62+
63+
Most services will have multiple consumers, and each consumer might have its own API key for authentication. You can define multiple entries for the same path prefix:
64+
65+
```yaml
66+
apikey.pathPrefixAuths:
67+
- pathPrefix: /test1
68+
headerName: x-gateway-apikey
69+
apiKey: abcdefg
70+
# The same prefix has another apikey header and value.
71+
- pathPrefix: /test1
72+
headerName: authorization
73+
apiKey: xyz
74+
```
75+
76+
## Security with Hash
77+
78+
Storing API keys in clear text is only recommended for testing. For production, enable hashing:
79+
80+
1. Enable hash in `values.yml`:
81+
```yaml
82+
apikey.hashEnabled: true
83+
```
84+
2. Generate the hash of your API key using the [light-hash](https://github.com/networknt/light-hash) utility.
85+
3. Use the generated hash string as the `apiKey` value in your configuration.
86+
87+
## Error Response
88+
89+
If the request path matches a configured prefix but the API key verification fails, the handler returns error `ERR10075`.
90+
91+
**Status Code**: 401
92+
**Code**: ERR10075
93+
**Message**: API_KEY_MISMATCH
94+
**Description**: APIKEY from header %s is not matched for request path prefix %s.
95+
96+
To prevent leaking sensitive information, the expected apiKey from the config file is not revealed in the error message.
97+
98+
## Usage
99+
100+
Register the `ApiKeyHandler` in your `handler.yml` chain.
101+
102+
```yaml
103+
handler.handlers:
104+
.
105+
- com.networknt.apikey.ApiKeyHandler@apikey
106+
107+
handler.chains.default:
108+
.
109+
- apikey
110+
.
111+
```
112+
113+
If you are using the Unified Security Handler, you can integrate the API Key handler there as well to support multiple authentication methods (ApiKey, Basic, OAuth2, SWT) simultaneously.

0 commit comments

Comments
 (0)