[WIP] Add mTLS and OAuth authentication to event REST API #109
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jzding
force-pushed
the
secure-event-api
branch
3 times, most recently
from
4e118ae to
033d427
Compare
jzding
changed the title
jzding
force-pushed
the
secure-event-api
branch
2 times, most recently
from
d7840e3 to
71e1f18
Compare
jzding
changed the title
jzding
changed the title
This commit introduces comprehensive authentication support for the cloud event notifications REST API v2, enabling secure communication in production environments. **Authentication Methods:** - mTLS (Mutual TLS) authentication with client certificate validation - OAuth JWT token authentication with strict issuer validation - Support for both OpenShift OAuth server and Kubernetes ServiceAccount tokens - Flexible authentication configuration via JSON config files **OpenShift Integration:** - Native OpenShift Service CA integration for automatic certificate management - OpenShift OAuth server integration for JWT token validation - ServiceAccount-based authentication for pod-to-pod communication - Dynamic cluster name configuration for multi-cluster deployments **Security Features:** - Strict OAuth validation with issuer verification - Comprehensive token validation (expiration, audience, signature) - Client certificate validation with configurable CA trust - Path-based authentication middleware (health endpoints bypass auth) - Localhost connection support for internal health checks **Configuration Options:** - JSON-based authentication configuration - Support for OpenShift Service CA and cert-manager - Configurable OAuth scopes and audience validation - Environment-based cluster name configuration **Core Implementation:** - `v2/auth.go`: OAuth and mTLS authentication middleware and validation logic - `v2/server.go`: Enhanced server with authentication support and TLS configuration - `go.mod`/`go.sum`: Added golang-jwt/jwt/v5 dependency for JWT validation **Documentation:** - `AUTHENTICATION.md`: Comprehensive authentication configuration guide - `OPENSHIFT_AUTHENTICATION.md`: OpenShift-specific deployment and configuration - `README.md`: Updated with authentication feature overview and links **Examples and Templates:** - `auth-config-example.json`: Example authentication configuration - `examples/openshift-auth-config.json`: OpenShift-specific configuration template - `examples/openshift-manifests.yaml`: Complete OpenShift deployment manifests - `examples/README.md`: Documentation for example configurations - **Multi-Issuer Support**: Accepts both OpenShift OAuth tokens and Kubernetes ServiceAccount tokens - **Strict Validation**: No authentication bypass mechanisms, exact issuer matching required - **Comprehensive Error Handling**: Clear error messages without exposing sensitive information - **Production Ready**: Designed for secure production deployments in OpenShift clusters - Authentication is optional and configurable - Existing deployments continue to work without authentication - Health check endpoints remain accessible for monitoring - Graceful fallback for non-authenticated deployments This implementation provides enterprise-grade security for cloud event notifications while maintaining compatibility with existing deployments and supporting flexible authentication scenarios across different Kubernetes environments. Resolves authentication requirements for secure cloud event communication in production OpenShift environments. Signed-off-by: Jack Ding <jackding@gmail.com>
jzding
changed the title
jzding
force-pushed
the
secure-event-api
branch
from
71e1f18 to
c342267
Compare
Signed-off-by: Jack Ding <jackding@gmail.com>
jzding
force-pushed
the
secure-event-api
branch
from
41968ea to
c33868c
Compare
- Enhanced swagger.json with mTLS and OAuth 2.0 security definitions - Added authentication requirements for protected endpoints (POST, DELETE operations) - Updated API descriptions with detailed authentication documentation - Added comprehensive error response documentation (401 Unauthorized) - Expanded tags.json with detailed API categories and descriptions - Updated dev-readme.md with authentication testing examples - Regenerated rest_api_v2.md with complete API reference including security model - Added security schemes documentation for dual authentication (mTLS + OAuth) - Included contact information and license details in API specification - Validated swagger specification for compliance with OpenAPI 2.0 standard The updated documentation provides complete guidance for: - mTLS certificate authentication setup - OAuth 2.0 Bearer token authentication - Dual authentication testing scenarios - Protected vs public endpoint identification - Comprehensive error handling documentation Signed-off-by: Jack Ding <jackding@gmail.com>
Signed-off-by: Jack Ding <jackding@gmail.com>
This commit updates the O-RAN Cloud Notification API specification (oran.md)
to include comprehensive authentication and security documentation:
Authentication Mechanisms:
- Added new Chapter 4: Authentication and Security
- Documented mTLS (Mutual TLS) authentication at transport layer
- Documented OAuth 2.0 authentication at application layer
- Described dual authentication approach (mTLS + OAuth)
Security Features:
- Certificate-based client authentication (X.509)
- Bearer token authentication (JWT - JSON Web Tokens)
- Support for OpenShift OAuth and Kubernetes ServiceAccount tokens
- Token validation: issuer, audience, signature, expiration, scopes
- Certificate verification against trusted CA
- OpenShift Service CA integration
Authentication Requirements:
- Added authentication requirements table by endpoint and HTTP method
- POST /subscriptions: requires authentication (mTLS and/or OAuth)
- DELETE /subscriptions: requires authentication
- DELETE /subscriptions/{id}: requires authentication
- GET endpoints: public (no authentication required)
- /health endpoint: always public
Response Codes:
- Added 401 Unauthorized responses to POST and DELETE operations
- Updated response code descriptions with authentication details
- Clarified error scenarios for failed authentication
Security Considerations:
- Certificate management best practices
- Token management and lifecycle
- RBAC integration with Kubernetes ServiceAccount tokens
- Localhost exception for Helper/Sidecar containers
- Defense-in-depth security model
Configuration Examples:
- mTLS client certificate authentication example
- OAuth 2.0 Bearer token authentication example
- Dual authentication (mTLS + OAuth) example
- curl command examples for all authentication scenarios
Updated Documentation:
- Enhanced Authorization header description with OAuth details
- Added note about mTLS certificate verification at TLS layer
- Updated Table of Contents with new authentication chapter
- Maintained O-RAN specification formatting and structure
This update aligns the O-RAN specification with the implemented
authentication features in rest-api v2 and provides comprehensive
guidance for Event Consumers implementing secure API access.
Signed-off-by: Jack Ding <jackding@gmail.com>
Signed-off-by: Jack Ding <jackding@gmail.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Assisted by Cursor AI
This PR introduces enterprise-grade authentication support for the cloud event notifications REST API, enabling secure communication in production OpenShift environments.
🚀 Key Features
Authentication Methods
OpenShift Integration
🛡️ Security Features
Strict Validation
https://oauth-openshift.apps.cluster.com) and Kubernetes ServiceAccount (https://kubernetes.default.svc) tokensSmart Authentication Logic
/health) bypass authentication for monitoring📁 Files Added
Core Implementation
v2/auth.go- Authentication middleware and OAuth/mTLS validation logicv2/server.go- TLS configuration and authentication integrationComprehensive Documentation
AUTHENTICATION.md- Complete authentication configuration guide (436 lines)OPENSHIFT_AUTHENTICATION.md- OpenShift-specific deployment guide (389 lines)README.md- Feature overview with authentication sectionExamples & Templates
auth-config-example.json- Basic authentication configurationexamples/openshift-auth-config.json- OpenShift-specific templateexamples/openshift-manifests.yaml- Complete deployment manifests (159 lines)examples/README.md- Example configuration documentation🔧 Configuration Example
{ "enableMTLS": true, "useServiceCA": true, "caCertPath": "/etc/ssl/certs/service-ca.crt", "serverCertPath": "/etc/ssl/certs/tls.crt", "serverKeyPath": "/etc/ssl/private/tls.key", "enableOAuth": true, "useOpenShiftOAuth": true, "oauthIssuer": "https://oauth-openshift.apps.cluster.example.com", "oauthJWKSURL": "https://oauth-openshift.apps.cluster.example.com/oauth/jwks", "requiredScopes": ["user:info"], "requiredAudience": "openshift" }🔄 Backward Compatibility
🧪 Testing & Validation
The implementation has been tested with:
📊 Impact
github.com/golang-jwt/jwt/v5for secure JWT validation🎯 Use Cases
This authentication system enables: