diff --git a/.gitignore b/.gitignore index 4cf204b..32add9a 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,8 @@ cover.out pub.json sub.json +# Per-clientID subscription store files written by tests (storePath ".") +v2/????????-????-????-????-????????????.json .idea .cache diff --git a/AUTHENTICATION.md b/AUTHENTICATION.md new file mode 100644 index 0000000..14908b7 --- /dev/null +++ b/AUTHENTICATION.md @@ -0,0 +1,428 @@ +# Authentication Configuration for REST API + +This document describes how to configure mTLS (mutual TLS) and OAuth authentication for the REST API server using OpenShift's built-in Service CA and OAuth server. + +## Overview + +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. Tokens are validated server-side via the Kubernetes **TokenReview** API, which verifies the token's issuer, signature, expiry, and audience. The REST API library itself does not parse JWTs or fetch a JWKS; it delegates verification to the cluster and only enforces the required audiences it is configured with. + +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, every non-loopback request must present a valid bearer token +- **Server-side Token Validation**: Issuer, signature, expiry, and audience are all validated by the Kubernetes TokenReview API +- **Audience Binding**: When `requiredAudiences` is configured, the token must be bound to one of those audiences +- **Clear Error Messages**: Authentication failures return specific error codes without exposing sensitive information + +## Protected vs Public Endpoints + +### Protected Endpoints (Require Authentication) + +When authentication is enabled, **every** data endpoint requires authentication for non-loopback requests. Only `GET /health` is exempt. (Requests originating from the pod's own loopback interface are treated as a trusted same-pod fast-path and skip authentication.) + +#### Subscription Management +- `POST /subscriptions` - Create subscription +- `GET /subscriptions` - List all subscriptions +- `GET /subscriptions/{subscriptionId}` - Get subscription details +- `DELETE /subscriptions/{subscriptionId}` - Delete specific subscription +- `DELETE /subscriptions` - Delete all subscriptions +- `PUT /subscriptions/status/{subscriptionId}` - Ping for subscription status + +#### Publisher Management +- `POST /publishers` - Create publisher +- `GET /publishers` - List all publishers +- `GET /publishers/{publisherid}` - Get publisher details +- `DELETE /publishers/{publisherid}` - Delete specific publisher +- `DELETE /publishers` - Delete all publishers + +#### Event Management +- `POST /create/event` - Publish event +- `POST /log` - Log event +- `GET /{ResourceAddress}/CurrentState` - Get current state + +#### Test Endpoints +- `POST /dummy` - Test endpoint +- `POST /dummy2` - Test endpoint + +### Public Endpoints (No Authentication Required) + +Only the health endpoint is reachable without authentication: + +- `GET /health` - Service health check (see the special mTLS behavior below) + +### Health Endpoint Behavior + +The `/health` endpoint has special behavior based on authentication configuration: + +#### When Authentication is Disabled +- Accessible via HTTP without any authentication +- Simple health check for service availability + +#### When mTLS is Enabled +- Accessible via HTTPS only +- **Requires a valid client certificate** for access +- Used by internal services (like PTP daemon) for health checks +- Service CA certificate is required for internal health checks + +**Note**: Even though the `/health` endpoint is considered "public" in terms of business logic, when mTLS is enabled, it still requires proper certificate authentication for security reasons. + +## Server Architecture + +### Single Server with Conditional Authentication + +The REST API uses a single server architecture that adapts based on authentication configuration: + +1. **No Authentication**: Server runs on HTTP, all endpoints accessible without authentication +2. **mTLS Only**: Server runs on HTTPS with client certificate validation +3. **OAuth Only**: Server runs on HTTP with Bearer token validation +4. **Both mTLS and OAuth**: Server runs on HTTPS with both client certificate and Bearer token validation + +### Health Endpoint Implementation + +The `/health` endpoint is always included in the main server but behaves differently based on authentication: + +- **Without mTLS**: Accessible via HTTP without authentication +- **With mTLS**: Accessible via HTTPS but requires valid client certificate +- **Internal health checks** (like PTP daemon) use the service CA certificate for authentication + +This approach ensures: +- Consistent server architecture +- No port conflicts +- Proper security when mTLS is enabled +- Internal services can still perform health checks + +## Configuration + +### Authentication Configuration Structure + +```go +type AuthConfig struct { + // mTLS configuration - works for both single and multi-node clusters + EnableMTLS bool `json:"enableMTLS"` + CACertPath string `json:"caCertPath"` + ServerCertPath string `json:"serverCertPath"` + ServerKeyPath string `json:"serverKeyPath"` + UseServiceCA bool `json:"useServiceCA"` // Use OpenShift Service CA (recommended for all cluster sizes) + + // OAuth 2.0 / bearer-token configuration. Tokens are validated by the + // TokenValidator installed via Server.SetTokenValidator (cloud-event-proxy + // uses the Kubernetes TokenReview API), so no issuer/JWKS is configured here. + EnableOAuth bool `json:"enableOAuth"` + RequiredAudiences []string `json:"requiredAudiences"` // Required token audiences (validated by TokenReview) + ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount used by clients for authentication + ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path (client side) + UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Client hint: obtain tokens from OpenShift OAuth + + // TLS profile - centrally managed by the cluster's TLSSecurityProfile and + // propagated by the operator. Nothing is hardcoded in this library. + TLSMinVersion string `json:"tlsMinVersion"` // e.g. "VersionTLS12", "VersionTLS13" + TLSCipherSuites []string `json:"tlsCipherSuites"` // IANA cipher suite names +} +``` + +### Example Configuration + +See `openshift-auth-config.json` for a complete configuration example that works for both single node and multi-node clusters: + +```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, + "requiredAudiences": ["https://kubernetes.default.svc"], + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" +} +``` + +> **Note:** There is no `oauthIssuer`, `oauthJWKSURL`, `requiredScopes`, or `requiredAudience` (singular) field. Token issuer, signature, and expiry are validated by the Kubernetes TokenReview API. The only OAuth policy this library enforces locally is `requiredAudiences` (an array): the presented token must be bound to one of the listed audiences. + +## OpenShift Integration + +### Service CA (Recommended) + +OpenShift's Service CA provides automatic certificate management for both single node and multi-node clusters: + +#### Prerequisites +- OpenShift cluster (single node or multi-node) +- No additional operators required + +#### Certificate Resources +- **Service**: Annotated with `service.beta.openshift.io/serving-cert-secret-name` for automatic certificate generation +- **Secret**: Automatically created by Service CA with server certificates + +#### Example Service CA Configuration +```yaml +apiVersion: v1 +kind: Service +metadata: + name: ptp-event-publisher-service + namespace: openshift-ptp + annotations: + service.beta.openshift.io/serving-cert-secret-name: cloud-event-proxy-tls +spec: + selector: + app: linuxptp-daemon + ports: + - port: 9043 + targetPort: 9043 + type: ClusterIP +``` + +### OpenShift OAuth / TokenReview + +The OAuth implementation validates bearer tokens through the Kubernetes TokenReview API: + +#### Prerequisites +- OpenShift cluster (single node or multi-node) +- The server's ServiceAccount must be permitted to create `tokenreviews` (via the `system:auth-delegator` ClusterRole or an equivalent binding) +- No additional operators required + +#### OAuth Configuration +- **Token Validation**: The server calls the Kubernetes TokenReview API, which verifies issuer, signature, expiry, and audience server-side +- **ServiceAccount Tokens**: Clients present a projected ServiceAccount token bound to the required audience +- **Audience Binding**: `requiredAudiences` enforces that the token was minted for this service +- **RBAC**: The server SA needs `create` on `authentication.k8s.io/tokenreviews` + +#### Example ServiceAccount Configuration +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: cloud-event-proxy-client + namespace: openshift-ptp +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + namespace: openshift-ptp + name: cloud-event-proxy-oauth +rules: +- apiGroups: [""] + resources: ["serviceaccounts"] + verbs: ["get", "list"] +- apiGroups: ["authentication.k8s.io"] + resources: ["tokenreviews"] + verbs: ["create"] +- apiGroups: ["authorization.k8s.io"] + resources: ["subjectaccessreviews"] + verbs: ["create"] +``` + +## mTLS Configuration + +### Certificate Requirements + +1. **CA Certificate** (`caCertPath`): The Certificate Authority certificate used to validate client certificates +2. **Server Certificate** (`serverCertPath`): The server's TLS certificate +3. **Server Private Key** (`serverKeyPath`): The server's private key + +### Certificate Generation Example + +```bash +# Generate CA private key +openssl genrsa -out ca.key 4096 + +# Generate CA certificate +openssl req -new -x509 -key ca.key -sha256 -subj "/C=US/ST=CA/O=MyOrg/CN=MyCA" -days 3650 -out ca.crt + +# Generate server private key +openssl genrsa -out server.key 4096 + +# Generate server certificate signing request +openssl req -new -key server.key -out server.csr -subj "/C=US/ST=CA/O=MyOrg/CN=localhost" + +# Generate server certificate signed by CA +openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -sha256 + +# Generate client private key +openssl genrsa -out client.key 4096 + +# Generate client certificate signing request +openssl req -new -key client.key -out client.csr -subj "/C=US/ST=CA/O=MyOrg/CN=client" + +# Generate client certificate signed by CA +openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365 -sha256 +``` + +## Client Examples + +### Protected Endpoint Examples + +#### Create Subscription (with both mTLS and OAuth) + +```bash +# With both mTLS and OAuth +curl -X POST https://localhost:9043/api/ocloudNotifications/v2/subscriptions \ + --cert client.crt \ + --key client.key \ + --cacert ca.crt \ + -H "Authorization: Bearer valid_your_jwt_token_here" \ + -H "Content-Type: application/json" \ + -d '{"EndpointUri": "http://example.com/callback", "ResourceAddress": "/test/resource"}' + +# With only mTLS (if OAuth is disabled) +curl -X POST https://localhost:9043/api/ocloudNotifications/v2/subscriptions \ + --cert client.crt \ + --key client.key \ + --cacert ca.crt \ + -H "Content-Type: application/json" \ + -d '{"EndpointUri": "http://example.com/callback", "ResourceAddress": "/test/resource"}' + +# With only OAuth (if mTLS is disabled) +curl -X POST http://localhost:9043/api/ocloudNotifications/v2/subscriptions \ + -H "Authorization: Bearer valid_your_jwt_token_here" \ + -H "Content-Type: application/json" \ + -d '{"EndpointUri": "http://example.com/callback", "ResourceAddress": "/test/resource"}' +``` + +#### Delete Publisher (with both mTLS and OAuth) + +```bash +curl -X DELETE https://localhost:9043/api/ocloudNotifications/v2/publishers/publisher-id \ + --cert client.crt \ + --key client.key \ + --cacert ca.crt \ + -H "Authorization: Bearer valid_your_jwt_token_here" +``` + +### Read (GET) Endpoint Examples + +`GET` endpoints are protected too - when authentication is enabled they require the same mTLS client certificate and/or bearer token as the write endpoints. + +#### List Subscriptions + +```bash +# With both mTLS and OAuth +curl -X GET https://localhost:9043/api/ocloudNotifications/v2/subscriptions \ + --cert client.crt \ + --key client.key \ + --cacert ca.crt \ + -H "Authorization: Bearer valid_your_token_here" + +# When authentication is disabled (plain HTTP, no auth) +curl -X GET http://localhost:9043/api/ocloudNotifications/v2/subscriptions +``` + +#### Health Check + +```bash +# When mTLS is enabled (requires client certificate) +curl -X GET https://localhost:9043/api/ocloudNotifications/v2/health \ + --cert client.crt \ + --key client.key \ + --cacert ca.crt + +# When mTLS is disabled (no authentication required) +curl -X GET http://localhost:9043/api/ocloudNotifications/v2/health + +# Internal health check (for services like PTP daemon) +curl -X GET https://localhost:9043/api/ocloudNotifications/v2/health \ + --cacert /etc/cloud-event-proxy/ca-bundle/service-ca.crt +``` + +## OAuth Security Implementation + +### Validation via Kubernetes TokenReview + +The OAuth implementation delegates all cryptographic token validation to the Kubernetes TokenReview API. The following checks are performed server-side by the cluster: + +1. **Issuer & Signature Validation**: + - The token's issuer and signature are verified by the cluster; tokens the API server does not recognize are rejected. + - No bypass mechanisms or fallbacks. + +2. **Expiration Checking**: + ``` + Token expired + ``` + - Expired tokens are rejected by TokenReview. + +3. **Audience Validation**: + ``` + Token audience validation failed + ``` + - When `requiredAudiences` is set, the token must be bound to one of those audiences. + - 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 Properties + +- **No local JWT parsing / JWKS fetching**: verification is performed by the Kubernetes API server via TokenReview. +- **Bounded token cache**: validated results are cached briefly with a short TTL to bound TokenReview load. +- **Memory Safety**: tokens are never logged or otherwise exposed. + +## Security Considerations + +1. **Certificate Management** + - Implement proper certificate rotation + - Use secure storage for private keys + - Use OpenShift Service CA for automated certificate management + +2. **OAuth Security** + - **Server-side Validation**: All tokens are validated by the Kubernetes TokenReview API (issuer, signature, expiry, audience) + - **No Bypass Mechanisms**: Non-loopback requests without a valid token are rejected with 401 + - **Audience Binding**: Configure `requiredAudiences` so tokens minted for other services are rejected + - A short-TTL cache bounds TokenReview load without weakening validation + +3. **TLS Configuration** + - Use TLS 1.2 or higher + - Configure secure cipher suites + - Enable HTTP/2 when possible + +4. **Access Control** + - Monitor and log authentication failures + - Implement rate limiting + - Consider IP whitelisting for sensitive endpoints + +5. **Error Handling** + - Use generic error messages in production + - Don't expose internal details in error responses + - Log detailed errors server-side + +6. **Health Endpoint Security** + - When mTLS is enabled, health endpoint requires client certificates + - Internal services should use service CA certificates for health checks + - External health checks require proper client certificates + - Consider network policies to restrict health endpoint access + +## Production Recommendations + +1. **Authentication Infrastructure** + - Use a proper OAuth 2.0 server (e.g., Keycloak, Auth0) + - Implement a certificate management solution + - Consider using a service mesh for mTLS + +2. **Monitoring and Logging** + - Log all authentication events + - Monitor authentication failures + - Set up alerts for suspicious activity + +3. **Security Hardening** + - Use hardware security modules (HSMs) for key storage + - Implement certificate revocation checking + - Regular security audits and penetration testing + +4. **Performance Optimization** + - Implement token caching + - Use connection pooling + - Configure appropriate timeouts + +5. **Operational Considerations** + - Document certificate rotation procedures + - Create incident response plans + - Regular security training for team members diff --git a/OPENSHIFT_AUTHENTICATION.md b/OPENSHIFT_AUTHENTICATION.md new file mode 100644 index 0000000..6751328 --- /dev/null +++ b/OPENSHIFT_AUTHENTICATION.md @@ -0,0 +1,362 @@ +# OpenShift Authentication Solution + +This document describes the unified authentication solution for the Cloud Native Events REST API using OpenShift's built-in components. This approach works seamlessly for both single node and multi-node OpenShift clusters. + +## Overview + +The authentication solution leverages OpenShift's native components to provide enterprise-grade security with minimal complexity: + +- **mTLS**: OpenShift Service CA for automatic certificate management +- **OAuth2**: OpenShift's built-in OAuth server with ServiceAccounts + +## Why This Approach? + +### Benefits for All Cluster Sizes: + +| Aspect | Single Node | Multi-Node | Improvement | +|--------|-------------|------------|-------------| +| **Complexity** | ✅ Low | ✅ Low | Same simple configuration | +| **Resource Usage** | ✅ Minimal | ✅ Minimal | No additional operators | +| **High Availability** | ❌ Single point | ✅ **HA Built-in** | OAuth server runs in HA mode | +| **Performance** | ✅ Good | ✅ **Excellent** | Better throughput in multi-node | +| **Maintenance** | ✅ Automatic | ✅ Automatic | Same automation, better resilience | +| **Cost** | ✅ Free | ✅ Free | No additional licensing | + +### Comparison with Alternatives: + +| Approach | Single Node | Multi-Node | Complexity | Resource Usage | +|----------|-------------|------------|------------|----------------| +| **Service CA + OAuth** | ✅ **Perfect** | ✅ **Perfect** | ✅ Low | ✅ Minimal | +| cert-manager + Auth Operator | ⚠️ Overkill | ⚠️ Overkill | ❌ High | ❌ High | +| Service Mesh | ❌ Overkill | ⚠️ Overkill | ❌ Very High | ❌ Very High | +| Manual certificates | ⚠️ Maintenance burden | ❌ Poor | ❌ Very High | ⚠️ Low | + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ OpenShift Cluster (Any Size) │ +├─────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────┐ ┌─────────────────────────────────────────┐ │ +│ │ Service CA │ │ OpenShift OAuth Server (HA) │ │ +│ │ │ │ │ │ +│ │ • Auto certs │ │ • High Availability │ │ +│ │ • Auto rotation │ │ • Load balanced │ │ +│ │ • No operators │ │ • Multiple replicas │ │ +│ │ • Cluster-wide │ │ • Distributed across nodes │ │ +│ └─────────────────┘ └─────────────────────────────────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ cloud-event-proxy API (DaemonSet) │ │ +│ │ │ │ +│ │ ┌─────────────┐ ┌─────────────────────┐ │ │ +│ │ │ mTLS │ │ OAuth2 │ │ +│ │ │ │ │ │ │ +│ │ │ • Client │ │ • JWT validation │ │ +│ │ │ certs │ │ • Scope checking │ │ +│ │ │ • Server │ │ • Audience check │ │ +│ │ │ certs │ │ • ServiceAccount │ │ +│ │ │ • Same on │ │ • Same across │ │ +│ │ │ all nodes │ │ all nodes │ │ +│ │ └─────────────┘ └─────────────────────┘ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Node 1 │ │ Node 2 │ │ Node 3 │ │ Node N │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ • Same │ │ • Same │ │ • Same │ │ • Same │ │ +│ │ config │ │ config │ │ config │ │ config │ │ +│ │ • Same │ │ • Same │ │ • Same │ │ • Same │ │ +│ │ certs │ │ certs │ │ certs │ │ certs │ │ +│ │ • Same │ │ • Same │ │ • Same │ │ • Same │ │ +│ │ auth │ │ auth │ │ auth │ │ auth │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +## Configuration + +### Unified Configuration + +The same configuration works for both single node and multi-node clusters: + +```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, + "requiredAudiences": ["https://kubernetes.default.svc"], + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" +} +``` + +### Token Audience Configuration + +Token issuer and JWKS discovery are handled entirely by the Kubernetes TokenReview API, so no cluster-specific OAuth URLs need to be templated. The only OAuth policy configured here is the set of accepted audiences: + +```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, + "requiredAudiences": ["https://kubernetes.default.svc"], + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" +} +``` + +Clients should request a projected ServiceAccount token bound to one of the `requiredAudiences`; TokenReview then validates the token's issuer, signature, expiry, and audience server-side. + +### Key Configuration Fields + +#### mTLS Configuration: +- `useServiceCA: true` - Use OpenShift Service CA (recommended for all cluster sizes) +- `caCertPath` - Path to Service CA certificate +- `serverCertPath` - Path to server certificate (auto-generated by Service CA) +- `serverKeyPath` - Path to server private key (auto-generated by Service CA) + +#### OAuth Configuration: +- `useOpenShiftOAuth: true` - Client hint to obtain tokens from OpenShift's built-in OAuth (recommended for all cluster sizes) +- `requiredAudiences` - Array of accepted token audiences (validated by TokenReview). There is no `oauthIssuer`, `oauthJWKSURL`, `requiredScopes`, or `requiredAudience` (singular) field; issuer/signature/expiry are validated by the Kubernetes API server. + +## Deployment + +### 1. Service with Service CA Annotation + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: ptp-event-publisher-service + namespace: openshift-ptp + annotations: + service.beta.openshift.io/serving-cert-secret-name: cloud-event-proxy-tls +spec: + selector: + app: linuxptp-daemon + ports: + - port: 9043 + targetPort: 9043 + type: ClusterIP +``` + +### 2. ServiceAccount and RBAC + +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: cloud-event-proxy-sa + namespace: openshift-ptp +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cloud-event-proxy-role + namespace: openshift-ptp +rules: +- apiGroups: [""] + resources: ["events"] + verbs: ["create", "update", "patch"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: cloud-event-proxy-binding + namespace: openshift-ptp +subjects: +- kind: ServiceAccount + name: cloud-event-proxy-sa + namespace: openshift-ptp +roleRef: + kind: Role + name: cloud-event-proxy-role + apiGroup: rbac.authorization.k8s.io +``` + +### 3. ConfigMap with Auth Configuration + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: cloud-event-proxy-auth-config + namespace: openshift-ptp +data: + auth-config.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, + "requiredAudiences": ["https://kubernetes.default.svc"], + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" + } +``` + +### 4. DaemonSet with Volume Mounts + +```yaml +apiVersion: apps/v1 +kind: DaemonSet +metadata: + name: linuxptp-daemon + namespace: openshift-ptp +spec: + selector: + matchLabels: + app: linuxptp-daemon + template: + metadata: + labels: + app: linuxptp-daemon + spec: + serviceAccountName: cloud-event-proxy-sa + containers: + - name: cloud-event-proxy + image: quay.io/redhat-cne/cloud-event-proxy:latest + args: + - "--auth-config=/etc/cloud-event-proxy/auth/auth-config.json" + volumeMounts: + - name: server-certs + mountPath: /etc/cloud-event-proxy/server-certs + readOnly: true + - name: ca-bundle + mountPath: /etc/cloud-event-proxy/ca-bundle + readOnly: true + - name: auth-config + mountPath: /etc/cloud-event-proxy/auth + readOnly: true + volumes: + - name: server-certs + secret: + secretName: cloud-event-proxy-tls + - name: ca-bundle + secret: + secretName: cloud-event-proxy-tls + - name: auth-config + configMap: + name: cloud-event-proxy-auth-config +``` + +## Multi-Node Benefits + +### Performance Improvements: + +1. **Parallel Processing**: Authentication requests processed in parallel across nodes +2. **Load Distribution**: No single node bottleneck +3. **Faster Response**: Multiple OAuth server instances +4. **Better Throughput**: Higher concurrent request handling +5. **Automatic Failover**: If one node fails, others continue serving + +### High Availability: + +- **OAuth Server HA**: Runs in HA mode by default +- **Service CA Resilience**: Certificate authority is cluster-wide +- **No Single Points of Failure**: Distributed across multiple nodes + +## Client Configuration + +### For Clients in the Same Cluster: + +```json +{ + "enableMTLS": true, + "useServiceCA": true, + "caCertPath": "/etc/cloud-event-consumer/ca-bundle/service-ca.crt", + "clientCertPath": "/etc/cloud-event-consumer/client-certs/tls.crt", + "clientKeyPath": "/etc/cloud-event-consumer/client-certs/tls.key", + "enableOAuth": true, + "useOpenShiftOAuth": true, + "requiredAudiences": ["https://kubernetes.default.svc"], + "serviceAccountName": "consumer-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" +} +``` + +## Troubleshooting + +### Common Issues: + +1. **Certificate Not Found**: Ensure Service CA annotation is correct +2. **OAuth Validation Fails**: Verify the server SA can create `tokenreviews` and that the client token's audience matches `requiredAudiences` +3. **Permission Denied**: Verify ServiceAccount has proper RBAC permissions + +### Debug Commands: + +```bash +# Check if Service CA secret exists +oc get secret cloud-event-proxy-tls -n openshift-ptp + +# Check ServiceAccount token +oc get secret -n openshift-ptp -o name | grep cloud-event-proxy-sa + +# Verify the server SA is allowed to create TokenReviews +oc auth can-i create tokenreviews.authentication.k8s.io \ + --as=system:serviceaccount:openshift-ptp:cloud-event-proxy-sa + +# Check OAuth server HA status +oc get deployment oauth-openshift -n openshift-authentication + +# Monitor authentication performance +oc top pods -n openshift-authentication +oc top pods -n openshift-ptp +``` + +## Migration + +### From Other Approaches: + +#### From Manual Certificates: +1. Set `useServiceCA: true` +2. Remove manual certificate generation scripts +3. Update certificate paths to use Service CA secrets + +#### From Service Mesh: +1. Remove Service Mesh configuration +2. Use this Service CA + OAuth approach +3. Update client configurations accordingly + +### Scaling Up: + +1. **No Configuration Changes**: Same configuration works for multi-node +2. **Automatic Scaling**: DaemonSet automatically deploys to new nodes +3. **HA Benefits**: Automatically get high availability benefits +4. **Performance Improvement**: Better performance without changes + +## Best Practices + +1. **Use DaemonSet**: Ensures consistent deployment across nodes +2. **Monitor OAuth Server**: Keep an eye on OAuth server performance +3. **Resource Planning**: Plan for increased resource usage in multi-node +4. **Network Policies**: Consider network policies for inter-node communication +5. **Regular Updates**: Keep OpenShift cluster updated for security patches + +## Conclusion + +The Service CA + OpenShift OAuth approach provides: + +- ✅ **Unified Solution**: Same configuration for single and multi-node clusters +- ✅ **Better Performance**: Load distribution and parallel processing +- ✅ **High Availability**: Built-in HA for OAuth server +- ✅ **Simplified Management**: Same configuration across all nodes +- ✅ **Automatic Scaling**: Scales with cluster size +- ✅ **Enterprise Security**: Consistent security across cluster +- ✅ **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. diff --git a/README.md b/README.md index 0d9bb17..f5044ee 100644 --- a/README.md +++ b/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). diff --git a/auth-config-example.json b/auth-config-example.json new file mode 100644 index 0000000..25f1fec --- /dev/null +++ b/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": [] +} diff --git a/docs/dev-readme.md b/docs/dev-readme.md index ac8a5d2..e8750ed 100644 --- a/docs/dev-readme.md +++ b/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"}' +``` diff --git a/docs/oran.docx b/docs/oran.docx new file mode 100644 index 0000000..58bf6c8 Binary files /dev/null and b/docs/oran.docx differ diff --git a/docs/oran.md b/docs/oran.md new file mode 100644 index 0000000..e1c0b1d --- /dev/null +++ b/docs/oran.md @@ -0,0 +1,2094 @@ ++-----------------------------------------------------------------------+ +| ![](media/image1.png){width="1.0748031496062993in" | +| height="0.4566929133858268in"} O-RAN.WG6.O-Cloud Notification | +| API-v04.00 | ++=======================================================================+ +| Technical Specification | ++-----------------------------------------------------------------------+ +| O-RAN Working Group 6 | +| | +| O-Cloud Notification API Specification for Event Consumers | ++-----------------------------------------------------------------------+ +| | ++-----------------------------------------------------------------------+ +| | ++-----------------------------------------------------------------------+ + +Copyright © 2024 by the O-RAN ALLIANCE e.V. + +The copying or incorporation into any other work of part or all of the +material available in this specification in any form without the prior +written permission of O-RAN ALLIANCE e.V. is prohibited, save that you +may print or download extracts of the material of this specification for +your personal use, or copy the material of this specification for the +purpose of sending to individual third parties for their information +provided that you acknowledge O-RAN ALLIANCE as the source of the +material and that you inform the third party that these conditions apply +to them and that they must comply with them. + +O-RAN ALLIANCE e.V., Buschkauler Weg 27, 53347 Alfter, Germany + +Register of Associations, Bonn VR 11238, VAT ID DE321720189 + +# Table of Contents {#table-of-contents .TT} + +[Chapter 1 Introductory Material +[3](#introductory-material)](#introductory-material) + +[1.1 Scope [3](#scope)](#scope) + +[1.2 References [3](#references)](#references) + +[1.3 Definitions and Abbreviations +[4](#definitions-and-abbreviations)](#definitions-and-abbreviations) + +[1.3.1 Definitions [4](#definitions)](#definitions) + +[1.3.2 Abbreviations [4](#abbreviations)](#abbreviations) + +[Chapter 2 Introduction [5](#introduction)](#introduction) + +[Chapter 3 Usage of HTTP [6](#usage-of-http)](#usage-of-http) + +[3.1 General [6](#general)](#general) + +[3.1.1 HTTP/2 shall be transported over Transmission Control Protocol +(TCP), as required by HTTP/2 (see IETF RFC 7540 \[8\]) HTTP standard +headers +[6](#http2-shall-be-transported-over-transmission-control-protocol-tcp-as-required-by-http2-see-ietf-rfc-7540-8-http-standard-headers)](#http2-shall-be-transported-over-transmission-control-protocol-tcp-as-required-by-http2-see-ietf-rfc-7540-8-http-standard-headers) + +[3.1.2 Content type [7](#content-type)](#content-type) + +[3.1.3 Void [7](#void)](#void) + +[3.1.4 Resource addressing +[8](#resource-addressing)](#resource-addressing) + +[Chapter 4 Authentication and Security +[9](#authentication-and-security)](#authentication-and-security) + +[4.1 Overview [9](#overview-1)](#overview-1) + +[4.2 Authentication Mechanisms +[9](#authentication-mechanisms)](#authentication-mechanisms) + +[4.2.1 mTLS (Mutual TLS) Authentication +[9](#mtls-mutual-tls-authentication)](#mtls-mutual-tls-authentication) + +[4.2.2 OAuth 2.0 Authentication +[9](#oauth-20-authentication)](#oauth-20-authentication) + +[4.2.3 Dual Authentication +[10](#dual-authentication)](#dual-authentication) + +[4.3 Authentication Requirements by Endpoint +[10](#authentication-requirements-by-endpoint)](#authentication-requirements-by-endpoint) + +[4.4 Security Considerations +[10](#security-considerations)](#security-considerations) + +[4.5 Configuration Examples +[11](#configuration-examples)](#configuration-examples) + +[Chapter 5 Subscription API Definition +[12](#subscription-api-definition)](#subscription-api-definition) + +[4.1 Resource Structure [10](#resource-structure)](#resource-structure) + +[4.1.1 Resources and HTTP Methods +[11](#resources-and-http-methods)](#resources-and-http-methods) + +[4.1.2 Subscription resource definition +[12](#subscription-resource-definition)](#subscription-resource-definition) + +[4.1.3 Individual subscription resource definition +[14](#individual-subscription-resource-definition)](#individual-subscription-resource-definition) + +[Chapter 5 Status Notifications API Definition +[17](#status-notifications-api-definition)](#status-notifications-api-definition) + +[5.1 Description [17](#description)](#description) + +[5.1.1 Event Consumer Notification Resource Definition +[18](#event-consumer-notification-resource-definition)](#event-consumer-notification-resource-definition) + +[Chapter 6 Event Pull Status Notifications API Definition +[22](#event-pull-status-notifications-api-definition)](#event-pull-status-notifications-api-definition) + +[6.1 Description [22](#description-1)](#description-1) + +[6.1.1 Resources Pull Status Notification Definition +[23](#resources-pull-status-notification-definition)](#resources-pull-status-notification-definition) + +[Chapter 7 Event Data Model [25](#event-data-model)](#event-data-model) + +[7.1 Subscription Data Model +[25](#subscription-data-model)](#subscription-data-model) + +[7.1.1 Structured data types +[25](#structured-data-types)](#structured-data-types) + +[7.2 Status Notifications Data Model +[25](#status-notifications-data-model)](#status-notifications-data-model) + +[7.2.1 Structured data types +[25](#structured-data-types-1)](#structured-data-types-1) + +[7.2.2 Event Data Model [26](#event-data-model-1)](#event-data-model-1) + +[7.2.3 Synchronization Event Specifications +[28](#synchronization-event-specifications)](#synchronization-event-specifications) + +[7.3 Appendix A [33](#appendix-a)](#appendix-a) + +[7.3.1 Helper/Sidecar containers +[33](#helpersidecar-containers)](#helpersidecar-containers) + +[Helper/Sidecar value: [33](#helpersidecar-value)](#helpersidecar-value) + +# Introductory Material + +## Scope + +This Technical Specification has been produced by the O-RAN Alliance. + +The contents of the present document are subject to continuing work +within O-RAN and may change following formal O-RAN approval. Should the +O-RAN Alliance modify the contents of the present document, it will be +re-released by O-RAN with an identifying change of release date and an +increase in version number as follows: + +Release x.y.z + +where: + +x the first digit is incremented for all changes of substance, i.e. +technical enhancements, corrections, updates, etc. (the initial approved +document will have x=01). + +y the second digit is incremented when editorial only changes have been +incorporated in the document. + +> z the third digit included only in working versions of the document +> indicating incremental changes during the editing process. + +The present document describes a REST API that allows Event Consumers +(EC) such as a O-RAN NFs to subscribe to events/status from the O-Cloud. +The O-Cloud shall provide Event Producers (EP) to enable workloads to +receive events/status that might be known only to the Cloud +Infrastructure (CInf). + +## References + +The following documents contain provisions which, through reference in +this text, constitute provisions of this specification (see also +). + +1. 3GPP TR 21.905, Vocabulary for 3GPP Specifications. + +2. 3GPP TS 28.622, Telecommunication management; Generic Network + Resource Model (NRM) Integration Reference Point (IRP); Information + Service (IS). + +3. O-RAN WG1, O-RAN Architecture Description -- v02.00, Technical + Specification. + +4. O-RAN WG1, Operations and Maintenance Architecture -- v03.00, + Technical Specification. + +5. O-RAN WG4, Control, User and Synchronization Plane Specification -- + v06.00, Technical Specification. + +6. O-RAN WG6, Cloud Architecture and Deployment Scenarios for O-RAN + Virtualized RAN -- v02.01, Technical Report. + +7. O-RAN Infrastructure Project, + + +8. IETF RFC 7540: \"Hypertext Transfer Protocol Version 2 (HTTP/2)\". + +9. IETF RFC 8259: \"The JavaScript Object Notation (JSON) Data + Interchange Format\". + +10. IETF RFC 7231: \"Hypertext Transfer Protocol (HTTP/1.1): Semantics + and Content\". + +11. IETF RFC 7230: \"Hypertext Transfer Protocol (HTTP/1.1): Message + Syntax and Routing\". + +12. IETF RFC 7807: \"Problem Details for HTTP APIs\". + +13. IETF RFC 7235 for authentication mechanisms over HTTP/1.1, + +14. 3GPP TS 29.501, 5G System; Principles and Guidelines for Services + Definition + +15. CloudEvents.io specification, https://github.com/cloudevents/ + +## Definitions and Abbreviations + +### Definitions + +For the purposes of the present document, the terms given in +O-RAN.WG6.CADS \[6\] and the following apply. A term defined in the +present document takes precedence over the definition of the same term, +if any, in \[6\]. + +### Abbreviations + +For the purposes of the present document, the abbreviations given in +O-RAN.WG6.CADS \[6\] and the following apply. An abbreviation defined in +the present document takes precedence over the definition of the same +abbreviation, if any, in \[6\]. + +EC Event Consumer + +EP Event Producer + +REST Representational State Transfer + +# Introduction + +This document describes a REST API that allows Event Consumers (EC) such +as a vO-DU or CNF to subscribe to events/status from the O-Cloud. The +cloud infrastructure will provide Event Producers (EP) to enable cloud +workloads to receive events/status that might be known only to the +infrastructure. + +An EC will use the REST API to subscribe to specific event types or +categories of events by specifying the event / status producer address. +The addressing scheme is covered in [Resource +Addressing](#51w7kj7rf0x8). An EC will be able to unsubscribe from +receiving events and status by deleting the subscription through the +REST API. The REST API is an integration point to an event and status +framework that is running in the underlying O-Cloud (IMS and/or DMS). + +The REST API and associated event framework implementation is intended +to be used in situations where the path from event detection to event +consumption must have the lowest possible latency. Intra-node delivery +of events is a primary focus with inter-node delivery also supported. + +The event framework described here is not intended to be an island of +communication and should interact with north-bound interfaces such as O2 +through the IMS. Hence, this Event Consumers API is not intended to +replace O2ims notifications (including PTP loss of sync), but rather to +complement it. Please see the CAD \[6\] for more information. + +Interfacing with external entities is necessary for communication with +orchestrating entities and for permanent storage of event information +for root-cause analysis. Communication with external entities is +intended to be in one direction with events flowing from this framework +outward. The flow of events from this framework to external entities +must not affect the latency performance of the framework for intra-node +or inter-node delivery. + +Please note that while this API document describes an interface to +general events and status provided by the cloud infrastructure, the +discussions and examples in this document will focus on events and +status related to PTP / Synchronization as it this is the first defined +use case that affects the vO-DU per the CUSP \[5\] requirements. + +*"If an O-DU transits to the FREERUN state, the O-DU shall disable RF +transmission on all connected O-RUs, and keep it turned off until +synchronization is reacquired."* + +*"Whether in 'synchronized' or 'Holdover' state, it is expected that +O-DU monitors the 'SYNCED/HOLDOVER' status of the O-RUs under its +management."* + +Please note that the timing requirements for notification regarding +FREERUN should follow WG4 guidelines when available in the CUSP +document. These guidelines may influence the future evolution and design +of this API. Please see the CUSP \[5\] for more information. + +Subscription/Publication use case: + +- Subscription by the Event Consumer (e.g. vO-DU or other CNF) triggers + the readiness of the Event Consumer to receive the notifications. + +- The REST API handler implementation, provided by the Cloud + infrastructure, resides in the application (workload) and is an + application appropriate implementation of a REST API handler. + +- Upon subscription, the EC will receive an initial notification of the + EP resource status. For example, the current synchronization status of + the PTP system will be sent to the EC when subscribing to the + sync-status address. Or as another example, the current interface + carrier status will be sent to the EC when subscribing to the + interface-status address. This initial notification allows the joining + application to synchronize to the current status of the system being + observed. + +- Event Consumers will be able to subscribe to resource status + notifications offered by the cloud. + +- Multiple Event Consumers in the same container, Pod, or VM can + subscribe to events and status as the REST API allows multiple receive + endpoint URI. + +- If the eventing framework cannot provide the requested subscription + the eventing framework will deny the subscription request and Event + Consumer (vO-DU, vO-CU etc) will be able to make a decision if to + proceed with its operation + +# Usage of HTTP + +## General + +HTTP/2, IETF RFC 7540, shall be used. + +### HTTP/2 shall be transported over Transmission Control Protocol (TCP), as required by HTTP/2 (see IETF RFC 7540 \[8\]) HTTP standard headers + +#### Request header fields + +This clause describes the usage of selected HTTP header fields of the +request messages in the O-Cloud APIs. + +> **Table 3.1.3.2-1: Header fields supported in the request message** + ++------------------+----------------------+-----------------------------------------+ +| **Header field | **Reference** | **Descriptions** | +| name** | | | ++:=================+:=====================+:========================================+ +| Accept | IETF RFC 7231 \[10\] | This field is used to specify response | +| | | media types that are acceptable by the | +| | | client sending the request. | +| | | | +| | | Content-Types that are acceptable for | +| | | the response. | +| | | | +| | | This header field shall be present in | +| | | the HTTP request message sent by the | +| | | client if the response is expected to | +| | | have a non-empty message body. | ++------------------+----------------------+-----------------------------------------+ +| Content-Type | IETF RFC 7231 \[10\] | This field is used to indicate the | +| | | media type of the associated | +| | | representation. | +| | | | +| | | This header field shall be present if | +| | | the request has a non-empty message | +| | | body. | ++------------------+----------------------+-----------------------------------------+ +| Authorization | IETF RFC 7235 \[13\] | The authorization token for the request | +| | | using Bearer scheme (OAuth 2.0). This | +| | | field is optional for local scenarios | +| | | (i.e. within the POD/VM). If the | +| | | consumer is external to the POD/VM or | +| | | when authentication is required, this | +| | | header shall contain a valid OAuth 2.0 | +| | | Bearer token or ServiceAccount token. | +| | | | +| | | Format: "Bearer " | +| | | | +| | | Note: When mTLS is enabled, client | +| | | certificate authentication is performed | +| | | at the TLS layer in addition to token | +| | | validation. | ++------------------+----------------------+-----------------------------------------+ +| Accept-Encoding | IETF RFC 7231 \[10\] | This field may be used to indicate what | +| | | response content-encodings (e.g gzip) | +| | | are acceptable in the response. | ++------------------+----------------------+-----------------------------------------+ +| Content-Length | IETF RFC 7230 \[11\] | This field is used to provide the | +| | | anticipated size, as a decimal number | +| | | of octets, for a potential payload | +| | | body. | ++------------------+----------------------+-----------------------------------------+ +| Content-Encoding | IETF RFC 7231\[10\] | This field may be used in some requests | +| | | to indicate the content encodings (e.g | +| | | gzip) applied to the resource | +| | | representation beyond those inherent in | +| | | the media type. | ++------------------+----------------------+-----------------------------------------+ + +#### Response header fields + +This clause describes the usage of selected HTTP header fields of the +response messages in the O-Cloud APIs. + +> **Table 3.1.3.3-1: Header fields supported in the response message** + ++------------------+---------------+----------------------------------------+ +| **Header field | **Reference** | **Descriptions** | +| name** | | | ++:=================+:==============+:=======================================+ +| Content-Type | IETF RFC 7231 | This header field shall be used to | +| | \[10\] | indicate the media type of the | +| | | associated representation. | ++------------------+---------------+----------------------------------------+ +| Content-Length | IETF RFC 7231 | This header field may be used to | +| | \[10\] | provide the anticipated size, as a | +| | | decimal number of octets, for a | +| | | potential payload body. | +| | | | +| | | This header field shall be present if | +| | | the response has a non-empty message | +| | | body. | ++------------------+---------------+----------------------------------------+ +| Location | IETF RFC 7231 | This field may be used in some | +| | \[10\] | responses to refer to a specific | +| | | resource in relation to the response. | +| | | | +| | | Used in redirection, or when a new | +| | | resource has been created. | +| | | | +| | | This header field shall be present if | +| | | the response status code is 201 or | +| | | 3xx. | ++------------------+---------------+----------------------------------------+ +| Content-Encoding | IETF RFC 7231 | This header may be used in some | +| | \[10\] | responses to indicate to the HTTP/2 | +| | | client the content encodings (e.g | +| | | gzip) applied to the resource | +| | | representation beyond those inherent | +| | | in the media type. | ++------------------+---------------+----------------------------------------+ +| WWW-Authenticate | IETF RFC 7235 | Challenge if the corresponding HTTP | +| | \[13\] | request has not provided | +| | | authorization, or error details if the | +| | | corresponding HTTP request has | +| | | provided an invalid authorization | +| | | token. This is optional. When the | +| | | notification producer and consumer are | +| | | locally present in the same compute, | +| | | API authorization is not mandatory. | ++------------------+---------------+----------------------------------------+ +| Retry-After | IETF RFC 7231 | Used to indicate how long the user | +| | \[10\] | agent ought to wait before making a | +| | | follow-up request. | +| | | | +| | | It can be used with 503 responses. | +| | | | +| | | The value of this field can be an | +| | | HTTP-date or a number of seconds to | +| | | delay after the response is received. | ++------------------+---------------+----------------------------------------+ + +### Content type + +JSON, IETF RFC 8259 shall be used as content type of the HTTP bodies +specified in the present specification.The use of the JSON format shall +be signaled by the content type \"application/json\". + +\"Problem Details\" JSON object shall be used to indicate additional +details of the error in a HTTP response body and shall be signalled by +the content type \"application/problem+json\", as defined in +IETF RFC 7807. + +### Void + +. + +### Resource addressing + +The format of the resource address is shown in [[Table +1]{.underline}](#table1). The resource address specifies the Event +Producer with a hierarchical path. The path format provides the ability +for management and monitoring to extend beyond a single cluster and +node. + +[]{#table1 .anchor}**Table 1: Resource address format** + + ----------------------------------------------------------------------------------------------- + /{clusterName}/{siteName}(/optional/hierarchy/..)/{nodeName}/{(/optional/hierarchy)/resource} + + ----------------------------------------------------------------------------------------------- + +An example hierarchy could include an IMS and DMS designator i.e., +**/ims-1/dms-2/node1/*sync/sync-status/sync-state***. The event +framework is minimally required to support nodeName addressing. The +event framework addressing nomenclature for nodeName shall match the +O-Cloud technology naming scheme. + +This hierarchy path is part of the environment variables provided to the +CNF by the Downward API (see +[[https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api]{.underline}](https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)) + +Field definitions are shown in [[Table 2]{.underline}](#table2). + +[]{#table2 .anchor}**Table 2: Resource address fields** + ++:---------------------------------:+:--------------------:+:-----------------------------------------------------:+ +| **Address Component** | **Description** | **Example** | ++-----------------------------------+----------------------+-------------------------------------------------------+ +| /optional/hierarchy/nodeName/\... | The hierarchical | /dms1/nodeName1/\... to specify a specif DMS and | +| or /./nodeName/\... | name that uniquely | node, or | +| | specifies the DMS | | +| | where the nodeName | /./nodeName/\...1 to specify the current DMS and | +| | node resides. name | specific node | +| | of the cloud where | | +| | the producer exists. | /././...\... to specify the current DMS and current | +| | A '.' is used to | node. | +| | indicate the current | | +| | DMS where the Event | | +| | Consumer nodeName | | +| | node is located. The | | +| | additional hierarchy | | +| | is optional. If | | +| | addressing begins | | +| | with **/./** a | | +| | nodeName or nodeName | | +| | wildcard is | | +| | required. | | ++-----------------------------------+----------------------+-------------------------------------------------------+ +| nodeName | Name of the Worker | node27 | +| | node or Compute node | | +| | where the producer | node\* -\> all nodes | +| | exists. The name | | +| | must map to the | . -\> current node | +| | nomenclature in use | | +| | for the underlying | | +| | cloud | | +| | infrastructure. A | | +| | regular expression | | +| | with \* or . may be | | +| | specified to | | +| | subscribe to | | +| | multiple nodes. | | ++-----------------------------------+----------------------+-------------------------------------------------------+ +| resource | The hierarchical | A subscription to /***sync*** would deliver | +| | path for the | notifications for all types of synchronization events | +| | subsystem that will | implemented by the synchronization subsystem. Since | +| | produce the | this cover all notification, individual subscriptions | +| | notifications. This | (as described below) will be ignored. | +| | path may also | | +| | include an optional | A subscription to /***sync/sync-status/sync-state*** | +| | hierarchy to | would deliver notifications for the | +| | describe different | event.sync.sync-status.synchronization-state-change | +| | Event Producers in | event only. | +| | the same Node.  The | | +| | hierarchical path is | Individual subscriptions to | +| | inclusive such that | /***sync/sync-status/sync-state** and | +| | all notifications | /**sync/gnss-status/gnss-sync-status*** would deliver | +| | for subsystems below | notifications for both the overall synchronization | +| | the specified path | health | +| | will be delivered as | (event.sync.sync-status.synchronization-state-change) | +| | part of the | and GNSS specific status | +| | subscription.  The | (event.sync.gnss-status.gnss-state-change). | +| | full path can be | | +| | used to explicitly | Examples for a 'resource' with an optional hierarchy: | +| | specify a single | | +| | type of | *../Node1/NIC1/sync* | +| | notification.  | | +| | Multiple | *../Node1/NIC2/sync/sync-status/sync-state/* | +| | subscriptions can be | | +| | used to select a | Note: In the future, Resource can be expanded to | +| | subset of | other infrastructure subsystems such as thermal | +| | notification types | notifications and network interface link status. | +| | for event delivery | | +| | specified level. | | ++-----------------------------------+----------------------+-------------------------------------------------------+ + +# Authentication and Security + +## Overview + +The O-Cloud Notification API supports two complementary authentication mechanisms to ensure secure communication between Event Consumers and Event Producers: + +1. **Mutual TLS (mTLS)**: Certificate-based authentication at the transport layer +2. **OAuth 2.0**: Token-based authentication at the application layer + +These authentication mechanisms can be used independently or in combination (dual authentication) depending on the deployment security requirements. + +## Authentication Mechanisms + +### mTLS (Mutual TLS) Authentication + +mTLS provides transport layer security by requiring both the client and server to authenticate using X.509 certificates. + +**Key Features:** +- Certificate-based client authentication +- Encrypted communication channel +- Certificate verification against trusted Certificate Authority (CA) +- Support for platform-specific CA services for automatic certificate management + +**Implementation Requirements:** +- Client must present valid X.509 certificate signed by trusted CA +- Server verifies client certificate during TLS handshake +- Certificate Subject Name and validity period are validated +- Certificate revocation checking may be implemented + +**Error Responses:** +- **401 Unauthorized**: Client certificate not provided or invalid +- **403 Forbidden**: Valid certificate but insufficient permissions + +### OAuth 2.0 Authentication + +OAuth 2.0 provides application layer authentication using Bearer tokens (JWT - JSON Web Tokens). + +**Supported Token Types:** +1. **Platform OAuth Tokens**: Issued by the platform's OAuth server +2. **Kubernetes ServiceAccount Tokens**: Native Kubernetes authentication tokens + +**Token Validation:** +- **Issuer Verification**: Token must be issued by trusted OAuth server +- **Audience Validation**: Token audience must match the API service +- **Signature Verification**: Token signature verified using JWKS (JSON Web Key Set) +- **Expiration Check**: Token must not be expired +- **Scope Validation**: Token must contain required scopes (if configured) + +**Implementation Requirements:** +- Client includes Bearer token in Authorization header: `Authorization: Bearer ` +- Server validates token against the platform's OAuth server or Kubernetes API +- Token introspection performed on each API request +- Failed validation results in 401 Unauthorized response + +**Error Responses:** +- **401 Unauthorized**: Token missing, invalid, expired, or failed validation +- **403 Forbidden**: Valid token but insufficient permissions + +### Dual Authentication + +When both mTLS and OAuth are enabled, clients must satisfy both authentication mechanisms: + +1. **TLS Layer**: Client certificate verified during TLS handshake +2. **Application Layer**: Bearer token validated in Authorization header + +**Benefits of Dual Authentication:** +- Defense-in-depth security model +- Compliance with security standards requiring multiple authentication factors +- Protection against compromised credentials (either certificate or token) + +## Authentication Requirements by Endpoint + +The following table describes authentication requirements for each API endpoint: + +**Table: Authentication Requirements by HTTP Method** + ++---------------------------+---------------+------------------+-------------------------+ +| **Endpoint** | **Method** | **Auth Required**| **Description** | ++:==========================+:==============+:=================+:========================+ +| /subscriptions | POST | Yes | Create subscription | +| | | | (mTLS and/or OAuth) | ++---------------------------+---------------+------------------+-------------------------+ +| /subscriptions | GET | No | List subscriptions | +| | | | (public endpoint) | ++---------------------------+---------------+------------------+-------------------------+ +| /subscriptions | DELETE | Yes | Delete all | +| | | | subscriptions | +| | | | (mTLS and/or OAuth) | ++---------------------------+---------------+------------------+-------------------------+ +| /subscriptions/ | GET | No | Get specific | +| {subscriptionId} | | | subscription | +| | | | (public endpoint) | ++---------------------------+---------------+------------------+-------------------------+ +| /subscriptions/ | DELETE | Yes | Delete specific | +| {subscriptionId} | | | subscription | +| | | | (mTLS and/or OAuth) | ++---------------------------+---------------+------------------+-------------------------+ +| /{ResourceAddress}/ | GET | No | Pull current state | +| CurrentState | | | (public endpoint) | ++---------------------------+---------------+------------------+-------------------------+ +| /publishers | GET | No | List publishers | +| | | | (public endpoint) | ++---------------------------+---------------+------------------+-------------------------+ +| /health | GET | No | Health check | +| | | | (always public) | ++---------------------------+---------------+------------------+-------------------------+ + +**Note**: Localhost connections (within the same POD/VM) may bypass authentication requirements depending on deployment configuration. + +## Security Considerations + +### Certificate Management + +**For mTLS Authentication:** +- Certificates should be rotated regularly (recommended: 90 days or less) +- Use strong key sizes (minimum RSA 2048-bit or ECDSA P-256) +- Implement certificate revocation checking (CRL or OCSP) +- Store private keys securely (encrypted, restricted access) + +**Platform Certificate Authority Integration:** +- Automatic certificate issuance and rotation +- Certificates mounted as Kubernetes Secrets +- Trust bundle distributed via ConfigMaps + +### Token Management + +**For OAuth 2.0 Authentication:** +- Tokens should have limited lifetime (recommended: 1 hour or less) +- Use refresh tokens for long-running clients +- Implement token revocation support +- Protect tokens in transit (HTTPS only) +- Validate all token claims (issuer, audience, expiration) + +### Localhost Exception + +Connections originating from localhost (127.0.0.1 or ::1) may bypass authentication: +- **Rationale**: Helper/Sidecar containers in same POD/VM are trusted +- **Risk**: Compromise of any container in POD grants API access +- **Mitigation**: Use RBAC and Pod Security Policies to limit container capabilities + +### RBAC Integration + +When using Kubernetes ServiceAccount tokens: +- Token subject mapped to Kubernetes ServiceAccount +- RBAC policies control access to API operations +- Principle of least privilege: Grant minimal required permissions +- Use separate ServiceAccounts for different workload types + +## Configuration Examples + +### mTLS Configuration + +**Client Certificate Request:** +```bash +curl -X POST https://api-server:9043/api/ocloudNotifications/v2/subscriptions \ + --cert /etc/certs/client.crt \ + --key /etc/certs/client.key \ + --cacert /etc/certs/ca.crt \ + -H "Content-Type: application/json" \ + -d '{"ResourceAddress": "/sync/sync-status/sync-state", "EndpointUri": "http://localhost:8080/callback"}' +``` + +### OAuth 2.0 Configuration + +**Bearer Token Request:** +```bash +TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) +curl -X POST https://api-server:9043/api/ocloudNotifications/v2/subscriptions \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"ResourceAddress": "/sync/sync-status/sync-state", "EndpointUri": "http://localhost:8080/callback"}' +``` + +### Dual Authentication Configuration + +**mTLS + OAuth Request:** +```bash +TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token) +curl -X POST https://api-server:9043/api/ocloudNotifications/v2/subscriptions \ + --cert /etc/certs/client.crt \ + --key /etc/certs/client.key \ + --cacert /etc/certs/ca.crt \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"ResourceAddress": "/sync/sync-status/sync-state", "EndpointUri": "http://localhost:8080/callback"}' +``` + +# Subscription API Definition + +## Resource Structure + +[Figure 1](#figure1) shows the overall resource URI structure defined +for the subscription's API. [Table 3](#table3) lists the individual +resources defined, and the applicable HTTP methods with the message flow +diagram, [Figure 2](#figure2). + +[]{#figure1 .anchor} + +**Figure 1: Resource URI structure of the subscription's API** + +![Diagram Description automatically +generated](media/image2.png){width="5.212414698162729in" +height="4.085285433070866in"} + +[]{#figure2 .anchor}**Figure 2: Message flow diagram** + ++:----------------------------------------------------------------------------------------------------------------------------------------------------------------:+ +| [![Diagram Description automatically generated](media/image3.png){width="6.354166666666667in" | +| height="4.069444444444445in"}](https://lucid.app/documents/edit/c6911e15-e3c4-43e4-bcb0-579a8820c6e5/0?callback=close&name=docs&callback_type=back&v=2273&s=612) | +| | +| **Helper\*** | +| | +| **Workload** | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| []{#table3 .anchor} \*Helper provided by cloud vendors | +| | +| **Table 3: Resources and methods overview** | +| | +| +:-------------:+:-------------------------------------------------------------:+:-----------:+:---------------:+ | +| | **Resource | **Resource URI** | **HTTP | **Description** | | +| | name** | | method or | | | +| | | | custom | | | +| | | | operation** | | | +| +---------------+---------------------------------------------------------------+-------------+-----------------+ | +| | Subscriptions | {apiRoot}/ocloudNotifications/{apiMajorVersion}/subscriptions | POST | To create a new | | +| | | | | individual | | +| | | | | subscription | | +| | | | | resource. | | +| | | +-------------+-----------------+ | +| | | | GET | Get a list of | | +| | | | | subscription | | +| | | | | resources. | | +| +---------------+---------------------------------------------------------------+-------------+-----------------+ | +| | Individual | {apiRoot}/ocloudNotifications/{apiMajorVersion} | GET | Get Detail of | | +| | subscription | /subscriptions/{subscriptionId} | | individual | | +| | | | | subscription | | +| | | | | resources. | | +| | | +-------------+-----------------+ | +| | | | DELETE | Delete | | +| | | | | individual | | +| | | | | subscription | | +| | | | | resources. | | +| +---------------+---------------------------------------------------------------+-------------+-----------------+ | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +### Resources and HTTP Methods + +An Event Consumer (e.g. vDU or other CNF) will use a POST request to +subscribe to receive notifications per its desirable resource. This +resource is mapped to a data type/payload (see data model). + +The POST's payload will also include the notification endpoint (callback +URI) for the API Producer to send the notifications back to the EC. + +The API Producer, in this case the Helper (see appendix A), will +validate that the resource requested is offered by the cluster and +available at the particular address. If the resource does not exist an +error code will be sent to the client's EndpointURI. This will be +followed by a sanity check of the requested notification endpoint and +creating the resource if communication to the notification endpoint is +successful. To reduce security concerns and lifecycle management burden +the notification endpoint URI must be part of the same localhost, this +is the localhost shared by the Event Consumer and Helper, with the +assumption that they are located in the same POD or VM. + +###  Subscription resource definition + +The resource URI is: + +**{apiRoot}/ocloudNotifications/{apiMajorVersion}/subscriptions** + +The resource URI variables supported by the resource shall be defined as +[Table 4](#table4) illustrates. + +[]{#table4 .anchor} **Table 4: Resource URI variables for this +resource** + + ----------------- ------------------------------------------------------ + **Name** **Definition** + + apiRoot described in clause 4.4.1 of 3GPP TS 29.501  + + apiMajorVersion v2 + ----------------- ------------------------------------------------------ + +#### Subscription POST Method + +The POST method creates a subscription resource for the Event Consumer. +As the result of successfully executing this method, a new subscription +resource shall exist as defined in clause 1.2, and a variable value +(*subscriptionId*) will be used in the representation of that resource. +An initial status notification for the type of event (for example, PTP +synchronization status) shall be triggered. The status describes the +initial status of the producer resource when successfully executing this +method as defined in clause 1.1.4, followed by any PTP status +notifications (triggered if there is a change in PTP status). + +URI query parameters supported by the method shall be defined as [Table +5](#table5) illustrates. + +[]{#table5 .anchor}**Table 5: URI query parameters supported by a method +on the resource** + + ------------------ -------- ------- ----------------- ------------------- ------------------- + **Name** **Data **P** **Cardinality** **Description** **Applicability** + type** + + n/a + ------------------ -------- ------- ----------------- ------------------- ------------------- + +Data structures supported by the request body of the POST method shall +be specified as [Table 6](#table6) illustrates. + +[]{#table6 .anchor}**Table 6: Data structures supported by the request +body on the resource** + + ------------------ --------- ----------------- ------------------------------------ + **Data type** **P** **Cardinality** **Description** + + Subscriptioninfo M 1 The payload will include an event + notification request, endpointUri + and ResourceAddress. See note below. + ------------------ --------- ----------------- ------------------------------------ + +**Note**: The *Subscriptioninfo* is defined in the subscription data +model section + +Data structures supported by the response body of the method shall be +specified as [Table 7](#table7) illustrates. + +[]{#table7 .anchor}**Table 7: Data structures supported by the response +body on the resource** + ++------------+:----------------:+:-----:+:---------------:+:------------:+:----------------------:+ +| Response | **Data type** | **P** | **Cardinality** | **Response** | **Description** | +| body | | | | | | +| | | | | **codes** | | +| +------------------+-------+-----------------+--------------+------------------------+ +| | SubscriptionInfo | M | 1 | 201 | Shall be returned when | +| | | | | | the subscription | +| | | | | | resource is created | +| | | | | | successfully. | +| | | | | | | +| | | | | | See note below. | +| +------------------+-------+-----------------+--------------+------------------------+ +| | n/a | | | 400 | Bad request by the EC. | +| | | | | | For example, the | +| | | | | | endpoint URI does not | +| | | | | | include 'localhost'. | +| +------------------+-------+-----------------+--------------+------------------------+ +| | n/a | | | 401 | Unauthorized. | +| | | | | | Authentication | +| | | | | | required. This error | +| | | | | | is returned when mTLS | +| | | | | | and/or OAuth | +| | | | | | authentication fails. | +| | | | | | Client must provide | +| | | | | | valid certificate | +| | | | | | and/or Bearer token. | +| +------------------+-------+-----------------+--------------+------------------------+ +| | n/a | | | 404 | Subscription resource | +| | | | | | is not available. For | +| | | | | | example, PTP is not | +| | | | | | supported by the node. | +| +------------------+-------+-----------------+--------------+------------------------+ +| | n/a | | | 409 | The subscription | +| | | | | | resource already | +| | | | | | exists. | ++------------+------------------+-------+-----------------+--------------+------------------------+ + +**Note**: The *SubscriptionInfo* is defined in the subscription data +model section, see [Table 30](#table30) + +The following example shows a subscription request/response for +/sync-state which would deliver notifications for the +event.sync.sync-status.synchronization-state-change event only. + +**Example Create Subscription Resource: JSON request** + ++-----------------------------------------------------------------------+ +| { | +| | +| { | +| | +| > \"ResourceAddress\": | +| > \"/east-edge-10/Node3/sync/sync-status/sync-state/\", | +| > | +| > \"EndpointUri \"http://localhost:{port}/{path} | +| | +| } | +| | +| } | ++-----------------------------------------------------------------------+ + +**Example Create Subscription Resource: JSON response** + ++---------------------------------------------------------------------------------------------------------------------+ +| { | +| | +| "SubscriptionId": "789be75d-7ac3-472e-bbbc-6d62878aad4a", | +| | +| > \"ResourceAddress\": \"/east-edge-10/Node3/sync/sync-status/sync-state/\", | +| > | +| > "UriLocation": "http://localhost:8080/ocloudNotifications/v2/subsciptions/789be75d-7ac3-472e-bbbc-6d62878aad4a" | +| | +| \"EndpointUri \": | +| \"[[http://localhost:9090/publishers/{publisherid]{.underline}](http://localhost:9090/publishers/%7Bpublisherid)}\" | +| | +| } | ++---------------------------------------------------------------------------------------------------------------------+ + +#### Subscription GET Method + +The GET method queries the subscription object and its associated +properties. As a result of a successful execution of this method a list +of subscription object(s) and their associated properties will return by +the API Producer. + +URI query parameters supported by the method shall be defined as [Table +8](#table8) illustrates. + +[]{#table8 .anchor} **Table 8: URI query parameters supported by a +method on the resource** + + ---------- -------- ------- ----------------- ------------------- ----------------------- + **Name** **Data **P** **Cardinality** **Description** **Applicability** + type** + + n/a + ---------- -------- ------- ----------------- ------------------- ----------------------- + +Data structures supported by the response body of the method shall be +specified as [Table 9](#table9) illustrates. + +[]{#table9 .anchor}**Table 9: Data structures supported by the response +body on the resource** + ++------------+:----------------:+:-----:+:---------------:+:------------:+:----------------------:+ +| Response | **Data type** | **P** | **Cardinality** | **Response** | **Description** | +| body | | | | | | +| | | | | **codes** | | +| +------------------+-------+-----------------+--------------+------------------------+ +| | SubscriptionInfo | M | 0..N | 200 | Returns the | +| | | | | | subscription resources | +| | | | | | and their associated | +| | | | | | properties that | +| | | | | | already exist. | +| | | | | | | +| | | | | | See note below. | +| +------------------+-------+-----------------+--------------+------------------------+ +| | n/a | O | 0..1 | 400 | Bad request by the EC. | +| | | | | | For example, the | +| | | | | | endpoint URI does not | +| | | | | | include 'localhost'. | ++------------+------------------+-------+-----------------+--------------+------------------------+ + +**Note**: The *SubscriptionInfo* is defined in the subscription data +model section, see [Table 30](#table30) + +### Individual subscription resource definition + +The resource URI is: + +**{apiRoot}/ocloudNotifications/{apiMajorVersion}/subscriptions/{subscriptionId}** + +The resource URI variables supported by the resource shall be defined as +[Table 10](#table10) illustrates. + +[]{#table10 .anchor}**Table 10: Resource URI variables for this +resource** + + ------------------ ---------------------------------------------------- + **Name** **Definition** + + apiRoot described in clause 4.4.1 of 3GPP TS 29.501  + + apiMajorVersion v2 + + subscriptionId Identifier for subscription resource, created after + a successful subscription. See table Data Model's + [table 30](#table30) + ------------------ ---------------------------------------------------- + +#### Individual Subscription DELTE Method + +The DELETE method deletes an individual subscription resource object and +its associated properties. As the result of a successful execution of +this method a subscription resource object (the one associated with the +*subscriptionId*) and its associated properties will be deleted by the +API Producer. + +URI query parameters supported by the method shall be defined as [Table +11](#table11) illustrates. + +[]{#table11 .anchor} **Table 11: URI query parameters supported by a +method on the resource** + + -------------------- -------- ------- ----------------- ------------------ ------------------- + **Name** **Data **P** **Cardinality** **Description** **Applicability** + type** + + n/a + -------------------- -------- ------- ----------------- ------------------ ------------------- + +Data structures supported by the request body of the DELETE method shall +be specified as [Table 12](#table12) illustrates. + +[]{#table12 .anchor}**Table 12: Data structures supported by the request +body on the resource** + + ------------ --------- ----------------- ------------------------------------ + **Data **P** **Cardinality** **Description** + type** + + n/a + ------------ --------- ----------------- ------------------------------------ + +Data structures supported by the response body of the method shall be +specified as [Table 13](#table13) illustrates. + +[]{#table13 .anchor}**Table 13: Data structures supported by the +response body on the resource** + ++------------+:--------:+:-----:+:---------------:+:------------:+:----------------------------------:+ +| Response | **Data | **P** | **Cardinality** | **Response** | **Description** | +| body | type** | | | | | +| | | | | **codes** | | +| +----------+-------+-----------------+--------------+------------------------------------+ +| | n/a | | | 204 | *DELETE | +| | | | | | ../subscriptions/*{subscriptionId} | +| | | | | | deletes an individual subscription | +| | | | | | resource. | +| +----------+-------+-----------------+--------------+------------------------------------+ +| | n/a | | | 401 | Unauthorized. Authentication | +| | | | | | required. Client must provide | +| | | | | | valid mTLS certificate and/or | +| | | | | | OAuth Bearer token. | +| +----------+-------+-----------------+--------------+------------------------------------+ +| | n/a | | | 404 | Subscription resource not found. | ++------------+----------+-------+-----------------+--------------+------------------------------------+ + +#### Individual Subscription GET Method + +The GET method combined with the *subscriptionId* variable queries an +individual subscription object and its associated properties. As a +result of successful execution of this method an individual subscription +resource object (the one associated with the *subscriptionId*) and its +associated properties will return by the API Producer. + +URI query parameters supported by the method shall be defined as [Table +14](#table14) illustrates. + +[]{#table14 .anchor} **Table 14: URI query parameters supported by a +method on the resource** + + -------------------- -------- ------- ----------------- ------------------ ------------------- + **Name** **Data **P** **Cardinality** **Description** **Applicability** + type** + + n/a + -------------------- -------- ------- ----------------- ------------------ ------------------- + +Data structures supported by the request body of the GET method shall be +specified as [Table 15](#table15) illustrates. + +[]{#table15 .anchor}**Table 15: Data structures supported by the request +body on the resource** + + ----------- --------- ----------------- ------------------------------------- + **Data **P** **Cardinality** **Description** + type** + + n/a + ----------- --------- ----------------- ------------------------------------- + +Data structures supported by the response body of the method shall be +specified as [Table 16](#table16) illustrates. + +[]{#table16 .anchor}**Table 16: Data structures supported by the +response body on the resource** + ++------------+:----------------:+:-----:+:---------------:+:------------:+:-----------------------:+ +| Response | **Data type** | **P** | **Cardinality** | **Response** | **Description** | +| body | | | | | | +| | | | | **codes** | | +| +------------------+-------+-----------------+--------------+-------------------------+ +| | SubscriptionInfo | M | 1 | 200 | Returns the | +| | | | | | subscription resource | +| | | | | | object and its | +| | | | | | associated properties. | +| | | | | | | +| | | | | | See note below. | +| +------------------+-------+-----------------+--------------+-------------------------+ +| | n/a | | | 404 | Subscription resources | +| | | | | | are not available (not | +| | | | | | created). | ++------------+------------------+-------+-----------------+--------------+-------------------------+ + +**Note**: The *SubscriptionInfo* is defined in the subscription Data +Model section + +# Status Notifications API Definition + +## Description + +After a successful subscription (a subscription resource was created) +the Event Consumer (e.g. vO-DU or other CNF) shall be able to receive +event notifications from the subscribed resource. + +Events are sent by the Event Framework when a change of resource state +occurs. The significance of the change of state is dependent upon the +Event Producer service. An example for the PTP use case might be that a +**synchronization-state-change** has occurred, i.e. FREERUN-\>LOCKED or +LOCKED-\>HOLDOVER. + +The HTTP method for delivering the notification (push) to the EC shall +be POST and the notification shall be sent to the endpoint reference +provided by the EC client during the creation of the subscription +resource (see [Table 17](#mvrsb9imzfm) The payload body of the POST +request shall contain the event payload (see event data model). + +[[Figure 3]{.underline}](#figure3) illustrates an intra-node (local +notification) event delivery. In this example, the following occurs: + +1. The Event Framework determines that an event condition has occurred + +2. The Event Consumer (vO-DU etc) has previously subscribed to the + event type and the API Producer performs a POST to the EV (vO-DU + etc) with the complete JSON event payload + +[]{#figure3 .anchor}**Figure 3: Local Notification** + +![Diagram Description automatically +generated](media/image4.jpeg){width="6.695138888888889in" +height="4.459722222222222in"} + +[]{#mvrsb9imzfm .anchor} + +**Table 17: API Producer Notification methods overview** + ++:------------------------------:+:-----------------------:+:------------------------:+ +| **Resource URI** | **HTTP method or custom | **Description** | +| | operation** | | ++--------------------------------+-------------------------+--------------------------+ +| http://localhost:{port}/{path} | POST | **Deliver notification | +| | | to subscriber.** | +| | +--------------------------+ +| | | Sanity check of the | +| | | endpoint URI. | ++--------------------------------+-------------------------+--------------------------+ +| | ++-------------------------------------------------------------------------------------+ + +### Event Consumer Notification Resource Definition + +The EC's endpoint URI is used by the API Producer (Helper) to deliver +events to the Event Consumer (e.g. vO-DU or CNF). + +The EC's Endpoint URI^2^ is: + +**http://localhost:{port}/{path}** + +The resource URI variables supported by the resource shall be defined as +[Table 18](#table18) illustrates. + +[]{#table18 .anchor}**Table 18 Resource URI variables for this +resource** + + ---------- ------------------------------------------------------------ + **Name** **Definition** + + Port The port of the endpoint URI provided by the subscriber + + Path The path of the endpoint URI provided by the subscriber + ---------- ------------------------------------------------------------ + +#### Consumer Notification Delivery Method + +The HTTP method for the notification that corresponds to an explicit +subscription shall be POST and the notification shall be sent to the +endpoint reference provided during the creation of the subscription +resource. The payload body of the POST request shall contain the event +notification payload (see event data model). + +URI query parameters supported by the method shall be defined as [Table +19](#table19) illustrates. + +\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +^2^Note: To reduce security concerns and lifecycle management burden the +endpoint URI must be part of the same localhost, this is the localhost +shared by the EC and API Producer in a POD or VM. + +[]{#table19 .anchor}**Table 19: URI query parameters supported by a +method on the resource** + + ----------- ----------- ------- ------------------ ----------------- ------------------- + **Name** **Data **P** **Cardinality** **Description** **Applicability** + Type** + + n/a + ----------- ----------- ------- ------------------ ----------------- ------------------- + +Data structures supported by the request body of the POST method shall +be specified as [Table 20](#table20) illustrates. + +[]{#table20 .anchor}**Table 20: Data structures supported by the request +body on the resource** + ++:------------------:+:------------------:+:------------------:+:---------------------------------------:+ +| **Data type** | **P** | **Cardinality** | **Description** | ++--------------------+--------------------+--------------------+-----------------------------------------+ +| Event | M | 1 | The payload will include event | +| | | | notification^3^. | ++--------------------+--------------------+--------------------+-----------------------------------------+ +| | ++--------------------------------------------------------------------------------------------------------+ + +Data structures supported by the response body of the method shall be +specified as [Table 21](#table21) illustrates. + +[]{#table21 .anchor}**Table 21: Data structures supported by the +response body on the resource** + ++----------------+:--------------:+:--------------:+:---------------:+:--------------:+:----------------------:+ +| Response body | **Data type** | **P** | **Cardinality** | **Response** | **Description** | +| | | | | | | +| | | | | **codes** | | +| +----------------+----------------+-----------------+----------------+------------------------+ +| | n/a | M | 1 | 204 | Success (notification | +| | | | | | was received). | +| +----------------+----------------+-----------------+----------------+------------------------+ +| | n/a | | | 400 | Bad request by the API | +| | | | | | Producer. | +| +----------------+----------------+-----------------+----------------+------------------------+ +| | n/a | | | 404 | Not found. | +| +----------------+----------------+-----------------+----------------+------------------------+ +| | n/a | | | 408 | Request timeout. | ++----------------+----------------+----------------+-----------------+----------------+------------------------+ +| | ++--------------------------------------------------------------------------------------------------------------+ + +> + +\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +^3^Note: The *Notification* is defined in the notification Data Model +section + +[Figure 4](#figure4) shows an example event notification payload +received by an Event Consumer. + +[]{#figure4 .anchor} **Figure 4: Example Push Event Notification: +request body in JSON** + ++-----------------------------------------------------------------------+ +| { | +| | +| \"specversion\": \"1.0\", | +| | +| \"type\": "event.synchronization-state-change\", | +| | +| \"source\": "/sync/sync-status/sync-state\", | +| | +| \"id\": \"831e1650-001e-001b-66ab-eeb76e069631\", | +| | +| \"time\": \"2021-03-05T20:59:59.998888999Z\", | +| | +| "data": { | +| | +| \"version\": "1.0", | +| | +| "values": \[ | +| | +| { | +| | +| "type": "notification" | +| | +| "ResourceAddress": "/east-edge-10/Node3/sync/sync-status/sync-state", | +| | +| "value_type": "enumeration", | +| | +| \"value\": "HOLDOVER\" | +| | +| } | +| | +| \] | +| | +| } | +| | +| } | ++-----------------------------------------------------------------------+ +| | ++-----------------------------------------------------------------------+ + +#### Notification Sanity Check Method + +The Event Consumer POST request to create a subscription resource will +trigger the initial delivery of producer status of the resource that +will be sent to the endpoint URI provided by Event Consumer. The purpose +is to confirm that the endpoint URI is valid and to send the initial +status for the resource. If the validation fails, the subscription for +the resource will not be created. + +URI query parameters supported by the method shall be defined as [Table +22](#table22) illustrates. + +[]{#table22 .anchor} **Table 22: URI query parameters supported by a +method on the resource** + + ---------- -------- ------- ----------------- ------------------- ------------------------ + **Name** **Data **P** **Cardinality** **Description** **Applicability** + type** + + n/a + ---------- -------- ------- ----------------- ------------------- ------------------------ + +Data structures supported by the request body of the POST method shall +be specified as [Table 23](#table23) illustrates. + +[]{#table23 .anchor}**Table 23: Data structures supported by the request +body on the resource** + + ----------- --------- ----------------- ------------------------------------- + **Data **P** **Cardinality** **Description** + type** + + Event M 1 The payload will include event + notification. See note below. + ----------- --------- ----------------- ------------------------------------- + +**Note**: The *Notification* is defined in the notification Data Model +section + +Data structures supported by the response body of the method shall be +specified as [Table 24](#table24) illustrates. + +[]{#table24 .anchor}**Table 24: Data structures supported by the +response body on the resource** + ++------------+:-------:+:-----:+:---------------:+:------------:+:-----------------------:+ +| Response | **Data | **P** | **Cardinality** | **Response** | **Description** | +| body | type** | | | | | +| | | | | **codes** | | +| +---------+-------+-----------------+--------------+-------------------------+ +| | n/a | M | 1 | 204 | The API Producer tests | +| | | | | | the endpoint URI before | +| | | | | | creating a subscription | +| | | | | | resource. | +| +---------+-------+-----------------+--------------+-------------------------+ +| | n/a | O | 0..1 | 404 | URI not found. | ++------------+---------+-------+-----------------+--------------+-------------------------+ + +# Event Pull Status Notifications API Definition + +## Description + +In addition to receiving event status notifications the Event Consumer +(e.g. vO-DU or CNF) shall be able to pull event status notifications. +This status notifications will be limited only to the node that the +vO-DU resides on. + +[Figure 5](#figure5) illustrates event pull status notifications and +[Table 25](#table25) describes resources and methods. + +[]{#figure5 .anchor}**Figure 5: Pull Notifications** + ++-----------------------------------------------------------------------+ +| **Workload** | +| | +| Event Consumer / API Consumer | +| | +| ddddd | +| | +| API Producer | +| | +| 1\. GET PTP Status | +| | +| **Helper** | +| | +| **vDU** | +| | +| 2\. 200 OK with event status content | +| | +| Event Consumer / API Consumer | +| | +| c | +| | +| API Producer | ++-----------------------------------------------------------------------+ +| \*Helper is provided by cloud vendors | ++-----------------------------------------------------------------------+ + +[]{#table25 .anchor}**Table 25: Pull Events Notifications methods +overview** + ++--------------------+--------------------------------------------------------------------------------+:------------------:+:-------------------:+ +| **Resource name** | **Resource URI** | **HTTP method or | **Description** | +| | | custom operation** | | ++--------------------+--------------------------------------------------------------------------------+--------------------+---------------------+ +| Pull Status | {apiRoot}/ocloudNotifications/{apiMajorVersion}/{ResourceAddress}/CurrentState | GET | Event Consumer | +| Notifications | | | pulls status | +| | | | notifications | ++--------------------+--------------------------------------------------------------------------------+--------------------+---------------------+ +| | ++------------------------------------------------------------------------------------------------------------------------------------------------+ + +### Resources Pull Status Notification Definition + +The resource URI is: + +**{apiRoot}/ocloudNotifications/{apiMajorVersion}/{ResourceAddress}/CurrentState** + +The resource URI variables supported by the resource shall be defined as +[Table 26](#table26) illustrates. + +[]{#table26 .anchor}**Table 26: Resource URI variables for this +resource** + + ----------------------------- ----------------------------------------- + **Name** **Definition** + + apiRoot described in clause 4.4.1 of + 3GPP TS 29.501  + + apiMajorVersion v2 + + ResourceAddress see [Table 1](#table1) + ----------------------------- ----------------------------------------- + +#### Event Pull Status Notification GET Method + +The GET method combined with the *ResourceAddress* variable pulls the +event status notifications. As a result of successful execution of this +method the Event Consumer will receive the current event status +notifications of the node that the Event Consumer resides on. + +URI query parameters supported by the method shall be defined as [Table +27](#table27) illustrates. + +[]{#table27 .anchor}**Table 27: URI query parameters supported by a +method on the resource** + + ----------------------- -------- ------- ----------------- ----------------- ------------------- + **Name** **Data **P** **Cardinality** **Description** **Applicability** + type** + + n/a + ----------------------- -------- ------- ----------------- ----------------- ------------------- + +Data structures supported by the request body of the GET method shall be +specified as [Table 28](#table28) illustrates. + +[]{#table28 .anchor}**Table 28: Data structures supported by the request +body on the resource** + + ------------ --------- ----------------- ------------------------------------ + **Data **P** **Cardinality** **Description** + type** + + n/a + ------------ --------- ----------------- ------------------------------------ + +Data structures supported by the response body of the method shall be +specified as [Table 29](#table29) illustrates. + +[]{#table29 .anchor}**Table 29: Data structures supported by the +response body on the resource** + ++-----------+:-------:+:-----:+:---------------:+:------------:+:-------------------------:+ +| Response | **Data | **P** | **Cardinality** | **Response** | **Description** | +| body | type** | | | | | +| | | | | **codes** | | +| +---------+-------+-----------------+--------------+---------------------------+ +| | Event | M | 1 | 200 | The payload includes | +| | | | | | event notification as | +| | | | | | defined in the Data | +| | | | | | Model. | +| +---------+-------+-----------------+--------------+---------------------------+ +| | n/a | O | 0..1 | 404 | Event notification | +| | | | | | resource is not available | +| | | | | | on this node. | ++-----------+---------+-------+-----------------+--------------+---------------------------+ + +**Editor's note:** Currently the pull status operator returns the PTP +Sync State event as defined in [[PTP +Sync-State]{.underline}](#_9s5i4y3v6j4g). In future versions of this +specification, status information can be expanded to other metrics / +information pertinent to the operation of the system. + +# Event Data Model + +## Subscription Data Model + +This clause specifies the subscription data model supported by the API. + +### Structured data types + +This clause defines the structures to be used in resource +representations. + +#### Type: SubscriptionInfo + +**[Table 30](#table30) shows the data types used for subscription.** + +**Table 30: Definition of type \** + ++:---------------:+:-----------:+:-----:+-----------------+:----------------------------------------------:+:-----------------:+ +| **Attribute | **Data | **P** | **Cardinality** | **Description** | **Applicability** | +| name** | type** | | | | | ++-----------------+-------------+-------+-----------------+------------------------------------------------+-------------------+ +| SubscriptionId | string | M | 1 | Identifier for the created subscription | | +| | | | | resource. | | +| | | | | | | +| | | | | The EC can ignore it in the POST body when | | +| | | | | creating a subscription resource (this will be | | +| | | | | sent to the client after the resource is | | +| | | | | created). | | +| | | | | | | +| | | | | **See note 1 below.** | | ++-----------------+-------------+-------+-----------------+------------------------------------------------+-------------------+ +| UriLocation | string | M | 1 | ../subscriptions/{subscriptionId} | | +| | | | | | | +| | | | | The EC can ignore it in the POST body when | | +| | | | | creating a subscription resource (this will be | | +| | | | | sent to the client after the resource is | | +| | | | | created). | | +| | | | | | | +| | | | | **See note 1 below.** | | ++-----------------+-------------+-------+-----------------+------------------------------------------------+-------------------+ +| ResourceAddress | string | M | 1 | see [[Resource | | +| | | | | Addressing]{.underline}](#resource-addressing) | | ++-----------------+-------------+-------+-----------------+------------------------------------------------+-------------------+ +| EndpointUri | string | M | 1 | Endpoint URI (a.k.a callback URI), e.g. | | +| | | | | http://**localhost**:8080/resourcestatus/ptp | | +| | | | | | | +| | | | | **Please note that 'localhost' is mandatory | | +| | | | | and cannot be replaced by an IP or FQDN.** | | ++-----------------+-------------+-------+-----------------+------------------------------------------------+-------------------+ + +**Note 1:** The API Producer (Helper) shall ignore *SubscriptionId* and +*UriLocation* if sent by the EC for creating subscription. + +## Status Notifications Data Model + +This clause specifies the event Status Notification data model supported +by the API. The current model supports JSON encoding of the +[CloudEvents.io specification]{.underline} \[15\] for the event payload. + +### Structured data types + +This clause defines the structures to be used in notification +representations. + +[Table 31](#table31) shows the data types used in the event data model +JSON. + +[]{#table31 .anchor}**Table 31: Data Model Types** + ++:-----------------------------------:+:---------------------------------------------------------------:+ +| **CloudEvents** | **JSON** | ++-------------------------------------+-----------------------------------------------------------------+ +| Boolean | [boolean](https://tools.ietf.org/html/rfc7159#section-3) | ++-------------------------------------+-----------------------------------------------------------------+ +| Integer | [number](https://tools.ietf.org/html/rfc7159#section-6), only | +| | the integer component optionally prefixed with a minus sign is | +| | permitted | ++-------------------------------------+-----------------------------------------------------------------+ +| String | [string](https://tools.ietf.org/html/rfc7159#section-7) | ++-------------------------------------+-----------------------------------------------------------------+ +| Binary | [string](https://tools.ietf.org/html/rfc7159#section-7), | +| | [Base64-encoded](https://tools.ietf.org/html/rfc4648#section-4) | +| | binary | ++-------------------------------------+-----------------------------------------------------------------+ +| URI | [string](https://tools.ietf.org/html/rfc7159#section-7) | +| | following [RFC 3986](https://tools.ietf.org/html/rfc3986) | ++-------------------------------------+-----------------------------------------------------------------+ +| URI-reference | [string](https://tools.ietf.org/html/rfc7159#section-7) | +| | following [RFC 3986](https://tools.ietf.org/html/rfc3986) | ++-------------------------------------+-----------------------------------------------------------------+ +| Timestamp | [string](https://tools.ietf.org/html/rfc7159#section-7) | +| | following [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) (ISO | +| | 8601) | ++-------------------------------------+-----------------------------------------------------------------+ +| | ++-------------------------------------------------------------------------------------------------------+ + +### Event Data Model + + ----------------------------------------------------------------------- + + ----------------------------------------------------------------------- + +**Table 32: Top-Level JSON Schema** + ++:------------------:+:------------------:+:------------------:+:--------------------------------------:+ +| **Property** | **Type** | **Constraint** | **Description** | ++--------------------+--------------------+--------------------+----------------------------------------+ +| id | String | rcv-only | Identifies the event. The Event | +| | | | Producer SHALL ensure that source + id | +| | | | is unique for each distinct event. | ++--------------------+--------------------+--------------------+----------------------------------------+ +| type | String | req | This attribute contains a value | +| | | | describing the type of event related | +| | | | to the originating occurrence. | ++--------------------+--------------------+--------------------+----------------------------------------+ +| source | URI-reference | rcv-only | Identifies the context in which an | +| | | | event happened. | ++--------------------+--------------------+--------------------+----------------------------------------+ +| specversion | String | rcv-only | The version of the CloudEvents | +| | | | specification which the event uses. | +| | | | This enables the interpretation of the | +| | | | context. | ++--------------------+--------------------+--------------------+----------------------------------------+ +| time | Timestamp | req | Time at which the event occurred. | ++--------------------+--------------------+--------------------+----------------------------------------+ +| data | String | req | Array of JSON objects defining the | +| | | | information for the event | +| | (JSON array) | | | ++--------------------+--------------------+--------------------+----------------------------------------+ +| version | String | req | Version of the Notification API Schema | +| | | | generating the event. | +| | | | | +| | | | '1.0' until a future revision. | ++--------------------+--------------------+--------------------+----------------------------------------+ +| values | String | req | A json array of values defining the | +| | | | event. | +| | (JSON array) | | | ++--------------------+--------------------+--------------------+----------------------------------------+ +| | ++-------------------------------------------------------------------------------------------------------+ +| | ++-------------------------------------------------------------------------------------------------------+ + +**Table 35: Data Array Object Schema** + ++:-------------------------:+:-------------------------:+:--------------------------------------:+ +| **Property** | **Type** | **Description** | ++---------------------------+---------------------------+----------------------------------------+ +| data_type | String | Type of value object. ( | +| | | **notification** \| **metric)** | ++---------------------------+---------------------------+----------------------------------------+ +| ResourceAddress | String | See Table 2 | +| | | | +| | (path) | | ++---------------------------+---------------------------+----------------------------------------+ +| value_type | Enumeration | The type format of the *value* | +| | | property () | ++---------------------------+---------------------------+----------------------------------------+ +| value | String | String representation of value in | +| | | value_type format | ++---------------------------+---------------------------+----------------------------------------+ +| Table 34 shows an example event that contains Sync-State information. | +| | +| **Table 34: Example Event \-- Sync-State** | +| | +| +-----------------------------------------------------------------------+ | +| | { | | +| | | | +| | \"id\": \"A234-1234-1234\", | | +| | | | +| | \"specversion\": \"1.0\", | | +| | | | +| | \"source\": \"/sync/sync-status/sync-state\", | | +| | | | +| | \"type\": \"event.sync.sync-status.synchronization-state-change\", | | +| | | | +| | \"time\": \"2021-03-05T20:59:00.999999999Z\", | | +| | | | +| | \"data\": { | | +| | | | +| | \"version\": \"1.0\", | | +| | | | +| | \"values\": \[ | | +| | | | +| | { | | +| | | | +| | \"data_type\": \"notification\", | | +| | | | +| | \"ResourceAddress\": | | +| | \"/east-edge-10/Node3/sync/sync-status/sync-state\", | | +| | | | +| | \"value_type\": \"enumeration\", | | +| | | | +| | \"value\": \"HOLDOVER\" | | +| | | | +| | } | | +| | | | +| | \] | | +| | | | +| | } | | +| | | | +| | } | | +| +-----------------------------------------------------------------------+ | ++------------------------------------------------------------------------------------------------+ + +### Synchronization Event Specifications + +The following sections define the events related to synchronization +events. + +Editor\'s Note: synchronization state change events are addressed first +due to priority of the RAN use cases, the event distribution +infrastructure and associated interfaces are not limited to one specific +event category, and events from other subsystems will be added in the +future versions of this document. + +Editor\'s Note: the present event set is aligned with / based on the +WG4/WG5 YANG models; however, use of some other definitions such as +composite clock modes in G.8275 (10/2020), Appendix VIII (or composite +of the two approaches) \*may\* be more useful to convey the information +in detail required to adequately specify the states in the cloud nodes +context. + +#### + +#### Synchronization State + +This notification abstracts the underlying technology that the node is +using to synchronize itself. It provides the overall synchronization +health of the node. This notification includes the health of the OS +System Clock which is consumable by application(s). + +**Table 36: Synchronization State Notification** + ++:------------:+:---------------------------------------------------:+:-----------------------------------:+ +| **Property** | **Value** | **Description** | ++--------------+-----------------------------------------------------+-------------------------------------+ +| type | event.sync.sync-status.synchronization-state-change | Notification used to inform about | +| | | the overall synchronization state | +| | | change | ++--------------+-----------------------------------------------------+-------------------------------------+ +| source | /sync/sync-status/sync-state | Overall synchronization health of | +| | | the node, including the OS System | +| | | Clock | ++--------------+-----------------------------------------------------+-------------------------------------+ +| value_type | enumeration | | ++--------------+-----------------------------------------------------+-------------------------------------+ +| value | LOCKED | Equipment is in the locked mode, as | +| | | defined in ITU-T G.810 | +| +-----------------------------------------------------+-------------------------------------+ +| | HOLDOVER | Equipment clock is in holdover | +| | | mode, as defined in ITU-T G.810 | +| +-----------------------------------------------------+-------------------------------------+ +| | FREERUN | Equipment clock isn\'t locked to an | +| | | input reference, and is not in the | +| | | holdover mode, as defined in ITU-T | +| | | G.810 | ++--------------+-----------------------------------------------------+-------------------------------------+ + +#### + +#### PTP Synchronization State + +**Table 37: Synchronization State Notification** + ++:------------:+:--------------------------------------:+:-----------------------------------:+ +| **Property** | **Value** | **Description** | ++--------------+----------------------------------------+-------------------------------------+ +| type | event.sync.ptp-status.ptp-state-change | Notification used to inform about | +| | | ptp synchronization state change | ++--------------+----------------------------------------+-------------------------------------+ +| source | /sync/ptp-status/lock-state | ptp-state-change notification is | +| | | signalled from equipment at state | +| | | change | ++--------------+----------------------------------------+-------------------------------------+ +| value_type | enumeration | | ++--------------+----------------------------------------+-------------------------------------+ +| value | LOCKED | Equipment is in the locked mode, as | +| | | defined in ITU-T G.810 | +| +----------------------------------------+-------------------------------------+ +| | HOLDOVER | Equipment clock is in holdover | +| | | mode, as defined in ITU-T G.810 | +| +----------------------------------------+-------------------------------------+ +| | FREERUN | Equipment clock isn\'t locked to an | +| | | input reference, and is not in the | +| | | holdover mode, as defined in ITU-T | +| | | G.810 | ++--------------+----------------------------------------+-------------------------------------+ + +#### + +#### Void + +#### Void + +#### GNSS-Sync-State + +**Table 40: GNSS-Sync-State Notification** + ++:------------:+:----------------------------------------:+:-----------------------------------:+ +| **Property** | **Value** | **Description** | ++--------------+------------------------------------------+-------------------------------------+ +| type | event.sync.gnss-status.gnss-state-change | Notification used to inform about | +| | | gnss synchronization state change | ++--------------+------------------------------------------+-------------------------------------+ +| source | /sync/gnss-status/gnss-sync-status | gnss-state-change notification is | +| | | signalled from equipment at state | +| | | change | ++--------------+------------------------------------------+-------------------------------------+ +| value_type | enumeration | | ++--------------+------------------------------------------+-------------------------------------+ +| value | SYNCHRONIZED | GNSS functionality is synchronized | +| +------------------------------------------+-------------------------------------+ +| | ACQUIRING-SYNC | GNSS functionality is acquiring | +| | | sync | +| +------------------------------------------+-------------------------------------+ +| | ANTENNA-DISCONNECTED | GNSS functionality has its antenna | +| | | disconnected | +| +------------------------------------------+-------------------------------------+ +| | BOOTING | GNSS functionality is booting | +| +------------------------------------------+-------------------------------------+ +| | ANTENNA-SHORT-CIRCUIT | GNSS functionality has an antenna | +| | | short circuit | +| +------------------------------------------+-------------------------------------+ +| | FAILURE-MULTIPATH | GNSS Sync Failure - Multipath | +| | | condition detected | +| +------------------------------------------+-------------------------------------+ +| | FAILURE-NOFIX | GNSS Sync Failure - Unknown | +| +------------------------------------------+-------------------------------------+ +| | FAILURE-LOW-SNR | GNSS Sync Failure - Low SNR | +| | | condition detected | +| +------------------------------------------+-------------------------------------+ +| | FAILURE-PLL | GNSS Sync Failure - PLL is not | +| | | functioning | ++--------------+------------------------------------------+-------------------------------------+ + +#### Void + +#### OS Clock Sync-State + +**Table 37: OS clock Sync-State Notification** + ++:------------:+:-------------------------------------------------:+:-----------------------------------:+ +| **Property** | **Value** | **Description** | ++--------------+---------------------------------------------------+-------------------------------------+ +| type | event.sync.sync-status.os-clock-sync-state-change | The object contains information | +| | | related to a notification | ++--------------+---------------------------------------------------+-------------------------------------+ +| source | /sync/sync-status/os-clock-sync-state | State of node OS clock | +| | | synchronization is notified at | +| | | state change | ++--------------+---------------------------------------------------+-------------------------------------+ +| value_type | enumeration | | ++--------------+---------------------------------------------------+-------------------------------------+ +| value | LOCKED | Operating System real-time clock is | +| | | in the locked mode, node operating | +| | | system clock is synchronized to | +| | | traceable & valid time/phase source | +| +---------------------------------------------------+-------------------------------------+ +| | HOLDOVER | Operating System real-time clock is | +| | | in holdover mode | +| +---------------------------------------------------+-------------------------------------+ +| | FREERUN | Operating System real-time clock | +| | | isn\'t locked to an input | +| | | reference, and is not in the | +| | | holdover mode | ++--------------+---------------------------------------------------+-------------------------------------+ + +#### SyncE Lock-Status-Extended + +This notification is a SyncE Lock-state notification that provides +detail about the synce PLL states. + +**Table 39: SyncE-Extended Lock-State Notification** + ++:-----------------------:+:------------------------------------------:+:-----------------------------------:+ +| **Property** | **Value** | **Description** | ++-------------------------+--------------------------------------------+-------------------------------------+ +| **type** | event.sync.synce-status.synce-state-change | Notification used to inform about | +| | | synce synchronization state change, | +| | | enhanced state information | ++-------------------------+--------------------------------------------+-------------------------------------+ +| **source** | **/sync/synce-status/lock-state** | synce-state change notification is | +| | | signalled from equipment at state | +| | | change, enhanced information | ++-------------------------+--------------------------------------------+-------------------------------------+ +| **value_type** | **enumeration** | | ++-------------------------+--------------------------------------------+-------------------------------------+ +| **value** | **LOCKED** | **The integrated ordinary clock is | +| | | synchronizing to the reference, | +| | | recovered from SyncE signal** | +| +--------------------------------------------+-------------------------------------+ +| | **HOLDOVER** | **The integrated ordinary clock is | +| | | not synchronizing to the reference | +| | | recovered from the SyncE signal, | +| | | and is in holdover mode** | +| +--------------------------------------------+-------------------------------------+ +| | **FREERUN** | **The integrated ordinary clock is | +| | | not synchronizing to the reference, | +| | | recovered from SyncE signal** | ++-------------------------+--------------------------------------------+-------------------------------------+ +| | ++------------------------------------------------------------------------------------------------------------+ + +#### PTP Clock Class Change + +A PTP Clock Class change notification is generated when the PTP clock +change attribute in the Announce message changes. + +**Table 36: PTP Clock class change Notification** + + -------------- ---------------------------------------------- ------------------------------------- + **Property** **Value** **Description** + + type event.sync.ptp-status.ptp-clock-class-change Notification used to inform about ptp + clock class changes. + + source /sync/ptp-status/clock-class ptp-clock-class-change notification + is generated when the clock-class + changes. + + value_type metric + + value Uint8 New clock class attribute + -------------- ---------------------------------------------- ------------------------------------- + +#### + +#### SyncE Clock Quality Change + +A SyncE Clock Quality change notification is generated when the SyncE +clock quality attribute in the ESMC message changes. + +**Table 43: SyncE Clock class change Notification** + + -------------- ---------------------------------------------------- ------------------------------------- + **Property** **Value** **Description** + + type event.sync.synce-status.synce-clock-quality-change Notification used to inform about + changes in the clock quality of the + primary SyncE signal advertised in + ESMC packets + + source /sync/synce-status/clock-quality synce-clock-quality-change + notification is generated when the + clock-quality changes. + + value_type metric + + value Uint8 New clock quality attribute + -------------- ---------------------------------------------------- ------------------------------------- + +#### + +#### + + ----------------------------------------------------------------------- + + ----------------------------------------------------------------------- + +## Appendix A + +### Helper/Sidecar containers + +Reference: +[[https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/]{.underline}](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/) + +Helper/Sidecar containers extend and enhance the \"main\" container, +they take existing containers and make them better.   + +As an example, consider a container that runs the Nginx web server.  Add +a different container that syncs the file system with a git repository, +share the file system between the containers and one has built built Git +push-to-deploy. And it has been done in a modular manner where the git +synchronizer can be built by a different team, and can be reused across +many different web servers (Apache, Python, Tomcat, etc).  Because of +this modularity, the git synchronizer may be written and tested only +once and reused across numerous apps. + +![Diagram Description automatically +generated](media/image5.png){width="3.5787959317585303in" +height="2.2918044619422573in"} + +### Helper/Sidecar value: + +- Interacts with the notification framework on behalf of the vO-DU + +- Decouples the app logic from the notification framework, hence removes + the burden of implementing a lot of code on the vO-DU and maintaining + this code + +- Single secure and reliable API endpoint since it is exposed over the + localhost + +- Eliminating the discovery of an external pod implementation + +## + +######## Annex (informative): Change History + ++--------------------------------+--------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+ +| # **Date** {#date .TT} | # **Revision** {#revision .TT} | # **Author** {#author .TT} | # **Description** {#description-2 .TT} | ++================================+================================+==============================================================+=============================================================================================================================================+ +| # 05/10/2021 {#section-7 .TT} | # 00.00.01 {#section-8 .TT} | # Aaron Smith (RH) {#aaron-smith-rh .TT} | # Initial skeleton. {#initial-skeleton. .TT} | +| | | | | +| | | Udi Schwager (WRS) | | ++--------------------------------+--------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+ +| # 07/22/2021 {#section-9 .TT} | # 01.00.00 {#section-10 .TT} | # Kaustubh Joshi (AT&T) {#kaustubh-joshi-att .TT} | # Approved for publication. {#approved-for-publication. .TT} | ++--------------------------------+--------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+ +| # 03/28/2022 {#section-11 .TT} | # 02.00.00 {#section-12 .TT} | # Padma Sudarsan (VMWare) {#padma-sudarsan-vmware .TT} | # Incorporated 2 approved CRs (VMware, Wind River, RedHat, Altiostar) {#incorporated-2-approved-crs-vmware-wind-river-redhat-altiostar .TT} | ++--------------------------------+--------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+ +| # 03/05/2022 {#section-13 .TT} | # 02.00.01 {#section-14 .TT} | # Udi Schwager (Wind River) {#udi-schwager-wind-river .TT} | # Ready for TSC review. {#ready-for-tsc-review. .TT} | ++--------------------------------+--------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+ +| # 07/25/2022 {#section-15 .TT} | # 03.00.00 {#section-16 .TT} | # Udi Schwager (Wind River) {#udi-schwager-wind-river-1 .TT} | # Support for multiple event producers {#support-for-multiple-event-producers .TT} | ++--------------------------------+--------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+ +| # 03/15/2024 {#section-17 .TT} | # 03.00.01 {#section-18 .TT} | # Udi Schwager (Wind River) {#udi-schwager-wind-river-2 .TT} | # Incorporated Qualcomm CR {#incorporated-qualcomm-cr .TT} | ++--------------------------------+--------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+ +| # 03/21/2024 {#section-19 .TT} | # 03.00.03 {#section-20 .TT} | # Udi Schwager (Wind River) {#udi-schwager-wind-river-3 .TT} | # Editorial updates {#editorial-updates .TT} | ++--------------------------------+--------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+ + +# {#section-21 .TT} diff --git a/docs/rest_api_v2.md b/docs/rest_api_v2.md index 629131b..d6ff822 100644 --- a/docs/rest_api_v2.md +++ b/docs/rest_api_v2.md @@ -1,8 +1,8 @@ -# O-RAN Compliant REST API -REST API Spec. +# O-RAN Compliant REST API with Authentication +O-RAN compliant REST API for cloud event notifications with mTLS and OAuth 2.0 authentication support. This API provides secure event subscription management, publisher control, and real-time event notifications for OpenShift and Kubernetes environments. ## Informations @@ -11,15 +11,35 @@ REST API Spec. 2.0.0 +### License + +[Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) + +### Contact + +Red Hat CNE Team https://github.com/redhat-cne/rest-api + ## Tags ### Subscriptions -Manage Subscriptions +Manage event subscriptions for O-RAN compliant notifications. Includes both O-RAN standard operations and extensions. + + ### Publishers + +Manage event publishers and their configurations. Extensions to O-RAN API for internal cluster management. ### Events -Event Pull Status Notification +Event publication and status notification endpoints. Includes current state retrieval and event creation. + + ### HealthCheck + +Health and status monitoring endpoints. Extensions to O-RAN API for service availability checking. + + ### Authentication + +Authentication and authorization using mTLS (mutual TLS) and OAuth 2.0 with OpenShift integration. ## Content negotiation @@ -33,6 +53,35 @@ Event Pull Status Notification ### Produces * application/json +## Access control + +### Security Schemes + +#### OAuth2 + +OAuth 2.0 authentication using Bearer tokens. Supports OpenShift OAuth server and Kubernetes ServiceAccount tokens. + +> **Type**: oauth2 +> +> **Flow**: application +> +> **Token URL**: https://oauth-openshift.apps.cluster.local/oauth/token + + +##### Scopes + +Name | Description +-----|------------- +user:info | Access to user information +read | Read access to resources +write | Write access to resources + +#### mTLS + +Mutual TLS authentication using client certificates. Clients must present valid certificates signed by the trusted CA. + +> **Type**: basic + ## All endpoints ### events @@ -81,6 +130,10 @@ POST /api/ocloudNotifications/v2/subscriptions Creates a new subscription for the required event by passing the appropriate payload. +#### Security Requirements + * mTLS + * OAuth2: write + #### Parameters | Name | Source | Type | Go type | Separator | Required | Default | Description | @@ -92,6 +145,7 @@ Creates a new subscription for the required event by passing the appropriate pay |------|--------|-------------|:-----------:|--------| | [201](#create-subscription-201) | Created | Shall be returned when the subscription resource is created successfully. | | [schema](#create-subscription-201-schema) | | [400](#create-subscription-400) | Bad Request | Bad request. For example, the endpoint URI is not correctly formatted. | | [schema](#create-subscription-400-schema) | +| [401](#create-subscription-401) | Unauthorized | Unauthorized. Authentication required (mTLS and/or OAuth). | | [schema](#create-subscription-401-schema) | | [404](#create-subscription-404) | Not Found | Not Found. Subscription resource is not available. | | [schema](#create-subscription-404-schema) | | [409](#create-subscription-409) | Conflict | Conflict. The subscription resource already exists. | | [schema](#create-subscription-409-schema) | @@ -112,6 +166,11 @@ Status: Bad Request ###### Schema +##### 401 - Unauthorized. Authentication required (mTLS and/or OAuth). +Status: Unauthorized + +###### Schema + ##### 404 - Not Found. Subscription resource is not available. Status: Not Found @@ -130,10 +189,15 @@ DELETE /api/ocloudNotifications/v2/subscriptions Delete all subscriptions. +#### Security Requirements + * mTLS + * OAuth2: write + #### All responses | Code | Status | Description | Has headers | Schema | |------|--------|-------------|:-----------:|--------| | [204](#delete-all-subscriptions-204) | No Content | Deleted all subscriptions. | | [schema](#delete-all-subscriptions-204-schema) | +| [401](#delete-all-subscriptions-401) | Unauthorized | Unauthorized. Authentication required (mTLS and/or OAuth). | | [schema](#delete-all-subscriptions-401-schema) | #### Responses @@ -143,6 +207,11 @@ Status: No Content ###### Schema +##### 401 - Unauthorized. Authentication required (mTLS and/or OAuth). +Status: Unauthorized + +###### Schema + ### Delete a specific subscription. (*deleteSubscription*) ``` @@ -151,6 +220,10 @@ DELETE /api/ocloudNotifications/v2/subscriptions/{subscriptionId} Deletes an individual subscription resource object and its associated properties. +#### Security Requirements + * mTLS + * OAuth2: write + #### Parameters | Name | Source | Type | Go type | Separator | Required | Default | Description | @@ -161,6 +234,7 @@ Deletes an individual subscription resource object and its associated properties | Code | Status | Description | Has headers | Schema | |------|--------|-------------|:-----------:|--------| | [204](#delete-subscription-204) | No Content | Success. | | [schema](#delete-subscription-204-schema) | +| [401](#delete-subscription-401) | Unauthorized | Unauthorized. Authentication required (mTLS and/or OAuth). | | [schema](#delete-subscription-401-schema) | | [404](#delete-subscription-404) | Not Found | Not Found. Subscription resources are not available (not created). | | [schema](#delete-subscription-404-schema) | #### Responses @@ -171,6 +245,11 @@ Status: No Content ###### Schema +##### 401 - Unauthorized. Authentication required (mTLS and/or OAuth). +Status: Unauthorized + +###### Schema + ##### 404 - Not Found. Subscription resources are not available (not created). Status: Not Found @@ -403,7 +482,7 @@ Example: |------|------|---------|:--------:| ------- |-------------|---------| | DataType | string| `string` | | | Type of value object. ( notification | metric) | `notification` | | Resource | string| `string` | | | The resource address specifies the Event Producer with a hierarchical path. Currently hierarchical paths with wild cards are not supported. | `/east-edge-10/Node3/sync/sync-status/sync-state` | -| Value | [interface{}](#interface)| `interface{}` | | | value in value_type format. | `HOLDOVER` | +| Value | [any](#any)| `any` | | | value in value_type format. | `HOLDOVER` | | ValueType | string| `string` | | | The type format of the value property. | `enumeration` | diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..1f6afb3 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,34 @@ +# Authentication Configuration Examples + +This directory contains example configuration files for setting up authentication with the REST API. + +## Files + +### Configuration Examples + +- **`openshift-auth-config.json`** - Example authentication configuration for OpenShift environments + - Uses OpenShift Service CA for mTLS certificate management + - Integrates with OpenShift's built-in OAuth server + - Template format with placeholder URLs that should be customized for your cluster + +### Deployment Examples + +- **`openshift-manifests.yaml`** - Complete Kubernetes manifests for OpenShift deployment + - Service definitions with Service CA annotations + - ConfigMaps for cluster information and authentication configuration + - ServiceAccount and RBAC resources + - Template format with `{{.NodeName}}` and `{{.ClusterName}}` placeholders + +## Usage + +1. **For OpenShift deployments**: Use the `openshift-*` files as templates +2. **Replace placeholders**: Update `your-cluster.com` with your actual cluster domain +3. **Deploy**: Apply the manifests to your OpenShift cluster + +## Template Variables + +- `{{.NodeName}}` - Replaced with the actual node name during deployment +- `{{.ClusterName}}` - Should be replaced with your cluster's domain name +- `your-cluster.com` - Placeholder that should be replaced with your actual cluster domain + +For detailed instructions, see the main [Authentication Configuration](../AUTHENTICATION.md) documentation. diff --git a/examples/openshift-auth-config.json b/examples/openshift-auth-config.json new file mode 100644 index 0000000..425e9f0 --- /dev/null +++ b/examples/openshift-auth-config.json @@ -0,0 +1,16 @@ +{ + "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, + "requiredAudiences": ["https://kubernetes.default.svc"], + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token", + + "tlsMinVersion": "VersionTLS12", + "tlsCipherSuites": [] +} diff --git a/examples/openshift-manifests.yaml b/examples/openshift-manifests.yaml new file mode 100644 index 0000000..a562e54 --- /dev/null +++ b/examples/openshift-manifests.yaml @@ -0,0 +1,202 @@ +# Unified OpenShift Authentication Configuration +# Works for both single node and multi-node OpenShift clusters +# Uses OpenShift's built-in Service CA and OAuth server + +--- +# Service with Service CA annotation for automatic certificate generation +apiVersion: v1 +kind: Service +metadata: + annotations: + prometheus.io/scrape: "false" + service.beta.openshift.io/serving-cert-secret-name: cloud-event-proxy-tls + labels: + app: linuxptp-daemon + name: ptp-event-publisher-service-{{.NodeName}} + namespace: openshift-ptp +spec: + clusterIP: None + selector: + app: linuxptp-daemon + nodeName: {{.NodeName}} + ports: + - name: publisher-port + port: 9043 + sessionAffinity: None + type: ClusterIP + +--- +# ConfigMap for cluster information +apiVersion: v1 +kind: ConfigMap +metadata: + name: cluster-info + namespace: openshift-ptp +data: + cluster-name: "{{.ClusterName}}" + +--- +# ConfigMap for authentication configuration +apiVersion: v1 +kind: ConfigMap +metadata: + name: cloud-event-proxy-auth-config + namespace: openshift-ptp +data: + auth-config.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, + "requiredAudiences": ["https://kubernetes.default.svc"], + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" + } + +--- +# ServiceAccount for the cloud-event-proxy +apiVersion: v1 +kind: ServiceAccount +metadata: + name: cloud-event-proxy-sa + namespace: openshift-ptp + +--- +# Role for cloud-event-proxy permissions +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cloud-event-proxy-role + namespace: openshift-ptp +rules: +- apiGroups: [""] + resources: ["events"] + verbs: ["create", "update", "patch"] +- apiGroups: [""] + resources: ["configmaps"] + verbs: ["get", "list", "watch"] +- apiGroups: [""] + resources: ["secrets"] + verbs: ["get", "list", "watch"] + +--- +# RoleBinding to bind ServiceAccount to Role +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: cloud-event-proxy-binding + namespace: openshift-ptp +subjects: +- kind: ServiceAccount + name: cloud-event-proxy-sa + namespace: openshift-ptp +roleRef: + kind: Role + name: cloud-event-proxy-role + apiGroup: rbac.authorization.k8s.io + +--- +# ClusterRole granting permission to create TokenReviews. The server validates +# OAuth bearer tokens by calling the Kubernetes TokenReview API, which requires +# this cluster-scoped permission (equivalent to the built-in +# system:auth-delegator ClusterRole). +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cloud-event-proxy-tokenreview +rules: +- apiGroups: ["authentication.k8s.io"] + resources: ["tokenreviews"] + verbs: ["create"] + +--- +# ClusterRoleBinding binding the TokenReview ClusterRole to the server SA. +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: cloud-event-proxy-tokenreview +subjects: +- kind: ServiceAccount + name: cloud-event-proxy-sa + namespace: openshift-ptp +roleRef: + kind: ClusterRole + name: cloud-event-proxy-tokenreview + apiGroup: rbac.authorization.k8s.io + +--- +# ConfigMap that OpenShift's Service CA operator populates with the cluster's +# Service CA bundle (service-ca.crt). This is the CA that signs the serving +# certificate above, so it is what clients and the server's own mTLS pool must +# trust - NOT the serving-cert Secret (which holds tls.crt/tls.key, not a CA). +apiVersion: v1 +kind: ConfigMap +metadata: + name: cloud-event-proxy-ca-bundle + namespace: openshift-ptp + annotations: + service.beta.openshift.io/inject-cabundle: "true" + +--- +# DaemonSet configuration for cloud-event-proxy +# Works on both single node and multi-node clusters +apiVersion: apps/v1 +kind: DaemonSet +metadata: + name: linuxptp-daemon + namespace: openshift-ptp +spec: + selector: + matchLabels: + app: linuxptp-daemon + nodeName: {{.NodeName}} + template: + metadata: + labels: + app: linuxptp-daemon + nodeName: {{.NodeName}} + spec: + serviceAccountName: cloud-event-proxy-sa + containers: + - name: cloud-event-proxy + image: quay.io/redhat-cne/cloud-event-proxy:latest + args: + - "--auth-config=/etc/cloud-event-proxy/auth/auth-config.json" + env: + - name: CLUSTER_NAME + valueFrom: + configMapKeyRef: + name: cluster-info + key: cluster-name + - name: NODE_NAME + valueFrom: + fieldRef: + fieldPath: spec.nodeName + volumeMounts: + - name: server-certs + mountPath: /etc/cloud-event-proxy/server-certs + readOnly: true + - name: ca-bundle + mountPath: /etc/cloud-event-proxy/ca-bundle + readOnly: true + - name: auth-config + mountPath: /etc/cloud-event-proxy/auth + readOnly: true + volumes: + - name: server-certs + secret: + secretName: cloud-event-proxy-tls + # The CA bundle comes from the Service CA ConfigMap (service-ca.crt), + # not the serving-cert Secret. caCertPath above points at + # /etc/cloud-event-proxy/ca-bundle/service-ca.crt, which this ConfigMap + # provides. Without a valid CA the server fails closed and will not serve. + - name: ca-bundle + configMap: + name: cloud-event-proxy-ca-bundle + - name: auth-config + configMap: + name: cloud-event-proxy-auth-config diff --git a/pkg/restclient/client.go b/pkg/restclient/client.go index bfbbaeb..a021049 100644 --- a/pkg/restclient/client.go +++ b/pkg/restclient/client.go @@ -47,6 +47,18 @@ func New() *Rest { } } +// NewWithClient returns a Rest client that uses the supplied *http.Client. This +// lets callers inject an SSRF-hardened client (resolve-then-validate dialer plus +// a no-redirect policy) when POSTing to caller-supplied endpoints, instead of +// the default client which follows redirects and dials arbitrary resolved +// addresses. A nil client falls back to the default configuration. +func NewWithClient(client *http.Client) *Rest { + if client == nil { + return New() + } + return &Rest{client: *client} +} + // PostEvent post an event to the give url and check for error func (r *Rest) PostCloudEvent(url *types.URI, e ce.Event) (status int, err error) { b, err := json.Marshal(e) diff --git a/v2/auth.go b/v2/auth.go new file mode 100644 index 0000000..79667dc --- /dev/null +++ b/v2/auth.go @@ -0,0 +1,300 @@ +// Copyright 2025 The Cloud Native Events Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package restapi + +import ( + "context" + "crypto/tls" + "crypto/x509" + "fmt" + "net" + "net/http" + "net/url" + "os" + "strings" + + log "github.com/sirupsen/logrus" +) + +// initMTLSCACertPool initializes the CA certificate pool for mTLS +func (s *Server) initMTLSCACertPool() error { + if s.authConfig == nil || !s.authConfig.EnableMTLS || s.authConfig.CACertPath == "" { + return nil + } + + caCert, err := os.ReadFile(s.authConfig.CACertPath) + if err != nil { + log.Errorf("failed to read CA certificate: %v", err) + return err + } + + s.caCertPool = x509.NewCertPool() + if !s.caCertPool.AppendCertsFromPEM(caCert) { + log.Error("failed to parse CA certificate") + return fmt.Errorf("failed to parse CA certificate") + } + + log.Info("mTLS CA certificate pool initialized") + return nil +} + +// TokenInfo carries the authenticated identity returned by a TokenValidator. +type TokenInfo struct { + Username string + UID string + Groups []string + Audiences []string +} + +// TokenValidator validates an OAuth 2.0 / OIDC bearer token and returns the +// authenticated identity. Implementations are supplied by the embedding +// application (e.g. cloud-event-proxy uses the Kubernetes TokenReview API) so +// that this library remains free of any Kubernetes client dependency. +// +// A validator MUST cryptographically verify the token (signature and, when +// audiences are supplied, audience binding). Returning a non-nil error MUST +// cause the request to be rejected with 401. +type TokenValidator interface { + ValidateToken(ctx context.Context, token string, audiences []string) (*TokenInfo, error) +} + +// SetTokenValidator installs the bearer-token validator used when OAuth is +// enabled. When OAuth is enabled and no validator is installed, all +// non-localhost requests fail closed (401). +func (s *Server) SetTokenValidator(v TokenValidator) { + s.tokenValidator = v +} + +// isLoopbackRemoteAddr reports whether the request originates from the local +// loopback interface (same pod). Such requests never leave the pod's network +// namespace and are treated as a trusted fast-path. +func isLoopbackRemoteAddr(remoteAddr string) bool { + if remoteAddr == "" { + return false + } + host := remoteAddr + if h, _, err := net.SplitHostPort(remoteAddr); err == nil { + host = h + } + host = strings.Trim(host, "[]") + if ip := net.ParseIP(host); ip != nil { + return ip.IsLoopback() + } + return host == "localhost" +} + +// validateEndpointURI performs SSRF hardening on a caller-supplied callback / +// endpoint URI (subscriber EndpointUri or publisher endpoint). Per O-RAN +// RHT-0003 the host may be localhost, an IP, or an FQDN, so those are allowed; +// link-local, cloud-metadata, multicast and unspecified addresses are rejected. +func validateEndpointURI(raw string) error { + u, err := url.Parse(raw) + if err != nil { + return fmt.Errorf("invalid EndpointUri %q: %v", raw, err) + } + if u.Scheme != "http" && u.Scheme != "https" { + return fmt.Errorf("EndpointUri scheme must be http or https, got %q", u.Scheme) + } + host := u.Hostname() + if host == "" { + return fmt.Errorf("EndpointUri host is empty") + } + if ip := net.ParseIP(host); ip != nil && isBlockedDialIP(ip) { + return fmt.Errorf("EndpointUri host %q is not an allowed address", host) + } + return nil +} + +// isBlockedDialIP reports whether an IP is disallowed as an outbound +// destination. Loopback and private (RFC1918 / IPv6 ULA) addresses are +// permitted on purpose: per O-RAN RHT-0003 callbacks may be in-pod (localhost) +// and event consumers routinely run as cluster Pods with private IPs. Only +// link-local, multicast, unspecified and cloud-metadata addresses are blocked. +func isBlockedDialIP(ip net.IP) bool { + if ip == nil { + return true + } + if ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() || ip.IsMulticast() || ip.IsUnspecified() { + return true + } + // Cloud instance-metadata endpoints (IPv4 IMDS is already link-local; the + // IPv6 variant is unique-local so must be listed explicitly). + if ip.Equal(net.ParseIP("169.254.169.254")) || ip.Equal(net.ParseIP("fd00:ec2::254")) { + return true + } + return false +} + +// newSafeDialContext returns a DialContext that resolves the target host and +// rejects the connection if any resolved address is blocked, then dials the +// resolved IP directly. Dialing the already-resolved address (rather than the +// hostname) closes the DNS-rebinding TOCTOU window between validation and +// connection. +func newSafeDialContext(base *net.Dialer) func(ctx context.Context, network, addr string) (net.Conn, error) { + return func(ctx context.Context, network, addr string) (net.Conn, error) { + host, port, err := net.SplitHostPort(addr) + if err != nil { + return nil, err + } + ips, err := net.DefaultResolver.LookupIPAddr(ctx, host) + if err != nil { + return nil, err + } + for _, ipa := range ips { + if isBlockedDialIP(ipa.IP) { + return nil, fmt.Errorf("refusing to connect to blocked address %s (resolved from %q)", ipa.IP, host) + } + } + var firstErr error + for _, ipa := range ips { + conn, derr := base.DialContext(ctx, network, net.JoinHostPort(ipa.IP.String(), port)) + if derr == nil { + return conn, nil + } + firstErr = derr + } + return nil, firstErr + } +} + +// noRedirectPolicy prevents the endpoint-validation client from following +// redirects, which could otherwise be used to reach a blocked address after the +// initial destination passed validation. The 3xx response itself is returned to +// the caller unfollowed. +func noRedirectPolicy(_ *http.Request, _ []*http.Request) error { + return http.ErrUseLastResponse +} + +// tlsVersionFromString maps a TLS version name (as used by the OpenShift +// TLSSecurityProfile / crypto/tls) to its constant. Returns 0 when unknown. +func tlsVersionFromString(v string) uint16 { + switch strings.TrimSpace(v) { + case "VersionTLS10": + return tls.VersionTLS10 + case "VersionTLS11": + return tls.VersionTLS11 + case "VersionTLS12": + return tls.VersionTLS12 + case "VersionTLS13": + return tls.VersionTLS13 + default: + return 0 + } +} + +// cipherSuitesFromNames maps IANA cipher suite names to their crypto/tls IDs. +// Unknown names are ignored. TLS 1.3 cipher suites are not configurable in Go +// and are silently dropped, which is expected. +func cipherSuitesFromNames(names []string) []uint16 { + if len(names) == 0 { + return nil + } + lookup := make(map[string]uint16) + for _, cs := range tls.CipherSuites() { + lookup[cs.Name] = cs.ID + } + for _, cs := range tls.InsecureCipherSuites() { + lookup[cs.Name] = cs.ID + } + var out []uint16 + for _, n := range names { + if id, ok := lookup[strings.TrimSpace(n)]; ok { + out = append(out, id) + } + } + return out +} + +// ApplyTLSProfile applies the centrally-managed TLS profile (min version and +// cipher suites, sourced from the cluster's TLSSecurityProfile via the +// operator) onto a tls.Config. Nothing is hardcoded here: values come from the +// AuthConfig. Only when no min version is supplied at all do we fall back to +// TLS 1.2 to avoid negotiating an insecure protocol by default. +func (c *AuthConfig) ApplyTLSProfile(cfg *tls.Config) { + if c == nil { + return + } + if mv := tlsVersionFromString(c.TLSMinVersion); mv != 0 { + cfg.MinVersion = mv + } else if cfg.MinVersion == 0 { + cfg.MinVersion = tls.VersionTLS12 + } + if cs := cipherSuitesFromNames(c.TLSCipherSuites); len(cs) > 0 { + cfg.CipherSuites = cs + } +} + +// combinedAuthMiddleware enforces mTLS and/or OAuth on protected endpoints. +// +// Requests from the local loopback interface (same pod) are treated as a +// trusted fast-path and skip authentication - they never leave the pod. All +// other (FQDN / service-DNS / external) requests must satisfy every enabled +// mechanism: a verified client certificate when mTLS is enabled, and a valid +// bearer token when OAuth is enabled. +func (s *Server) combinedAuthMiddleware(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // Trusted loopback fast-path (same pod, e.g. in-process producer self-call). + if isLoopbackRemoteAddr(r.RemoteAddr) { + log.Debugf("allowing loopback connection from %s for %s", r.RemoteAddr, r.URL.Path) + next.ServeHTTP(w, r) + return + } + + // mTLS: the TLS handshake (ClientAuth: VerifyClientCertIfGiven) has + // already verified any presented certificate chain against the CA pool; + // here we require that a client certificate was in fact presented. + if s.authConfig != nil && s.authConfig.EnableMTLS { + if r.TLS == nil || len(r.TLS.PeerCertificates) == 0 { + log.Warnf("mTLS required but no client certificate provided for %s", r.URL.Path) + http.Error(w, "Client certificate required", http.StatusUnauthorized) + return + } + log.Debugf("client certificate present and verified for %s", r.URL.Path) + } + + // OAuth: require and validate a bearer token. + if s.authConfig != nil && s.authConfig.EnableOAuth { + authHeader := r.Header.Get("Authorization") + if authHeader == "" { + log.Warnf("OAuth required but no Authorization header provided for %s", r.URL.Path) + http.Error(w, "Authorization header required", http.StatusUnauthorized) + return + } + if !strings.HasPrefix(authHeader, "Bearer ") { + log.Warnf("invalid Authorization header format for %s", r.URL.Path) + http.Error(w, "Bearer token required", http.StatusUnauthorized) + return + } + token := strings.TrimSpace(strings.TrimPrefix(authHeader, "Bearer ")) + + // Fail closed: OAuth is enabled but no validator was installed. + if s.tokenValidator == nil { + log.Error("OAuth enabled but no TokenValidator configured; rejecting request") + http.Error(w, "token validation unavailable", http.StatusUnauthorized) + return + } + + info, err := s.tokenValidator.ValidateToken(r.Context(), token, s.authConfig.RequiredAudiences) + if err != nil { + log.Warnf("OAuth token validation failed for %s: %v", r.URL.Path, err) + http.Error(w, "Invalid OAuth token", http.StatusUnauthorized) + return + } + log.Debugf("OAuth token validated for %s (user=%s)", r.URL.Path, info.Username) + } + + next.ServeHTTP(w, r) + }) +} diff --git a/v2/auth_internal_test.go b/v2/auth_internal_test.go new file mode 100644 index 0000000..ef3a196 --- /dev/null +++ b/v2/auth_internal_test.go @@ -0,0 +1,124 @@ +// Copyright 2025 The Cloud Native Events Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package restapi + +import ( + "crypto/tls" + "net" + "testing" +) + +func TestIsBlockedDialIP(t *testing.T) { + cases := []struct { + ip string + blocked bool + }{ + // Allowed: loopback (RHT-0003 in-pod) and private (cluster Pod IPs). + {"127.0.0.1", false}, + {"::1", false}, + {"10.0.0.5", false}, + {"172.16.3.4", false}, + {"192.168.1.10", false}, + {"fd12:3456::1", false}, + {"93.184.216.34", false}, // public + // Blocked: link-local, cloud metadata, multicast, unspecified. + {"169.254.0.1", true}, + {"169.254.169.254", true}, + {"fe80::1", true}, + {"fd00:ec2::254", true}, + {"224.0.0.1", true}, + {"0.0.0.0", true}, + {"::", true}, + } + for _, c := range cases { + ip := net.ParseIP(c.ip) + if ip == nil { + t.Fatalf("bad test IP %q", c.ip) + } + if got := isBlockedDialIP(ip); got != c.blocked { + t.Errorf("isBlockedDialIP(%s) = %v, want %v", c.ip, got, c.blocked) + } + } + if !isBlockedDialIP(nil) { + t.Errorf("isBlockedDialIP(nil) should be blocked") + } +} + +func TestValidateEndpointURI(t *testing.T) { + valid := []string{ + "http://localhost:8080/event", + "https://consumer.ptp.svc.cluster.local:9043/ack", + "http://10.128.0.9:8080/callback", + } + for _, u := range valid { + if err := validateEndpointURI(u); err != nil { + t.Errorf("validateEndpointURI(%q) = %v, want nil", u, err) + } + } + invalid := []string{ + "ftp://host/x", // bad scheme + "http://", // empty host + "://nope", // unparseable scheme + "http://169.254.169.254/latest", // metadata + "http://[fe80::1]/x", // link-local + "http://224.0.0.1/x", // multicast + "http://0.0.0.0/x", // unspecified + } + for _, u := range invalid { + if err := validateEndpointURI(u); err == nil { + t.Errorf("validateEndpointURI(%q) = nil, want error", u) + } + } +} + +func TestIsLoopbackRemoteAddr(t *testing.T) { + yes := []string{"127.0.0.1:5000", "[::1]:5000", "localhost:5000", "127.0.0.1"} + no := []string{"", "10.0.0.1:5000", "192.168.1.1:80", "example.com:80"} + for _, a := range yes { + if !isLoopbackRemoteAddr(a) { + t.Errorf("isLoopbackRemoteAddr(%q) = false, want true", a) + } + } + for _, a := range no { + if isLoopbackRemoteAddr(a) { + t.Errorf("isLoopbackRemoteAddr(%q) = true, want false", a) + } + } +} + +func TestApplyTLSProfile(t *testing.T) { + // Explicit profile is applied verbatim. + c := &AuthConfig{ + TLSMinVersion: "VersionTLS13", + TLSCipherSuites: []string{"TLS_AES_128_GCM_SHA256", "bogus-name"}, + } + cfg := &tls.Config{} //nolint:gosec // MinVersion set by ApplyTLSProfile under test + c.ApplyTLSProfile(cfg) + if cfg.MinVersion != tls.VersionTLS13 { + t.Errorf("MinVersion = %x, want TLS13", cfg.MinVersion) + } + + // No profile => default floor of TLS 1.2, existing MinVersion preserved. + empty := &AuthConfig{} + cfg2 := &tls.Config{} //nolint:gosec // MinVersion set by ApplyTLSProfile under test + empty.ApplyTLSProfile(cfg2) + if cfg2.MinVersion != tls.VersionTLS12 { + t.Errorf("default MinVersion = %x, want TLS12", cfg2.MinVersion) + } + + // Nil receiver must not panic. + var nilCfg *AuthConfig + nilCfg.ApplyTLSProfile(&tls.Config{}) //nolint:gosec // nil-receiver no-op path under test +} diff --git a/v2/routes.go b/v2/routes.go index d8ad388..a3b9d19 100644 --- a/v2/routes.go +++ b/v2/routes.go @@ -78,6 +78,11 @@ func (s *Server) createSubscription(w http.ResponseWriter, r *http.Request) { localmetrics.UpdateSubscriptionCount(localmetrics.FAILCREATE, 1) return } + if err = validateEndpointURI(endPointURI); err != nil { + respondWithStatusCode(w, http.StatusBadRequest, err.Error()) + localmetrics.UpdateSubscriptionCount(localmetrics.FAILCREATE, 1) + return + } for id, address := range s.subscriberAPI.GetClientIDAddressByResource(sub.GetResource()) { if address.String() == endPointURI { respondWithStatusCode(w, http.StatusConflict, @@ -122,7 +127,11 @@ func (s *Server) createSubscription(w http.ResponseWriter, r *http.Request) { return } - restClient := restclient.New() + // Use the server's SSRF-hardened HTTP client (resolve-then-validate dialer + // plus no-redirect policy) for the initial-notification POST to the + // caller-supplied EndpointURI, rather than the default client which would + // follow redirects and dial arbitrary resolved addresses. + restClient := restclient.NewWithClient(s.HTTPClient) // make sure event ID is unique out.Data.SetID(uuid.New().String()) status, err := restClient.PostCloudEvent(sub.EndPointURI, *out.Data) @@ -199,6 +208,11 @@ func (s *Server) createPublisher(w http.ResponseWriter, r *http.Request) { return } if pub.GetEndpointURI() != "" { + if err = validateEndpointURI(pub.GetEndpointURI()); err != nil { + localmetrics.UpdatePublisherCount(localmetrics.FAILCREATE, 1) + respondWithError(w, err.Error()) + return + } response, err = s.HTTPClient.Post(pub.GetEndpointURI(), cloudevents.ApplicationJSON, nil) if err != nil { log.Infof("there was an error validating the publisher endpointurl %v, publisher won't be created.", err) diff --git a/v2/server.go b/v2/server.go index 899ff15..83c1a57 100644 --- a/v2/server.go +++ b/v2/server.go @@ -33,7 +33,9 @@ package restapi import ( + "encoding/json" "fmt" + "os" "github.com/redhat-cne/sdk-go/pkg/util/wait" @@ -47,7 +49,10 @@ import ( pubsubv1 "github.com/redhat-cne/sdk-go/v1/pubsub" subscriberApi "github.com/redhat-cne/sdk-go/v1/subscriber" + "crypto/tls" + "crypto/x509" "io" + "net" "net/http" "strings" "time" @@ -65,6 +70,23 @@ type ServerStatus int const ( HTTPReadHeaderTimeout = 2 * time.Second + // HTTPReadTimeout bounds the total time to read the entire request, including + // a slowly-transmitted body. ReadHeaderTimeout only covers the headers and + // WriteTimeout does not bound request-body reads, so without this a client + // could dribble a POST body to pin a handler goroutine indefinitely + // (Slowloris on the request body). Request bodies here are small JSON + // documents, so this is set to the same generous ceiling as the write side. + HTTPReadTimeout = 30 * time.Second + // HTTPWriteTimeout bounds the time to read the request body plus write the + // response, capping slow/stalled clients. It is set comfortably above the + // 10s timeout of the outbound initial-notification POST that + // createSubscription performs while handling a request. + HTTPWriteTimeout = 30 * time.Second + // HTTPIdleTimeout bounds how long an idle keep-alive connection is retained, + // so flooding the server with idle connections cannot exhaust it. + HTTPIdleTimeout = 60 * time.Second + // HTTPMaxHeaderBytes caps request header size to limit per-connection memory. + HTTPMaxHeaderBytes = 1 << 20 // 1 MiB ) const ( @@ -75,6 +97,73 @@ const ( CURRENTSTATE = "CurrentState" ) +// AuthConfig contains authentication configuration for both single and multi-node OpenShift clusters +type AuthConfig struct { + // mTLS configuration - works for both single and multi-node clusters + EnableMTLS bool `json:"enableMTLS"` + CACertPath string `json:"caCertPath"` + ServerCertPath string `json:"serverCertPath"` + ServerKeyPath string `json:"serverKeyPath"` + UseServiceCA bool `json:"useServiceCA"` // Use OpenShift Service CA (recommended for all cluster sizes) + + // OAuth 2.0 / bearer-token configuration. Tokens are validated by the + // TokenValidator installed via Server.SetTokenValidator (cloud-event-proxy + // uses the Kubernetes TokenReview API), so no issuer/JWKS is configured here. + EnableOAuth bool `json:"enableOAuth"` + RequiredAudiences []string `json:"requiredAudiences"` // Required token audiences (validated by TokenReview) + ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount used by clients for authentication + ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path (client side) + UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Client hint: obtain tokens from OpenShift OAuth + + // TLS profile - centrally managed by the cluster's TLSSecurityProfile and + // propagated by the operator. Nothing is hardcoded in this library. + TLSMinVersion string `json:"tlsMinVersion"` // e.g. "VersionTLS12", "VersionTLS13" + TLSCipherSuites []string `json:"tlsCipherSuites"` // IANA cipher suite names +} + +// LoadAuthConfig loads authentication configuration from a JSON file +func LoadAuthConfig(configPath string) (*AuthConfig, error) { + // Check if file exists + if _, err := os.Stat(configPath); os.IsNotExist(err) { + return nil, fmt.Errorf("authentication config file not found: %s", configPath) + } + + data, err := os.ReadFile(configPath) + if err != nil { + return nil, fmt.Errorf("failed to read authentication config file %s: %v", configPath, err) + } + + var config AuthConfig + if err := json.Unmarshal(data, &config); err != nil { + return nil, fmt.Errorf("failed to unmarshal authentication config: %v", err) + } + return &config, nil +} + +// GetConfigSummary returns a summary of the authentication configuration +func (c *AuthConfig) GetConfigSummary() string { + summary := "Authentication Configuration Summary:\n" + summary += fmt.Sprintf(" Enable mTLS: %t\n", c.EnableMTLS) + if c.EnableMTLS { + summary += fmt.Sprintf(" CA Cert Path: %s\n", c.CACertPath) + summary += fmt.Sprintf(" Server Cert Path: %s\n", c.ServerCertPath) + summary += fmt.Sprintf(" Server Key Path: %s\n", c.ServerKeyPath) + summary += fmt.Sprintf(" Use Service CA: %t\n", c.UseServiceCA) + } + summary += fmt.Sprintf(" Enable OAuth: %t\n", c.EnableOAuth) + if c.EnableOAuth { + summary += fmt.Sprintf(" Required Audiences: %v\n", c.RequiredAudiences) + summary += fmt.Sprintf(" Service Account Name: %s\n", c.ServiceAccountName) + summary += fmt.Sprintf(" Service Account Token Path: %s\n", c.ServiceAccountToken) + summary += fmt.Sprintf(" Use OpenShift OAuth: %t\n", c.UseOpenShiftOAuth) + } + if c.TLSMinVersion != "" || len(c.TLSCipherSuites) > 0 { + summary += fmt.Sprintf(" TLS Min Version: %s\n", c.TLSMinVersion) + summary += fmt.Sprintf(" TLS Cipher Suites: %v\n", c.TLSCipherSuites) + } + return summary +} + // Server defines rest routes server object type Server struct { port int @@ -90,6 +179,9 @@ type Server struct { status ServerStatus statusReceiveOverrideFn func(e cloudevents.Event, dataChan *channel.DataChan) error statusLock sync.RWMutex + authConfig *AuthConfig + caCertPool *x509.CertPool + tokenValidator TokenValidator } // SubscriptionInfo @@ -215,24 +307,71 @@ type swaggEventData struct { //nolint:deadcode,unused // InitServer is used to supply configurations for rest routes server func InitServer(port int, apiHost, apiPath, storePath string, dataOut chan<- *channel.DataChan, closeCh <-chan struct{}, - onStatusReceiveOverrideFn func(e cloudevents.Event, dataChan *channel.DataChan) error) *Server { + onStatusReceiveOverrideFn func(e cloudevents.Event, dataChan *channel.DataChan) error, + authConfig *AuthConfig) *Server { once.Do(func() { ServerInstance = &Server{ - port: port, - apiHost: apiHost, - apiPath: apiPath, - dataOut: dataOut, - closeCh: closeCh, - status: notReady, - HTTPClient: &http.Client{ - Transport: &http.Transport{ - MaxIdleConnsPerHost: 20, - }, - Timeout: 10 * time.Second, - }, + port: port, + apiHost: apiHost, + apiPath: apiPath, + dataOut: dataOut, + closeCh: closeCh, + status: notReady, pubSubAPI: pubsubv1.GetAPIInstance(storePath), subscriberAPI: subscriberApi.GetAPIInstance(storePath), statusReceiveOverrideFn: onStatusReceiveOverrideFn, + authConfig: authConfig, + } + + // Initialize the mTLS CA certificate pool first so the HTTPClient below + // can verify endpoint certificates against it. When mTLS is enabled a + // usable CA pool is mandatory: without it client certificates cannot be + // verified and endpoint server certificates cannot be validated, so we + // must fail closed rather than silently fall back to an unverified + // configuration. The absence of a pool is enforced in Start(), which + // refuses to begin serving TLS when it is nil. + if authConfig != nil && authConfig.EnableMTLS { + if authConfig.CACertPath == "" { + log.Error("InitServer: mTLS enabled but CACertPath is empty; server will fail closed at Start()") + } else if err := ServerInstance.initMTLSCACertPool(); err != nil { + log.Errorf("InitServer: failed to initialize mTLS CA certificate pool: %v; server will fail closed at Start()", err) + } + } + + // Configure HTTPClient used to validate publisher endpoints. When mTLS + // is enabled we verify the endpoint's server certificate against the CA + // pool (Service CA) rather than skipping verification. + // A shared dialer whose DialContext resolves the target and rejects + // blocked (link-local / metadata / multicast) addresses before + // connecting, closing the SSRF DNS-rebinding window for endpoint checks. + safeDial := newSafeDialContext(&net.Dialer{Timeout: 10 * time.Second}) + if authConfig != nil && authConfig.EnableMTLS { + tlsClientConfig := &tls.Config{ + RootCAs: ServerInstance.caCertPool, + MinVersion: tls.VersionTLS12, + } + // ApplyTLSProfile may raise MinVersion to the cluster-configured floor. + authConfig.ApplyTLSProfile(tlsClientConfig) + ServerInstance.HTTPClient = &http.Client{ + Transport: &http.Transport{ + MaxIdleConnsPerHost: 20, + TLSClientConfig: tlsClientConfig, + DialContext: safeDial, + }, + Timeout: 10 * time.Second, + CheckRedirect: noRedirectPolicy, + } + log.Info("InitServer: configured HTTPClient with CA verification for mTLS endpoint validation") + } else { + // Use default HTTP client for non-mTLS configurations + ServerInstance.HTTPClient = &http.Client{ + Transport: &http.Transport{ + MaxIdleConnsPerHost: 20, + DialContext: safeDial, + }, + Timeout: 10 * time.Second, + CheckRedirect: noRedirectPolicy, + } } }) // singleton @@ -249,8 +388,29 @@ func (s *Server) EndPointHealthChk() (err error) { continue } - log.Debugf("health check %s%s ", s.GetHostPath(), "health") - response, errResp := http.Get(fmt.Sprintf("%s%s", s.GetHostPath(), "health")) + healthURL := s.GetHealthPath() + log.Debugf("health check %s", healthURL) + + var response *http.Response + var errResp error + + if s.authConfig != nil && s.authConfig.EnableMTLS { + // Use HTTPS client without client certificate for health checks + client := &http.Client{ + Transport: &http.Transport{ + TLSClientConfig: &tls.Config{ + RootCAs: s.caCertPool, + InsecureSkipVerify: true, // nolint:gosec // Required for localhost health checks with self-signed certs + // No client certificate provided - this is allowed for /health + }, + }, + } + response, errResp = client.Get(healthURL) + } else { + // Use regular HTTP client + response, errResp = http.Get(healthURL) + } + if errResp != nil { log.Errorf("try %d, return health check of the rest service for error %v", i, errResp) time.Sleep(healthCheckPause) @@ -299,7 +459,28 @@ func (s *Server) GetStatus() ServerStatus { // GetHostPath returns hostpath func (s *Server) GetHostPath() *types.URI { - return types.ParseURI(fmt.Sprintf("http://localhost:%d%s", s.port, s.apiPath)) + protocol := "http" + port := s.port + path := s.apiPath + + if s.authConfig != nil && s.authConfig.EnableMTLS { + protocol = "https" + fmt.Printf("GetHostPath: Using HTTPS protocol (authConfig.EnableMTLS=%t)\n", s.authConfig.EnableMTLS) + } else { + fmt.Printf("GetHostPath: Using HTTP protocol (authConfig=%v, EnableMTLS=%t)\n", s.authConfig != nil, s.authConfig != nil && s.authConfig.EnableMTLS) + } + uri := types.ParseURI(fmt.Sprintf("%s://localhost:%d%s", protocol, port, path)) + fmt.Printf("GetHostPath: Returning URI=%s\n", uri.String()) + return uri +} + +// GetHealthPath returns the health check URL +func (s *Server) GetHealthPath() string { + protocol := "http" + if s.authConfig != nil && s.authConfig.EnableMTLS { + protocol = "https" + } + return fmt.Sprintf("%s://localhost:%d%shealth", protocol, s.port, s.apiPath) } // Start will start res routes service @@ -314,6 +495,14 @@ func (s *Server) Start() { api := r.PathPrefix(s.apiPath).Subrouter() + // Helper function to apply authentication to handlers + applyAuth := func(handler http.HandlerFunc, needsAuth bool) http.Handler { + if needsAuth { + return s.combinedAuthMiddleware(http.Handler(handler)) + } + return handler + } + // createSubscription create subscription and send it to a channel that is shared by middleware to process // swagger:operation POST /subscriptions Subscriptions createSubscription // --- @@ -330,11 +519,13 @@ func (s *Server) Start() { // "$ref": "#/responses/pubSubResp" // "400": // description: Bad request. For example, the endpoint URI is not correctly formatted. + // "401": + // description: Unauthorized. Authentication required (mTLS and/or OAuth). // "404": // description: Not Found. Subscription resource is not available. // "409": // description: Conflict. The subscription resource already exists. - api.HandleFunc("/subscriptions", s.createSubscription).Methods(http.MethodPost) + api.Handle("/subscriptions", applyAuth(s.createSubscription, true)).Methods(http.MethodPost) // swagger:operation GET /subscriptions Subscriptions getSubscriptions // --- @@ -345,7 +536,7 @@ func (s *Server) Start() { // "$ref": "#/responses/subscriptions" // "400": // description: Bad request by the client. - api.HandleFunc("/subscriptions", s.getSubscriptions).Methods(http.MethodGet) + api.Handle("/subscriptions", applyAuth(s.getSubscriptions, true)).Methods(http.MethodGet) // swagger:operation GET /subscriptions/{subscriptionId} Subscriptions getSubscriptionByID // --- @@ -356,7 +547,7 @@ func (s *Server) Start() { // "$ref": "#/responses/subscription" // "404": // description: Not Found. Subscription resources are not available (not created). - api.HandleFunc("/subscriptions/{subscriptionId}", s.getSubscriptionByID).Methods(http.MethodGet) + api.Handle("/subscriptions/{subscriptionId}", applyAuth(s.getSubscriptionByID, true)).Methods(http.MethodGet) // swagger:operation DELETE /subscriptions/{subscriptionId} Subscriptions deleteSubscription // --- @@ -365,9 +556,11 @@ func (s *Server) Start() { // responses: // "204": // description: Success. + // "401": + // description: Unauthorized. Authentication required (mTLS and/or OAuth). // "404": // description: Not Found. Subscription resources are not available (not created). - api.HandleFunc("/subscriptions/{subscriptionId}", s.deleteSubscription).Methods(http.MethodDelete) + api.Handle("/subscriptions/{subscriptionId}", applyAuth(s.deleteSubscription, true)).Methods(http.MethodDelete) // swagger:operation GET /{ResourceAddress}/CurrentState Events getCurrentState // --- @@ -378,7 +571,7 @@ func (s *Server) Start() { // "$ref": "#/responses/eventResp" // "404": // description: Not Found. Event notification resource is not available on this node. - api.HandleFunc("/{resourceAddress:.*}/CurrentState", s.getCurrentState).Methods(http.MethodGet) + api.Handle("/{resourceAddress:.*}/CurrentState", applyAuth(s.getCurrentState, true)).Methods(http.MethodGet) // *** Extensions to O-RAN API *** @@ -389,6 +582,7 @@ func (s *Server) Start() { // responses: // "200": // "$ref": "#/responses/statusOK" + // Note: Health endpoint is always accessible without authentication api.HandleFunc("/health", func(w http.ResponseWriter, _ *http.Request) { io.WriteString(w, "OK") //nolint:errcheck }).Methods(http.MethodGet) @@ -404,7 +598,7 @@ func (s *Server) Start() { // "$ref": "#/responses/publishers" // "404": // description: Publishers not found - api.HandleFunc("/publishers", s.getPublishers).Methods(http.MethodGet) + api.Handle("/publishers", applyAuth(s.getPublishers, true)).Methods(http.MethodGet) // swagger:operation DELETE /subscriptions Subscriptions deleteAllSubscriptions // --- @@ -413,13 +607,15 @@ func (s *Server) Start() { // responses: // "204": // description: Deleted all subscriptions. - api.HandleFunc("/subscriptions", s.deleteAllSubscriptions).Methods(http.MethodDelete) + // "401": + // description: Unauthorized. Authentication required (mTLS and/or OAuth). + api.Handle("/subscriptions", applyAuth(s.deleteAllSubscriptions, true)).Methods(http.MethodDelete) // *** Internal API *** - api.HandleFunc("/publishers/{publisherid}", s.getPublisherByID).Methods(http.MethodGet) - api.HandleFunc("/publishers/{publisherid}", s.deletePublisher).Methods(http.MethodDelete) - api.HandleFunc("/publishers", s.deleteAllPublishers).Methods(http.MethodDelete) + api.Handle("/publishers/{publisherid}", applyAuth(s.getPublisherByID, true)).Methods(http.MethodGet) + api.Handle("/publishers/{publisherid}", applyAuth(s.deletePublisher, true)).Methods(http.MethodDelete) + api.Handle("/publishers", applyAuth(s.deleteAllPublishers, true)).Methods(http.MethodDelete) //pingForSubscribedEventStatus pings for event status if the publisher has capability to push event on demand // this API is internal @@ -435,11 +631,13 @@ func (s *Server) Start() { // "$ref": "#/responses/pubSubResp" // "400": // "$ref": "#/responses/badReq" - api.HandleFunc("/subscriptions/status/{subscriptionId}", s.pingForSubscribedEventStatus).Methods(http.MethodPut) + // "401": + // description: Unauthorized. Authentication required (mTLS and/or OAuth). + api.Handle("/subscriptions/status/{subscriptionId}", applyAuth(s.pingForSubscribedEventStatus, true)).Methods(http.MethodPut) - api.HandleFunc("/log", s.logEvent).Methods(http.MethodPost) + api.Handle("/log", applyAuth(s.logEvent, true)).Methods(http.MethodPost) - api.HandleFunc("/publishers", s.createPublisher).Methods(http.MethodPost) + api.Handle("/publishers", applyAuth(s.createPublisher, true)).Methods(http.MethodPost) //publishEvent create event and send it to a channel that is shared by middleware to process // this API is internal @@ -457,12 +655,14 @@ func (s *Server) Start() { // "$ref": "#/responses/acceptedReq" // "400": // "$ref": "#/responses/badReq" - api.HandleFunc("/create/event", s.publishEvent).Methods(http.MethodPost) + // "401": + // description: Unauthorized. Authentication required (mTLS and/or OAuth). + api.Handle("/create/event", applyAuth(s.publishEvent, true)).Methods(http.MethodPost) // for internal test - api.HandleFunc("/dummy", dummy).Methods(http.MethodPost) + api.Handle("/dummy", applyAuth(dummy, true)).Methods(http.MethodPost) // for internal test: test multiple clients - api.HandleFunc("/dummy2", dummy).Methods(http.MethodPost) + api.Handle("/dummy2", applyAuth(dummy, true)).Methods(http.MethodPost) err := r.Walk(func(route *mux.Route, _ *mux.Router, _ []*mux.Route) error { pathTemplate, err := route.GetPathTemplate() @@ -492,22 +692,78 @@ func (s *Server) Start() { if err != nil { log.Println(err) } - api.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { - fmt.Fprintln(w, r) - }) log.Infof("starting v2 rest api server at port %d, endpoint %s", s.port, s.apiPath) go wait.Until(func() { s.SetStatus(started) s.httpServer = &http.Server{ ReadHeaderTimeout: HTTPReadHeaderTimeout, + ReadTimeout: HTTPReadTimeout, + WriteTimeout: HTTPWriteTimeout, + IdleTimeout: HTTPIdleTimeout, + MaxHeaderBytes: HTTPMaxHeaderBytes, Addr: fmt.Sprintf(":%d", s.port), Handler: api, } - err := s.httpServer.ListenAndServe() - if err != nil { - log.Errorf("restarting due to error with api server %s\n", err.Error()) - s.SetStatus(failed) + + // Configure TLS if mTLS is enabled + if s.authConfig != nil && s.authConfig.EnableMTLS { + if s.authConfig.ServerCertPath == "" || s.authConfig.ServerKeyPath == "" { + log.Error("mTLS enabled but server certificate or key path not provided") + s.SetStatus(failed) + return + } + + // Fail closed: without a CA pool, presented client certificates + // cannot be verified against a trusted authority, so an mTLS + // server must not begin listening. + if s.caCertPool == nil { + log.Error("mTLS enabled but CA certificate pool is not initialized; refusing to start (fail closed)") + s.SetStatus(failed) + return + } + + // Load server certificate and key + cert, err := tls.LoadX509KeyPair(s.authConfig.ServerCertPath, s.authConfig.ServerKeyPath) + if err != nil { + log.Errorf("failed to load server certificate: %v", err) + s.SetStatus(failed) + return + } + + // VerifyClientCertIfGiven lets loopback clients connect without a + // certificate (trusted same-pod fast-path) while cryptographically + // verifying any certificate that IS presented against the CA pool. + // The middleware then requires a verified certificate for all + // non-loopback (FQDN/service-DNS/external) requests. + tlsConfig := &tls.Config{ + Certificates: []tls.Certificate{cert}, + ClientAuth: tls.VerifyClientCertIfGiven, + ClientCAs: s.caCertPool, + MinVersion: tls.VersionTLS12, + } + // Apply the centrally-managed TLS profile (min version + ciphers). + // A configured profile may raise MinVersion above the TLS 1.2 floor. + s.authConfig.ApplyTLSProfile(tlsConfig) + + s.httpServer.TLSConfig = tlsConfig + + // Note: When mTLS is enabled, client certificates are requested but validated at middleware level. + // The /health endpoint allows connections without certificates, while other endpoints require them. + + log.Info("starting HTTPS server with application-level mTLS") + err = s.httpServer.ListenAndServeTLS("", "") + if err != nil { + log.Errorf("restarting due to error with TLS api server %s\n", err.Error()) + s.SetStatus(failed) + } + } else { + log.Info("starting HTTP server") + err := s.httpServer.ListenAndServe() + if err != nil { + log.Errorf("restarting due to error with api server %s\n", err.Error()) + s.SetStatus(failed) + } } }, 1*time.Second, s.closeCh) } diff --git a/v2/server_test.go b/v2/server_test.go index 6df1b9e..74a8ad3 100644 --- a/v2/server_test.go +++ b/v2/server_test.go @@ -22,6 +22,7 @@ import ( "net/http" "net/url" "os" + "strings" "sync" "testing" "time" @@ -91,7 +92,7 @@ func init() { } func TestMain(m *testing.M) { - server = restapi.InitServer(port, apHost, apPath, storePath, eventOutCh, closeCh, onReceiveOverrideFn) + server = restapi.InitServer(port, apHost, apPath, storePath, eventOutCh, closeCh, onReceiveOverrideFn, nil) //start http server server.Start() @@ -483,7 +484,7 @@ func TestServer_CreatePublisher(t *testing.T) { // 5.3.6.5 (1) Expected results: The return code is “200 OK”. func TestServer_GetCurrentState_OK(t *testing.T) { ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -511,7 +512,7 @@ func TestServer_GetCurrentState_KO_ResourceInvalid(t *testing.T) { // try getting event time.Sleep(2 * time.Second) - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, resourceInvalid, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(resourceInvalid, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -543,7 +544,7 @@ func onReceiveOverrideFnEmptyEventData(e cloudevents.Event, d *channel.DataChan) func TestServer_GetCurrentState_KO_EmptyEventData(t *testing.T) { server.SetOnStatusReceiveOverrideFn(onReceiveOverrideFnEmptyEventData) ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -579,7 +580,7 @@ func onReceiveOverrideFnInvalidEventData(e cloudevents.Event, d *channel.DataCha func TestServer_GetCurrentState_KO_InvalidEventData(t *testing.T) { server.SetOnStatusReceiveOverrideFn(onReceiveOverrideFnInvalidEventData) ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -614,7 +615,7 @@ func onReceiveOverrideFnEventNotFound(e cloudevents.Event, d *channel.DataChan) func TestServer_GetCurrentState_KO_EventNotFound(t *testing.T) { server.SetOnStatusReceiveOverrideFn(onReceiveOverrideFnEventNotFound) ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -650,7 +651,7 @@ func onReceiveOverrideFnPTPNotSet(e cloudevents.Event, d *channel.DataChan) erro func TestServer_GetCurrentState_KO_PTPNotSet(t *testing.T) { server.SetOnStatusReceiveOverrideFn(onReceiveOverrideFnPTPNotSet) ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) diff --git a/v2/swagger.json b/v2/swagger.json index 8666e15..bffa065 100644 --- a/v2/swagger.json +++ b/v2/swagger.json @@ -6,17 +6,32 @@ "application/json" ], "schemes": [ - "http", "https" ], "swagger": "2.0", "info": { - "description": "REST API Spec.", - "title": "O-RAN Compliant REST API", - "version": "2.0.0" + "description": "O-RAN compliant REST API for cloud event notifications with mTLS and OAuth 2.0 authentication support. This API provides secure event subscription management, publisher control, and real-time event notifications for OpenShift and Kubernetes environments.", + "title": "O-RAN Compliant REST API with Authentication", + "version": "2.0.0", + "contact": { + "name": "Red Hat CNE Team", + "url": "https://github.com/redhat-cne/rest-api" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0" + } }, "host": "localhost:9043", "basePath": "/api/ocloudNotifications/v2", + "securityDefinitions": { + "BearerToken": { + "type": "apiKey", + "name": "Authorization", + "in": "header", + "description": "OAuth 2.0 Bearer token supplied in the Authorization header, e.g. `Authorization: Bearer `. Tokens (OpenShift OAuth or Kubernetes ServiceAccount tokens) are validated server-side via the Kubernetes TokenReview API, which checks the issuer, signature, expiry and audience. NOTE: in addition to the Bearer token, every protected endpoint also requires mutual TLS - the client must present a certificate signed by the trusted CA. mTLS cannot be represented in the Swagger 2.0 security model but is enforced at the transport layer for all non-loopback requests. CONFIGURATION-DEPENDENT: this document describes the fully-secured (strict) deployment. Each mechanism is applied only when enabled in the server's AuthConfig - the Bearer token is required only when OAuth is enabled (EnableOAuth) and mTLS only when mTLS is enabled (EnableMTLS); a deployment may enable either, both, or neither. Loopback (same-pod) requests bypass both checks." + } + }, "paths": { "/health": { "get": { @@ -41,10 +56,18 @@ ], "summary": "(Extensions to O-RAN API) Get publishers.", "operationId": "getPublishers", + "security": [ + { + "BearerToken": [] + } + ], "responses": { "200": { "$ref": "#/responses/publishers" }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." + }, "404": { "description": "Publishers not found" } @@ -59,12 +82,20 @@ ], "summary": "Retrieves a list of subscriptions.", "operationId": "getSubscriptions", + "security": [ + { + "BearerToken": [] + } + ], "responses": { "200": { "$ref": "#/responses/subscriptions" }, "400": { "description": "Bad request by the client." + }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." } } }, @@ -75,6 +106,11 @@ ], "summary": "Creates a subscription resource for the Event Consumer.", "operationId": "createSubscription", + "security": [ + { + "BearerToken": [] + } + ], "parameters": [ { "description": "The payload will include an event notification request, endpointUri and ResourceAddress. The SubscriptionId and UriLocation are ignored in the POST body (these will be sent to the client after the resource is created).", @@ -92,6 +128,9 @@ "400": { "description": "Bad request. For example, the endpoint URI is not correctly formatted." }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." + }, "404": { "description": "Not Found. Subscription resource is not available." }, @@ -107,9 +146,17 @@ ], "summary": "(Extensions to O-RAN API) Delete all subscriptions.", "operationId": "deleteAllSubscriptions", + "security": [ + { + "BearerToken": [] + } + ], "responses": { "204": { "description": "Deleted all subscriptions." + }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." } } } @@ -122,6 +169,11 @@ ], "summary": "Returns details for a specific subscription.", "operationId": "getSubscriptionByID", + "security": [ + { + "BearerToken": [] + } + ], "parameters": [ { "type": "string", @@ -136,6 +188,9 @@ "200": { "$ref": "#/responses/subscription" }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." + }, "404": { "description": "Not Found. Subscription resources are not available (not created)." } @@ -148,6 +203,11 @@ ], "summary": "Delete a specific subscription.", "operationId": "deleteSubscription", + "security": [ + { + "BearerToken": [] + } + ], "parameters": [ { "type": "string", @@ -162,6 +222,9 @@ "204": { "description": "Success." }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." + }, "404": { "description": "Not Found. Subscription resources are not available (not created)." } @@ -176,6 +239,11 @@ ], "summary": "Pulls the event status notifications for specified ResourceAddress.", "operationId": "getCurrentState", + "security": [ + { + "BearerToken": [] + } + ], "parameters": [ { "type": "string", @@ -190,6 +258,9 @@ "200": { "$ref": "#/responses/eventResp" }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." + }, "404": { "description": "Not Found. Event notification resource is not available on this node." } @@ -366,12 +437,24 @@ }, "tags": [ { - "description": "Manage Subscriptions", - "name": "Subscriptions" + "name": "Subscriptions", + "description": "Manage event subscriptions for O-RAN compliant notifications. Includes both O-RAN standard operations and extensions." + }, + { + "name": "Publishers", + "description": "Manage event publishers and their configurations. Extensions to O-RAN API for internal cluster management." + }, + { + "name": "Events", + "description": "Event publication and status notification endpoints. Includes current state retrieval and event creation." + }, + { + "name": "HealthCheck", + "description": "Health and status monitoring endpoints. Extensions to O-RAN API for service availability checking." }, { - "description": "Event Pull Status Notification", - "name": "Events" + "name": "Authentication", + "description": "Authentication and authorization using mTLS (mutual TLS) and OAuth 2.0 with OpenShift integration." } ] -} \ No newline at end of file +} diff --git a/v2/tags.json b/v2/tags.json index 5f09737..db41d63 100644 --- a/v2/tags.json +++ b/v2/tags.json @@ -1,12 +1,24 @@ { "tags": [ { - "name":"Subscriptions", - "description":"Manage Subscriptions" + "name": "Subscriptions", + "description": "Manage event subscriptions for O-RAN compliant notifications. Includes both O-RAN standard operations and extensions." }, { - "name":"Events", - "description":"Event Pull Status Notification" + "name": "Publishers", + "description": "Manage event publishers and their configurations. Extensions to O-RAN API for internal cluster management." + }, + { + "name": "Events", + "description": "Event publication and status notification endpoints. Includes current state retrieval and event creation." + }, + { + "name": "HealthCheck", + "description": "Health and status monitoring endpoints. Extensions to O-RAN API for service availability checking." + }, + { + "name": "Authentication", + "description": "Authentication and authorization using mTLS (mutual TLS) and OAuth 2.0 with OpenShift integration." } ] }