update docs

Signed-off-by: Jack Ding <jackding@gmail.com>

Author: jzding

AUTHENTICATION.md

@@ -7,10 +7,17 @@ This document describes how to configure mTLS (mutual TLS) and OAuth authenticat
 The REST API supports two authentication mechanisms that can be applied to specific endpoints:
 
 1. **mTLS (Mutual TLS)**: Client certificate-based authentication using OpenShift Service CA
-2. **OAuth**: Bearer token-based authentication using OpenShift's built-in OAuth server and JWT tokens
+2. **OAuth**: Bearer token-based authentication using OpenShift's built-in OAuth server and JWT tokens with **strict validation**
 
 Both mechanisms can be enabled independently or together for enhanced security. This unified approach works seamlessly for both single node and multi-node OpenShift clusters, providing enterprise-grade security with minimal complexity.
 
+### Security Guarantees
+
+- **No Authentication Bypass**: When OAuth is enabled, all requests must include valid JWT tokens
+- **Strict Issuer Validation**: Token issuer must exactly match the configured OAuth issuer
+- **Comprehensive Token Validation**: Expiration, audience, and signature verification
+- **Clear Error Messages**: Authentication failures return specific error codes without exposing sensitive information
+
 ## Protected vs Public Endpoints
 
 ### Protected Endpoints (Require Authentication)
@@ -326,6 +333,47 @@ curl -X GET https://localhost:9043/api/ocloudNotifications/v2/health \
   --cacert /etc/cloud-event-proxy/ca-bundle/service-ca.crt
 ```
 
+## OAuth Security Implementation
+
+### Strict Validation Features
+
+The OAuth implementation includes comprehensive security measures:
+
+1. **Issuer Validation**:
+   ```
+   Token issuer mismatch: expected https://oauth-openshift.apps.cluster.com, got https://dummy.com
+   ```
+   - Tokens from unauthorized issuers are immediately rejected
+   - No bypass mechanisms or fallbacks
+
+2. **Expiration Checking**:
+   ```
+   Token expired
+   ```
+   - Expired tokens are rejected with clear error messages
+   - Time-based validation prevents replay attacks
+
+3. **Audience Validation**:
+   ```
+   Token audience validation failed
+   ```
+   - Tokens must contain the required audience claim
+   - Prevents token misuse across different services
+
+4. **Missing Token Handling**:
+   ```
+   Authorization header required
+   Bearer token required
+   ```
+   - Clear error messages for missing or malformed tokens
+   - Proper HTTP status codes (401 Unauthorized)
+
+### Security Libraries
+
+- **JWT Library**: Uses `golang-jwt/jwt/v5` for secure token parsing and validation
+- **Cryptographic Verification**: Full signature validation against JWKS endpoints
+- **Memory Safety**: Secure token handling without exposing sensitive data in logs
+
 ## Security Considerations
 
 1. **Certificate Management**
@@ -334,7 +382,8 @@ curl -X GET https://localhost:9043/api/ocloudNotifications/v2/health \
    - Consider using a certificate manager in production
 
 2. **OAuth Security**
-   - Use a proper JWT validation library in production
+   - **Strict Validation**: All tokens are validated against the exact configured issuer
+   - **No Bypass Mechanisms**: Authentication cannot be bypassed with mismatched issuers
    - Implement token caching and JWKS key rotation
    - Validate all claims (issuer, audience, scopes, expiration)
 

OPENSHIFT_AUTHENTICATION.md

@@ -100,6 +100,43 @@ The same configuration works for both single node and multi-node clusters:
 }
 ```
 
+### Dynamic Cluster Configuration
+
+For environments with multiple clusters or dynamic cluster names, use the `CLUSTER_NAME` environment variable:
+
+#### Environment Variable Configuration
+```bash
+# Default cluster name (used by ptp-operator)
+export CLUSTER_NAME="openshift.local"
+
+# Custom cluster name
+export CLUSTER_NAME="cnfdg4.sno.ptp.eng.rdu2.dc.redhat.com"
+
+# OAuth URLs are automatically generated as:
+# https://oauth-openshift.apps.${CLUSTER_NAME}
+```
+
+#### Template Configuration
+```json
+{
+  "enableMTLS": true,
+  "useServiceCA": true,
+  "caCertPath": "/etc/cloud-event-proxy/ca-bundle/service-ca.crt",
+  "serverCertPath": "/etc/cloud-event-proxy/server-certs/tls.crt",
+  "serverKeyPath": "/etc/cloud-event-proxy/server-certs/tls.key",
+  "enableOAuth": true,
+  "useOpenShiftOAuth": true,
+  "oauthIssuer": "https://oauth-openshift.apps.{{.ClusterName}}",
+  "oauthJWKSURL": "https://oauth-openshift.apps.{{.ClusterName}}/oauth/jwks",
+  "requiredScopes": ["user:info"],
+  "requiredAudience": "openshift",
+  "serviceAccountName": "cloud-event-proxy-sa",
+  "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token"
+}
+```
+
+This ensures OAuth issuer URLs match your actual OpenShift cluster configuration and prevents authentication bypass due to issuer mismatches.
+
 ### Key Configuration Fields
 
 #### mTLS Configuration:
@@ -350,4 +387,3 @@ The Service CA + OpenShift OAuth approach provides:
 - ✅ **Cost Effective**: No additional licensing or resource costs
 
 This approach scales from single node to large multi-node clusters without any configuration changes, making it the ideal solution for OpenShift deployments of any size.
-

README.md

@@ -9,11 +9,25 @@ The REST-API specification below is generated by Swagger tools. Please refer to
 
 ## Authentication
 
-This REST API supports enterprise-grade authentication using mTLS and OAuth. For detailed configuration instructions, see:
+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).