From c342267169dc8c6676961cccf30072bab92163ad Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Tue, 26 Aug 2025 17:39:36 -0400 Subject: [PATCH 1/6] Add mTLS and OAuth authentication to event REST API This commit introduces comprehensive authentication support for the cloud event notifications REST API v2, enabling secure communication in production environments. **Authentication Methods:** - mTLS (Mutual TLS) authentication with client certificate validation - OAuth JWT token authentication with strict issuer validation - Support for both OpenShift OAuth server and Kubernetes ServiceAccount tokens - Flexible authentication configuration via JSON config files **OpenShift Integration:** - Native OpenShift Service CA integration for automatic certificate management - OpenShift OAuth server integration for JWT token validation - ServiceAccount-based authentication for pod-to-pod communication - Dynamic cluster name configuration for multi-cluster deployments **Security Features:** - Strict OAuth validation with issuer verification - Comprehensive token validation (expiration, audience, signature) - Client certificate validation with configurable CA trust - Path-based authentication middleware (health endpoints bypass auth) - Localhost connection support for internal health checks **Configuration Options:** - JSON-based authentication configuration - Support for OpenShift Service CA and cert-manager - Configurable OAuth scopes and audience validation - Environment-based cluster name configuration **Core Implementation:** - `v2/auth.go`: OAuth and mTLS authentication middleware and validation logic - `v2/server.go`: Enhanced server with authentication support and TLS configuration - `go.mod`/`go.sum`: Added golang-jwt/jwt/v5 dependency for JWT validation **Documentation:** - `AUTHENTICATION.md`: Comprehensive authentication configuration guide - `OPENSHIFT_AUTHENTICATION.md`: OpenShift-specific deployment and configuration - `README.md`: Updated with authentication feature overview and links **Examples and Templates:** - `auth-config-example.json`: Example authentication configuration - `examples/openshift-auth-config.json`: OpenShift-specific configuration template - `examples/openshift-manifests.yaml`: Complete OpenShift deployment manifests - `examples/README.md`: Documentation for example configurations - **Multi-Issuer Support**: Accepts both OpenShift OAuth tokens and Kubernetes ServiceAccount tokens - **Strict Validation**: No authentication bypass mechanisms, exact issuer matching required - **Comprehensive Error Handling**: Clear error messages without exposing sensitive information - **Production Ready**: Designed for secure production deployments in OpenShift clusters - Authentication is optional and configurable - Existing deployments continue to work without authentication - Health check endpoints remain accessible for monitoring - Graceful fallback for non-authenticated deployments This implementation provides enterprise-grade security for cloud event notifications while maintaining compatibility with existing deployments and supporting flexible authentication scenarios across different Kubernetes environments. Resolves authentication requirements for secure cloud event communication in production OpenShift environments. Signed-off-by: Jack Ding --- AUTHENTICATION.md | 436 ++++++++++++++++++ OPENSHIFT_AUTHENTICATION.md | 389 ++++++++++++++++ README.md | 21 + auth-config-example.json | 12 + examples/README.md | 34 ++ examples/openshift-auth-config.json | 15 + examples/openshift-manifests.yaml | 159 +++++++ go.mod | 1 + go.sum | 2 + v2/auth.go | 220 +++++++++ v2/server.go | 271 +++++++++-- v2/server_test.go | 2 +- .../github.com/golang-jwt/jwt/v5/.gitignore | 4 + vendor/github.com/golang-jwt/jwt/v5/LICENSE | 9 + .../golang-jwt/jwt/v5/MIGRATION_GUIDE.md | 195 ++++++++ vendor/github.com/golang-jwt/jwt/v5/README.md | 167 +++++++ .../github.com/golang-jwt/jwt/v5/SECURITY.md | 19 + .../golang-jwt/jwt/v5/VERSION_HISTORY.md | 137 ++++++ vendor/github.com/golang-jwt/jwt/v5/claims.go | 16 + vendor/github.com/golang-jwt/jwt/v5/doc.go | 4 + vendor/github.com/golang-jwt/jwt/v5/ecdsa.go | 134 ++++++ .../golang-jwt/jwt/v5/ecdsa_utils.go | 69 +++ .../github.com/golang-jwt/jwt/v5/ed25519.go | 79 ++++ .../golang-jwt/jwt/v5/ed25519_utils.go | 64 +++ vendor/github.com/golang-jwt/jwt/v5/errors.go | 89 ++++ vendor/github.com/golang-jwt/jwt/v5/hmac.go | 104 +++++ .../golang-jwt/jwt/v5/map_claims.go | 109 +++++ vendor/github.com/golang-jwt/jwt/v5/none.go | 50 ++ vendor/github.com/golang-jwt/jwt/v5/parser.go | 268 +++++++++++ .../golang-jwt/jwt/v5/parser_option.go | 145 ++++++ .../golang-jwt/jwt/v5/registered_claims.go | 63 +++ vendor/github.com/golang-jwt/jwt/v5/rsa.go | 93 ++++ .../github.com/golang-jwt/jwt/v5/rsa_pss.go | 132 ++++++ .../github.com/golang-jwt/jwt/v5/rsa_utils.go | 107 +++++ .../golang-jwt/jwt/v5/signing_method.go | 49 ++ .../golang-jwt/jwt/v5/staticcheck.conf | 1 + vendor/github.com/golang-jwt/jwt/v5/token.go | 100 ++++ .../golang-jwt/jwt/v5/token_option.go | 5 + vendor/github.com/golang-jwt/jwt/v5/types.go | 149 ++++++ .../github.com/golang-jwt/jwt/v5/validator.go | 326 +++++++++++++ vendor/modules.txt | 3 + 41 files changed, 4216 insertions(+), 36 deletions(-) create mode 100644 AUTHENTICATION.md create mode 100644 OPENSHIFT_AUTHENTICATION.md create mode 100644 auth-config-example.json create mode 100644 examples/README.md create mode 100644 examples/openshift-auth-config.json create mode 100644 examples/openshift-manifests.yaml create mode 100644 v2/auth.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/.gitignore create mode 100644 vendor/github.com/golang-jwt/jwt/v5/LICENSE create mode 100644 vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md create mode 100644 vendor/github.com/golang-jwt/jwt/v5/README.md create mode 100644 vendor/github.com/golang-jwt/jwt/v5/SECURITY.md create mode 100644 vendor/github.com/golang-jwt/jwt/v5/VERSION_HISTORY.md create mode 100644 vendor/github.com/golang-jwt/jwt/v5/claims.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/doc.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/ecdsa.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/ecdsa_utils.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/ed25519.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/ed25519_utils.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/errors.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/hmac.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/map_claims.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/none.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/parser.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/parser_option.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/registered_claims.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/rsa.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/rsa_pss.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/rsa_utils.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/signing_method.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/staticcheck.conf create mode 100644 vendor/github.com/golang-jwt/jwt/v5/token.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/token_option.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/types.go create mode 100644 vendor/github.com/golang-jwt/jwt/v5/validator.go diff --git a/AUTHENTICATION.md b/AUTHENTICATION.md new file mode 100644 index 0000000..c30f29e --- /dev/null +++ b/AUTHENTICATION.md @@ -0,0 +1,436 @@ +# 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 using OpenShift's built-in OAuth server and JWT tokens with **strict validation** + +Both mechanisms can be enabled independently or together for enhanced security. This unified approach works seamlessly for both single node and multi-node OpenShift clusters, providing enterprise-grade security with minimal complexity. + +### Security Guarantees + +- **No Authentication Bypass**: When OAuth is enabled, all requests must include valid JWT tokens +- **Strict Issuer Validation**: Token issuer must exactly match the configured OAuth issuer +- **Comprehensive Token Validation**: Expiration, audience, and signature verification +- **Clear Error Messages**: Authentication failures return specific error codes without exposing sensitive information + +## Protected vs Public Endpoints + +### Protected Endpoints (Require Authentication) + +The following endpoints require authentication when enabled: + +#### Subscription Management +- `POST /subscriptions` - Create subscription +- `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 +- `DELETE /publishers/{publisherid}` - Delete specific publisher +- `DELETE /publishers` - Delete all publishers + +#### Event Management +- `POST /create/event` - Publish event +- `POST /log` - Log event + +#### Test Endpoints +- `POST /dummy` - Test endpoint +- `POST /dummy2` - Test endpoint + +### Public Endpoints (No Authentication Required) + +These endpoints remain accessible without authentication: + +#### Read Operations +- `GET /subscriptions` - List all subscriptions +- `GET /subscriptions/{subscriptionId}` - Get subscription details +- `GET /publishers` - List all publishers +- `GET /publishers/{publisherid}` - Get publisher details +- `GET /{ResourceAddress}/CurrentState` - Get current state + +### 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) + CertManagerIssuer string `json:"certManagerIssuer"` // cert-manager ClusterIssuer name (optional alternative) + CertManagerNamespace string `json:"certManagerNamespace"` // namespace for cert-manager resources (optional alternative) + + // OAuth configuration using OpenShift OAuth Server - works for both single and multi-node clusters + EnableOAuth bool `json:"enableOAuth"` + OAuthIssuer string `json:"oauthIssuer"` // OpenShift OAuth server URL + OAuthJWKSURL string `json:"oauthJWKSURL"` // OpenShift JWKS endpoint + RequiredScopes []string `json:"requiredScopes"` // Required OAuth scopes + RequiredAudience string `json:"requiredAudience"` // Required OAuth audience + ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount for client authentication + ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path + UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Use OpenShift's built-in OAuth server (recommended for all cluster sizes) + AuthenticationOperator bool `json:"authenticationOperator"` // Use OpenShift Authentication Operator (optional alternative) +} +``` + +### 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, + "oauthIssuer": "https://oauth-openshift.apps.your-cluster.com", + "oauthJWKSURL": "https://oauth-openshift.apps.your-cluster.com/.well-known/jwks.json", + "requiredScopes": ["user:info"], + "requiredAudience": "openshift", + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" +} +``` + +## 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 Server + +The OAuth implementation uses OpenShift's built-in OAuth server: + +#### Prerequisites +- OpenShift cluster (single node or multi-node) +- ServiceAccount with appropriate RBAC permissions +- No additional operators required + +#### OAuth Configuration +- **OAuth Server**: Uses OpenShift's built-in OAuth server +- **JWKS Endpoint**: OpenShift's JWKS endpoint for token validation +- **ServiceAccount Tokens**: For client authentication +- **RBAC**: Role-based access control for API permissions + +#### 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 + +### cert-manager Certificate Management + +With cert-manager, certificates are automatically managed: + +1. **Automatic Generation**: Certificates are automatically generated by cert-manager +2. **Automatic Renewal**: Certificates are automatically renewed before expiration +3. **Secret Management**: Certificates and keys are stored in Kubernetes secrets +4. **DNS Validation**: Automatic DNS validation for certificate requests + +### 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" +``` + +### Public Endpoint Examples + +#### List Subscriptions (no authentication required) + +```bash +# Over HTTPS (when mTLS is enabled) +curl -X GET https://localhost:9043/api/ocloudNotifications/v2/subscriptions \ + --cacert ca.crt + +# Over HTTP (when mTLS is disabled) +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 + +### Strict Validation Features + +The OAuth implementation includes comprehensive security measures: + +1. **Issuer Validation**: + ``` + Token issuer mismatch: expected https://oauth-openshift.apps.cluster.com, got https://dummy.com + ``` + - Tokens from unauthorized issuers are immediately rejected + - No bypass mechanisms or fallbacks + +2. **Expiration Checking**: + ``` + Token expired + ``` + - Expired tokens are rejected with clear error messages + - Time-based validation prevents replay attacks + +3. **Audience Validation**: + ``` + Token audience validation failed + ``` + - Tokens must contain the required audience claim + - Prevents token misuse across different services + +4. **Missing Token Handling**: + ``` + Authorization header required + Bearer token required + ``` + - Clear error messages for missing or malformed tokens + - Proper HTTP status codes (401 Unauthorized) + +### Security Libraries + +- **JWT Library**: Uses `golang-jwt/jwt/v5` for secure token parsing and validation +- **Cryptographic Verification**: Full signature validation against JWKS endpoints +- **Memory Safety**: Secure token handling without exposing sensitive data in logs + +## Security Considerations + +1. **Certificate Management** + - Implement proper certificate rotation + - Use secure storage for private keys + - Consider using a certificate manager in production + +2. **OAuth Security** + - **Strict Validation**: All tokens are validated against the exact configured issuer + - **No Bypass Mechanisms**: Authentication cannot be bypassed with mismatched issuers + - Implement token caching and JWKS key rotation + - Validate all claims (issuer, audience, scopes, expiration) + +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..83f6142 --- /dev/null +++ b/OPENSHIFT_AUTHENTICATION.md @@ -0,0 +1,389 @@ +# 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, + "oauthIssuer": "https://oauth-openshift.apps.your-cluster.com", + "oauthJWKSURL": "https://oauth-openshift.apps.your-cluster.com/.well-known/jwks.json", + "requiredScopes": ["user:info"], + "requiredAudience": "openshift", + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" +} +``` + +### Dynamic Cluster Configuration + +For environments with multiple clusters or dynamic cluster names, use the `CLUSTER_NAME` environment variable: + +#### Environment Variable Configuration +```bash +# Default cluster name (used by ptp-operator) +export CLUSTER_NAME="openshift.local" + +# Custom cluster name +export CLUSTER_NAME="cnfdg4.sno.ptp.eng.rdu2.dc.redhat.com" + +# OAuth URLs are automatically generated as: +# https://oauth-openshift.apps.${CLUSTER_NAME} +``` + +#### Template Configuration +```json +{ + "enableMTLS": true, + "useServiceCA": true, + "caCertPath": "/etc/cloud-event-proxy/ca-bundle/service-ca.crt", + "serverCertPath": "/etc/cloud-event-proxy/server-certs/tls.crt", + "serverKeyPath": "/etc/cloud-event-proxy/server-certs/tls.key", + "enableOAuth": true, + "useOpenShiftOAuth": true, + "oauthIssuer": "https://oauth-openshift.apps.{{.ClusterName}}", + "oauthJWKSURL": "https://oauth-openshift.apps.{{.ClusterName}}/oauth/jwks", + "requiredScopes": ["user:info"], + "requiredAudience": "openshift", + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" +} +``` + +This ensures OAuth issuer URLs match your actual OpenShift cluster configuration and prevents authentication bypass due to issuer mismatches. + +### Key Configuration Fields + +#### mTLS Configuration: +- `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` - Use OpenShift's built-in OAuth server (recommended for all cluster sizes) +- `oauthIssuer` - OpenShift OAuth server URL +- `oauthJWKSURL` - JWKS endpoint for JWT validation +- `requiredScopes` - Required OAuth scopes +- `requiredAudience` - Required OAuth audience + +## 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, + "oauthIssuer": "https://oauth-openshift.apps.your-cluster.com", + "oauthJWKSURL": "https://oauth-openshift.apps.your-cluster.com/.well-known/jwks.json", + "requiredScopes": ["user:info"], + "requiredAudience": "openshift", + "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, + "oauthIssuer": "https://oauth-openshift.apps.your-cluster.com", + "oauthJWKSURL": "https://oauth-openshift.apps.your-cluster.com/.well-known/jwks.json", + "requiredScopes": ["user:info"], + "requiredAudience": "openshift", + "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**: Check OAuth server URL and JWKS endpoint +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 OAuth server accessibility +curl -k https://oauth-openshift.apps.your-cluster.com/.well-known/jwks.json + +# 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 cert-manager: +1. Set `useServiceCA: true` +2. Remove cert-manager Certificate resources +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..b50afdd 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 + +- **Strict OAuth Validation**: JWT tokens are validated against the configured issuer with no bypass mechanisms +- **Issuer Verification**: Token issuer must exactly match the configured OAuth issuer +- **Expiration Checking**: Expired tokens are rejected with clear error messages +- **Audience Validation**: Tokens must contain the required audience claim +- **mTLS Certificate Validation**: Client certificates are verified against the configured CA + +### Recent Security Improvements + +- **Fixed OAuth Security Vulnerability** (v2.1.0): Implemented proper OAuth token validation to prevent unauthorized access +- **Added JWT Library Support**: Uses `golang-jwt/jwt/v5` for secure token parsing and validation +- **Enhanced Error Handling**: Clear error messages for authentication failures without exposing sensitive information + ## O-RAN Compliant REST API Specification Starting from release [v1.21.0](https://github.com/redhat-cne/rest-api/releases/tag/v1.21.0), the REST API implemented in this repo is compliant with [O-RAN O-Cloud Notification API Specification for Event Consumers 4.0](https://orandownloadsweb.azurewebsites.net/specifications). diff --git a/auth-config-example.json b/auth-config-example.json new file mode 100644 index 0000000..0e6a4cc --- /dev/null +++ b/auth-config-example.json @@ -0,0 +1,12 @@ +{ + "enableMTLS": true, + "caCertPath": "/etc/certs/ca.crt", + "serverCertPath": "/etc/certs/server.crt", + "serverKeyPath": "/etc/certs/server.key", + + "enableOAuth": true, + "oauthIssuer": "https://your-oauth-provider.com", + "oauthJWKSURL": "https://your-oauth-provider.com/.well-known/jwks.json", + "requiredScopes": ["subscription:create", "events:read"], + "requiredAudience": "rest-api-service" +} 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..b439df2 --- /dev/null +++ b/examples/openshift-auth-config.json @@ -0,0 +1,15 @@ +{ + "enableMTLS": true, + "useServiceCA": true, + "caCertPath": "/etc/cloud-event-proxy/ca-bundle/service-ca.crt", + "serverCertPath": "/etc/cloud-event-proxy/server-certs/tls.crt", + "serverKeyPath": "/etc/cloud-event-proxy/server-certs/tls.key", + "enableOAuth": true, + "useOpenShiftOAuth": true, + "oauthIssuer": "https://oauth-openshift.apps.your-cluster.com", + "oauthJWKSURL": "https://oauth-openshift.apps.your-cluster.com/oauth/jwks", + "requiredScopes": ["user:info"], + "requiredAudience": "openshift", + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" +} diff --git a/examples/openshift-manifests.yaml b/examples/openshift-manifests.yaml new file mode 100644 index 0000000..9c5cf67 --- /dev/null +++ b/examples/openshift-manifests.yaml @@ -0,0 +1,159 @@ +# 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, + "oauthIssuer": "https://oauth-openshift.apps.{{.ClusterName}}", + "oauthJWKSURL": "https://oauth-openshift.apps.{{.ClusterName}}/oauth/jwks", + "requiredScopes": ["user:info"], + "requiredAudience": "openshift", + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" + } + +--- +# 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 + +--- +# 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 + - name: ca-bundle + secret: + secretName: cloud-event-proxy-tls + - name: auth-config + configMap: + name: cloud-event-proxy-auth-config diff --git a/go.mod b/go.mod index edfbdb6..1f836af 100644 --- a/go.mod +++ b/go.mod @@ -20,6 +20,7 @@ require ( github.com/beorn7/perks v1.0.1 // indirect github.com/cespare/xxhash/v2 v2.1.2 // indirect github.com/davecgh/go-spew v1.1.1 // indirect + github.com/golang-jwt/jwt/v5 v5.3.0 // indirect github.com/golang/protobuf v1.5.2 // indirect github.com/json-iterator/go v1.1.12 // indirect github.com/matttproud/golang_protobuf_extensions v1.0.4 // indirect diff --git a/go.sum b/go.sum index 2398dc8..042e88a 100644 --- a/go.sum +++ b/go.sum @@ -9,6 +9,8 @@ github.com/cloudevents/sdk-go/v2 v2.15.2/go.mod h1:lL7kSWAE/V8VI4Wh0jbL2v/jvqsm6 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/golang-jwt/jwt/v5 v5.3.0 h1:pv4AsKCKKZuqlgs5sUmn4x8UlGa0kEVt/puTpKx9vvo= +github.com/golang-jwt/jwt/v5 v5.3.0/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE= github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U= github.com/golang/protobuf v1.3.5/go.mod h1:6O5/vntMXwX2lRkT1hjjk0nAC1IDOTvTlVgjlRvqsdk= github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk= diff --git a/v2/auth.go b/v2/auth.go new file mode 100644 index 0000000..bc60fa2 --- /dev/null +++ b/v2/auth.go @@ -0,0 +1,220 @@ +// 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/x509" + "fmt" + "net/http" + "os" + "strings" + "time" + + "github.com/golang-jwt/jwt/v5" + 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 +} + +// OAuthClaims represents the claims in an OAuth JWT token +type OAuthClaims struct { + Issuer string `json:"iss"` + Subject string `json:"sub"` + Audience []string `json:"aud"` + ExpiresAt int64 `json:"exp"` + IssuedAt int64 `json:"iat"` + Scopes []string `json:"scope"` +} + +// validateOAuthToken validates the OAuth JWT token +func (s *Server) validateOAuthToken(tokenString string) (*OAuthClaims, error) { + if s.authConfig == nil || !s.authConfig.EnableOAuth { + return nil, fmt.Errorf("OAuth not enabled") + } + + // Parse the token without verification first to get the issuer + token, _, err := new(jwt.Parser).ParseUnverified(tokenString, jwt.MapClaims{}) + if err != nil { + return nil, fmt.Errorf("failed to parse token: %v", err) + } + + claims, ok := token.Claims.(jwt.MapClaims) + if !ok { + return nil, fmt.Errorf("invalid token claims") + } + + // Validate issuer + issuer, ok := claims["iss"].(string) + if !ok { + return nil, fmt.Errorf("missing or invalid issuer in token") + } + + // Accept both OpenShift OAuth tokens and Kubernetes ServiceAccount tokens + validIssuers := []string{ + s.authConfig.OAuthIssuer, // OpenShift OAuth server + "https://kubernetes.default.svc.cluster.local", // Kubernetes ServiceAccount tokens (full) + "https://kubernetes.default.svc", // Kubernetes ServiceAccount tokens (short) + "kubernetes.default.svc.cluster.local", // Kubernetes ServiceAccount tokens (no https) + "kubernetes.default.svc", // Kubernetes ServiceAccount tokens (minimal) + } + + issuerValid := false + for _, validIssuer := range validIssuers { + if issuer == validIssuer { + issuerValid = true + break + } + } + + if !issuerValid { + return nil, fmt.Errorf("token issuer not accepted: got %s, expected one of: %v", issuer, validIssuers) + } + + // Validate expiration + if exp, ok := claims["exp"].(float64); ok { + if time.Now().Unix() > int64(exp) { + return nil, fmt.Errorf("token expired") + } + } else { + return nil, fmt.Errorf("missing or invalid expiration in token") + } + + // Validate audience if required + if len(s.authConfig.RequiredAudience) > 0 { + var audiences []string + if aud, ok := claims["aud"].([]interface{}); ok { + for _, a := range aud { + if audStr, ok := a.(string); ok { + audiences = append(audiences, audStr) + } + } + } else if audStr, ok := claims["aud"].(string); ok { + audiences = []string{audStr} + } + + audienceValid := false + for _, aud := range audiences { + if aud == s.authConfig.RequiredAudience { + audienceValid = true + break + } + } + if !audienceValid { + return nil, fmt.Errorf("token audience validation failed") + } + } + + // Convert to OAuthClaims struct + oauthClaims := &OAuthClaims{ + Issuer: issuer, + ExpiresAt: int64(claims["exp"].(float64)), + } + + if sub, ok := claims["sub"].(string); ok { + oauthClaims.Subject = sub + } + + if iat, ok := claims["iat"].(float64); ok { + oauthClaims.IssuedAt = int64(iat) + } + + return oauthClaims, nil +} + +// combinedAuthMiddleware applies both mTLS and OAuth authentication +func (s *Server) combinedAuthMiddleware(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // Skip authentication for localhost connections (same pod) + if r.RemoteAddr != "" { + host := r.RemoteAddr + if idx := strings.LastIndex(host, ":"); idx != -1 { + host = host[:idx] // Remove port + } + if host == "127.0.0.1" || host == "::1" || host == "[::1]" { + log.Debugf("Allowing localhost connection from %s for %s", r.RemoteAddr, r.URL.Path) + next.ServeHTTP(w, r) + return + } + } + + // Check for client certificate when mTLS is enabled + 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 + } + + // Verify the client certificate against our CA + cert := r.TLS.PeerCertificates[0] + opts := x509.VerifyOptions{Roots: s.caCertPool} + if _, err := cert.Verify(opts); err != nil { + log.Warnf("Client certificate verification failed for %s: %v", r.URL.Path, err) + http.Error(w, "Invalid client certificate", http.StatusUnauthorized) + return + } + log.Debugf("Client certificate verified successfully for %s", r.URL.Path) + } + + // Validate OAuth token if OAuth is enabled + 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 + } + + // Extract Bearer token + if !strings.HasPrefix(authHeader, "Bearer ") { + log.Warnf("OAuth required but invalid Authorization header format for %s", r.URL.Path) + http.Error(w, "Bearer token required", http.StatusUnauthorized) + return + } + + token := strings.TrimPrefix(authHeader, "Bearer ") + _, err := s.validateOAuthToken(token) + 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 successfully for %s", r.URL.Path) + } + + // Call the next handler + next.ServeHTTP(w, r) + }) +} diff --git a/v2/server.go b/v2/server.go index 899ff15..c862c97 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,6 +49,8 @@ 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/http" "strings" @@ -75,6 +79,71 @@ 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) + CertManagerIssuer string `json:"certManagerIssuer"` // cert-manager ClusterIssuer name (optional alternative) + CertManagerNamespace string `json:"certManagerNamespace"` // namespace for cert-manager resources (optional alternative) + + // OAuth configuration using OpenShift OAuth Server - works for both single and multi-node clusters + EnableOAuth bool `json:"enableOAuth"` + OAuthIssuer string `json:"oauthIssuer"` // OpenShift OAuth server URL + OAuthJWKSURL string `json:"oauthJWKSURL"` // OpenShift JWKS endpoint + RequiredScopes []string `json:"requiredScopes"` // Required OAuth scopes + RequiredAudience string `json:"requiredAudience"` // Required OAuth audience + ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount for client authentication + ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path + UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Use OpenShift's built-in OAuth server (recommended for all cluster sizes) + AuthenticationOperator bool `json:"authenticationOperator"` // Use OpenShift Authentication Operator (optional alternative) +} + +// 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(" OAuth Issuer: %s\n", c.OAuthIssuer) + summary += fmt.Sprintf(" OAuth JWKS URL: %s\n", c.OAuthJWKSURL) + summary += fmt.Sprintf(" Required Scopes: %v\n", c.RequiredScopes) + summary += fmt.Sprintf(" Required Audience: %s\n", c.RequiredAudience) + 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) + } + return summary +} + // Server defines rest routes server object type Server struct { port int @@ -90,6 +159,8 @@ type Server struct { status ServerStatus statusReceiveOverrideFn func(e cloudevents.Event, dataChan *channel.DataChan) error statusLock sync.RWMutex + authConfig *AuthConfig + caCertPool *x509.CertPool } // SubscriptionInfo @@ -215,24 +286,53 @@ 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{ + port: port, + apiHost: apiHost, + apiPath: apiPath, + dataOut: dataOut, + closeCh: closeCh, + status: notReady, + pubSubAPI: pubsubv1.GetAPIInstance(storePath), + subscriberAPI: subscriberApi.GetAPIInstance(storePath), + statusReceiveOverrideFn: onStatusReceiveOverrideFn, + authConfig: authConfig, + } + + // Configure HTTPClient with proper TLS settings for publisher endpoint validation + if authConfig != nil && authConfig.EnableMTLS { + // Create HTTPClient with TLS configuration that allows localhost connections + ServerInstance.HTTPClient = &http.Client{ Transport: &http.Transport{ MaxIdleConnsPerHost: 20, + TLSClientConfig: &tls.Config{ + InsecureSkipVerify: true, // nolint:gosec // Required for localhost connections in mTLS setup + }, }, Timeout: 10 * time.Second, - }, - pubSubAPI: pubsubv1.GetAPIInstance(storePath), - subscriberAPI: subscriberApi.GetAPIInstance(storePath), - statusReceiveOverrideFn: onStatusReceiveOverrideFn, + } + log.Infof("InitServer: Configured HTTPClient with InsecureSkipVerify for mTLS localhost connections") + } else { + // Use default HTTP client for non-mTLS configurations + ServerInstance.HTTPClient = &http.Client{ + Transport: &http.Transport{ + MaxIdleConnsPerHost: 20, + }, + Timeout: 10 * time.Second, + } + } + + // Initialize mTLS CA certificate pool if mTLS is enabled + if authConfig != nil && authConfig.EnableMTLS && authConfig.CACertPath != "" { + fmt.Printf("InitServer: Setting authConfig with EnableMTLS=%t\n", authConfig.EnableMTLS) + if err := ServerInstance.initMTLSCACertPool(); err != nil { + log.Errorf("failed to initialize mTLS CA certificate pool: %v", err) + } + } else { + fmt.Printf("InitServer: authConfig is nil or EnableMTLS is false (authConfig=%v, EnableMTLS=%t)\n", authConfig != nil, authConfig != nil && authConfig.EnableMTLS) } }) // singleton @@ -249,8 +349,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 +420,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 +456,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 +480,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 +497,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, false)).Methods(http.MethodGet) // swagger:operation GET /subscriptions/{subscriptionId} Subscriptions getSubscriptionByID // --- @@ -356,7 +508,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, false)).Methods(http.MethodGet) // swagger:operation DELETE /subscriptions/{subscriptionId} Subscriptions deleteSubscription // --- @@ -365,9 +517,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 +532,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, false)).Methods(http.MethodGet) // *** Extensions to O-RAN API *** @@ -389,6 +543,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 +559,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, false)).Methods(http.MethodGet) // swagger:operation DELETE /subscriptions Subscriptions deleteAllSubscriptions // --- @@ -413,13 +568,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, false)).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 +592,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 +616,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() @@ -504,10 +665,50 @@ func (s *Server) Start() { 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 + } + + // 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 + } + + // Configure TLS to request client certificates but not require them + // We'll handle certificate validation at the application level + tlsConfig := &tls.Config{ + Certificates: []tls.Certificate{cert}, + ClientAuth: tls.RequestClientCert, // Request but don't require + ClientCAs: s.caCertPool, + MinVersion: tls.VersionTLS12, + } + + 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..6289344 100644 --- a/v2/server_test.go +++ b/v2/server_test.go @@ -91,7 +91,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() diff --git a/vendor/github.com/golang-jwt/jwt/v5/.gitignore b/vendor/github.com/golang-jwt/jwt/v5/.gitignore new file mode 100644 index 0000000..09573e0 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/.gitignore @@ -0,0 +1,4 @@ +.DS_Store +bin +.idea/ + diff --git a/vendor/github.com/golang-jwt/jwt/v5/LICENSE b/vendor/github.com/golang-jwt/jwt/v5/LICENSE new file mode 100644 index 0000000..35dbc25 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/LICENSE @@ -0,0 +1,9 @@ +Copyright (c) 2012 Dave Grijalva +Copyright (c) 2021 golang-jwt maintainers + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + diff --git a/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md b/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md new file mode 100644 index 0000000..b3178e7 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md @@ -0,0 +1,195 @@ +# Migration Guide (v5.0.0) + +Version `v5` contains a major rework of core functionalities in the `jwt-go` +library. This includes support for several validation options as well as a +re-design of the `Claims` interface. Lastly, we reworked how errors work under +the hood, which should provide a better overall developer experience. + +Starting from [v5.0.0](https://github.com/golang-jwt/jwt/releases/tag/v5.0.0), +the import path will be: + + "github.com/golang-jwt/jwt/v5" + +For most users, changing the import path *should* suffice. However, since we +intentionally changed and cleaned some of the public API, existing programs +might need to be updated. The following sections describe significant changes +and corresponding updates for existing programs. + +## Parsing and Validation Options + +Under the hood, a new `Validator` struct takes care of validating the claims. A +long awaited feature has been the option to fine-tune the validation of tokens. +This is now possible with several `ParserOption` functions that can be appended +to most `Parse` functions, such as `ParseWithClaims`. The most important options +and changes are: + * Added `WithLeeway` to support specifying the leeway that is allowed when + validating time-based claims, such as `exp` or `nbf`. + * Changed default behavior to not check the `iat` claim. Usage of this claim + is OPTIONAL according to the JWT RFC. The claim itself is also purely + informational according to the RFC, so a strict validation failure is not + recommended. If you want to check for sensible values in these claims, + please use the `WithIssuedAt` parser option. + * Added `WithAudience`, `WithSubject` and `WithIssuer` to support checking for + expected `aud`, `sub` and `iss`. + * Added `WithStrictDecoding` and `WithPaddingAllowed` options to allow + previously global settings to enable base64 strict encoding and the parsing + of base64 strings with padding. The latter is strictly speaking against the + standard, but unfortunately some of the major identity providers issue some + of these incorrect tokens. Both options are disabled by default. + +## Changes to the `Claims` interface + +### Complete Restructuring + +Previously, the claims interface was satisfied with an implementation of a +`Valid() error` function. This had several issues: + * The different claim types (struct claims, map claims, etc.) then contained + similar (but not 100 % identical) code of how this validation was done. This + lead to a lot of (almost) duplicate code and was hard to maintain + * It was not really semantically close to what a "claim" (or a set of claims) + really is; which is a list of defined key/value pairs with a certain + semantic meaning. + +Since all the validation functionality is now extracted into the validator, all +`VerifyXXX` and `Valid` functions have been removed from the `Claims` interface. +Instead, the interface now represents a list of getters to retrieve values with +a specific meaning. This allows us to completely decouple the validation logic +with the underlying storage representation of the claim, which could be a +struct, a map or even something stored in a database. + +```go +type Claims interface { + GetExpirationTime() (*NumericDate, error) + GetIssuedAt() (*NumericDate, error) + GetNotBefore() (*NumericDate, error) + GetIssuer() (string, error) + GetSubject() (string, error) + GetAudience() (ClaimStrings, error) +} +``` + +Users that previously directly called the `Valid` function on their claims, +e.g., to perform validation independently of parsing/verifying a token, can now +use the `jwt.NewValidator` function to create a `Validator` independently of the +`Parser`. + +```go +var v = jwt.NewValidator(jwt.WithLeeway(5*time.Second)) +v.Validate(myClaims) +``` + +### Supported Claim Types and Removal of `StandardClaims` + +The two standard claim types supported by this library, `MapClaims` and +`RegisteredClaims` both implement the necessary functions of this interface. The +old `StandardClaims` struct, which has already been deprecated in `v4` is now +removed. + +Users using custom claims, in most cases, will not experience any changes in the +behavior as long as they embedded `RegisteredClaims`. If they created a new +claim type from scratch, they now need to implemented the proper getter +functions. + +### Migrating Application Specific Logic of the old `Valid` + +Previously, users could override the `Valid` method in a custom claim, for +example to extend the validation with application-specific claims. However, this +was always very dangerous, since once could easily disable the standard +validation and signature checking. + +In order to avoid that, while still supporting the use-case, a new +`ClaimsValidator` interface has been introduced. This interface consists of the +`Validate() error` function. If the validator sees, that a `Claims` struct +implements this interface, the errors returned to the `Validate` function will +be *appended* to the regular standard validation. It is not possible to disable +the standard validation anymore (even only by accident). + +Usage examples can be found in [example_test.go](./example_test.go), to build +claims structs like the following. + +```go +// MyCustomClaims includes all registered claims, plus Foo. +type MyCustomClaims struct { + Foo string `json:"foo"` + jwt.RegisteredClaims +} + +// Validate can be used to execute additional application-specific claims +// validation. +func (m MyCustomClaims) Validate() error { + if m.Foo != "bar" { + return errors.New("must be foobar") + } + + return nil +} +``` + +## Changes to the `Token` and `Parser` struct + +The previously global functions `DecodeSegment` and `EncodeSegment` were moved +to the `Parser` and `Token` struct respectively. This will allow us in the +future to configure the behavior of these two based on options supplied on the +parser or the token (creation). This also removes two previously global +variables and moves them to parser options `WithStrictDecoding` and +`WithPaddingAllowed`. + +In order to do that, we had to adjust the way signing methods work. Previously +they were given a base64 encoded signature in `Verify` and were expected to +return a base64 encoded version of the signature in `Sign`, both as a `string`. +However, this made it necessary to have `DecodeSegment` and `EncodeSegment` +global and was a less than perfect design because we were repeating +encoding/decoding steps for all signing methods. Now, `Sign` and `Verify` +operate on a decoded signature as a `[]byte`, which feels more natural for a +cryptographic operation anyway. Lastly, `Parse` and `SignedString` take care of +the final encoding/decoding part. + +In addition to that, we also changed the `Signature` field on `Token` from a +`string` to `[]byte` and this is also now populated with the decoded form. This +is also more consistent, because the other parts of the JWT, mainly `Header` and +`Claims` were already stored in decoded form in `Token`. Only the signature was +stored in base64 encoded form, which was redundant with the information in the +`Raw` field, which contains the complete token as base64. + +```go +type Token struct { + Raw string // Raw contains the raw token + Method SigningMethod // Method is the signing method used or to be used + Header map[string]any // Header is the first segment of the token in decoded form + Claims Claims // Claims is the second segment of the token in decoded form + Signature []byte // Signature is the third segment of the token in decoded form + Valid bool // Valid specifies if the token is valid +} +``` + +Most (if not all) of these changes should not impact the normal usage of this +library. Only users directly accessing the `Signature` field as well as +developers of custom signing methods should be affected. + +# Migration Guide (v4.0.0) + +Starting from [v4.0.0](https://github.com/golang-jwt/jwt/releases/tag/v4.0.0), +the import path will be: + + "github.com/golang-jwt/jwt/v4" + +The `/v4` version will be backwards compatible with existing `v3.x.y` tags in +this repo, as well as `github.com/dgrijalva/jwt-go`. For most users this should +be a drop-in replacement, if you're having troubles migrating, please open an +issue. + +You can replace all occurrences of `github.com/dgrijalva/jwt-go` or +`github.com/golang-jwt/jwt` with `github.com/golang-jwt/jwt/v4`, either manually +or by using tools such as `sed` or `gofmt`. + +And then you'd typically run: + +``` +go get github.com/golang-jwt/jwt/v4 +go mod tidy +``` + +# Older releases (before v3.2.0) + +The original migration guide for older releases can be found at +https://github.com/dgrijalva/jwt-go/blob/master/MIGRATION_GUIDE.md. diff --git a/vendor/github.com/golang-jwt/jwt/v5/README.md b/vendor/github.com/golang-jwt/jwt/v5/README.md new file mode 100644 index 0000000..0bb636f --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/README.md @@ -0,0 +1,167 @@ +# jwt-go + +[![build](https://github.com/golang-jwt/jwt/actions/workflows/build.yml/badge.svg)](https://github.com/golang-jwt/jwt/actions/workflows/build.yml) +[![Go +Reference](https://pkg.go.dev/badge/github.com/golang-jwt/jwt/v5.svg)](https://pkg.go.dev/github.com/golang-jwt/jwt/v5) +[![Coverage Status](https://coveralls.io/repos/github/golang-jwt/jwt/badge.svg?branch=main)](https://coveralls.io/github/golang-jwt/jwt?branch=main) + +A [go](http://www.golang.org) (or 'golang' for search engine friendliness) +implementation of [JSON Web +Tokens](https://datatracker.ietf.org/doc/html/rfc7519). + +Starting with [v4.0.0](https://github.com/golang-jwt/jwt/releases/tag/v4.0.0) +this project adds Go module support, but maintains backward compatibility with +older `v3.x.y` tags and upstream `github.com/dgrijalva/jwt-go`. See the +[`MIGRATION_GUIDE.md`](./MIGRATION_GUIDE.md) for more information. Version +v5.0.0 introduces major improvements to the validation of tokens, but is not +entirely backward compatible. + +> After the original author of the library suggested migrating the maintenance +> of `jwt-go`, a dedicated team of open source maintainers decided to clone the +> existing library into this repository. See +> [dgrijalva/jwt-go#462](https://github.com/dgrijalva/jwt-go/issues/462) for a +> detailed discussion on this topic. + + +**SECURITY NOTICE:** Some older versions of Go have a security issue in the +crypto/elliptic. The recommendation is to upgrade to at least 1.15 See issue +[dgrijalva/jwt-go#216](https://github.com/dgrijalva/jwt-go/issues/216) for more +detail. + +**SECURITY NOTICE:** It's important that you [validate the `alg` presented is +what you +expect](https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/). +This library attempts to make it easy to do the right thing by requiring key +types to match the expected alg, but you should take the extra step to verify it in +your usage. See the examples provided. + +### Supported Go versions + +Our support of Go versions is aligned with Go's [version release +policy](https://golang.org/doc/devel/release#policy). So we will support a major +version of Go until there are two newer major releases. We no longer support +building jwt-go with unsupported Go versions, as these contain security +vulnerabilities that will not be fixed. + +## What the heck is a JWT? + +JWT.io has [a great introduction](https://jwt.io/introduction) to JSON Web +Tokens. + +In short, it's a signed JSON object that does something useful (for example, +authentication). It's commonly used for `Bearer` tokens in Oauth 2. A token is +made of three parts, separated by `.`'s. The first two parts are JSON objects, +that have been [base64url](https://datatracker.ietf.org/doc/html/rfc4648) +encoded. The last part is the signature, encoded the same way. + +The first part is called the header. It contains the necessary information for +verifying the last part, the signature. For example, which encryption method +was used for signing and what key was used. + +The part in the middle is the interesting bit. It's called the Claims and +contains the actual stuff you care about. Refer to [RFC +7519](https://datatracker.ietf.org/doc/html/rfc7519) for information about +reserved keys and the proper way to add your own. + +## What's in the box? + +This library supports the parsing and verification as well as the generation and +signing of JWTs. Current supported signing algorithms are HMAC SHA, RSA, +RSA-PSS, and ECDSA, though hooks are present for adding your own. + +## Installation Guidelines + +1. To install the jwt package, you first need to have + [Go](https://go.dev/doc/install) installed, then you can use the command + below to add `jwt-go` as a dependency in your Go program. + +```sh +go get -u github.com/golang-jwt/jwt/v5 +``` + +2. Import it in your code: + +```go +import "github.com/golang-jwt/jwt/v5" +``` + +## Usage + +A detailed usage guide, including how to sign and verify tokens can be found on +our [documentation website](https://golang-jwt.github.io/jwt/usage/create/). + +## Examples + +See [the project documentation](https://pkg.go.dev/github.com/golang-jwt/jwt/v5) +for examples of usage: + +* [Simple example of parsing and validating a + token](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#example-Parse-Hmac) +* [Simple example of building and signing a + token](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#example-New-Hmac) +* [Directory of + Examples](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#pkg-examples) + +## Compliance + +This library was last reviewed to comply with [RFC +7519](https://datatracker.ietf.org/doc/html/rfc7519) dated May 2015 with a few +notable differences: + +* In order to protect against accidental use of [Unsecured + JWTs](https://datatracker.ietf.org/doc/html/rfc7519#section-6), tokens using + `alg=none` will only be accepted if the constant + `jwt.UnsafeAllowNoneSignatureType` is provided as the key. + +## Project Status & Versioning + +This library is considered production ready. Feedback and feature requests are +appreciated. The API should be considered stable. There should be very few +backward-incompatible changes outside of major version updates (and only with +good reason). + +This project uses [Semantic Versioning 2.0.0](http://semver.org). Accepted pull +requests will land on `main`. Periodically, versions will be tagged from +`main`. You can find all the releases on [the project releases +page](https://github.com/golang-jwt/jwt/releases). + +**BREAKING CHANGES:** A full list of breaking changes is available in +`VERSION_HISTORY.md`. See [`MIGRATION_GUIDE.md`](./MIGRATION_GUIDE.md) for more information on updating +your code. + +## Extensions + +This library publishes all the necessary components for adding your own signing +methods or key functions. Simply implement the `SigningMethod` interface and +register a factory method using `RegisterSigningMethod` or provide a +`jwt.Keyfunc`. + +A common use case would be integrating with different 3rd party signature +providers, like key management services from various cloud providers or Hardware +Security Modules (HSMs) or to implement additional standards. + +| Extension | Purpose | Repo | +| --------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| GCP | Integrates with multiple Google Cloud Platform signing tools (AppEngine, IAM API, Cloud KMS) | https://github.com/someone1/gcp-jwt-go | +| AWS | Integrates with AWS Key Management Service, KMS | https://github.com/matelang/jwt-go-aws-kms | +| JWKS | Provides support for JWKS ([RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)) as a `jwt.Keyfunc` | https://github.com/MicahParks/keyfunc | + +*Disclaimer*: Unless otherwise specified, these integrations are maintained by +third parties and should not be considered as a primary offer by any of the +mentioned cloud providers + +## More + +Go package documentation can be found [on +pkg.go.dev](https://pkg.go.dev/github.com/golang-jwt/jwt/v5). Additional +documentation can be found on [our project +page](https://golang-jwt.github.io/jwt/). + +The command line utility included in this project (cmd/jwt) provides a +straightforward example of token creation and parsing as well as a useful tool +for debugging your own integration. You'll also find several implementation +examples in the documentation. + +[golang-jwt](https://github.com/orgs/golang-jwt) incorporates a modified version +of the JWT logo, which is distributed under the terms of the [MIT +License](https://github.com/jsonwebtoken/jsonwebtoken.github.io/blob/master/LICENSE.txt). diff --git a/vendor/github.com/golang-jwt/jwt/v5/SECURITY.md b/vendor/github.com/golang-jwt/jwt/v5/SECURITY.md new file mode 100644 index 0000000..2740597 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/SECURITY.md @@ -0,0 +1,19 @@ +# Security Policy + +## Supported Versions + +As of November 2024 (and until this document is updated), the latest version `v5` is supported. In critical cases, we might supply back-ported patches for `v4`. + +## Reporting a Vulnerability + +If you think you found a vulnerability, and even if you are not sure, please report it a [GitHub Security Advisory](https://github.com/golang-jwt/jwt/security/advisories/new). Please try be explicit, describe steps to reproduce the security issue with code example(s). + +You will receive a response within a timely manner. If the issue is confirmed, we will do our best to release a patch as soon as possible given the complexity of the problem. + +## Public Discussions + +Please avoid publicly discussing a potential security vulnerability. + +Let's take this offline and find a solution first, this limits the potential impact as much as possible. + +We appreciate your help! diff --git a/vendor/github.com/golang-jwt/jwt/v5/VERSION_HISTORY.md b/vendor/github.com/golang-jwt/jwt/v5/VERSION_HISTORY.md new file mode 100644 index 0000000..b5039e4 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/VERSION_HISTORY.md @@ -0,0 +1,137 @@ +# `jwt-go` Version History + +The following version history is kept for historic purposes. To retrieve the current changes of each version, please refer to the change-log of the specific release versions on https://github.com/golang-jwt/jwt/releases. + +## 4.0.0 + +* Introduces support for Go modules. The `v4` version will be backwards compatible with `v3.x.y`. + +## 3.2.2 + +* Starting from this release, we are adopting the policy to support the most 2 recent versions of Go currently available. By the time of this release, this is Go 1.15 and 1.16 ([#28](https://github.com/golang-jwt/jwt/pull/28)). +* Fixed a potential issue that could occur when the verification of `exp`, `iat` or `nbf` was not required and contained invalid contents, i.e. non-numeric/date. Thanks for @thaJeztah for making us aware of that and @giorgos-f3 for originally reporting it to the formtech fork ([#40](https://github.com/golang-jwt/jwt/pull/40)). +* Added support for EdDSA / ED25519 ([#36](https://github.com/golang-jwt/jwt/pull/36)). +* Optimized allocations ([#33](https://github.com/golang-jwt/jwt/pull/33)). + +## 3.2.1 + +* **Import Path Change**: See MIGRATION_GUIDE.md for tips on updating your code + * Changed the import path from `github.com/dgrijalva/jwt-go` to `github.com/golang-jwt/jwt` +* Fixed type confusing issue between `string` and `[]string` in `VerifyAudience` ([#12](https://github.com/golang-jwt/jwt/pull/12)). This fixes CVE-2020-26160 + +#### 3.2.0 + +* Added method `ParseUnverified` to allow users to split up the tasks of parsing and validation +* HMAC signing method returns `ErrInvalidKeyType` instead of `ErrInvalidKey` where appropriate +* Added options to `request.ParseFromRequest`, which allows for an arbitrary list of modifiers to parsing behavior. Initial set include `WithClaims` and `WithParser`. Existing usage of this function will continue to work as before. +* Deprecated `ParseFromRequestWithClaims` to simplify API in the future. + +#### 3.1.0 + +* Improvements to `jwt` command line tool +* Added `SkipClaimsValidation` option to `Parser` +* Documentation updates + +#### 3.0.0 + +* **Compatibility Breaking Changes**: See MIGRATION_GUIDE.md for tips on updating your code + * Dropped support for `[]byte` keys when using RSA signing methods. This convenience feature could contribute to security vulnerabilities involving mismatched key types with signing methods. + * `ParseFromRequest` has been moved to `request` subpackage and usage has changed + * The `Claims` property on `Token` is now type `Claims` instead of `map[string]interface{}`. The default value is type `MapClaims`, which is an alias to `map[string]interface{}`. This makes it possible to use a custom type when decoding claims. +* Other Additions and Changes + * Added `Claims` interface type to allow users to decode the claims into a custom type + * Added `ParseWithClaims`, which takes a third argument of type `Claims`. Use this function instead of `Parse` if you have a custom type you'd like to decode into. + * Dramatically improved the functionality and flexibility of `ParseFromRequest`, which is now in the `request` subpackage + * Added `ParseFromRequestWithClaims` which is the `FromRequest` equivalent of `ParseWithClaims` + * Added new interface type `Extractor`, which is used for extracting JWT strings from http requests. Used with `ParseFromRequest` and `ParseFromRequestWithClaims`. + * Added several new, more specific, validation errors to error type bitmask + * Moved examples from README to executable example files + * Signing method registry is now thread safe + * Added new property to `ValidationError`, which contains the raw error returned by calls made by parse/verify (such as those returned by keyfunc or json parser) + +#### 2.7.0 + +This will likely be the last backwards compatible release before 3.0.0, excluding essential bug fixes. + +* Added new option `-show` to the `jwt` command that will just output the decoded token without verifying +* Error text for expired tokens includes how long it's been expired +* Fixed incorrect error returned from `ParseRSAPublicKeyFromPEM` +* Documentation updates + +#### 2.6.0 + +* Exposed inner error within ValidationError +* Fixed validation errors when using UseJSONNumber flag +* Added several unit tests + +#### 2.5.0 + +* Added support for signing method none. You shouldn't use this. The API tries to make this clear. +* Updated/fixed some documentation +* Added more helpful error message when trying to parse tokens that begin with `BEARER ` + +#### 2.4.0 + +* Added new type, Parser, to allow for configuration of various parsing parameters + * You can now specify a list of valid signing methods. Anything outside this set will be rejected. + * You can now opt to use the `json.Number` type instead of `float64` when parsing token JSON +* Added support for [Travis CI](https://travis-ci.org/dgrijalva/jwt-go) +* Fixed some bugs with ECDSA parsing + +#### 2.3.0 + +* Added support for ECDSA signing methods +* Added support for RSA PSS signing methods (requires go v1.4) + +#### 2.2.0 + +* Gracefully handle a `nil` `Keyfunc` being passed to `Parse`. Result will now be the parsed token and an error, instead of a panic. + +#### 2.1.0 + +Backwards compatible API change that was missed in 2.0.0. + +* The `SignedString` method on `Token` now takes `interface{}` instead of `[]byte` + +#### 2.0.0 + +There were two major reasons for breaking backwards compatibility with this update. The first was a refactor required to expand the width of the RSA and HMAC-SHA signing implementations. There will likely be no required code changes to support this change. + +The second update, while unfortunately requiring a small change in integration, is required to open up this library to other signing methods. Not all keys used for all signing methods have a single standard on-disk representation. Requiring `[]byte` as the type for all keys proved too limiting. Additionally, this implementation allows for pre-parsed tokens to be reused, which might matter in an application that parses a high volume of tokens with a small set of keys. Backwards compatibilty has been maintained for passing `[]byte` to the RSA signing methods, but they will also accept `*rsa.PublicKey` and `*rsa.PrivateKey`. + +It is likely the only integration change required here will be to change `func(t *jwt.Token) ([]byte, error)` to `func(t *jwt.Token) (interface{}, error)` when calling `Parse`. + +* **Compatibility Breaking Changes** + * `SigningMethodHS256` is now `*SigningMethodHMAC` instead of `type struct` + * `SigningMethodRS256` is now `*SigningMethodRSA` instead of `type struct` + * `KeyFunc` now returns `interface{}` instead of `[]byte` + * `SigningMethod.Sign` now takes `interface{}` instead of `[]byte` for the key + * `SigningMethod.Verify` now takes `interface{}` instead of `[]byte` for the key +* Renamed type `SigningMethodHS256` to `SigningMethodHMAC`. Specific sizes are now just instances of this type. + * Added public package global `SigningMethodHS256` + * Added public package global `SigningMethodHS384` + * Added public package global `SigningMethodHS512` +* Renamed type `SigningMethodRS256` to `SigningMethodRSA`. Specific sizes are now just instances of this type. + * Added public package global `SigningMethodRS256` + * Added public package global `SigningMethodRS384` + * Added public package global `SigningMethodRS512` +* Moved sample private key for HMAC tests from an inline value to a file on disk. Value is unchanged. +* Refactored the RSA implementation to be easier to read +* Exposed helper methods `ParseRSAPrivateKeyFromPEM` and `ParseRSAPublicKeyFromPEM` + +## 1.0.2 + +* Fixed bug in parsing public keys from certificates +* Added more tests around the parsing of keys for RS256 +* Code refactoring in RS256 implementation. No functional changes + +## 1.0.1 + +* Fixed panic if RS256 signing method was passed an invalid key + +## 1.0.0 + +* First versioned release +* API stabilized +* Supports creating, signing, parsing, and validating JWT tokens +* Supports RS256 and HS256 signing methods diff --git a/vendor/github.com/golang-jwt/jwt/v5/claims.go b/vendor/github.com/golang-jwt/jwt/v5/claims.go new file mode 100644 index 0000000..d50ff3d --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/claims.go @@ -0,0 +1,16 @@ +package jwt + +// Claims represent any form of a JWT Claims Set according to +// https://datatracker.ietf.org/doc/html/rfc7519#section-4. In order to have a +// common basis for validation, it is required that an implementation is able to +// supply at least the claim names provided in +// https://datatracker.ietf.org/doc/html/rfc7519#section-4.1 namely `exp`, +// `iat`, `nbf`, `iss`, `sub` and `aud`. +type Claims interface { + GetExpirationTime() (*NumericDate, error) + GetIssuedAt() (*NumericDate, error) + GetNotBefore() (*NumericDate, error) + GetIssuer() (string, error) + GetSubject() (string, error) + GetAudience() (ClaimStrings, error) +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/doc.go b/vendor/github.com/golang-jwt/jwt/v5/doc.go new file mode 100644 index 0000000..a86dc1a --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/doc.go @@ -0,0 +1,4 @@ +// Package jwt is a Go implementation of JSON Web Tokens: http://self-issued.info/docs/draft-jones-json-web-token.html +// +// See README.md for more info. +package jwt diff --git a/vendor/github.com/golang-jwt/jwt/v5/ecdsa.go b/vendor/github.com/golang-jwt/jwt/v5/ecdsa.go new file mode 100644 index 0000000..06cd94d --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/ecdsa.go @@ -0,0 +1,134 @@ +package jwt + +import ( + "crypto" + "crypto/ecdsa" + "crypto/rand" + "errors" + "math/big" +) + +var ( + // Sadly this is missing from crypto/ecdsa compared to crypto/rsa + ErrECDSAVerification = errors.New("crypto/ecdsa: verification error") +) + +// SigningMethodECDSA implements the ECDSA family of signing methods. +// Expects *ecdsa.PrivateKey for signing and *ecdsa.PublicKey for verification +type SigningMethodECDSA struct { + Name string + Hash crypto.Hash + KeySize int + CurveBits int +} + +// Specific instances for EC256 and company +var ( + SigningMethodES256 *SigningMethodECDSA + SigningMethodES384 *SigningMethodECDSA + SigningMethodES512 *SigningMethodECDSA +) + +func init() { + // ES256 + SigningMethodES256 = &SigningMethodECDSA{"ES256", crypto.SHA256, 32, 256} + RegisterSigningMethod(SigningMethodES256.Alg(), func() SigningMethod { + return SigningMethodES256 + }) + + // ES384 + SigningMethodES384 = &SigningMethodECDSA{"ES384", crypto.SHA384, 48, 384} + RegisterSigningMethod(SigningMethodES384.Alg(), func() SigningMethod { + return SigningMethodES384 + }) + + // ES512 + SigningMethodES512 = &SigningMethodECDSA{"ES512", crypto.SHA512, 66, 521} + RegisterSigningMethod(SigningMethodES512.Alg(), func() SigningMethod { + return SigningMethodES512 + }) +} + +func (m *SigningMethodECDSA) Alg() string { + return m.Name +} + +// Verify implements token verification for the SigningMethod. +// For this verify method, key must be an ecdsa.PublicKey struct +func (m *SigningMethodECDSA) Verify(signingString string, sig []byte, key any) error { + // Get the key + var ecdsaKey *ecdsa.PublicKey + switch k := key.(type) { + case *ecdsa.PublicKey: + ecdsaKey = k + default: + return newError("ECDSA verify expects *ecdsa.PublicKey", ErrInvalidKeyType) + } + + if len(sig) != 2*m.KeySize { + return ErrECDSAVerification + } + + r := big.NewInt(0).SetBytes(sig[:m.KeySize]) + s := big.NewInt(0).SetBytes(sig[m.KeySize:]) + + // Create hasher + if !m.Hash.Available() { + return ErrHashUnavailable + } + hasher := m.Hash.New() + hasher.Write([]byte(signingString)) + + // Verify the signature + if verifystatus := ecdsa.Verify(ecdsaKey, hasher.Sum(nil), r, s); verifystatus { + return nil + } + + return ErrECDSAVerification +} + +// Sign implements token signing for the SigningMethod. +// For this signing method, key must be an ecdsa.PrivateKey struct +func (m *SigningMethodECDSA) Sign(signingString string, key any) ([]byte, error) { + // Get the key + var ecdsaKey *ecdsa.PrivateKey + switch k := key.(type) { + case *ecdsa.PrivateKey: + ecdsaKey = k + default: + return nil, newError("ECDSA sign expects *ecdsa.PrivateKey", ErrInvalidKeyType) + } + + // Create the hasher + if !m.Hash.Available() { + return nil, ErrHashUnavailable + } + + hasher := m.Hash.New() + hasher.Write([]byte(signingString)) + + // Sign the string and return r, s + if r, s, err := ecdsa.Sign(rand.Reader, ecdsaKey, hasher.Sum(nil)); err == nil { + curveBits := ecdsaKey.Curve.Params().BitSize + + if m.CurveBits != curveBits { + return nil, ErrInvalidKey + } + + keyBytes := curveBits / 8 + if curveBits%8 > 0 { + keyBytes += 1 + } + + // We serialize the outputs (r and s) into big-endian byte arrays + // padded with zeros on the left to make sure the sizes work out. + // Output must be 2*keyBytes long. + out := make([]byte, 2*keyBytes) + r.FillBytes(out[0:keyBytes]) // r is assigned to the first half of output. + s.FillBytes(out[keyBytes:]) // s is assigned to the second half of output. + + return out, nil + } else { + return nil, err + } +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/ecdsa_utils.go b/vendor/github.com/golang-jwt/jwt/v5/ecdsa_utils.go new file mode 100644 index 0000000..44a3b7a --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/ecdsa_utils.go @@ -0,0 +1,69 @@ +package jwt + +import ( + "crypto/ecdsa" + "crypto/x509" + "encoding/pem" + "errors" +) + +var ( + ErrNotECPublicKey = errors.New("key is not a valid ECDSA public key") + ErrNotECPrivateKey = errors.New("key is not a valid ECDSA private key") +) + +// ParseECPrivateKeyFromPEM parses a PEM encoded Elliptic Curve Private Key Structure +func ParseECPrivateKeyFromPEM(key []byte) (*ecdsa.PrivateKey, error) { + var err error + + // Parse PEM block + var block *pem.Block + if block, _ = pem.Decode(key); block == nil { + return nil, ErrKeyMustBePEMEncoded + } + + // Parse the key + var parsedKey any + if parsedKey, err = x509.ParseECPrivateKey(block.Bytes); err != nil { + if parsedKey, err = x509.ParsePKCS8PrivateKey(block.Bytes); err != nil { + return nil, err + } + } + + var pkey *ecdsa.PrivateKey + var ok bool + if pkey, ok = parsedKey.(*ecdsa.PrivateKey); !ok { + return nil, ErrNotECPrivateKey + } + + return pkey, nil +} + +// ParseECPublicKeyFromPEM parses a PEM encoded PKCS1 or PKCS8 public key +func ParseECPublicKeyFromPEM(key []byte) (*ecdsa.PublicKey, error) { + var err error + + // Parse PEM block + var block *pem.Block + if block, _ = pem.Decode(key); block == nil { + return nil, ErrKeyMustBePEMEncoded + } + + // Parse the key + var parsedKey any + if parsedKey, err = x509.ParsePKIXPublicKey(block.Bytes); err != nil { + if cert, err := x509.ParseCertificate(block.Bytes); err == nil { + parsedKey = cert.PublicKey + } else { + return nil, err + } + } + + var pkey *ecdsa.PublicKey + var ok bool + if pkey, ok = parsedKey.(*ecdsa.PublicKey); !ok { + return nil, ErrNotECPublicKey + } + + return pkey, nil +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/ed25519.go b/vendor/github.com/golang-jwt/jwt/v5/ed25519.go new file mode 100644 index 0000000..4159e57 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/ed25519.go @@ -0,0 +1,79 @@ +package jwt + +import ( + "crypto" + "crypto/ed25519" + "crypto/rand" + "errors" +) + +var ( + ErrEd25519Verification = errors.New("ed25519: verification error") +) + +// SigningMethodEd25519 implements the EdDSA family. +// Expects ed25519.PrivateKey for signing and ed25519.PublicKey for verification +type SigningMethodEd25519 struct{} + +// Specific instance for EdDSA +var ( + SigningMethodEdDSA *SigningMethodEd25519 +) + +func init() { + SigningMethodEdDSA = &SigningMethodEd25519{} + RegisterSigningMethod(SigningMethodEdDSA.Alg(), func() SigningMethod { + return SigningMethodEdDSA + }) +} + +func (m *SigningMethodEd25519) Alg() string { + return "EdDSA" +} + +// Verify implements token verification for the SigningMethod. +// For this verify method, key must be an ed25519.PublicKey +func (m *SigningMethodEd25519) Verify(signingString string, sig []byte, key any) error { + var ed25519Key ed25519.PublicKey + var ok bool + + if ed25519Key, ok = key.(ed25519.PublicKey); !ok { + return newError("Ed25519 verify expects ed25519.PublicKey", ErrInvalidKeyType) + } + + if len(ed25519Key) != ed25519.PublicKeySize { + return ErrInvalidKey + } + + // Verify the signature + if !ed25519.Verify(ed25519Key, []byte(signingString), sig) { + return ErrEd25519Verification + } + + return nil +} + +// Sign implements token signing for the SigningMethod. +// For this signing method, key must be an ed25519.PrivateKey +func (m *SigningMethodEd25519) Sign(signingString string, key any) ([]byte, error) { + var ed25519Key crypto.Signer + var ok bool + + if ed25519Key, ok = key.(crypto.Signer); !ok { + return nil, newError("Ed25519 sign expects crypto.Signer", ErrInvalidKeyType) + } + + if _, ok := ed25519Key.Public().(ed25519.PublicKey); !ok { + return nil, ErrInvalidKey + } + + // Sign the string and return the result. ed25519 performs a two-pass hash + // as part of its algorithm. Therefore, we need to pass a non-prehashed + // message into the Sign function, as indicated by crypto.Hash(0) + sig, err := ed25519Key.Sign(rand.Reader, []byte(signingString), crypto.Hash(0)) + if err != nil { + return nil, err + } + + return sig, nil +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/ed25519_utils.go b/vendor/github.com/golang-jwt/jwt/v5/ed25519_utils.go new file mode 100644 index 0000000..6f46e88 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/ed25519_utils.go @@ -0,0 +1,64 @@ +package jwt + +import ( + "crypto" + "crypto/ed25519" + "crypto/x509" + "encoding/pem" + "errors" +) + +var ( + ErrNotEdPrivateKey = errors.New("key is not a valid Ed25519 private key") + ErrNotEdPublicKey = errors.New("key is not a valid Ed25519 public key") +) + +// ParseEdPrivateKeyFromPEM parses a PEM-encoded Edwards curve private key +func ParseEdPrivateKeyFromPEM(key []byte) (crypto.PrivateKey, error) { + var err error + + // Parse PEM block + var block *pem.Block + if block, _ = pem.Decode(key); block == nil { + return nil, ErrKeyMustBePEMEncoded + } + + // Parse the key + var parsedKey any + if parsedKey, err = x509.ParsePKCS8PrivateKey(block.Bytes); err != nil { + return nil, err + } + + var pkey ed25519.PrivateKey + var ok bool + if pkey, ok = parsedKey.(ed25519.PrivateKey); !ok { + return nil, ErrNotEdPrivateKey + } + + return pkey, nil +} + +// ParseEdPublicKeyFromPEM parses a PEM-encoded Edwards curve public key +func ParseEdPublicKeyFromPEM(key []byte) (crypto.PublicKey, error) { + var err error + + // Parse PEM block + var block *pem.Block + if block, _ = pem.Decode(key); block == nil { + return nil, ErrKeyMustBePEMEncoded + } + + // Parse the key + var parsedKey any + if parsedKey, err = x509.ParsePKIXPublicKey(block.Bytes); err != nil { + return nil, err + } + + var pkey ed25519.PublicKey + var ok bool + if pkey, ok = parsedKey.(ed25519.PublicKey); !ok { + return nil, ErrNotEdPublicKey + } + + return pkey, nil +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/errors.go b/vendor/github.com/golang-jwt/jwt/v5/errors.go new file mode 100644 index 0000000..14e0075 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/errors.go @@ -0,0 +1,89 @@ +package jwt + +import ( + "errors" + "fmt" + "strings" +) + +var ( + ErrInvalidKey = errors.New("key is invalid") + ErrInvalidKeyType = errors.New("key is of invalid type") + ErrHashUnavailable = errors.New("the requested hash function is unavailable") + ErrTokenMalformed = errors.New("token is malformed") + ErrTokenUnverifiable = errors.New("token is unverifiable") + ErrTokenSignatureInvalid = errors.New("token signature is invalid") + ErrTokenRequiredClaimMissing = errors.New("token is missing required claim") + ErrTokenInvalidAudience = errors.New("token has invalid audience") + ErrTokenExpired = errors.New("token is expired") + ErrTokenUsedBeforeIssued = errors.New("token used before issued") + ErrTokenInvalidIssuer = errors.New("token has invalid issuer") + ErrTokenInvalidSubject = errors.New("token has invalid subject") + ErrTokenNotValidYet = errors.New("token is not valid yet") + ErrTokenInvalidId = errors.New("token has invalid id") + ErrTokenInvalidClaims = errors.New("token has invalid claims") + ErrInvalidType = errors.New("invalid type for claim") +) + +// joinedError is an error type that works similar to what [errors.Join] +// produces, with the exception that it has a nice error string; mainly its +// error messages are concatenated using a comma, rather than a newline. +type joinedError struct { + errs []error +} + +func (je joinedError) Error() string { + msg := []string{} + for _, err := range je.errs { + msg = append(msg, err.Error()) + } + + return strings.Join(msg, ", ") +} + +// joinErrors joins together multiple errors. Useful for scenarios where +// multiple errors next to each other occur, e.g., in claims validation. +func joinErrors(errs ...error) error { + return &joinedError{ + errs: errs, + } +} + +// Unwrap implements the multiple error unwrapping for this error type, which is +// possible in Go 1.20. +func (je joinedError) Unwrap() []error { + return je.errs +} + +// newError creates a new error message with a detailed error message. The +// message will be prefixed with the contents of the supplied error type. +// Additionally, more errors, that provide more context can be supplied which +// will be appended to the message. This makes use of Go 1.20's possibility to +// include more than one %w formatting directive in [fmt.Errorf]. +// +// For example, +// +// newError("no keyfunc was provided", ErrTokenUnverifiable) +// +// will produce the error string +// +// "token is unverifiable: no keyfunc was provided" +func newError(message string, err error, more ...error) error { + var format string + var args []any + if message != "" { + format = "%w: %s" + args = []any{err, message} + } else { + format = "%w" + args = []any{err} + } + + for _, e := range more { + format += ": %w" + args = append(args, e) + } + + err = fmt.Errorf(format, args...) + return err +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/hmac.go b/vendor/github.com/golang-jwt/jwt/v5/hmac.go new file mode 100644 index 0000000..1bef138 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/hmac.go @@ -0,0 +1,104 @@ +package jwt + +import ( + "crypto" + "crypto/hmac" + "errors" +) + +// SigningMethodHMAC implements the HMAC-SHA family of signing methods. +// Expects key type of []byte for both signing and validation +type SigningMethodHMAC struct { + Name string + Hash crypto.Hash +} + +// Specific instances for HS256 and company +var ( + SigningMethodHS256 *SigningMethodHMAC + SigningMethodHS384 *SigningMethodHMAC + SigningMethodHS512 *SigningMethodHMAC + ErrSignatureInvalid = errors.New("signature is invalid") +) + +func init() { + // HS256 + SigningMethodHS256 = &SigningMethodHMAC{"HS256", crypto.SHA256} + RegisterSigningMethod(SigningMethodHS256.Alg(), func() SigningMethod { + return SigningMethodHS256 + }) + + // HS384 + SigningMethodHS384 = &SigningMethodHMAC{"HS384", crypto.SHA384} + RegisterSigningMethod(SigningMethodHS384.Alg(), func() SigningMethod { + return SigningMethodHS384 + }) + + // HS512 + SigningMethodHS512 = &SigningMethodHMAC{"HS512", crypto.SHA512} + RegisterSigningMethod(SigningMethodHS512.Alg(), func() SigningMethod { + return SigningMethodHS512 + }) +} + +func (m *SigningMethodHMAC) Alg() string { + return m.Name +} + +// Verify implements token verification for the SigningMethod. Returns nil if +// the signature is valid. Key must be []byte. +// +// Note it is not advised to provide a []byte which was converted from a 'human +// readable' string using a subset of ASCII characters. To maximize entropy, you +// should ideally be providing a []byte key which was produced from a +// cryptographically random source, e.g. crypto/rand. Additional information +// about this, and why we intentionally are not supporting string as a key can +// be found on our usage guide +// https://golang-jwt.github.io/jwt/usage/signing_methods/#signing-methods-and-key-types. +func (m *SigningMethodHMAC) Verify(signingString string, sig []byte, key any) error { + // Verify the key is the right type + keyBytes, ok := key.([]byte) + if !ok { + return newError("HMAC verify expects []byte", ErrInvalidKeyType) + } + + // Can we use the specified hashing method? + if !m.Hash.Available() { + return ErrHashUnavailable + } + + // This signing method is symmetric, so we validate the signature + // by reproducing the signature from the signing string and key, then + // comparing that against the provided signature. + hasher := hmac.New(m.Hash.New, keyBytes) + hasher.Write([]byte(signingString)) + if !hmac.Equal(sig, hasher.Sum(nil)) { + return ErrSignatureInvalid + } + + // No validation errors. Signature is good. + return nil +} + +// Sign implements token signing for the SigningMethod. Key must be []byte. +// +// Note it is not advised to provide a []byte which was converted from a 'human +// readable' string using a subset of ASCII characters. To maximize entropy, you +// should ideally be providing a []byte key which was produced from a +// cryptographically random source, e.g. crypto/rand. Additional information +// about this, and why we intentionally are not supporting string as a key can +// be found on our usage guide https://golang-jwt.github.io/jwt/usage/signing_methods/. +func (m *SigningMethodHMAC) Sign(signingString string, key any) ([]byte, error) { + if keyBytes, ok := key.([]byte); ok { + if !m.Hash.Available() { + return nil, ErrHashUnavailable + } + + hasher := hmac.New(m.Hash.New, keyBytes) + hasher.Write([]byte(signingString)) + + return hasher.Sum(nil), nil + } + + return nil, newError("HMAC sign expects []byte", ErrInvalidKeyType) +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/map_claims.go b/vendor/github.com/golang-jwt/jwt/v5/map_claims.go new file mode 100644 index 0000000..3b92052 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/map_claims.go @@ -0,0 +1,109 @@ +package jwt + +import ( + "encoding/json" + "fmt" +) + +// MapClaims is a claims type that uses the map[string]any for JSON +// decoding. This is the default claims type if you don't supply one +type MapClaims map[string]any + +// GetExpirationTime implements the Claims interface. +func (m MapClaims) GetExpirationTime() (*NumericDate, error) { + return m.parseNumericDate("exp") +} + +// GetNotBefore implements the Claims interface. +func (m MapClaims) GetNotBefore() (*NumericDate, error) { + return m.parseNumericDate("nbf") +} + +// GetIssuedAt implements the Claims interface. +func (m MapClaims) GetIssuedAt() (*NumericDate, error) { + return m.parseNumericDate("iat") +} + +// GetAudience implements the Claims interface. +func (m MapClaims) GetAudience() (ClaimStrings, error) { + return m.parseClaimsString("aud") +} + +// GetIssuer implements the Claims interface. +func (m MapClaims) GetIssuer() (string, error) { + return m.parseString("iss") +} + +// GetSubject implements the Claims interface. +func (m MapClaims) GetSubject() (string, error) { + return m.parseString("sub") +} + +// parseNumericDate tries to parse a key in the map claims type as a number +// date. This will succeed, if the underlying type is either a [float64] or a +// [json.Number]. Otherwise, nil will be returned. +func (m MapClaims) parseNumericDate(key string) (*NumericDate, error) { + v, ok := m[key] + if !ok { + return nil, nil + } + + switch exp := v.(type) { + case float64: + if exp == 0 { + return nil, nil + } + + return newNumericDateFromSeconds(exp), nil + case json.Number: + v, _ := exp.Float64() + + return newNumericDateFromSeconds(v), nil + } + + return nil, newError(fmt.Sprintf("%s is invalid", key), ErrInvalidType) +} + +// parseClaimsString tries to parse a key in the map claims type as a +// [ClaimsStrings] type, which can either be a string or an array of string. +func (m MapClaims) parseClaimsString(key string) (ClaimStrings, error) { + var cs []string + switch v := m[key].(type) { + case string: + cs = append(cs, v) + case []string: + cs = v + case []any: + for _, a := range v { + vs, ok := a.(string) + if !ok { + return nil, newError(fmt.Sprintf("%s is invalid", key), ErrInvalidType) + } + cs = append(cs, vs) + } + } + + return cs, nil +} + +// parseString tries to parse a key in the map claims type as a [string] type. +// If the key does not exist, an empty string is returned. If the key has the +// wrong type, an error is returned. +func (m MapClaims) parseString(key string) (string, error) { + var ( + ok bool + raw any + iss string + ) + raw, ok = m[key] + if !ok { + return "", nil + } + + iss, ok = raw.(string) + if !ok { + return "", newError(fmt.Sprintf("%s is invalid", key), ErrInvalidType) + } + + return iss, nil +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/none.go b/vendor/github.com/golang-jwt/jwt/v5/none.go new file mode 100644 index 0000000..624ad55 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/none.go @@ -0,0 +1,50 @@ +package jwt + +// SigningMethodNone implements the none signing method. This is required by the spec +// but you probably should never use it. +var SigningMethodNone *signingMethodNone + +const UnsafeAllowNoneSignatureType unsafeNoneMagicConstant = "none signing method allowed" + +var NoneSignatureTypeDisallowedError error + +type signingMethodNone struct{} +type unsafeNoneMagicConstant string + +func init() { + SigningMethodNone = &signingMethodNone{} + NoneSignatureTypeDisallowedError = newError("'none' signature type is not allowed", ErrTokenUnverifiable) + + RegisterSigningMethod(SigningMethodNone.Alg(), func() SigningMethod { + return SigningMethodNone + }) +} + +func (m *signingMethodNone) Alg() string { + return "none" +} + +// Only allow 'none' alg type if UnsafeAllowNoneSignatureType is specified as the key +func (m *signingMethodNone) Verify(signingString string, sig []byte, key any) (err error) { + // Key must be UnsafeAllowNoneSignatureType to prevent accidentally + // accepting 'none' signing method + if _, ok := key.(unsafeNoneMagicConstant); !ok { + return NoneSignatureTypeDisallowedError + } + // If signing method is none, signature must be an empty string + if len(sig) != 0 { + return newError("'none' signing method with non-empty signature", ErrTokenUnverifiable) + } + + // Accept 'none' signing method. + return nil +} + +// Only allow 'none' signing if UnsafeAllowNoneSignatureType is specified as the key +func (m *signingMethodNone) Sign(signingString string, key any) ([]byte, error) { + if _, ok := key.(unsafeNoneMagicConstant); ok { + return []byte{}, nil + } + + return nil, NoneSignatureTypeDisallowedError +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/parser.go b/vendor/github.com/golang-jwt/jwt/v5/parser.go new file mode 100644 index 0000000..054c7eb --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/parser.go @@ -0,0 +1,268 @@ +package jwt + +import ( + "bytes" + "encoding/base64" + "encoding/json" + "fmt" + "strings" +) + +const tokenDelimiter = "." + +type Parser struct { + // If populated, only these methods will be considered valid. + validMethods []string + + // Use JSON Number format in JSON decoder. + useJSONNumber bool + + // Skip claims validation during token parsing. + skipClaimsValidation bool + + validator *Validator + + decodeStrict bool + + decodePaddingAllowed bool +} + +// NewParser creates a new Parser with the specified options +func NewParser(options ...ParserOption) *Parser { + p := &Parser{ + validator: &Validator{}, + } + + // Loop through our parsing options and apply them + for _, option := range options { + option(p) + } + + return p +} + +// Parse parses, validates, verifies the signature and returns the parsed token. +// keyFunc will receive the parsed token and should return the key for validating. +func (p *Parser) Parse(tokenString string, keyFunc Keyfunc) (*Token, error) { + return p.ParseWithClaims(tokenString, MapClaims{}, keyFunc) +} + +// ParseWithClaims parses, validates, and verifies like Parse, but supplies a default object implementing the Claims +// interface. This provides default values which can be overridden and allows a caller to use their own type, rather +// than the default MapClaims implementation of Claims. +// +// Note: If you provide a custom claim implementation that embeds one of the standard claims (such as RegisteredClaims), +// make sure that a) you either embed a non-pointer version of the claims or b) if you are using a pointer, allocate the +// proper memory for it before passing in the overall claims, otherwise you might run into a panic. +func (p *Parser) ParseWithClaims(tokenString string, claims Claims, keyFunc Keyfunc) (*Token, error) { + token, parts, err := p.ParseUnverified(tokenString, claims) + if err != nil { + return token, err + } + + // Verify signing method is in the required set + if p.validMethods != nil { + var signingMethodValid = false + var alg = token.Method.Alg() + for _, m := range p.validMethods { + if m == alg { + signingMethodValid = true + break + } + } + if !signingMethodValid { + // signing method is not in the listed set + return token, newError(fmt.Sprintf("signing method %v is invalid", alg), ErrTokenSignatureInvalid) + } + } + + // Decode signature + token.Signature, err = p.DecodeSegment(parts[2]) + if err != nil { + return token, newError("could not base64 decode signature", ErrTokenMalformed, err) + } + text := strings.Join(parts[0:2], ".") + + // Lookup key(s) + if keyFunc == nil { + // keyFunc was not provided. short circuiting validation + return token, newError("no keyfunc was provided", ErrTokenUnverifiable) + } + + got, err := keyFunc(token) + if err != nil { + return token, newError("error while executing keyfunc", ErrTokenUnverifiable, err) + } + + switch have := got.(type) { + case VerificationKeySet: + if len(have.Keys) == 0 { + return token, newError("keyfunc returned empty verification key set", ErrTokenUnverifiable) + } + // Iterate through keys and verify signature, skipping the rest when a match is found. + // Return the last error if no match is found. + for _, key := range have.Keys { + if err = token.Method.Verify(text, token.Signature, key); err == nil { + break + } + } + default: + err = token.Method.Verify(text, token.Signature, have) + } + if err != nil { + return token, newError("", ErrTokenSignatureInvalid, err) + } + + // Validate Claims + if !p.skipClaimsValidation { + // Make sure we have at least a default validator + if p.validator == nil { + p.validator = NewValidator() + } + + if err := p.validator.Validate(claims); err != nil { + return token, newError("", ErrTokenInvalidClaims, err) + } + } + + // No errors so far, token is valid. + token.Valid = true + + return token, nil +} + +// ParseUnverified parses the token but doesn't validate the signature. +// +// WARNING: Don't use this method unless you know what you're doing. +// +// It's only ever useful in cases where you know the signature is valid (since it has already +// been or will be checked elsewhere in the stack) and you want to extract values from it. +func (p *Parser) ParseUnverified(tokenString string, claims Claims) (token *Token, parts []string, err error) { + var ok bool + parts, ok = splitToken(tokenString) + if !ok { + return nil, nil, newError("token contains an invalid number of segments", ErrTokenMalformed) + } + + token = &Token{Raw: tokenString} + + // parse Header + var headerBytes []byte + if headerBytes, err = p.DecodeSegment(parts[0]); err != nil { + return token, parts, newError("could not base64 decode header", ErrTokenMalformed, err) + } + if err = json.Unmarshal(headerBytes, &token.Header); err != nil { + return token, parts, newError("could not JSON decode header", ErrTokenMalformed, err) + } + + // parse Claims + token.Claims = claims + + claimBytes, err := p.DecodeSegment(parts[1]) + if err != nil { + return token, parts, newError("could not base64 decode claim", ErrTokenMalformed, err) + } + + // If `useJSONNumber` is enabled then we must use *json.Decoder to decode + // the claims. However, this comes with a performance penalty so only use + // it if we must and, otherwise, simple use json.Unmarshal. + if !p.useJSONNumber { + // JSON Unmarshal. Special case for map type to avoid weird pointer behavior. + if c, ok := token.Claims.(MapClaims); ok { + err = json.Unmarshal(claimBytes, &c) + } else { + err = json.Unmarshal(claimBytes, &claims) + } + } else { + dec := json.NewDecoder(bytes.NewBuffer(claimBytes)) + dec.UseNumber() + // JSON Decode. Special case for map type to avoid weird pointer behavior. + if c, ok := token.Claims.(MapClaims); ok { + err = dec.Decode(&c) + } else { + err = dec.Decode(&claims) + } + } + if err != nil { + return token, parts, newError("could not JSON decode claim", ErrTokenMalformed, err) + } + + // Lookup signature method + if method, ok := token.Header["alg"].(string); ok { + if token.Method = GetSigningMethod(method); token.Method == nil { + return token, parts, newError("signing method (alg) is unavailable", ErrTokenUnverifiable) + } + } else { + return token, parts, newError("signing method (alg) is unspecified", ErrTokenUnverifiable) + } + + return token, parts, nil +} + +// splitToken splits a token string into three parts: header, claims, and signature. It will only +// return true if the token contains exactly two delimiters and three parts. In all other cases, it +// will return nil parts and false. +func splitToken(token string) ([]string, bool) { + parts := make([]string, 3) + header, remain, ok := strings.Cut(token, tokenDelimiter) + if !ok { + return nil, false + } + parts[0] = header + claims, remain, ok := strings.Cut(remain, tokenDelimiter) + if !ok { + return nil, false + } + parts[1] = claims + // One more cut to ensure the signature is the last part of the token and there are no more + // delimiters. This avoids an issue where malicious input could contain additional delimiters + // causing unecessary overhead parsing tokens. + signature, _, unexpected := strings.Cut(remain, tokenDelimiter) + if unexpected { + return nil, false + } + parts[2] = signature + + return parts, true +} + +// DecodeSegment decodes a JWT specific base64url encoding. This function will +// take into account whether the [Parser] is configured with additional options, +// such as [WithStrictDecoding] or [WithPaddingAllowed]. +func (p *Parser) DecodeSegment(seg string) ([]byte, error) { + encoding := base64.RawURLEncoding + + if p.decodePaddingAllowed { + if l := len(seg) % 4; l > 0 { + seg += strings.Repeat("=", 4-l) + } + encoding = base64.URLEncoding + } + + if p.decodeStrict { + encoding = encoding.Strict() + } + return encoding.DecodeString(seg) +} + +// Parse parses, validates, verifies the signature and returns the parsed token. +// keyFunc will receive the parsed token and should return the cryptographic key +// for verifying the signature. The caller is strongly encouraged to set the +// WithValidMethods option to validate the 'alg' claim in the token matches the +// expected algorithm. For more details about the importance of validating the +// 'alg' claim, see +// https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/ +func Parse(tokenString string, keyFunc Keyfunc, options ...ParserOption) (*Token, error) { + return NewParser(options...).Parse(tokenString, keyFunc) +} + +// ParseWithClaims is a shortcut for NewParser().ParseWithClaims(). +// +// Note: If you provide a custom claim implementation that embeds one of the +// standard claims (such as RegisteredClaims), make sure that a) you either +// embed a non-pointer version of the claims or b) if you are using a pointer, +// allocate the proper memory for it before passing in the overall claims, +// otherwise you might run into a panic. +func ParseWithClaims(tokenString string, claims Claims, keyFunc Keyfunc, options ...ParserOption) (*Token, error) { + return NewParser(options...).ParseWithClaims(tokenString, claims, keyFunc) +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/parser_option.go b/vendor/github.com/golang-jwt/jwt/v5/parser_option.go new file mode 100644 index 0000000..4315735 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/parser_option.go @@ -0,0 +1,145 @@ +package jwt + +import "time" + +// ParserOption is used to implement functional-style options that modify the +// behavior of the parser. To add new options, just create a function (ideally +// beginning with With or Without) that returns an anonymous function that takes +// a *Parser type as input and manipulates its configuration accordingly. +type ParserOption func(*Parser) + +// WithValidMethods is an option to supply algorithm methods that the parser +// will check. Only those methods will be considered valid. It is heavily +// encouraged to use this option in order to prevent attacks such as +// https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/. +func WithValidMethods(methods []string) ParserOption { + return func(p *Parser) { + p.validMethods = methods + } +} + +// WithJSONNumber is an option to configure the underlying JSON parser with +// UseNumber. +func WithJSONNumber() ParserOption { + return func(p *Parser) { + p.useJSONNumber = true + } +} + +// WithoutClaimsValidation is an option to disable claims validation. This +// option should only be used if you exactly know what you are doing. +func WithoutClaimsValidation() ParserOption { + return func(p *Parser) { + p.skipClaimsValidation = true + } +} + +// WithLeeway returns the ParserOption for specifying the leeway window. +func WithLeeway(leeway time.Duration) ParserOption { + return func(p *Parser) { + p.validator.leeway = leeway + } +} + +// WithTimeFunc returns the ParserOption for specifying the time func. The +// primary use-case for this is testing. If you are looking for a way to account +// for clock-skew, WithLeeway should be used instead. +func WithTimeFunc(f func() time.Time) ParserOption { + return func(p *Parser) { + p.validator.timeFunc = f + } +} + +// WithIssuedAt returns the ParserOption to enable verification +// of issued-at. +func WithIssuedAt() ParserOption { + return func(p *Parser) { + p.validator.verifyIat = true + } +} + +// WithExpirationRequired returns the ParserOption to make exp claim required. +// By default exp claim is optional. +func WithExpirationRequired() ParserOption { + return func(p *Parser) { + p.validator.requireExp = true + } +} + +// WithAudience configures the validator to require any of the specified +// audiences in the `aud` claim. Validation will fail if the audience is not +// listed in the token or the `aud` claim is missing. +// +// NOTE: While the `aud` claim is OPTIONAL in a JWT, the handling of it is +// application-specific. Since this validation API is helping developers in +// writing secure application, we decided to REQUIRE the existence of the claim, +// if an audience is expected. +func WithAudience(aud ...string) ParserOption { + return func(p *Parser) { + p.validator.expectedAud = aud + } +} + +// WithAllAudiences configures the validator to require all the specified +// audiences in the `aud` claim. Validation will fail if the specified audiences +// are not listed in the token or the `aud` claim is missing. Duplicates within +// the list are de-duplicated since internally, we use a map to look up the +// audiences. +// +// NOTE: While the `aud` claim is OPTIONAL in a JWT, the handling of it is +// application-specific. Since this validation API is helping developers in +// writing secure application, we decided to REQUIRE the existence of the claim, +// if an audience is expected. +func WithAllAudiences(aud ...string) ParserOption { + return func(p *Parser) { + p.validator.expectedAud = aud + p.validator.expectAllAud = true + } +} + +// WithIssuer configures the validator to require the specified issuer in the +// `iss` claim. Validation will fail if a different issuer is specified in the +// token or the `iss` claim is missing. +// +// NOTE: While the `iss` claim is OPTIONAL in a JWT, the handling of it is +// application-specific. Since this validation API is helping developers in +// writing secure application, we decided to REQUIRE the existence of the claim, +// if an issuer is expected. +func WithIssuer(iss string) ParserOption { + return func(p *Parser) { + p.validator.expectedIss = iss + } +} + +// WithSubject configures the validator to require the specified subject in the +// `sub` claim. Validation will fail if a different subject is specified in the +// token or the `sub` claim is missing. +// +// NOTE: While the `sub` claim is OPTIONAL in a JWT, the handling of it is +// application-specific. Since this validation API is helping developers in +// writing secure application, we decided to REQUIRE the existence of the claim, +// if a subject is expected. +func WithSubject(sub string) ParserOption { + return func(p *Parser) { + p.validator.expectedSub = sub + } +} + +// WithPaddingAllowed will enable the codec used for decoding JWTs to allow +// padding. Note that the JWS RFC7515 states that the tokens will utilize a +// Base64url encoding with no padding. Unfortunately, some implementations of +// JWT are producing non-standard tokens, and thus require support for decoding. +func WithPaddingAllowed() ParserOption { + return func(p *Parser) { + p.decodePaddingAllowed = true + } +} + +// WithStrictDecoding will switch the codec used for decoding JWTs into strict +// mode. In this mode, the decoder requires that trailing padding bits are zero, +// as described in RFC 4648 section 3.5. +func WithStrictDecoding() ParserOption { + return func(p *Parser) { + p.decodeStrict = true + } +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/registered_claims.go b/vendor/github.com/golang-jwt/jwt/v5/registered_claims.go new file mode 100644 index 0000000..77951a5 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/registered_claims.go @@ -0,0 +1,63 @@ +package jwt + +// RegisteredClaims are a structured version of the JWT Claims Set, +// restricted to Registered Claim Names, as referenced at +// https://datatracker.ietf.org/doc/html/rfc7519#section-4.1 +// +// This type can be used on its own, but then additional private and +// public claims embedded in the JWT will not be parsed. The typical use-case +// therefore is to embedded this in a user-defined claim type. +// +// See examples for how to use this with your own claim types. +type RegisteredClaims struct { + // the `iss` (Issuer) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1 + Issuer string `json:"iss,omitempty"` + + // the `sub` (Subject) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2 + Subject string `json:"sub,omitempty"` + + // the `aud` (Audience) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3 + Audience ClaimStrings `json:"aud,omitempty"` + + // the `exp` (Expiration Time) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4 + ExpiresAt *NumericDate `json:"exp,omitempty"` + + // the `nbf` (Not Before) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5 + NotBefore *NumericDate `json:"nbf,omitempty"` + + // the `iat` (Issued At) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6 + IssuedAt *NumericDate `json:"iat,omitempty"` + + // the `jti` (JWT ID) claim. See https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.7 + ID string `json:"jti,omitempty"` +} + +// GetExpirationTime implements the Claims interface. +func (c RegisteredClaims) GetExpirationTime() (*NumericDate, error) { + return c.ExpiresAt, nil +} + +// GetNotBefore implements the Claims interface. +func (c RegisteredClaims) GetNotBefore() (*NumericDate, error) { + return c.NotBefore, nil +} + +// GetIssuedAt implements the Claims interface. +func (c RegisteredClaims) GetIssuedAt() (*NumericDate, error) { + return c.IssuedAt, nil +} + +// GetAudience implements the Claims interface. +func (c RegisteredClaims) GetAudience() (ClaimStrings, error) { + return c.Audience, nil +} + +// GetIssuer implements the Claims interface. +func (c RegisteredClaims) GetIssuer() (string, error) { + return c.Issuer, nil +} + +// GetSubject implements the Claims interface. +func (c RegisteredClaims) GetSubject() (string, error) { + return c.Subject, nil +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/rsa.go b/vendor/github.com/golang-jwt/jwt/v5/rsa.go new file mode 100644 index 0000000..98b960a --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/rsa.go @@ -0,0 +1,93 @@ +package jwt + +import ( + "crypto" + "crypto/rand" + "crypto/rsa" +) + +// SigningMethodRSA implements the RSA family of signing methods. +// Expects *rsa.PrivateKey for signing and *rsa.PublicKey for validation +type SigningMethodRSA struct { + Name string + Hash crypto.Hash +} + +// Specific instances for RS256 and company +var ( + SigningMethodRS256 *SigningMethodRSA + SigningMethodRS384 *SigningMethodRSA + SigningMethodRS512 *SigningMethodRSA +) + +func init() { + // RS256 + SigningMethodRS256 = &SigningMethodRSA{"RS256", crypto.SHA256} + RegisterSigningMethod(SigningMethodRS256.Alg(), func() SigningMethod { + return SigningMethodRS256 + }) + + // RS384 + SigningMethodRS384 = &SigningMethodRSA{"RS384", crypto.SHA384} + RegisterSigningMethod(SigningMethodRS384.Alg(), func() SigningMethod { + return SigningMethodRS384 + }) + + // RS512 + SigningMethodRS512 = &SigningMethodRSA{"RS512", crypto.SHA512} + RegisterSigningMethod(SigningMethodRS512.Alg(), func() SigningMethod { + return SigningMethodRS512 + }) +} + +func (m *SigningMethodRSA) Alg() string { + return m.Name +} + +// Verify implements token verification for the SigningMethod +// For this signing method, must be an *rsa.PublicKey structure. +func (m *SigningMethodRSA) Verify(signingString string, sig []byte, key any) error { + var rsaKey *rsa.PublicKey + var ok bool + + if rsaKey, ok = key.(*rsa.PublicKey); !ok { + return newError("RSA verify expects *rsa.PublicKey", ErrInvalidKeyType) + } + + // Create hasher + if !m.Hash.Available() { + return ErrHashUnavailable + } + hasher := m.Hash.New() + hasher.Write([]byte(signingString)) + + // Verify the signature + return rsa.VerifyPKCS1v15(rsaKey, m.Hash, hasher.Sum(nil), sig) +} + +// Sign implements token signing for the SigningMethod +// For this signing method, must be an *rsa.PrivateKey structure. +func (m *SigningMethodRSA) Sign(signingString string, key any) ([]byte, error) { + var rsaKey *rsa.PrivateKey + var ok bool + + // Validate type of key + if rsaKey, ok = key.(*rsa.PrivateKey); !ok { + return nil, newError("RSA sign expects *rsa.PrivateKey", ErrInvalidKeyType) + } + + // Create the hasher + if !m.Hash.Available() { + return nil, ErrHashUnavailable + } + + hasher := m.Hash.New() + hasher.Write([]byte(signingString)) + + // Sign the string and return the encoded bytes + if sigBytes, err := rsa.SignPKCS1v15(rand.Reader, rsaKey, m.Hash, hasher.Sum(nil)); err == nil { + return sigBytes, nil + } else { + return nil, err + } +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/rsa_pss.go b/vendor/github.com/golang-jwt/jwt/v5/rsa_pss.go new file mode 100644 index 0000000..f17590c --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/rsa_pss.go @@ -0,0 +1,132 @@ +package jwt + +import ( + "crypto" + "crypto/rand" + "crypto/rsa" +) + +// SigningMethodRSAPSS implements the RSAPSS family of signing methods signing methods +type SigningMethodRSAPSS struct { + *SigningMethodRSA + Options *rsa.PSSOptions + // VerifyOptions is optional. If set overrides Options for rsa.VerifyPPS. + // Used to accept tokens signed with rsa.PSSSaltLengthAuto, what doesn't follow + // https://tools.ietf.org/html/rfc7518#section-3.5 but was used previously. + // See https://github.com/dgrijalva/jwt-go/issues/285#issuecomment-437451244 for details. + VerifyOptions *rsa.PSSOptions +} + +// Specific instances for RS/PS and company. +var ( + SigningMethodPS256 *SigningMethodRSAPSS + SigningMethodPS384 *SigningMethodRSAPSS + SigningMethodPS512 *SigningMethodRSAPSS +) + +func init() { + // PS256 + SigningMethodPS256 = &SigningMethodRSAPSS{ + SigningMethodRSA: &SigningMethodRSA{ + Name: "PS256", + Hash: crypto.SHA256, + }, + Options: &rsa.PSSOptions{ + SaltLength: rsa.PSSSaltLengthEqualsHash, + }, + VerifyOptions: &rsa.PSSOptions{ + SaltLength: rsa.PSSSaltLengthAuto, + }, + } + RegisterSigningMethod(SigningMethodPS256.Alg(), func() SigningMethod { + return SigningMethodPS256 + }) + + // PS384 + SigningMethodPS384 = &SigningMethodRSAPSS{ + SigningMethodRSA: &SigningMethodRSA{ + Name: "PS384", + Hash: crypto.SHA384, + }, + Options: &rsa.PSSOptions{ + SaltLength: rsa.PSSSaltLengthEqualsHash, + }, + VerifyOptions: &rsa.PSSOptions{ + SaltLength: rsa.PSSSaltLengthAuto, + }, + } + RegisterSigningMethod(SigningMethodPS384.Alg(), func() SigningMethod { + return SigningMethodPS384 + }) + + // PS512 + SigningMethodPS512 = &SigningMethodRSAPSS{ + SigningMethodRSA: &SigningMethodRSA{ + Name: "PS512", + Hash: crypto.SHA512, + }, + Options: &rsa.PSSOptions{ + SaltLength: rsa.PSSSaltLengthEqualsHash, + }, + VerifyOptions: &rsa.PSSOptions{ + SaltLength: rsa.PSSSaltLengthAuto, + }, + } + RegisterSigningMethod(SigningMethodPS512.Alg(), func() SigningMethod { + return SigningMethodPS512 + }) +} + +// Verify implements token verification for the SigningMethod. +// For this verify method, key must be an rsa.PublicKey struct +func (m *SigningMethodRSAPSS) Verify(signingString string, sig []byte, key any) error { + var rsaKey *rsa.PublicKey + switch k := key.(type) { + case *rsa.PublicKey: + rsaKey = k + default: + return newError("RSA-PSS verify expects *rsa.PublicKey", ErrInvalidKeyType) + } + + // Create hasher + if !m.Hash.Available() { + return ErrHashUnavailable + } + hasher := m.Hash.New() + hasher.Write([]byte(signingString)) + + opts := m.Options + if m.VerifyOptions != nil { + opts = m.VerifyOptions + } + + return rsa.VerifyPSS(rsaKey, m.Hash, hasher.Sum(nil), sig, opts) +} + +// Sign implements token signing for the SigningMethod. +// For this signing method, key must be an rsa.PrivateKey struct +func (m *SigningMethodRSAPSS) Sign(signingString string, key any) ([]byte, error) { + var rsaKey *rsa.PrivateKey + + switch k := key.(type) { + case *rsa.PrivateKey: + rsaKey = k + default: + return nil, newError("RSA-PSS sign expects *rsa.PrivateKey", ErrInvalidKeyType) + } + + // Create the hasher + if !m.Hash.Available() { + return nil, ErrHashUnavailable + } + + hasher := m.Hash.New() + hasher.Write([]byte(signingString)) + + // Sign the string and return the encoded bytes + if sigBytes, err := rsa.SignPSS(rand.Reader, rsaKey, m.Hash, hasher.Sum(nil), m.Options); err == nil { + return sigBytes, nil + } else { + return nil, err + } +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/rsa_utils.go b/vendor/github.com/golang-jwt/jwt/v5/rsa_utils.go new file mode 100644 index 0000000..f22c3d0 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/rsa_utils.go @@ -0,0 +1,107 @@ +package jwt + +import ( + "crypto/rsa" + "crypto/x509" + "encoding/pem" + "errors" +) + +var ( + ErrKeyMustBePEMEncoded = errors.New("invalid key: Key must be a PEM encoded PKCS1 or PKCS8 key") + ErrNotRSAPrivateKey = errors.New("key is not a valid RSA private key") + ErrNotRSAPublicKey = errors.New("key is not a valid RSA public key") +) + +// ParseRSAPrivateKeyFromPEM parses a PEM encoded PKCS1 or PKCS8 private key +func ParseRSAPrivateKeyFromPEM(key []byte) (*rsa.PrivateKey, error) { + var err error + + // Parse PEM block + var block *pem.Block + if block, _ = pem.Decode(key); block == nil { + return nil, ErrKeyMustBePEMEncoded + } + + var parsedKey any + if parsedKey, err = x509.ParsePKCS1PrivateKey(block.Bytes); err != nil { + if parsedKey, err = x509.ParsePKCS8PrivateKey(block.Bytes); err != nil { + return nil, err + } + } + + var pkey *rsa.PrivateKey + var ok bool + if pkey, ok = parsedKey.(*rsa.PrivateKey); !ok { + return nil, ErrNotRSAPrivateKey + } + + return pkey, nil +} + +// ParseRSAPrivateKeyFromPEMWithPassword parses a PEM encoded PKCS1 or PKCS8 private key protected with password +// +// Deprecated: This function is deprecated and should not be used anymore. It uses the deprecated x509.DecryptPEMBlock +// function, which was deprecated since RFC 1423 is regarded insecure by design. Unfortunately, there is no alternative +// in the Go standard library for now. See https://github.com/golang/go/issues/8860. +func ParseRSAPrivateKeyFromPEMWithPassword(key []byte, password string) (*rsa.PrivateKey, error) { + var err error + + // Parse PEM block + var block *pem.Block + if block, _ = pem.Decode(key); block == nil { + return nil, ErrKeyMustBePEMEncoded + } + + var parsedKey any + + var blockDecrypted []byte + if blockDecrypted, err = x509.DecryptPEMBlock(block, []byte(password)); err != nil { + return nil, err + } + + if parsedKey, err = x509.ParsePKCS1PrivateKey(blockDecrypted); err != nil { + if parsedKey, err = x509.ParsePKCS8PrivateKey(blockDecrypted); err != nil { + return nil, err + } + } + + var pkey *rsa.PrivateKey + var ok bool + if pkey, ok = parsedKey.(*rsa.PrivateKey); !ok { + return nil, ErrNotRSAPrivateKey + } + + return pkey, nil +} + +// ParseRSAPublicKeyFromPEM parses a certificate or a PEM encoded PKCS1 or PKIX public key +func ParseRSAPublicKeyFromPEM(key []byte) (*rsa.PublicKey, error) { + var err error + + // Parse PEM block + var block *pem.Block + if block, _ = pem.Decode(key); block == nil { + return nil, ErrKeyMustBePEMEncoded + } + + // Parse the key + var parsedKey any + if parsedKey, err = x509.ParsePKIXPublicKey(block.Bytes); err != nil { + if cert, err := x509.ParseCertificate(block.Bytes); err == nil { + parsedKey = cert.PublicKey + } else { + if parsedKey, err = x509.ParsePKCS1PublicKey(block.Bytes); err != nil { + return nil, err + } + } + } + + var pkey *rsa.PublicKey + var ok bool + if pkey, ok = parsedKey.(*rsa.PublicKey); !ok { + return nil, ErrNotRSAPublicKey + } + + return pkey, nil +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/signing_method.go b/vendor/github.com/golang-jwt/jwt/v5/signing_method.go new file mode 100644 index 0000000..096d0ed --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/signing_method.go @@ -0,0 +1,49 @@ +package jwt + +import ( + "sync" +) + +var signingMethods = map[string]func() SigningMethod{} +var signingMethodLock = new(sync.RWMutex) + +// SigningMethod can be used add new methods for signing or verifying tokens. It +// takes a decoded signature as an input in the Verify function and produces a +// signature in Sign. The signature is then usually base64 encoded as part of a +// JWT. +type SigningMethod interface { + Verify(signingString string, sig []byte, key any) error // Returns nil if signature is valid + Sign(signingString string, key any) ([]byte, error) // Returns signature or error + Alg() string // returns the alg identifier for this method (example: 'HS256') +} + +// RegisterSigningMethod registers the "alg" name and a factory function for signing method. +// This is typically done during init() in the method's implementation +func RegisterSigningMethod(alg string, f func() SigningMethod) { + signingMethodLock.Lock() + defer signingMethodLock.Unlock() + + signingMethods[alg] = f +} + +// GetSigningMethod retrieves a signing method from an "alg" string +func GetSigningMethod(alg string) (method SigningMethod) { + signingMethodLock.RLock() + defer signingMethodLock.RUnlock() + + if methodF, ok := signingMethods[alg]; ok { + method = methodF() + } + return +} + +// GetAlgorithms returns a list of registered "alg" names +func GetAlgorithms() (algs []string) { + signingMethodLock.RLock() + defer signingMethodLock.RUnlock() + + for alg := range signingMethods { + algs = append(algs, alg) + } + return +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/staticcheck.conf b/vendor/github.com/golang-jwt/jwt/v5/staticcheck.conf new file mode 100644 index 0000000..53745d5 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/staticcheck.conf @@ -0,0 +1 @@ +checks = ["all", "-ST1000", "-ST1003", "-ST1016", "-ST1023"] diff --git a/vendor/github.com/golang-jwt/jwt/v5/token.go b/vendor/github.com/golang-jwt/jwt/v5/token.go new file mode 100644 index 0000000..3f71558 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/token.go @@ -0,0 +1,100 @@ +package jwt + +import ( + "crypto" + "encoding/base64" + "encoding/json" +) + +// Keyfunc will be used by the Parse methods as a callback function to supply +// the key for verification. The function receives the parsed, but unverified +// Token. This allows you to use properties in the Header of the token (such as +// `kid`) to identify which key to use. +// +// The returned any may be a single key or a VerificationKeySet containing +// multiple keys. +type Keyfunc func(*Token) (any, error) + +// VerificationKey represents a public or secret key for verifying a token's signature. +type VerificationKey interface { + crypto.PublicKey | []uint8 +} + +// VerificationKeySet is a set of public or secret keys. It is used by the parser to verify a token. +type VerificationKeySet struct { + Keys []VerificationKey +} + +// Token represents a JWT Token. Different fields will be used depending on +// whether you're creating or parsing/verifying a token. +type Token struct { + Raw string // Raw contains the raw token. Populated when you [Parse] a token + Method SigningMethod // Method is the signing method used or to be used + Header map[string]any // Header is the first segment of the token in decoded form + Claims Claims // Claims is the second segment of the token in decoded form + Signature []byte // Signature is the third segment of the token in decoded form. Populated when you Parse a token + Valid bool // Valid specifies if the token is valid. Populated when you Parse/Verify a token +} + +// New creates a new [Token] with the specified signing method and an empty map +// of claims. Additional options can be specified, but are currently unused. +func New(method SigningMethod, opts ...TokenOption) *Token { + return NewWithClaims(method, MapClaims{}, opts...) +} + +// NewWithClaims creates a new [Token] with the specified signing method and +// claims. Additional options can be specified, but are currently unused. +func NewWithClaims(method SigningMethod, claims Claims, opts ...TokenOption) *Token { + return &Token{ + Header: map[string]any{ + "typ": "JWT", + "alg": method.Alg(), + }, + Claims: claims, + Method: method, + } +} + +// SignedString creates and returns a complete, signed JWT. The token is signed +// using the SigningMethod specified in the token. Please refer to +// https://golang-jwt.github.io/jwt/usage/signing_methods/#signing-methods-and-key-types +// for an overview of the different signing methods and their respective key +// types. +func (t *Token) SignedString(key any) (string, error) { + sstr, err := t.SigningString() + if err != nil { + return "", err + } + + sig, err := t.Method.Sign(sstr, key) + if err != nil { + return "", err + } + + return sstr + "." + t.EncodeSegment(sig), nil +} + +// SigningString generates the signing string. This is the most expensive part +// of the whole deal. Unless you need this for something special, just go +// straight for the SignedString. +func (t *Token) SigningString() (string, error) { + h, err := json.Marshal(t.Header) + if err != nil { + return "", err + } + + c, err := json.Marshal(t.Claims) + if err != nil { + return "", err + } + + return t.EncodeSegment(h) + "." + t.EncodeSegment(c), nil +} + +// EncodeSegment encodes a JWT specific base64url encoding with padding +// stripped. In the future, this function might take into account a +// [TokenOption]. Therefore, this function exists as a method of [Token], rather +// than a global function. +func (*Token) EncodeSegment(seg []byte) string { + return base64.RawURLEncoding.EncodeToString(seg) +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/token_option.go b/vendor/github.com/golang-jwt/jwt/v5/token_option.go new file mode 100644 index 0000000..b4ae3ba --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/token_option.go @@ -0,0 +1,5 @@ +package jwt + +// TokenOption is a reserved type, which provides some forward compatibility, +// if we ever want to introduce token creation-related options. +type TokenOption func(*Token) diff --git a/vendor/github.com/golang-jwt/jwt/v5/types.go b/vendor/github.com/golang-jwt/jwt/v5/types.go new file mode 100644 index 0000000..a3e0ef1 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/types.go @@ -0,0 +1,149 @@ +package jwt + +import ( + "encoding/json" + "fmt" + "math" + "strconv" + "time" +) + +// TimePrecision sets the precision of times and dates within this library. This +// has an influence on the precision of times when comparing expiry or other +// related time fields. Furthermore, it is also the precision of times when +// serializing. +// +// For backwards compatibility the default precision is set to seconds, so that +// no fractional timestamps are generated. +var TimePrecision = time.Second + +// MarshalSingleStringAsArray modifies the behavior of the ClaimStrings type, +// especially its MarshalJSON function. +// +// If it is set to true (the default), it will always serialize the type as an +// array of strings, even if it just contains one element, defaulting to the +// behavior of the underlying []string. If it is set to false, it will serialize +// to a single string, if it contains one element. Otherwise, it will serialize +// to an array of strings. +var MarshalSingleStringAsArray = true + +// NumericDate represents a JSON numeric date value, as referenced at +// https://datatracker.ietf.org/doc/html/rfc7519#section-2. +type NumericDate struct { + time.Time +} + +// NewNumericDate constructs a new *NumericDate from a standard library time.Time struct. +// It will truncate the timestamp according to the precision specified in TimePrecision. +func NewNumericDate(t time.Time) *NumericDate { + return &NumericDate{t.Truncate(TimePrecision)} +} + +// newNumericDateFromSeconds creates a new *NumericDate out of a float64 representing a +// UNIX epoch with the float fraction representing non-integer seconds. +func newNumericDateFromSeconds(f float64) *NumericDate { + round, frac := math.Modf(f) + return NewNumericDate(time.Unix(int64(round), int64(frac*1e9))) +} + +// MarshalJSON is an implementation of the json.RawMessage interface and serializes the UNIX epoch +// represented in NumericDate to a byte array, using the precision specified in TimePrecision. +func (date NumericDate) MarshalJSON() (b []byte, err error) { + var prec int + if TimePrecision < time.Second { + prec = int(math.Log10(float64(time.Second) / float64(TimePrecision))) + } + truncatedDate := date.Truncate(TimePrecision) + + // For very large timestamps, UnixNano would overflow an int64, but this + // function requires nanosecond level precision, so we have to use the + // following technique to get round the issue: + // + // 1. Take the normal unix timestamp to form the whole number part of the + // output, + // 2. Take the result of the Nanosecond function, which returns the offset + // within the second of the particular unix time instance, to form the + // decimal part of the output + // 3. Concatenate them to produce the final result + seconds := strconv.FormatInt(truncatedDate.Unix(), 10) + nanosecondsOffset := strconv.FormatFloat(float64(truncatedDate.Nanosecond())/float64(time.Second), 'f', prec, 64) + + output := append([]byte(seconds), []byte(nanosecondsOffset)[1:]...) + + return output, nil +} + +// UnmarshalJSON is an implementation of the json.RawMessage interface and +// deserializes a [NumericDate] from a JSON representation, i.e. a +// [json.Number]. This number represents an UNIX epoch with either integer or +// non-integer seconds. +func (date *NumericDate) UnmarshalJSON(b []byte) (err error) { + var ( + number json.Number + f float64 + ) + + if err = json.Unmarshal(b, &number); err != nil { + return fmt.Errorf("could not parse NumericData: %w", err) + } + + if f, err = number.Float64(); err != nil { + return fmt.Errorf("could not convert json number value to float: %w", err) + } + + n := newNumericDateFromSeconds(f) + *date = *n + + return nil +} + +// ClaimStrings is basically just a slice of strings, but it can be either +// serialized from a string array or just a string. This type is necessary, +// since the "aud" claim can either be a single string or an array. +type ClaimStrings []string + +func (s *ClaimStrings) UnmarshalJSON(data []byte) (err error) { + var value any + + if err = json.Unmarshal(data, &value); err != nil { + return err + } + + var aud []string + + switch v := value.(type) { + case string: + aud = append(aud, v) + case []string: + aud = ClaimStrings(v) + case []any: + for _, vv := range v { + vs, ok := vv.(string) + if !ok { + return ErrInvalidType + } + aud = append(aud, vs) + } + case nil: + return nil + default: + return ErrInvalidType + } + + *s = aud + + return +} + +func (s ClaimStrings) MarshalJSON() (b []byte, err error) { + // This handles a special case in the JWT RFC. If the string array, e.g. + // used by the "aud" field, only contains one element, it MAY be serialized + // as a single string. This may or may not be desired based on the ecosystem + // of other JWT library used, so we make it configurable by the variable + // MarshalSingleStringAsArray. + if len(s) == 1 && !MarshalSingleStringAsArray { + return json.Marshal(s[0]) + } + + return json.Marshal([]string(s)) +} diff --git a/vendor/github.com/golang-jwt/jwt/v5/validator.go b/vendor/github.com/golang-jwt/jwt/v5/validator.go new file mode 100644 index 0000000..92b5c05 --- /dev/null +++ b/vendor/github.com/golang-jwt/jwt/v5/validator.go @@ -0,0 +1,326 @@ +package jwt + +import ( + "fmt" + "slices" + "time" +) + +// ClaimsValidator is an interface that can be implemented by custom claims who +// wish to execute any additional claims validation based on +// application-specific logic. The Validate function is then executed in +// addition to the regular claims validation and any error returned is appended +// to the final validation result. +// +// type MyCustomClaims struct { +// Foo string `json:"foo"` +// jwt.RegisteredClaims +// } +// +// func (m MyCustomClaims) Validate() error { +// if m.Foo != "bar" { +// return errors.New("must be foobar") +// } +// return nil +// } +type ClaimsValidator interface { + Claims + Validate() error +} + +// Validator is the core of the new Validation API. It is automatically used by +// a [Parser] during parsing and can be modified with various parser options. +// +// The [NewValidator] function should be used to create an instance of this +// struct. +type Validator struct { + // leeway is an optional leeway that can be provided to account for clock skew. + leeway time.Duration + + // timeFunc is used to supply the current time that is needed for + // validation. If unspecified, this defaults to time.Now. + timeFunc func() time.Time + + // requireExp specifies whether the exp claim is required + requireExp bool + + // verifyIat specifies whether the iat (Issued At) claim will be verified. + // According to https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6 this + // only specifies the age of the token, but no validation check is + // necessary. However, if wanted, it can be checked if the iat is + // unrealistic, i.e., in the future. + verifyIat bool + + // expectedAud contains the audience this token expects. Supplying an empty + // slice will disable aud checking. + expectedAud []string + + // expectAllAud specifies whether all expected audiences must be present in + // the token. If false, only one of the expected audiences must be present. + expectAllAud bool + + // expectedIss contains the issuer this token expects. Supplying an empty + // string will disable iss checking. + expectedIss string + + // expectedSub contains the subject this token expects. Supplying an empty + // string will disable sub checking. + expectedSub string +} + +// NewValidator can be used to create a stand-alone validator with the supplied +// options. This validator can then be used to validate already parsed claims. +// +// Note: Under normal circumstances, explicitly creating a validator is not +// needed and can potentially be dangerous; instead functions of the [Parser] +// class should be used. +// +// The [Validator] is only checking the *validity* of the claims, such as its +// expiration time, but it does NOT perform *signature verification* of the +// token. +func NewValidator(opts ...ParserOption) *Validator { + p := NewParser(opts...) + return p.validator +} + +// Validate validates the given claims. It will also perform any custom +// validation if claims implements the [ClaimsValidator] interface. +// +// Note: It will NOT perform any *signature verification* on the token that +// contains the claims and expects that the [Claim] was already successfully +// verified. +func (v *Validator) Validate(claims Claims) error { + var ( + now time.Time + errs = make([]error, 0, 6) + err error + ) + + // Check, if we have a time func + if v.timeFunc != nil { + now = v.timeFunc() + } else { + now = time.Now() + } + + // We always need to check the expiration time, but usage of the claim + // itself is OPTIONAL by default. requireExp overrides this behavior + // and makes the exp claim mandatory. + if err = v.verifyExpiresAt(claims, now, v.requireExp); err != nil { + errs = append(errs, err) + } + + // We always need to check not-before, but usage of the claim itself is + // OPTIONAL. + if err = v.verifyNotBefore(claims, now, false); err != nil { + errs = append(errs, err) + } + + // Check issued-at if the option is enabled + if v.verifyIat { + if err = v.verifyIssuedAt(claims, now, false); err != nil { + errs = append(errs, err) + } + } + + // If we have an expected audience, we also require the audience claim + if len(v.expectedAud) > 0 { + if err = v.verifyAudience(claims, v.expectedAud, v.expectAllAud); err != nil { + errs = append(errs, err) + } + } + + // If we have an expected issuer, we also require the issuer claim + if v.expectedIss != "" { + if err = v.verifyIssuer(claims, v.expectedIss, true); err != nil { + errs = append(errs, err) + } + } + + // If we have an expected subject, we also require the subject claim + if v.expectedSub != "" { + if err = v.verifySubject(claims, v.expectedSub, true); err != nil { + errs = append(errs, err) + } + } + + // Finally, we want to give the claim itself some possibility to do some + // additional custom validation based on a custom Validate function. + cvt, ok := claims.(ClaimsValidator) + if ok { + if err := cvt.Validate(); err != nil { + errs = append(errs, err) + } + } + + if len(errs) == 0 { + return nil + } + + return joinErrors(errs...) +} + +// verifyExpiresAt compares the exp claim in claims against cmp. This function +// will succeed if cmp < exp. Additional leeway is taken into account. +// +// If exp is not set, it will succeed if the claim is not required, +// otherwise ErrTokenRequiredClaimMissing will be returned. +// +// Additionally, if any error occurs while retrieving the claim, e.g., when its +// the wrong type, an ErrTokenUnverifiable error will be returned. +func (v *Validator) verifyExpiresAt(claims Claims, cmp time.Time, required bool) error { + exp, err := claims.GetExpirationTime() + if err != nil { + return err + } + + if exp == nil { + return errorIfRequired(required, "exp") + } + + return errorIfFalse(cmp.Before((exp.Time).Add(+v.leeway)), ErrTokenExpired) +} + +// verifyIssuedAt compares the iat claim in claims against cmp. This function +// will succeed if cmp >= iat. Additional leeway is taken into account. +// +// If iat is not set, it will succeed if the claim is not required, +// otherwise ErrTokenRequiredClaimMissing will be returned. +// +// Additionally, if any error occurs while retrieving the claim, e.g., when its +// the wrong type, an ErrTokenUnverifiable error will be returned. +func (v *Validator) verifyIssuedAt(claims Claims, cmp time.Time, required bool) error { + iat, err := claims.GetIssuedAt() + if err != nil { + return err + } + + if iat == nil { + return errorIfRequired(required, "iat") + } + + return errorIfFalse(!cmp.Before(iat.Add(-v.leeway)), ErrTokenUsedBeforeIssued) +} + +// verifyNotBefore compares the nbf claim in claims against cmp. This function +// will return true if cmp >= nbf. Additional leeway is taken into account. +// +// If nbf is not set, it will succeed if the claim is not required, +// otherwise ErrTokenRequiredClaimMissing will be returned. +// +// Additionally, if any error occurs while retrieving the claim, e.g., when its +// the wrong type, an ErrTokenUnverifiable error will be returned. +func (v *Validator) verifyNotBefore(claims Claims, cmp time.Time, required bool) error { + nbf, err := claims.GetNotBefore() + if err != nil { + return err + } + + if nbf == nil { + return errorIfRequired(required, "nbf") + } + + return errorIfFalse(!cmp.Before(nbf.Add(-v.leeway)), ErrTokenNotValidYet) +} + +// verifyAudience compares the aud claim against cmp. +// +// If aud is not set or an empty list, it will succeed if the claim is not required, +// otherwise ErrTokenRequiredClaimMissing will be returned. +// +// Additionally, if any error occurs while retrieving the claim, e.g., when its +// the wrong type, an ErrTokenUnverifiable error will be returned. +func (v *Validator) verifyAudience(claims Claims, cmp []string, expectAllAud bool) error { + aud, err := claims.GetAudience() + if err != nil { + return err + } + + // Check that aud exists and is not empty. We only require the aud claim + // if we expect at least one audience to be present. + if len(aud) == 0 || len(aud) == 1 && aud[0] == "" { + required := len(v.expectedAud) > 0 + return errorIfRequired(required, "aud") + } + + if !expectAllAud { + for _, a := range aud { + // If we only expect one match, we can stop early if we find a match + if slices.Contains(cmp, a) { + return nil + } + } + + return ErrTokenInvalidAudience + } + + // Note that we are looping cmp here to ensure that all expected audiences + // are present in the aud claim. + for _, a := range cmp { + if !slices.Contains(aud, a) { + return ErrTokenInvalidAudience + } + } + + return nil +} + +// verifyIssuer compares the iss claim in claims against cmp. +// +// If iss is not set, it will succeed if the claim is not required, +// otherwise ErrTokenRequiredClaimMissing will be returned. +// +// Additionally, if any error occurs while retrieving the claim, e.g., when its +// the wrong type, an ErrTokenUnverifiable error will be returned. +func (v *Validator) verifyIssuer(claims Claims, cmp string, required bool) error { + iss, err := claims.GetIssuer() + if err != nil { + return err + } + + if iss == "" { + return errorIfRequired(required, "iss") + } + + return errorIfFalse(iss == cmp, ErrTokenInvalidIssuer) +} + +// verifySubject compares the sub claim against cmp. +// +// If sub is not set, it will succeed if the claim is not required, +// otherwise ErrTokenRequiredClaimMissing will be returned. +// +// Additionally, if any error occurs while retrieving the claim, e.g., when its +// the wrong type, an ErrTokenUnverifiable error will be returned. +func (v *Validator) verifySubject(claims Claims, cmp string, required bool) error { + sub, err := claims.GetSubject() + if err != nil { + return err + } + + if sub == "" { + return errorIfRequired(required, "sub") + } + + return errorIfFalse(sub == cmp, ErrTokenInvalidSubject) +} + +// errorIfFalse returns the error specified in err, if the value is true. +// Otherwise, nil is returned. +func errorIfFalse(value bool, err error) error { + if value { + return nil + } else { + return err + } +} + +// errorIfRequired returns an ErrTokenRequiredClaimMissing error if required is +// true. Otherwise, nil is returned. +func errorIfRequired(required bool, claim string) error { + if required { + return newError(fmt.Sprintf("%s claim is required", claim), ErrTokenRequiredClaimMissing) + } else { + return nil + } +} diff --git a/vendor/modules.txt b/vendor/modules.txt index a30aef1..b8f0cff 100644 --- a/vendor/modules.txt +++ b/vendor/modules.txt @@ -26,6 +26,9 @@ github.com/cloudevents/sdk-go/v2/types # github.com/davecgh/go-spew v1.1.1 ## explicit github.com/davecgh/go-spew/spew +# github.com/golang-jwt/jwt/v5 v5.3.0 +## explicit; go 1.21 +github.com/golang-jwt/jwt/v5 # github.com/golang/protobuf v1.5.2 ## explicit; go 1.9 github.com/golang/protobuf/proto From c33868c0cd19bd725eabda0e74b141550c22cd31 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 1 Oct 2025 20:28:08 -0400 Subject: [PATCH 2/6] clean up server/client AuthConfig struct Signed-off-by: Jack Ding --- AUTHENTICATION.md | 40 +++++++++++++------------------------ OPENSHIFT_AUTHENTICATION.md | 4 ++-- v2/server.go | 29 ++++++++++++--------------- 3 files changed, 29 insertions(+), 44 deletions(-) diff --git a/AUTHENTICATION.md b/AUTHENTICATION.md index c30f29e..fd85bb0 100644 --- a/AUTHENTICATION.md +++ b/AUTHENTICATION.md @@ -102,24 +102,21 @@ This approach ensures: ```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) - CertManagerIssuer string `json:"certManagerIssuer"` // cert-manager ClusterIssuer name (optional alternative) - CertManagerNamespace string `json:"certManagerNamespace"` // namespace for cert-manager resources (optional alternative) + 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 configuration using OpenShift OAuth Server - works for both single and multi-node clusters - EnableOAuth bool `json:"enableOAuth"` - OAuthIssuer string `json:"oauthIssuer"` // OpenShift OAuth server URL - OAuthJWKSURL string `json:"oauthJWKSURL"` // OpenShift JWKS endpoint - RequiredScopes []string `json:"requiredScopes"` // Required OAuth scopes - RequiredAudience string `json:"requiredAudience"` // Required OAuth audience - ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount for client authentication - ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path - UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Use OpenShift's built-in OAuth server (recommended for all cluster sizes) - AuthenticationOperator bool `json:"authenticationOperator"` // Use OpenShift Authentication Operator (optional alternative) + EnableOAuth bool `json:"enableOAuth"` + OAuthIssuer string `json:"oauthIssuer"` // OpenShift OAuth server URL + OAuthJWKSURL string `json:"oauthJWKSURL"` // OpenShift JWKS endpoint + RequiredScopes []string `json:"requiredScopes"` // Required OAuth scopes + RequiredAudience string `json:"requiredAudience"` // Required OAuth audience + ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount for client authentication + ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path + UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Use OpenShift's built-in OAuth server (recommended for all cluster sizes) } ``` @@ -225,15 +222,6 @@ rules: 2. **Server Certificate** (`serverCertPath`): The server's TLS certificate 3. **Server Private Key** (`serverKeyPath`): The server's private key -### cert-manager Certificate Management - -With cert-manager, certificates are automatically managed: - -1. **Automatic Generation**: Certificates are automatically generated by cert-manager -2. **Automatic Renewal**: Certificates are automatically renewed before expiration -3. **Secret Management**: Certificates and keys are stored in Kubernetes secrets -4. **DNS Validation**: Automatic DNS validation for certificate requests - ### Certificate Generation Example ```bash @@ -379,7 +367,7 @@ The OAuth implementation includes comprehensive security measures: 1. **Certificate Management** - Implement proper certificate rotation - Use secure storage for private keys - - Consider using a certificate manager in production + - Use OpenShift Service CA for automated certificate management 2. **OAuth Security** - **Strict Validation**: All tokens are validated against the exact configured issuer diff --git a/OPENSHIFT_AUTHENTICATION.md b/OPENSHIFT_AUTHENTICATION.md index 83f6142..f0957b5 100644 --- a/OPENSHIFT_AUTHENTICATION.md +++ b/OPENSHIFT_AUTHENTICATION.md @@ -349,9 +349,9 @@ oc top pods -n openshift-ptp ### From Other Approaches: -#### From cert-manager: +#### From Manual Certificates: 1. Set `useServiceCA: true` -2. Remove cert-manager Certificate resources +2. Remove manual certificate generation scripts 3. Update certificate paths to use Service CA secrets #### From Service Mesh: diff --git a/v2/server.go b/v2/server.go index c862c97..6b6b2bb 100644 --- a/v2/server.go +++ b/v2/server.go @@ -82,24 +82,21 @@ const ( // 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) - CertManagerIssuer string `json:"certManagerIssuer"` // cert-manager ClusterIssuer name (optional alternative) - CertManagerNamespace string `json:"certManagerNamespace"` // namespace for cert-manager resources (optional alternative) + 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 configuration using OpenShift OAuth Server - works for both single and multi-node clusters - EnableOAuth bool `json:"enableOAuth"` - OAuthIssuer string `json:"oauthIssuer"` // OpenShift OAuth server URL - OAuthJWKSURL string `json:"oauthJWKSURL"` // OpenShift JWKS endpoint - RequiredScopes []string `json:"requiredScopes"` // Required OAuth scopes - RequiredAudience string `json:"requiredAudience"` // Required OAuth audience - ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount for client authentication - ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path - UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Use OpenShift's built-in OAuth server (recommended for all cluster sizes) - AuthenticationOperator bool `json:"authenticationOperator"` // Use OpenShift Authentication Operator (optional alternative) + EnableOAuth bool `json:"enableOAuth"` + OAuthIssuer string `json:"oauthIssuer"` // OpenShift OAuth server URL + OAuthJWKSURL string `json:"oauthJWKSURL"` // OpenShift JWKS endpoint + RequiredScopes []string `json:"requiredScopes"` // Required OAuth scopes + RequiredAudience string `json:"requiredAudience"` // Required OAuth audience + ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount for client authentication + ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path + UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Use OpenShift's built-in OAuth server (recommended for all cluster sizes) } // LoadAuthConfig loads authentication configuration from a JSON file From 685310dbf61e90e03109883a60f88313cf891a74 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 8 Oct 2025 10:25:48 -0400 Subject: [PATCH 3/6] Update Swagger documentation with comprehensive authentication support - Enhanced swagger.json with mTLS and OAuth 2.0 security definitions - Added authentication requirements for protected endpoints (POST, DELETE operations) - Updated API descriptions with detailed authentication documentation - Added comprehensive error response documentation (401 Unauthorized) - Expanded tags.json with detailed API categories and descriptions - Updated dev-readme.md with authentication testing examples - Regenerated rest_api_v2.md with complete API reference including security model - Added security schemes documentation for dual authentication (mTLS + OAuth) - Included contact information and license details in API specification - Validated swagger specification for compliance with OpenAPI 2.0 standard The updated documentation provides complete guidance for: - mTLS certificate authentication setup - OAuth 2.0 Bearer token authentication - Dual authentication testing scenarios - Protected vs public endpoint identification - Comprehensive error handling documentation Signed-off-by: Jack Ding --- docs/dev-readme.md | 72 ++++++++++++++++++++++++++++++++++++ docs/rest_api_v2.md | 89 ++++++++++++++++++++++++++++++++++++++++++--- v2/swagger.json | 78 +++++++++++++++++++++++++++++++++++---- v2/tags.json | 20 ++++++++-- 4 files changed, 243 insertions(+), 16 deletions(-) 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/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/v2/swagger.json b/v2/swagger.json index 8666e15..0dc5104 100644 --- a/v2/swagger.json +++ b/v2/swagger.json @@ -11,12 +11,37 @@ ], "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": { + "mTLS": { + "type": "basic", + "description": "Mutual TLS authentication using client certificates. Clients must present valid certificates signed by the trusted CA." + }, + "OAuth2": { + "type": "oauth2", + "description": "OAuth 2.0 authentication using Bearer tokens. Supports OpenShift OAuth server and Kubernetes ServiceAccount tokens.", + "flow": "application", + "tokenUrl": "https://oauth-openshift.apps.cluster.local/oauth/token", + "scopes": { + "user:info": "Access to user information", + "read": "Read access to resources", + "write": "Write access to resources" + } + } + }, "paths": { "/health": { "get": { @@ -75,6 +100,12 @@ ], "summary": "Creates a subscription resource for the Event Consumer.", "operationId": "createSubscription", + "security": [ + { + "mTLS": [], + "OAuth2": ["write"] + } + ], "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 +123,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 +141,18 @@ ], "summary": "(Extensions to O-RAN API) Delete all subscriptions.", "operationId": "deleteAllSubscriptions", + "security": [ + { + "mTLS": [], + "OAuth2": ["write"] + } + ], "responses": { "204": { "description": "Deleted all subscriptions." + }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." } } } @@ -148,6 +191,12 @@ ], "summary": "Delete a specific subscription.", "operationId": "deleteSubscription", + "security": [ + { + "mTLS": [], + "OAuth2": ["write"] + } + ], "parameters": [ { "type": "string", @@ -162,6 +211,9 @@ "204": { "description": "Success." }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." + }, "404": { "description": "Not Found. Subscription resources are not available (not created)." } @@ -366,12 +418,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." } ] } From bb696d36dd4bfd42753687f1b0bb4bd28a61494f Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Mon, 17 Nov 2025 10:19:38 -0500 Subject: [PATCH 4/6] add oran doc Signed-off-by: Jack Ding --- docs/oran.md | 1855 +++++++++++++++++++++++++++++++++++++++++++++++ v2/swagger.json | 2 +- 2 files changed, 1856 insertions(+), 1 deletion(-) create mode 100644 docs/oran.md diff --git a/docs/oran.md b/docs/oran.md new file mode 100644 index 0000000..6973b78 --- /dev/null +++ b/docs/oran.md @@ -0,0 +1,1855 @@ ++-----------------------------------------------------------------------+ +| ![](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 Subscription API Definition +[10](#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 | +| | | and is optional. In a local scenario | +| | | (i.e. within the POD/VM) this is not | +| | | mandated. If the consumer is external | +| | | to the POD/VM then Authorization is | +| | | mandated. | ++------------------+----------------------+-----------------------------------------+ +| 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. | | ++-----------------------------------+----------------------+-------------------------------------------------------+ + +# 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 | | | 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. | ++------------+----------+-------+-----------------+--------------+------------------------------------+ + +#### 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/v2/swagger.json b/v2/swagger.json index 0dc5104..92fcfb8 100644 --- a/v2/swagger.json +++ b/v2/swagger.json @@ -438,4 +438,4 @@ "description": "Authentication and authorization using mTLS (mutual TLS) and OAuth 2.0 with OpenShift integration." } ] -} \ No newline at end of file +} From 32f72469d6c1bc3124f50cb1465b76f42abd5cef Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Mon, 17 Nov 2025 10:23:17 -0500 Subject: [PATCH 5/6] Add mTLS and OAuth authentication documentation to O-RAN specification This commit updates the O-RAN Cloud Notification API specification (oran.md) to include comprehensive authentication and security documentation: Authentication Mechanisms: - Added new Chapter 4: Authentication and Security - Documented mTLS (Mutual TLS) authentication at transport layer - Documented OAuth 2.0 authentication at application layer - Described dual authentication approach (mTLS + OAuth) Security Features: - Certificate-based client authentication (X.509) - Bearer token authentication (JWT - JSON Web Tokens) - Support for OpenShift OAuth and Kubernetes ServiceAccount tokens - Token validation: issuer, audience, signature, expiration, scopes - Certificate verification against trusted CA - OpenShift Service CA integration Authentication Requirements: - Added authentication requirements table by endpoint and HTTP method - POST /subscriptions: requires authentication (mTLS and/or OAuth) - DELETE /subscriptions: requires authentication - DELETE /subscriptions/{id}: requires authentication - GET endpoints: public (no authentication required) - /health endpoint: always public Response Codes: - Added 401 Unauthorized responses to POST and DELETE operations - Updated response code descriptions with authentication details - Clarified error scenarios for failed authentication Security Considerations: - Certificate management best practices - Token management and lifecycle - RBAC integration with Kubernetes ServiceAccount tokens - Localhost exception for Helper/Sidecar containers - Defense-in-depth security model Configuration Examples: - mTLS client certificate authentication example - OAuth 2.0 Bearer token authentication example - Dual authentication (mTLS + OAuth) example - curl command examples for all authentication scenarios Updated Documentation: - Enhanced Authorization header description with OAuth details - Added note about mTLS certificate verification at TLS layer - Updated Table of Contents with new authentication chapter - Maintained O-RAN specification formatting and structure This update aligns the O-RAN specification with the implemented authentication features in rest-api v2 and provides comprehensive guidance for Event Consumers implementing secure API access. Signed-off-by: Jack Ding --- docs/oran.md | 333 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 286 insertions(+), 47 deletions(-) diff --git a/docs/oran.md b/docs/oran.md index 6973b78..7307475 100644 --- a/docs/oran.md +++ b/docs/oran.md @@ -64,8 +64,34 @@ headers [3.1.4 Resource addressing [8](#resource-addressing)](#resource-addressing) -[Chapter 4 Subscription API Definition -[10](#subscription-api-definition)](#subscription-api-definition) +[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) @@ -221,7 +247,7 @@ EP Event Producer REST Representational State Transfer -# Introduction +# 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 @@ -305,9 +331,9 @@ Subscription/Publication use case: Consumer (vO-DU, vO-CU etc) will be able to make a decision if to proceed with its operation -# Usage of HTTP +# Usage of HTTP -## General +## General HTTP/2, IETF RFC 7540, shall be used. @@ -345,11 +371,20 @@ request messages in the O-Cloud APIs. | | | body. | +------------------+----------------------+-----------------------------------------+ | Authorization | IETF RFC 7235 \[13\] | The authorization token for the request | -| | | and is optional. In a local scenario | -| | | (i.e. within the POD/VM) this is not | -| | | mandated. If the consumer is external | -| | | to the POD/VM then Authorization is | -| | | mandated. | +| | | 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) | @@ -545,9 +580,196 @@ Field definitions are shown in [[Table 2]{.underline}](#table2). | | specified level. | | +-----------------------------------+----------------------+-------------------------------------------------------+ -# Subscription API Definition +# 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 -## Resource Structure +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 OpenShift Service CA 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. **OpenShift OAuth Tokens**: Issued by OpenShift 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 OpenShift 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) + +**OpenShift Service CA 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 @@ -663,9 +885,9 @@ on the resource** ------------------ -------- ------- ----------------- ------------------- ------------------- **Name** **Data **P** **Cardinality** **Description** **Applicability** - type** + type** - n/a + n/a ------------------ -------- ------- ----------------- ------------------- ------------------- Data structures supported by the request body of the POST method shall @@ -708,6 +930,16 @@ body on the resource** | | | | | | 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 | @@ -774,9 +1006,9 @@ method on the resource** ---------- -------- ------- ----------------- ------------------- ----------------------- **Name** **Data **P** **Cardinality** **Description** **Applicability** - type** + type** - n/a + n/a ---------- -------- ------- ----------------- ------------------- ----------------------- Data structures supported by the response body of the method shall be @@ -847,9 +1079,9 @@ method on the resource** -------------------- -------- ------- ----------------- ------------------ ------------------- **Name** **Data **P** **Cardinality** **Description** **Applicability** - type** + type** - n/a + n/a -------------------- -------- ------- ----------------- ------------------ ------------------- Data structures supported by the request body of the DELETE method shall @@ -860,9 +1092,9 @@ body on the resource** ------------ --------- ----------------- ------------------------------------ **Data **P** **Cardinality** **Description** - type** + type** - n/a + n/a ------------ --------- ----------------- ------------------------------------ Data structures supported by the response body of the method shall be @@ -880,6 +1112,13 @@ response body on the resource** | | | | | | ../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 @@ -898,9 +1137,9 @@ method on the resource** -------------------- -------- ------- ----------------- ------------------ ------------------- **Name** **Data **P** **Cardinality** **Description** **Applicability** - type** + type** - n/a + n/a -------------------- -------- ------- ----------------- ------------------ ------------------- Data structures supported by the request body of the GET method shall be @@ -911,9 +1150,9 @@ body on the resource** ----------- --------- ----------------- ------------------------------------- **Data **P** **Cardinality** **Description** - type** + type** - n/a + n/a ----------- --------- ----------------- ------------------------------------- Data structures supported by the response body of the method shall be @@ -942,9 +1181,9 @@ response body on the resource** **Note**: The *SubscriptionInfo* is defined in the subscription Data Model section -# Status Notifications API Definition +# Status Notifications API Definition -## Description +## 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 @@ -1039,9 +1278,9 @@ method on the resource** ----------- ----------- ------- ------------------ ----------------- ------------------- **Name** **Data **P** **Cardinality** **Description** **Applicability** - Type** + Type** - n/a + n/a ----------- ----------- ------- ------------------ ----------------- ------------------- Data structures supported by the request body of the POST method shall @@ -1083,7 +1322,7 @@ response body on the resource** | | +--------------------------------------------------------------------------------------------------------------+ -> +> \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ @@ -1153,9 +1392,9 @@ method on the resource** ---------- -------- ------- ----------------- ------------------- ------------------------ **Name** **Data **P** **Cardinality** **Description** **Applicability** - type** + type** - n/a + n/a ---------- -------- ------- ----------------- ------------------- ------------------------ Data structures supported by the request body of the POST method shall @@ -1166,7 +1405,7 @@ body on the resource** ----------- --------- ----------------- ------------------------------------- **Data **P** **Cardinality** **Description** - type** + type** Event M 1 The payload will include event notification. See note below. @@ -1194,7 +1433,7 @@ response body on the resource** | | n/a | O | 0..1 | 404 | URI not found. | +------------+---------+-------+-----------------+--------------+-------------------------+ -# Event Pull Status Notifications API Definition +# Event Pull Status Notifications API Definition ## Description @@ -1286,9 +1525,9 @@ method on the resource** ----------------------- -------- ------- ----------------- ----------------- ------------------- **Name** **Data **P** **Cardinality** **Description** **Applicability** - type** + type** - n/a + n/a ----------------------- -------- ------- ----------------- ----------------- ------------------- Data structures supported by the request body of the GET method shall be @@ -1299,9 +1538,9 @@ body on the resource** ------------ --------- ----------------- ------------------------------------ **Data **P** **Cardinality** **Description** - type** + type** - n/a + n/a ------------ --------- ----------------- ------------------------------------ Data structures supported by the response body of the method shall be @@ -1331,7 +1570,7 @@ 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 +# Event Data Model ## Subscription Data Model @@ -1555,7 +1794,7 @@ 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 @@ -1591,7 +1830,7 @@ System Clock which is consumable by application(s). | | | G.810 | +--------------+-----------------------------------------------------+-------------------------------------+ -#### +#### #### PTP Synchronization State @@ -1621,7 +1860,7 @@ System Clock which is consumable by application(s). | | | G.810 | +--------------+----------------------------------------+-------------------------------------+ -#### +#### #### Void @@ -1753,12 +1992,12 @@ change attribute in the Announce message changes. is generated when the clock-class changes. - value_type metric + value_type metric value Uint8 New clock class attribute -------------- ---------------------------------------------- ------------------------------------- -#### +#### #### SyncE Clock Quality Change @@ -1779,14 +2018,14 @@ clock quality attribute in the ESMC message changes. notification is generated when the clock-quality changes. - value_type metric + value_type metric value Uint8 New clock quality attribute -------------- ---------------------------------------------------- ------------------------------------- -#### +#### -#### +#### ----------------------------------------------------------------------- @@ -1828,7 +2067,7 @@ height="2.2918044619422573in"} - Eliminating the discovery of an external pod implementation -## +## ######## Annex (informative): Change History From 5eef748c99fd66b5c4ad4007408f69672e0c981d Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Fri, 12 Dec 2025 12:14:23 -0500 Subject: [PATCH 6/6] remove Openshift specific details in oran docs Signed-off-by: Jack Ding --- docs/oran.docx | Bin 0 -> 40683 bytes docs/oran.md | 8 ++++---- 2 files changed, 4 insertions(+), 4 deletions(-) create mode 100644 docs/oran.docx diff --git a/docs/oran.docx b/docs/oran.docx new file mode 100644 index 0000000000000000000000000000000000000000..58bf6c8eec5326be34e0172cda496c2d249dbe71 GIT binary patch literal 40683 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 S`3(^E#zcaH8%q7>+y4Mg2dAX~ literal 0 HcmV?d00001 diff --git a/docs/oran.md b/docs/oran.md index 7307475..e1c0b1d 100644 --- a/docs/oran.md +++ b/docs/oran.md @@ -601,7 +601,7 @@ mTLS provides transport layer security by requiring both the client and server t - Certificate-based client authentication - Encrypted communication channel - Certificate verification against trusted Certificate Authority (CA) -- Support for OpenShift Service CA for automatic certificate management +- Support for platform-specific CA services for automatic certificate management **Implementation Requirements:** - Client must present valid X.509 certificate signed by trusted CA @@ -618,7 +618,7 @@ mTLS provides transport layer security by requiring both the client and server t OAuth 2.0 provides application layer authentication using Bearer tokens (JWT - JSON Web Tokens). **Supported Token Types:** -1. **OpenShift OAuth Tokens**: Issued by OpenShift OAuth server +1. **Platform OAuth Tokens**: Issued by the platform's OAuth server 2. **Kubernetes ServiceAccount Tokens**: Native Kubernetes authentication tokens **Token Validation:** @@ -630,7 +630,7 @@ OAuth 2.0 provides application layer authentication using Bearer tokens (JWT - J **Implementation Requirements:** - Client includes Bearer token in Authorization header: `Authorization: Bearer ` -- Server validates token against OpenShift OAuth server or Kubernetes API +- 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 @@ -699,7 +699,7 @@ The following table describes authentication requirements for each API endpoint: - Implement certificate revocation checking (CRL or OCSP) - Store private keys securely (encrypted, restricted access) -**OpenShift Service CA Integration:** +**Platform Certificate Authority Integration:** - Automatic certificate issuance and rotation - Certificates mounted as Kubernetes Secrets - Trust bundle distributed via ConfigMaps