[WIP] Add mTLS and OAuth authentication to event REST API

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
+
+- **Strict OAuth Validation**: JWT tokens are validated against the configured issuer with no bypass mechanisms
+- **Issuer Verification**: Token issuer must exactly match the configured OAuth issuer
+- **Expiration Checking**: Expired tokens are rejected with clear error messages
+- **Audience Validation**: Tokens must contain the required audience claim
+- **mTLS Certificate Validation**: Client certificates are verified against the configured CA
+
+### Recent Security Improvements
+
+- **Fixed OAuth Security Vulnerability** (v2.1.0): Implemented proper OAuth token validation to prevent unauthorized access
+- **Added JWT Library Support**: Uses `golang-jwt/jwt/v5` for secure token parsing and validation
+- **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,12 @@
+{
+  "enableMTLS": true,
+  "caCertPath": "/etc/certs/ca.crt",
+  "serverCertPath": "/etc/certs/server.crt",
+  "serverKeyPath": "/etc/certs/server.key",
+
+  "enableOAuth": true,
+  "oauthIssuer": "https://your-oauth-provider.com",
+  "oauthJWKSURL": "https://your-oauth-provider.com/.well-known/jwks.json",
+  "requiredScopes": ["subscription:create", "events:read"],
+  "requiredAudience": "rest-api-service"
+}

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"}'
+```