Enforce mTLS + OAuth on all event REST APIs (CNF-26787)

.gitignore

@@ -16,6 +16,8 @@
 cover.out
 pub.json
 sub.json
+# Per-clientID subscription store files written by tests (storePath ".")
+v2/????????-????-????-????-????????????.json
 
 .idea
 .cache

README.md

@@ -7,6 +7,27 @@
 
 The REST-API specification below is generated by Swagger tools. Please refer to the [Developers Guide](docs/dev-readme.md) on how to use Swagger to generate specs and documentations.
 
+## Authentication
+
+This REST API supports enterprise-grade authentication using mTLS and OAuth with **strict security validation**. For detailed configuration instructions, see:
+
+- **[Authentication Configuration](AUTHENTICATION.md)** - Complete guide for configuring mTLS and OAuth authentication
+- **[OpenShift Authentication](OPENSHIFT_AUTHENTICATION.md)** - OpenShift-specific deployment guide with native Service CA and OAuth server integration
+
+### Security Features
+
+- **Server-side OAuth Validation**: Bearer tokens are validated by the Kubernetes TokenReview API (issuer, signature, expiry, audience) with no bypass mechanisms
+- **Audience Binding**: `requiredAudiences` ensures tokens minted for other services are rejected
+- **Expiration Checking**: Expired tokens are rejected by TokenReview
+- **mTLS Certificate Validation**: Client certificates are verified against the configured CA
+- **SSRF Hardening**: Caller-supplied endpoint URIs are validated (resolve-then-connect, no redirects) before the server dials them
+
+### Recent Security Improvements
+
+- **TokenReview-based OAuth**: Token validation is delegated to the Kubernetes API server; the library performs no local JWT parsing or JWKS fetching
+- **Bounded Token Cache**: Validated results are cached briefly with a short TTL to bound TokenReview load
+- **Enhanced Error Handling**: Clear error messages for authentication failures without exposing sensitive information
+
 ## O-RAN Compliant REST API Specification
 
 Starting from release [v1.21.0](https://github.com/redhat-cne/rest-api/releases/tag/v1.21.0), the REST API implemented in this repo is compliant with [O-RAN O-Cloud Notification API Specification for Event Consumers 4.0](https://orandownloadsweb.azurewebsites.net/specifications).

auth-config-example.json

@@ -0,0 +1,14 @@
+{
+  "enableMTLS": true,
+  "caCertPath": "/etc/certs/ca.crt",
+  "serverCertPath": "/etc/certs/server.crt",
+  "serverKeyPath": "/etc/certs/server.key",
+
+  "enableOAuth": true,
+  "requiredAudiences": ["https://kubernetes.default.svc"],
+  "serviceAccountName": "cloud-event-proxy-sa",
+  "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token",
+
+  "tlsMinVersion": "VersionTLS12",
+  "tlsCipherSuites": []
+}

docs/dev-readme.md

@@ -8,11 +8,36 @@ Open https://editor.swagger.io/ in a browser. Click `File` - `Import file` from
 
 ![Alt text](swagger-editor.png "Swagger Editor")
 
+The updated Swagger specification includes:
+
+- **Authentication Documentation**: Comprehensive mTLS and OAuth 2.0 security definitions
+- **Enhanced API Descriptions**: Detailed endpoint descriptions with authentication requirements
+- **Security Schemes**: Proper documentation of dual authentication (mTLS + OAuth)
+- **Error Responses**: Complete 401 Unauthorized responses for protected endpoints
+- **Tags and Categories**: Organized endpoints by functionality (Subscriptions, Publishers, Events, HealthCheck, Authentication)
+
 ### Interact with REST-API in Swagger UI
 
 You can interact with API endpoint by click `Try it out`, enter required parameters and click `Execute`.
 This requires a REST-API server to be deployed at backend and accessible from localhost.
 
+**Important**: When testing authenticated endpoints, you must:
+
+1. **Configure mTLS**: Set up client certificates in your HTTP client
+2. **Provide OAuth Token**: Include valid Bearer token in Authorization header
+3. **Use HTTPS**: Ensure secure connection for mTLS authentication
+
+Example authentication setup:
+```bash
+# For mTLS
+--cert /path/to/client.crt \
+--key /path/to/client.key \
+--cacert /path/to/ca.crt \
+
+# For OAuth
+-H "Authorization: Bearer your_jwt_token_here"
+```
+
 ## Generate Swagger Spec
 
 The swagger documentation of this repo is generated using tools and annotations based on https://github.com/go-swagger/go-swagger. The current version of go-swagger has an issue of generating empty definitions with go 1.20+. The workaround is to run swagger tool from docker.
@@ -32,6 +57,12 @@ SWAGGER_GENERATE_EXTENSION=false swagger generate spec --input tags.json -o swag
 swagger validate swagger.json
 ```
 
+**Note**: The swagger.json file has been enhanced with:
+- Security definitions for mTLS and OAuth 2.0
+- Authentication requirements for protected endpoints
+- Comprehensive error response documentation
+- Updated API descriptions and metadata
+
 ## Generate REST API Documentation
 
 Use the following commands to generate swagger documentation markdown file [rest_api_v2.md](rest_api_v2.md).
@@ -41,3 +72,44 @@ Use the following commands to generate swagger documentation markdown file [rest
 cd $WORKSPACE/redhat-cne/rest-api/v2
 swagger generate markdown --skip-validation --output=../docs/rest_api_v2.md
 ```
+
+The generated documentation includes:
+
+- **Security Model**: Complete authentication and authorization documentation
+- **Endpoint Reference**: All endpoints with authentication requirements
+- **Request/Response Examples**: Sample payloads and responses
+- **Error Handling**: Comprehensive error response documentation
+- **Authentication Guide**: mTLS and OAuth integration examples
+
+## Authentication Testing
+
+When testing the API with authentication enabled:
+
+### mTLS Testing
+```bash
+curl -X POST https://localhost:9043/api/ocloudNotifications/v2/subscriptions \
+  --cert /path/to/client.crt \
+  --key /path/to/client.key \
+  --cacert /path/to/ca.crt \
+  -H "Content-Type: application/json" \
+  -d '{"EndpointUri": "http://example.com/callback", "ResourceAddress": "/test/resource"}'
+```
+
+### OAuth Testing
+```bash
+curl -X POST https://localhost:9043/api/ocloudNotifications/v2/subscriptions \
+  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
+  -H "Content-Type: application/json" \
+  -d '{"EndpointUri": "http://example.com/callback", "ResourceAddress": "/test/resource"}'
+```
+
+### Dual Authentication Testing
+```bash
+curl -X POST https://localhost:9043/api/ocloudNotifications/v2/subscriptions \
+  --cert /path/to/client.crt \
+  --key /path/to/client.key \
+  --cacert /path/to/ca.crt \
+  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
+  -H "Content-Type: application/json" \
+  -d '{"EndpointUri": "http://example.com/callback", "ResourceAddress": "/test/resource"}'
+```