Skip to content

Commit fb5e823

Browse files
thivinduthivindu
committed
Implement API key policy
1 parent 4b91145 commit fb5e823

File tree

5 files changed

+562
-0
lines changed

5 files changed

+562
-0
lines changed

‎docs/gateway/policies/apikey-authentication.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
Introduce **APIKeyAuthentication Policy (v1.0.0)** featuring:
2+
- API key validation from headers or query parameters
3+
- Configurable key extraction with optional prefix stripping
4+
- Flexible authentication source configuration (header/query)
5+
- Pre-shared key validation against configured key lists
6+
- Request context enrichment with authentication metadata
7+
8+
## Configuration Schema
9+
10+
```yaml
11+
name: APIKeyAuthentication
12+
version: v1.0.0
13+
description: |
14+
Implements API Key Authentication to protect APIs with pre-shared API keys.
15+
Validates API keys from request headers or query parameters against a configured
16+
list of valid keys and sets authentication metadata in the request context.
17+
18+
parameters:
19+
type: object
20+
additionalProperties: false
21+
properties:
22+
key:
23+
type: string
24+
required: true
25+
description: |
26+
The name of the header or query parameter that contains the API key.
27+
For headers: case-insensitive matching is used (e.g., "X-API-Key", "Authorization")
28+
For query parameters: exact name matching is used (e.g., "api_key", "token")
29+
validation:
30+
minLength: 1
31+
maxLength: 128
32+
33+
in:
34+
type: string
35+
required: true
36+
description: |
37+
Specifies where to look for the API key.
38+
Must be either "header" or "query".
39+
enum:
40+
- "header"
41+
- "query"
42+
43+
value-prefix:
44+
type: string
45+
required: false
46+
description: |
47+
Optional prefix that should be stripped from the API key value before validation.
48+
Case-insensitive matching and removal. Common use case is "Bearer " for Authorization headers.
49+
If specified, the prefix will be removed from the extracted value.
50+
validation:
51+
minLength: 1
52+
maxLength: 64
53+
54+
required:
55+
- key
56+
- in
57+
58+
initParameters:
59+
type: object
60+
properties: {}
61+
```
62+
63+
## Configuration Notes
64+
65+
The APIKeyAuthentication policy configuration only requires user provided parameters when attaching to an API or API resource. The policy does not define system-level initialization parameters (`initParameters` is empty), meaning all configuration is done by the API developer who attaches this policy to an API or API resource.
66+
67+
Valid API keys are generated by the gateway, management portal, or developer portal. When a request is received, the API key sent in the request will be validated against the keys generated by these services. The policy handles the extraction and validation logic, while the actual key generation and management is handled by the platform's key management system.
68+
69+
## Example API/Per-Route Configurations
70+
71+
### Header-based API Key Authentication
72+
73+
```yaml
74+
# API key in custom header
75+
name: APIKeyAuthentication
76+
version: v1.0.0
77+
params:
78+
key: X-API-Key
79+
in: header
80+
```
81+
82+
### Authorization Header with Bearer Prefix
83+
84+
```yaml
85+
# API key in Authorization header with Bearer prefix
86+
name: APIKeyAuthentication
87+
version: v1.0.0
88+
params:
89+
key: Authorization
90+
in: header
91+
value-prefix: "Bearer "
92+
```
93+
94+
### Query Parameter Authentication
95+
96+
```yaml
97+
# API key as query parameter
98+
name: APIKeyAuthentication
99+
version: v1.0.0
100+
params:
101+
key: api_key
102+
in: query
103+
```
104+
105+
### Custom Header with Prefix
106+
107+
```yaml
108+
# API key in custom header with custom prefix
109+
name: APIKeyAuthentication
110+
version: v1.0.0
111+
params:
112+
key: X-Custom-Auth
113+
in: header
114+
value-prefix: "ApiKey "
115+
```

‎gateway/gateway-controller/default-policies/api-key-auth-v1.0.yaml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: APIKeyAuthentication
2+
version: v1.0.0
3+
description: |
4+
Implements API Key Authentication to protect APIs with pre-shared API keys.
5+
Validates API keys from request headers or query parameters against a configured
6+
list of valid keys and sets authentication metadata in the request context.
7+
8+
parameters:
9+
type: object
10+
additionalProperties: false
11+
properties:
12+
key:
13+
type: string
14+
required: true
15+
description: |
16+
The name of the header or query parameter that contains the API key.
17+
For headers: case-insensitive matching is used (e.g., "X-API-Key", "Authorization")
18+
For query parameters: exact name matching is used (e.g., "api_key", "token")
19+
validation:
20+
minLength: 1
21+
maxLength: 128
22+
23+
in:
24+
type: string
25+
required: true
26+
description: |
27+
Specifies where to look for the API key.
28+
Must be either "header" or "query".
29+
enum:
30+
- "header"
31+
- "query"
32+
33+
value-prefix:
34+
type: string
35+
required: false
36+
description: |
37+
Optional prefix that should be stripped from the API key value before validation.
38+
Case-insensitive matching and removal. Common use case is "Bearer " for Authorization headers.
39+
If specified, the prefix will be removed from the extracted value.
40+
validation:
41+
minLength: 1
42+
maxLength: 64
43+
44+
required:
45+
- key
46+
- in
47+
48+
initParameters:
49+
type: object
50+
properties: {}

0 commit comments

Comments
 (0)