From e3bea2fa23743b9986c8a7628fb5d2901ad47450 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Tue, 26 Aug 2025 17:39:36 -0400 Subject: [PATCH 01/15] 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 3648844..c038794 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 968887a..6fc5219 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 f4bb954..c3f1ccd 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 513e769ab3249427f82b38959e96c1d90f1c7cb2 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 1 Oct 2025 20:28:08 -0400 Subject: [PATCH 02/15] 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 68a37aa3bc9f66f682a1fb77781b2697c23ddbd6 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 8 Oct 2025 10:25:48 -0400 Subject: [PATCH 03/15] 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 93b8a732eb74a0ee46d2863a36fa453ae904d9ca Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Mon, 17 Nov 2025 10:19:38 -0500 Subject: [PATCH 04/15] 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 280bc4221475337c2e555315773c648f3b951a76 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Mon, 17 Nov 2025 10:23:17 -0500 Subject: [PATCH 05/15] 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 1f750257a1c0415546d1eaf230d4a8ae2713ed40 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Fri, 12 Dec 2025 12:14:23 -0500 Subject: [PATCH 06/15] 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 From da663fa76a0942a5a10ac98a299d9ae00dec4159 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 9 Sep 2026 18:21:34 -0400 Subject: [PATCH 07/15] Enforce mTLS+OAuth on all APIs, TokenReview validation, TLS profile Extend the WIP auth work to satisfy CNF-26787 and the related security bugs (OCPBUGS-116059/116202/116139/116791/116817): - Replace insecure JWT ParseUnverified (no signature check) with a TokenValidator interface. rest-api stays free of any Kubernetes client dependency; cloud-event-proxy supplies a TokenReview-based validator. Fail closed when OAuth is enabled but no validator is installed. Drop the golang-jwt dependency. - Apply authentication to ALL data endpoints (GET reads and CurrentState included), not just mutating ones. /health and / stay open for probes. - mTLS: use VerifyClientCertIfGiven so the trusted loopback fast-path (same-pod) still works while any presented certificate is verified against the CA pool; the middleware requires a verified certificate for all non-loopback requests. - Honor the centrally-managed TLS profile (CNF-21982): apply MinVersion and CipherSuites from AuthConfig instead of hardcoding TLS 1.2/defaults. - Remove InsecureSkipVerify on the endpoint-validation HTTPClient; verify against the CA pool. Add SSRF hardening (validateEndpointURI) on subscriber/publisher callback URIs, rejecting link-local, multicast, unspecified and cloud-metadata addresses. Co-Authored-By: Claude Opus 4.8 Signed-off-by: Jack Ding --- auth-config-example.json | 10 +- examples/openshift-auth-config.json | 11 +- go.mod | 1 - go.sum | 2 - v2/auth.go | 259 +++++++------- v2/routes.go | 10 + v2/server.go | 85 +++-- .../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 - 36 files changed, 212 insertions(+), 2856 deletions(-) delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/.gitignore delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/LICENSE delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/README.md delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/SECURITY.md delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/VERSION_HISTORY.md delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/claims.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/doc.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/ecdsa.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/ecdsa_utils.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/ed25519.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/ed25519_utils.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/errors.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/hmac.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/map_claims.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/none.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/parser.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/parser_option.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/registered_claims.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/rsa.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/rsa_pss.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/rsa_utils.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/signing_method.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/staticcheck.conf delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/token.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/token_option.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/types.go delete mode 100644 vendor/github.com/golang-jwt/jwt/v5/validator.go diff --git a/auth-config-example.json b/auth-config-example.json index 0e6a4cc..25f1fec 100644 --- a/auth-config-example.json +++ b/auth-config-example.json @@ -5,8 +5,10 @@ "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" + "requiredAudiences": ["https://kubernetes.default.svc"], + "serviceAccountName": "cloud-event-proxy-sa", + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token", + + "tlsMinVersion": "VersionTLS12", + "tlsCipherSuites": [] } diff --git a/examples/openshift-auth-config.json b/examples/openshift-auth-config.json index b439df2..425e9f0 100644 --- a/examples/openshift-auth-config.json +++ b/examples/openshift-auth-config.json @@ -4,12 +4,13 @@ "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", + "requiredAudiences": ["https://kubernetes.default.svc"], "serviceAccountName": "cloud-event-proxy-sa", - "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" + "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token", + + "tlsMinVersion": "VersionTLS12", + "tlsCipherSuites": [] } diff --git a/go.mod b/go.mod index c038794..3648844 100644 --- a/go.mod +++ b/go.mod @@ -20,7 +20,6 @@ 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 6fc5219..968887a 100644 --- a/go.sum +++ b/go.sum @@ -9,8 +9,6 @@ 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 index bc60fa2..7f1af51 100644 --- a/v2/auth.go +++ b/v2/auth.go @@ -15,14 +15,16 @@ package restapi import ( + "context" + "crypto/tls" "crypto/x509" "fmt" + "net" "net/http" + "net/url" "os" "strings" - "time" - "github.com/golang-jwt/jwt/v5" log "github.com/sirupsen/logrus" ) @@ -48,147 +50,166 @@ func (s *Server) initMTLSCACertPool() error { 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"` +// TokenInfo carries the authenticated identity returned by a TokenValidator. +type TokenInfo struct { + Username string + UID string + Groups []string + Audiences []string } -// 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") - } +// TokenValidator validates an OAuth 2.0 / OIDC bearer token and returns the +// authenticated identity. Implementations are supplied by the embedding +// application (e.g. cloud-event-proxy uses the Kubernetes TokenReview API) so +// that this library remains free of any Kubernetes client dependency. +// +// A validator MUST cryptographically verify the token (signature and, when +// audiences are supplied, audience binding). Returning a non-nil error MUST +// cause the request to be rejected with 401. +type TokenValidator interface { + ValidateToken(ctx context.Context, token string, audiences []string) (*TokenInfo, error) +} - // 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) - } +// SetTokenValidator installs the bearer-token validator used when OAuth is +// enabled. When OAuth is enabled and no validator is installed, all +// non-localhost requests fail closed (401). +func (s *Server) SetTokenValidator(v TokenValidator) { + s.tokenValidator = v +} - claims, ok := token.Claims.(jwt.MapClaims) - if !ok { - return nil, fmt.Errorf("invalid token claims") +// isLoopbackRemoteAddr reports whether the request originates from the local +// loopback interface (same pod). Such requests never leave the pod's network +// namespace and are treated as a trusted fast-path. +func isLoopbackRemoteAddr(remoteAddr string) bool { + if remoteAddr == "" { + return false } - - // Validate issuer - issuer, ok := claims["iss"].(string) - if !ok { - return nil, fmt.Errorf("missing or invalid issuer in token") + host := remoteAddr + if h, _, err := net.SplitHostPort(remoteAddr); err == nil { + host = h } - - // 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) + host = strings.Trim(host, "[]") + if ip := net.ParseIP(host); ip != nil { + return ip.IsLoopback() } + return host == "localhost" +} - issuerValid := false - for _, validIssuer := range validIssuers { - if issuer == validIssuer { - issuerValid = true - break +// validateEndpointURI performs SSRF hardening on a caller-supplied callback / +// endpoint URI (subscriber EndpointUri or publisher endpoint). Per O-RAN +// RHT-0003 the host may be localhost, an IP, or an FQDN, so those are allowed; +// link-local, cloud-metadata, multicast and unspecified addresses are rejected. +func validateEndpointURI(raw string) error { + u, err := url.Parse(raw) + if err != nil { + return fmt.Errorf("invalid EndpointUri %q: %v", raw, err) + } + if u.Scheme != "http" && u.Scheme != "https" { + return fmt.Errorf("EndpointUri scheme must be http or https, got %q", u.Scheme) + } + host := u.Hostname() + if host == "" { + return fmt.Errorf("EndpointUri host is empty") + } + if ip := net.ParseIP(host); ip != nil { + switch { + case ip.IsLinkLocalUnicast(), ip.IsLinkLocalMulticast(), ip.IsMulticast(), ip.IsUnspecified(): + return fmt.Errorf("EndpointUri host %q is not an allowed address", host) + case ip.Equal(net.ParseIP("169.254.169.254")): + return fmt.Errorf("EndpointUri host %q (cloud metadata) is not allowed", host) } } + return nil +} - if !issuerValid { - return nil, fmt.Errorf("token issuer not accepted: got %s, expected one of: %v", issuer, validIssuers) +// tlsVersionFromString maps a TLS version name (as used by the OpenShift +// TLSSecurityProfile / crypto/tls) to its constant. Returns 0 when unknown. +func tlsVersionFromString(v string) uint16 { + switch strings.TrimSpace(v) { + case "VersionTLS10": + return tls.VersionTLS10 + case "VersionTLS11": + return tls.VersionTLS11 + case "VersionTLS12": + return tls.VersionTLS12 + case "VersionTLS13": + return tls.VersionTLS13 + default: + return 0 } +} - // 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") +// cipherSuitesFromNames maps IANA cipher suite names to their crypto/tls IDs. +// Unknown names are ignored. TLS 1.3 cipher suites are not configurable in Go +// and are silently dropped, which is expected. +func cipherSuitesFromNames(names []string) []uint16 { + if len(names) == 0 { + return nil + } + lookup := make(map[string]uint16) + for _, cs := range tls.CipherSuites() { + lookup[cs.Name] = cs.ID + } + for _, cs := range tls.InsecureCipherSuites() { + lookup[cs.Name] = cs.ID + } + var out []uint16 + for _, n := range names { + if id, ok := lookup[strings.TrimSpace(n)]; ok { + out = append(out, id) } } + return out +} - // Convert to OAuthClaims struct - oauthClaims := &OAuthClaims{ - Issuer: issuer, - ExpiresAt: int64(claims["exp"].(float64)), +// applyTLSProfile applies the centrally-managed TLS profile (min version and +// cipher suites, sourced from the cluster's TLSSecurityProfile via the +// operator) onto a tls.Config. Nothing is hardcoded here: values come from the +// AuthConfig. Only when no min version is supplied at all do we fall back to +// TLS 1.2 to avoid negotiating an insecure protocol by default. +func (c *AuthConfig) applyTLSProfile(cfg *tls.Config) { + if c == nil { + return } - - if sub, ok := claims["sub"].(string); ok { - oauthClaims.Subject = sub + if mv := tlsVersionFromString(c.TLSMinVersion); mv != 0 { + cfg.MinVersion = mv + } else if cfg.MinVersion == 0 { + cfg.MinVersion = tls.VersionTLS12 } - - if iat, ok := claims["iat"].(float64); ok { - oauthClaims.IssuedAt = int64(iat) + if cs := cipherSuitesFromNames(c.TLSCipherSuites); len(cs) > 0 { + cfg.CipherSuites = cs } - - return oauthClaims, nil } -// combinedAuthMiddleware applies both mTLS and OAuth authentication +// combinedAuthMiddleware enforces mTLS and/or OAuth on protected endpoints. +// +// Requests from the local loopback interface (same pod) are treated as a +// trusted fast-path and skip authentication - they never leave the pod. All +// other (FQDN / service-DNS / external) requests must satisfy every enabled +// mechanism: a verified client certificate when mTLS is enabled, and a valid +// bearer token when OAuth is enabled. func (s *Server) combinedAuthMiddleware(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - // 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 - } + // Trusted loopback fast-path (same pod, e.g. in-process producer self-call). + if isLoopbackRemoteAddr(r.RemoteAddr) { + log.Debugf("allowing loopback connection from %s for %s", r.RemoteAddr, r.URL.Path) + next.ServeHTTP(w, r) + return } - // Check for client certificate when mTLS is enabled + // mTLS: the TLS handshake (ClientAuth: VerifyClientCertIfGiven) has + // already verified any presented certificate chain against the CA pool; + // here we require that a client certificate was in fact presented. if s.authConfig != nil && s.authConfig.EnableMTLS { if r.TLS == nil || len(r.TLS.PeerCertificates) == 0 { log.Warnf("mTLS required but no client certificate provided for %s", r.URL.Path) http.Error(w, "Client certificate required", http.StatusUnauthorized) return } - - // 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) + log.Debugf("client certificate present and verified for %s", r.URL.Path) } - // Validate OAuth token if OAuth is enabled + // OAuth: require and validate a bearer token. if s.authConfig != nil && s.authConfig.EnableOAuth { authHeader := r.Header.Get("Authorization") if authHeader == "" { @@ -196,25 +217,29 @@ func (s *Server) combinedAuthMiddleware(next http.Handler) http.Handler { 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) + log.Warnf("invalid Authorization header format for %s", r.URL.Path) http.Error(w, "Bearer token required", http.StatusUnauthorized) return } + token := strings.TrimSpace(strings.TrimPrefix(authHeader, "Bearer ")) + + // Fail closed: OAuth is enabled but no validator was installed. + if s.tokenValidator == nil { + log.Error("OAuth enabled but no TokenValidator configured; rejecting request") + http.Error(w, "token validation unavailable", http.StatusUnauthorized) + return + } - token := strings.TrimPrefix(authHeader, "Bearer ") - _, err := s.validateOAuthToken(token) + info, err := s.tokenValidator.ValidateToken(r.Context(), token, s.authConfig.RequiredAudiences) if err != nil { log.Warnf("OAuth token validation failed for %s: %v", r.URL.Path, err) http.Error(w, "Invalid OAuth token", http.StatusUnauthorized) return } - log.Debugf("OAuth token validated successfully for %s", r.URL.Path) + log.Debugf("OAuth token validated for %s (user=%s)", r.URL.Path, info.Username) } - // Call the next handler next.ServeHTTP(w, r) }) } diff --git a/v2/routes.go b/v2/routes.go index d8ad388..bd4d141 100644 --- a/v2/routes.go +++ b/v2/routes.go @@ -78,6 +78,11 @@ func (s *Server) createSubscription(w http.ResponseWriter, r *http.Request) { localmetrics.UpdateSubscriptionCount(localmetrics.FAILCREATE, 1) return } + if err = validateEndpointURI(endPointURI); err != nil { + respondWithStatusCode(w, http.StatusBadRequest, err.Error()) + localmetrics.UpdateSubscriptionCount(localmetrics.FAILCREATE, 1) + return + } for id, address := range s.subscriberAPI.GetClientIDAddressByResource(sub.GetResource()) { if address.String() == endPointURI { respondWithStatusCode(w, http.StatusConflict, @@ -199,6 +204,11 @@ func (s *Server) createPublisher(w http.ResponseWriter, r *http.Request) { return } if pub.GetEndpointURI() != "" { + if err = validateEndpointURI(pub.GetEndpointURI()); err != nil { + localmetrics.UpdatePublisherCount(localmetrics.FAILCREATE, 1) + respondWithError(w, err.Error()) + return + } response, err = s.HTTPClient.Post(pub.GetEndpointURI(), cloudevents.ApplicationJSON, nil) if err != nil { log.Infof("there was an error validating the publisher endpointurl %v, publisher won't be created.", err) diff --git a/v2/server.go b/v2/server.go index 6b6b2bb..692c342 100644 --- a/v2/server.go +++ b/v2/server.go @@ -88,15 +88,19 @@ type AuthConfig struct { 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 + // OAuth 2.0 / bearer-token configuration. Tokens are validated by the + // TokenValidator installed via Server.SetTokenValidator (cloud-event-proxy + // uses the Kubernetes TokenReview API), so no issuer/JWKS is configured here. EnableOAuth bool `json:"enableOAuth"` - 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) + RequiredAudiences []string `json:"requiredAudiences"` // Required token audiences (validated by TokenReview) + ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount used by clients for authentication + ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path (client side) + UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Client hint: obtain tokens from OpenShift OAuth + + // TLS profile - centrally managed by the cluster's TLSSecurityProfile and + // propagated by the operator. Nothing is hardcoded in this library. + TLSMinVersion string `json:"tlsMinVersion"` // e.g. "VersionTLS12", "VersionTLS13" + TLSCipherSuites []string `json:"tlsCipherSuites"` // IANA cipher suite names } // LoadAuthConfig loads authentication configuration from a JSON file @@ -130,14 +134,15 @@ func (c *AuthConfig) GetConfigSummary() string { } 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(" Required Audiences: %v\n", c.RequiredAudiences) summary += fmt.Sprintf(" Service Account Name: %s\n", c.ServiceAccountName) summary += fmt.Sprintf(" Service Account Token Path: %s\n", c.ServiceAccountToken) summary += fmt.Sprintf(" Use OpenShift OAuth: %t\n", c.UseOpenShiftOAuth) } + if c.TLSMinVersion != "" || len(c.TLSCipherSuites) > 0 { + summary += fmt.Sprintf(" TLS Min Version: %s\n", c.TLSMinVersion) + summary += fmt.Sprintf(" TLS Cipher Suites: %v\n", c.TLSCipherSuites) + } return summary } @@ -158,6 +163,7 @@ type Server struct { statusLock sync.RWMutex authConfig *AuthConfig caCertPool *x509.CertPool + tokenValidator TokenValidator } // SubscriptionInfo @@ -299,19 +305,30 @@ func InitServer(port int, apiHost, apiPath, storePath string, authConfig: authConfig, } - // Configure HTTPClient with proper TLS settings for publisher endpoint validation + // Initialize the mTLS CA certificate pool first so the HTTPClient below + // can verify endpoint certificates against it. + if authConfig != nil && authConfig.EnableMTLS && authConfig.CACertPath != "" { + if err := ServerInstance.initMTLSCACertPool(); err != nil { + log.Errorf("failed to initialize mTLS CA certificate pool: %v", err) + } + } + + // Configure HTTPClient used to validate publisher endpoints. When mTLS + // is enabled we verify the endpoint's server certificate against the CA + // pool (Service CA) rather than skipping verification. if authConfig != nil && authConfig.EnableMTLS { - // Create HTTPClient with TLS configuration that allows localhost connections + tlsClientConfig := &tls.Config{ + RootCAs: ServerInstance.caCertPool, + } + authConfig.applyTLSProfile(tlsClientConfig) ServerInstance.HTTPClient = &http.Client{ Transport: &http.Transport{ MaxIdleConnsPerHost: 20, - TLSClientConfig: &tls.Config{ - InsecureSkipVerify: true, // nolint:gosec // Required for localhost connections in mTLS setup - }, + TLSClientConfig: tlsClientConfig, }, Timeout: 10 * time.Second, } - log.Infof("InitServer: Configured HTTPClient with InsecureSkipVerify for mTLS localhost connections") + log.Info("InitServer: configured HTTPClient with CA verification for mTLS endpoint validation") } else { // Use default HTTP client for non-mTLS configurations ServerInstance.HTTPClient = &http.Client{ @@ -321,16 +338,6 @@ func InitServer(port int, apiHost, apiPath, storePath string, 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 return ServerInstance @@ -494,7 +501,7 @@ func (s *Server) Start() { // "$ref": "#/responses/subscriptions" // "400": // description: Bad request by the client. - api.Handle("/subscriptions", applyAuth(s.getSubscriptions, false)).Methods(http.MethodGet) + api.Handle("/subscriptions", applyAuth(s.getSubscriptions, true)).Methods(http.MethodGet) // swagger:operation GET /subscriptions/{subscriptionId} Subscriptions getSubscriptionByID // --- @@ -505,7 +512,7 @@ func (s *Server) Start() { // "$ref": "#/responses/subscription" // "404": // description: Not Found. Subscription resources are not available (not created). - api.Handle("/subscriptions/{subscriptionId}", applyAuth(s.getSubscriptionByID, false)).Methods(http.MethodGet) + api.Handle("/subscriptions/{subscriptionId}", applyAuth(s.getSubscriptionByID, true)).Methods(http.MethodGet) // swagger:operation DELETE /subscriptions/{subscriptionId} Subscriptions deleteSubscription // --- @@ -529,7 +536,7 @@ func (s *Server) Start() { // "$ref": "#/responses/eventResp" // "404": // description: Not Found. Event notification resource is not available on this node. - api.Handle("/{resourceAddress:.*}/CurrentState", applyAuth(s.getCurrentState, false)).Methods(http.MethodGet) + api.Handle("/{resourceAddress:.*}/CurrentState", applyAuth(s.getCurrentState, true)).Methods(http.MethodGet) // *** Extensions to O-RAN API *** @@ -556,7 +563,7 @@ func (s *Server) Start() { // "$ref": "#/responses/publishers" // "404": // description: Publishers not found - api.Handle("/publishers", applyAuth(s.getPublishers, false)).Methods(http.MethodGet) + api.Handle("/publishers", applyAuth(s.getPublishers, true)).Methods(http.MethodGet) // swagger:operation DELETE /subscriptions Subscriptions deleteAllSubscriptions // --- @@ -571,7 +578,7 @@ func (s *Server) Start() { // *** Internal API *** - api.Handle("/publishers/{publisherid}", applyAuth(s.getPublisherByID, false)).Methods(http.MethodGet) + api.Handle("/publishers/{publisherid}", applyAuth(s.getPublisherByID, true)).Methods(http.MethodGet) api.Handle("/publishers/{publisherid}", applyAuth(s.deletePublisher, true)).Methods(http.MethodDelete) api.Handle("/publishers", applyAuth(s.deleteAllPublishers, true)).Methods(http.MethodDelete) @@ -679,14 +686,18 @@ func (s *Server) Start() { return } - // Configure TLS to request client certificates but not require them - // We'll handle certificate validation at the application level + // VerifyClientCertIfGiven lets loopback clients connect without a + // certificate (trusted same-pod fast-path) while cryptographically + // verifying any certificate that IS presented against the CA pool. + // The middleware then requires a verified certificate for all + // non-loopback (FQDN/service-DNS/external) requests. tlsConfig := &tls.Config{ Certificates: []tls.Certificate{cert}, - ClientAuth: tls.RequestClientCert, // Request but don't require + ClientAuth: tls.VerifyClientCertIfGiven, ClientCAs: s.caCertPool, - MinVersion: tls.VersionTLS12, } + // Apply the centrally-managed TLS profile (min version + ciphers). + s.authConfig.applyTLSProfile(tlsConfig) s.httpServer.TLSConfig = tlsConfig diff --git a/vendor/github.com/golang-jwt/jwt/v5/.gitignore b/vendor/github.com/golang-jwt/jwt/v5/.gitignore deleted file mode 100644 index 09573e0..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -.DS_Store -bin -.idea/ - diff --git a/vendor/github.com/golang-jwt/jwt/v5/LICENSE b/vendor/github.com/golang-jwt/jwt/v5/LICENSE deleted file mode 100644 index 35dbc25..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/LICENSE +++ /dev/null @@ -1,9 +0,0 @@ -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 deleted file mode 100644 index b3178e7..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/MIGRATION_GUIDE.md +++ /dev/null @@ -1,195 +0,0 @@ -# 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 deleted file mode 100644 index 0bb636f..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/README.md +++ /dev/null @@ -1,167 +0,0 @@ -# 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 deleted file mode 100644 index 2740597..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/SECURITY.md +++ /dev/null @@ -1,19 +0,0 @@ -# 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 deleted file mode 100644 index b5039e4..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/VERSION_HISTORY.md +++ /dev/null @@ -1,137 +0,0 @@ -# `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 deleted file mode 100644 index d50ff3d..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/claims.go +++ /dev/null @@ -1,16 +0,0 @@ -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 deleted file mode 100644 index a86dc1a..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/doc.go +++ /dev/null @@ -1,4 +0,0 @@ -// 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 deleted file mode 100644 index 06cd94d..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/ecdsa.go +++ /dev/null @@ -1,134 +0,0 @@ -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 deleted file mode 100644 index 44a3b7a..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/ecdsa_utils.go +++ /dev/null @@ -1,69 +0,0 @@ -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 deleted file mode 100644 index 4159e57..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/ed25519.go +++ /dev/null @@ -1,79 +0,0 @@ -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 deleted file mode 100644 index 6f46e88..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/ed25519_utils.go +++ /dev/null @@ -1,64 +0,0 @@ -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 deleted file mode 100644 index 14e0075..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/errors.go +++ /dev/null @@ -1,89 +0,0 @@ -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 deleted file mode 100644 index 1bef138..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/hmac.go +++ /dev/null @@ -1,104 +0,0 @@ -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 deleted file mode 100644 index 3b92052..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/map_claims.go +++ /dev/null @@ -1,109 +0,0 @@ -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 deleted file mode 100644 index 624ad55..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/none.go +++ /dev/null @@ -1,50 +0,0 @@ -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 deleted file mode 100644 index 054c7eb..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/parser.go +++ /dev/null @@ -1,268 +0,0 @@ -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 deleted file mode 100644 index 4315735..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/parser_option.go +++ /dev/null @@ -1,145 +0,0 @@ -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 deleted file mode 100644 index 77951a5..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/registered_claims.go +++ /dev/null @@ -1,63 +0,0 @@ -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 deleted file mode 100644 index 98b960a..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/rsa.go +++ /dev/null @@ -1,93 +0,0 @@ -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 deleted file mode 100644 index f17590c..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/rsa_pss.go +++ /dev/null @@ -1,132 +0,0 @@ -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 deleted file mode 100644 index f22c3d0..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/rsa_utils.go +++ /dev/null @@ -1,107 +0,0 @@ -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 deleted file mode 100644 index 096d0ed..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/signing_method.go +++ /dev/null @@ -1,49 +0,0 @@ -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 deleted file mode 100644 index 53745d5..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/staticcheck.conf +++ /dev/null @@ -1 +0,0 @@ -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 deleted file mode 100644 index 3f71558..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/token.go +++ /dev/null @@ -1,100 +0,0 @@ -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 deleted file mode 100644 index b4ae3ba..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/token_option.go +++ /dev/null @@ -1,5 +0,0 @@ -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 deleted file mode 100644 index a3e0ef1..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/types.go +++ /dev/null @@ -1,149 +0,0 @@ -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 deleted file mode 100644 index 92b5c05..0000000 --- a/vendor/github.com/golang-jwt/jwt/v5/validator.go +++ /dev/null @@ -1,326 +0,0 @@ -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 c3f1ccd..f4bb954 100644 --- a/vendor/modules.txt +++ b/vendor/modules.txt @@ -26,9 +26,6 @@ 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 6aaccdbd1f770197ec6cf4f9e457e9a02bd707fa Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 9 Sep 2026 18:34:10 -0400 Subject: [PATCH 08/15] Export ApplyTLSProfile for client-side TLS profile reuse Rename applyTLSProfile to ApplyTLSProfile so cloud-event-proxy's client config can apply the same centrally-managed TLS profile (min version and cipher suites) when building its mTLS client, keeping server and client TLS policy consistent per CNF-21982. Co-Authored-By: Claude Opus 4.8 Signed-off-by: Jack Ding --- v2/auth.go | 4 ++-- v2/server.go | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/v2/auth.go b/v2/auth.go index 7f1af51..74641e2 100644 --- a/v2/auth.go +++ b/v2/auth.go @@ -162,12 +162,12 @@ func cipherSuitesFromNames(names []string) []uint16 { return out } -// applyTLSProfile applies the centrally-managed TLS profile (min version and +// ApplyTLSProfile applies the centrally-managed TLS profile (min version and // cipher suites, sourced from the cluster's TLSSecurityProfile via the // operator) onto a tls.Config. Nothing is hardcoded here: values come from the // AuthConfig. Only when no min version is supplied at all do we fall back to // TLS 1.2 to avoid negotiating an insecure protocol by default. -func (c *AuthConfig) applyTLSProfile(cfg *tls.Config) { +func (c *AuthConfig) ApplyTLSProfile(cfg *tls.Config) { if c == nil { return } diff --git a/v2/server.go b/v2/server.go index 692c342..2e108e2 100644 --- a/v2/server.go +++ b/v2/server.go @@ -320,7 +320,7 @@ func InitServer(port int, apiHost, apiPath, storePath string, tlsClientConfig := &tls.Config{ RootCAs: ServerInstance.caCertPool, } - authConfig.applyTLSProfile(tlsClientConfig) + authConfig.ApplyTLSProfile(tlsClientConfig) ServerInstance.HTTPClient = &http.Client{ Transport: &http.Transport{ MaxIdleConnsPerHost: 20, @@ -697,7 +697,7 @@ func (s *Server) Start() { ClientCAs: s.caCertPool, } // Apply the centrally-managed TLS profile (min version + ciphers). - s.authConfig.applyTLSProfile(tlsConfig) + s.authConfig.ApplyTLSProfile(tlsConfig) s.httpServer.TLSConfig = tlsConfig From 7f73e7bd6710ece78018b78b3c00449841e0e2cf Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 9 Sep 2026 19:36:13 -0400 Subject: [PATCH 09/15] Fix gosec G402 and harden endpoint SSRF at dial time - Set an explicit TLS 1.2 floor on the endpoint-validation client and the mTLS listener config so gosec G402 is satisfied; ApplyTLSProfile still raises MinVersion to the cluster-configured floor. - Add isBlockedDialIP + newSafeDialContext: resolve the callback host and reject link-local, cloud-metadata, multicast and unspecified addresses before connecting (dialing the resolved IP closes the DNS-rebinding window). RFC1918/ULA and loopback stay allowed since consumers run as cluster Pods and RHT-0003 permits in-pod localhost callbacks. - Refuse to follow redirects during endpoint validation (CheckRedirect). - Add internal tests for the SSRF policy, loopback detection and TLS profile application. Addresses CodeRabbit review on #112. Co-Authored-By: Claude Opus 4.8 Signed-off-by: Jack Ding --- v2/107b70e2-ac1c-3977-9cda-f513908623c0.json | 16 +++ v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json | 16 +++ v2/auth.go | 69 +++++++++-- v2/auth_internal_test.go | 124 +++++++++++++++++++ v2/server.go | 19 ++- 5 files changed, 234 insertions(+), 10 deletions(-) create mode 100644 v2/107b70e2-ac1c-3977-9cda-f513908623c0.json create mode 100644 v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json create mode 100644 v2/auth_internal_test.go diff --git a/v2/107b70e2-ac1c-3977-9cda-f513908623c0.json b/v2/107b70e2-ac1c-3977-9cda-f513908623c0.json new file mode 100644 index 0000000..9c12310 --- /dev/null +++ b/v2/107b70e2-ac1c-3977-9cda-f513908623c0.json @@ -0,0 +1,16 @@ +{ + "clientID": "107b70e2-ac1c-3977-9cda-f513908623c0", + "subStore": { + "store": { + "cdc51d4f-6256-49aa-97c6-e378f5c7ff4a": { + "ResourceAddress": "/east-edge-10/Node3/sync/sync-status/sync-state", + "EndpointUri": "http://localhost:8990/api/ocloudNotifications/v2/dummy", + "SubscriptionId": "cdc51d4f-6256-49aa-97c6-e378f5c7ff4a", + "UriLocation": "http://localhost:8990/api/ocloudNotifications/v2/subscriptions/cdc51d4f-6256-49aa-97c6-e378f5c7ff4a" + } + } + }, + "EndpointUri": "http://localhost:8990/api/ocloudNotifications/v2/dummy", + "status": 1, + "action": 0 +} \ No newline at end of file diff --git a/v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json b/v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json new file mode 100644 index 0000000..e33650d --- /dev/null +++ b/v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json @@ -0,0 +1,16 @@ +{ + "clientID": "a6c814a2-2dc7-38de-8e4c-28c1745b82f4", + "subStore": { + "store": { + "4166b981-68dc-4dc6-87c5-99c84d550347": { + "ResourceAddress": "/east-edge-10/Node3/sync/sync-status/sync-state", + "EndpointUri": "http://localhost:8990/api/ocloudNotifications/v2/dummy2", + "SubscriptionId": "4166b981-68dc-4dc6-87c5-99c84d550347", + "UriLocation": "http://localhost:8990/api/ocloudNotifications/v2/subscriptions/4166b981-68dc-4dc6-87c5-99c84d550347" + } + } + }, + "EndpointUri": "http://localhost:8990/api/ocloudNotifications/v2/dummy2", + "status": 1, + "action": 0 +} \ No newline at end of file diff --git a/v2/auth.go b/v2/auth.go index 74641e2..79667dc 100644 --- a/v2/auth.go +++ b/v2/auth.go @@ -111,17 +111,72 @@ func validateEndpointURI(raw string) error { if host == "" { return fmt.Errorf("EndpointUri host is empty") } - if ip := net.ParseIP(host); ip != nil { - switch { - case ip.IsLinkLocalUnicast(), ip.IsLinkLocalMulticast(), ip.IsMulticast(), ip.IsUnspecified(): - return fmt.Errorf("EndpointUri host %q is not an allowed address", host) - case ip.Equal(net.ParseIP("169.254.169.254")): - return fmt.Errorf("EndpointUri host %q (cloud metadata) is not allowed", host) - } + if ip := net.ParseIP(host); ip != nil && isBlockedDialIP(ip) { + return fmt.Errorf("EndpointUri host %q is not an allowed address", host) } return nil } +// isBlockedDialIP reports whether an IP is disallowed as an outbound +// destination. Loopback and private (RFC1918 / IPv6 ULA) addresses are +// permitted on purpose: per O-RAN RHT-0003 callbacks may be in-pod (localhost) +// and event consumers routinely run as cluster Pods with private IPs. Only +// link-local, multicast, unspecified and cloud-metadata addresses are blocked. +func isBlockedDialIP(ip net.IP) bool { + if ip == nil { + return true + } + if ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() || ip.IsMulticast() || ip.IsUnspecified() { + return true + } + // Cloud instance-metadata endpoints (IPv4 IMDS is already link-local; the + // IPv6 variant is unique-local so must be listed explicitly). + if ip.Equal(net.ParseIP("169.254.169.254")) || ip.Equal(net.ParseIP("fd00:ec2::254")) { + return true + } + return false +} + +// newSafeDialContext returns a DialContext that resolves the target host and +// rejects the connection if any resolved address is blocked, then dials the +// resolved IP directly. Dialing the already-resolved address (rather than the +// hostname) closes the DNS-rebinding TOCTOU window between validation and +// connection. +func newSafeDialContext(base *net.Dialer) func(ctx context.Context, network, addr string) (net.Conn, error) { + return func(ctx context.Context, network, addr string) (net.Conn, error) { + host, port, err := net.SplitHostPort(addr) + if err != nil { + return nil, err + } + ips, err := net.DefaultResolver.LookupIPAddr(ctx, host) + if err != nil { + return nil, err + } + for _, ipa := range ips { + if isBlockedDialIP(ipa.IP) { + return nil, fmt.Errorf("refusing to connect to blocked address %s (resolved from %q)", ipa.IP, host) + } + } + var firstErr error + for _, ipa := range ips { + conn, derr := base.DialContext(ctx, network, net.JoinHostPort(ipa.IP.String(), port)) + if derr == nil { + return conn, nil + } + firstErr = derr + } + return nil, firstErr + } +} + +// noRedirectPolicy prevents the endpoint-validation client from following +// redirects, which could otherwise be used to reach a blocked address after the +// initial destination passed validation. The 3xx response itself is returned to +// the caller unfollowed. +func noRedirectPolicy(_ *http.Request, _ []*http.Request) error { + return http.ErrUseLastResponse +} + // tlsVersionFromString maps a TLS version name (as used by the OpenShift // TLSSecurityProfile / crypto/tls) to its constant. Returns 0 when unknown. func tlsVersionFromString(v string) uint16 { diff --git a/v2/auth_internal_test.go b/v2/auth_internal_test.go new file mode 100644 index 0000000..1e892ee --- /dev/null +++ b/v2/auth_internal_test.go @@ -0,0 +1,124 @@ +// Copyright 2025 The Cloud Native Events Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package restapi + +import ( + "crypto/tls" + "net" + "testing" +) + +func TestIsBlockedDialIP(t *testing.T) { + cases := []struct { + ip string + blocked bool + }{ + // Allowed: loopback (RHT-0003 in-pod) and private (cluster Pod IPs). + {"127.0.0.1", false}, + {"::1", false}, + {"10.0.0.5", false}, + {"172.16.3.4", false}, + {"192.168.1.10", false}, + {"fd12:3456::1", false}, + {"93.184.216.34", false}, // public + // Blocked: link-local, cloud metadata, multicast, unspecified. + {"169.254.0.1", true}, + {"169.254.169.254", true}, + {"fe80::1", true}, + {"fd00:ec2::254", true}, + {"224.0.0.1", true}, + {"0.0.0.0", true}, + {"::", true}, + } + for _, c := range cases { + ip := net.ParseIP(c.ip) + if ip == nil { + t.Fatalf("bad test IP %q", c.ip) + } + if got := isBlockedDialIP(ip); got != c.blocked { + t.Errorf("isBlockedDialIP(%s) = %v, want %v", c.ip, got, c.blocked) + } + } + if !isBlockedDialIP(nil) { + t.Errorf("isBlockedDialIP(nil) should be blocked") + } +} + +func TestValidateEndpointURI(t *testing.T) { + valid := []string{ + "http://localhost:8080/event", + "https://consumer.ptp.svc.cluster.local:9043/ack", + "http://10.128.0.9:8080/callback", + } + for _, u := range valid { + if err := validateEndpointURI(u); err != nil { + t.Errorf("validateEndpointURI(%q) = %v, want nil", u, err) + } + } + invalid := []string{ + "ftp://host/x", // bad scheme + "http://", // empty host + "://nope", // unparseable scheme + "http://169.254.169.254/latest", // metadata + "http://[fe80::1]/x", // link-local + "http://224.0.0.1/x", // multicast + "http://0.0.0.0/x", // unspecified + } + for _, u := range invalid { + if err := validateEndpointURI(u); err == nil { + t.Errorf("validateEndpointURI(%q) = nil, want error", u) + } + } +} + +func TestIsLoopbackRemoteAddr(t *testing.T) { + yes := []string{"127.0.0.1:5000", "[::1]:5000", "localhost:5000", "127.0.0.1"} + no := []string{"", "10.0.0.1:5000", "192.168.1.1:80", "example.com:80"} + for _, a := range yes { + if !isLoopbackRemoteAddr(a) { + t.Errorf("isLoopbackRemoteAddr(%q) = false, want true", a) + } + } + for _, a := range no { + if isLoopbackRemoteAddr(a) { + t.Errorf("isLoopbackRemoteAddr(%q) = true, want false", a) + } + } +} + +func TestApplyTLSProfile(t *testing.T) { + // Explicit profile is applied verbatim. + c := &AuthConfig{ + TLSMinVersion: "VersionTLS13", + TLSCipherSuites: []string{"TLS_AES_128_GCM_SHA256", "bogus-name"}, + } + cfg := &tls.Config{} + c.ApplyTLSProfile(cfg) + if cfg.MinVersion != tls.VersionTLS13 { + t.Errorf("MinVersion = %x, want TLS13", cfg.MinVersion) + } + + // No profile => default floor of TLS 1.2, existing MinVersion preserved. + empty := &AuthConfig{} + cfg2 := &tls.Config{} + empty.ApplyTLSProfile(cfg2) + if cfg2.MinVersion != tls.VersionTLS12 { + t.Errorf("default MinVersion = %x, want TLS12", cfg2.MinVersion) + } + + // Nil receiver must not panic. + var nilCfg *AuthConfig + nilCfg.ApplyTLSProfile(&tls.Config{}) +} diff --git a/v2/server.go b/v2/server.go index 2e108e2..ba2148b 100644 --- a/v2/server.go +++ b/v2/server.go @@ -52,6 +52,7 @@ import ( "crypto/tls" "crypto/x509" "io" + "net" "net/http" "strings" "time" @@ -316,17 +317,25 @@ func InitServer(port int, apiHost, apiPath, storePath string, // Configure HTTPClient used to validate publisher endpoints. When mTLS // is enabled we verify the endpoint's server certificate against the CA // pool (Service CA) rather than skipping verification. + // A shared dialer whose DialContext resolves the target and rejects + // blocked (link-local / metadata / multicast) addresses before + // connecting, closing the SSRF DNS-rebinding window for endpoint checks. + safeDial := newSafeDialContext(&net.Dialer{Timeout: 10 * time.Second}) if authConfig != nil && authConfig.EnableMTLS { tlsClientConfig := &tls.Config{ - RootCAs: ServerInstance.caCertPool, + RootCAs: ServerInstance.caCertPool, + MinVersion: tls.VersionTLS12, } + // ApplyTLSProfile may raise MinVersion to the cluster-configured floor. authConfig.ApplyTLSProfile(tlsClientConfig) ServerInstance.HTTPClient = &http.Client{ Transport: &http.Transport{ MaxIdleConnsPerHost: 20, TLSClientConfig: tlsClientConfig, + DialContext: safeDial, }, - Timeout: 10 * time.Second, + Timeout: 10 * time.Second, + CheckRedirect: noRedirectPolicy, } log.Info("InitServer: configured HTTPClient with CA verification for mTLS endpoint validation") } else { @@ -334,8 +343,10 @@ func InitServer(port int, apiHost, apiPath, storePath string, ServerInstance.HTTPClient = &http.Client{ Transport: &http.Transport{ MaxIdleConnsPerHost: 20, + DialContext: safeDial, }, - Timeout: 10 * time.Second, + Timeout: 10 * time.Second, + CheckRedirect: noRedirectPolicy, } } }) @@ -695,8 +706,10 @@ func (s *Server) Start() { Certificates: []tls.Certificate{cert}, ClientAuth: tls.VerifyClientCertIfGiven, ClientCAs: s.caCertPool, + MinVersion: tls.VersionTLS12, } // Apply the centrally-managed TLS profile (min version + ciphers). + // A configured profile may raise MinVersion above the TLS 1.2 floor. s.authConfig.ApplyTLSProfile(tlsConfig) s.httpServer.TLSConfig = tlsConfig From 65ede7d57149ac4ed0633ae7e61b3ff64bbaef2b Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 9 Sep 2026 20:09:27 -0400 Subject: [PATCH 10/15] test: fix gosec G402 lint and remove committed store artifacts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add //nolint:gosec directives to TestApplyTLSProfile: the empty tls.Config literals are intentional — the test verifies that ApplyTLSProfile sets the MinVersion floor. - Remove two per-clientID subscription store JSON files that were accidentally committed; in CI they pre-seed the store and cause CreateSubscription tests to fail with "already exists" / empty body. - Gitignore UUID-named store files (storePath ".") so test runs can't re-commit them. Co-Authored-By: Claude Opus 4.8 Signed-off-by: Jack Ding --- .gitignore | 2 ++ v2/107b70e2-ac1c-3977-9cda-f513908623c0.json | 16 ---------------- v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json | 16 ---------------- v2/auth_internal_test.go | 6 +++--- 4 files changed, 5 insertions(+), 35 deletions(-) delete mode 100644 v2/107b70e2-ac1c-3977-9cda-f513908623c0.json delete mode 100644 v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json diff --git a/.gitignore b/.gitignore index 4cf204b..32add9a 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,8 @@ cover.out pub.json sub.json +# Per-clientID subscription store files written by tests (storePath ".") +v2/????????-????-????-????-????????????.json .idea .cache diff --git a/v2/107b70e2-ac1c-3977-9cda-f513908623c0.json b/v2/107b70e2-ac1c-3977-9cda-f513908623c0.json deleted file mode 100644 index 9c12310..0000000 --- a/v2/107b70e2-ac1c-3977-9cda-f513908623c0.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "clientID": "107b70e2-ac1c-3977-9cda-f513908623c0", - "subStore": { - "store": { - "cdc51d4f-6256-49aa-97c6-e378f5c7ff4a": { - "ResourceAddress": "/east-edge-10/Node3/sync/sync-status/sync-state", - "EndpointUri": "http://localhost:8990/api/ocloudNotifications/v2/dummy", - "SubscriptionId": "cdc51d4f-6256-49aa-97c6-e378f5c7ff4a", - "UriLocation": "http://localhost:8990/api/ocloudNotifications/v2/subscriptions/cdc51d4f-6256-49aa-97c6-e378f5c7ff4a" - } - } - }, - "EndpointUri": "http://localhost:8990/api/ocloudNotifications/v2/dummy", - "status": 1, - "action": 0 -} \ No newline at end of file diff --git a/v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json b/v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json deleted file mode 100644 index e33650d..0000000 --- a/v2/a6c814a2-2dc7-38de-8e4c-28c1745b82f4.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "clientID": "a6c814a2-2dc7-38de-8e4c-28c1745b82f4", - "subStore": { - "store": { - "4166b981-68dc-4dc6-87c5-99c84d550347": { - "ResourceAddress": "/east-edge-10/Node3/sync/sync-status/sync-state", - "EndpointUri": "http://localhost:8990/api/ocloudNotifications/v2/dummy2", - "SubscriptionId": "4166b981-68dc-4dc6-87c5-99c84d550347", - "UriLocation": "http://localhost:8990/api/ocloudNotifications/v2/subscriptions/4166b981-68dc-4dc6-87c5-99c84d550347" - } - } - }, - "EndpointUri": "http://localhost:8990/api/ocloudNotifications/v2/dummy2", - "status": 1, - "action": 0 -} \ No newline at end of file diff --git a/v2/auth_internal_test.go b/v2/auth_internal_test.go index 1e892ee..ef3a196 100644 --- a/v2/auth_internal_test.go +++ b/v2/auth_internal_test.go @@ -104,7 +104,7 @@ func TestApplyTLSProfile(t *testing.T) { TLSMinVersion: "VersionTLS13", TLSCipherSuites: []string{"TLS_AES_128_GCM_SHA256", "bogus-name"}, } - cfg := &tls.Config{} + cfg := &tls.Config{} //nolint:gosec // MinVersion set by ApplyTLSProfile under test c.ApplyTLSProfile(cfg) if cfg.MinVersion != tls.VersionTLS13 { t.Errorf("MinVersion = %x, want TLS13", cfg.MinVersion) @@ -112,7 +112,7 @@ func TestApplyTLSProfile(t *testing.T) { // No profile => default floor of TLS 1.2, existing MinVersion preserved. empty := &AuthConfig{} - cfg2 := &tls.Config{} + cfg2 := &tls.Config{} //nolint:gosec // MinVersion set by ApplyTLSProfile under test empty.ApplyTLSProfile(cfg2) if cfg2.MinVersion != tls.VersionTLS12 { t.Errorf("default MinVersion = %x, want TLS12", cfg2.MinVersion) @@ -120,5 +120,5 @@ func TestApplyTLSProfile(t *testing.T) { // Nil receiver must not panic. var nilCfg *AuthConfig - nilCfg.ApplyTLSProfile(&tls.Config{}) + nilCfg.ApplyTLSProfile(&tls.Config{}) //nolint:gosec // nil-receiver no-op path under test } From 6fe1192d1b296263b07a936163cf7a0a003d32a9 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 9 Sep 2026 20:17:45 -0400 Subject: [PATCH 11/15] test: fix double-slash CurrentState URLs breaking with no-redirect client The GetCurrentState tests reuse the server's outbound endpoint-validation HTTPClient, which now enforces a no-redirect policy (SSRF safeguard). Those tests built the request URL as apPath + "/"-prefixed resource, yielding a double slash (".../v2//east-edge-...") that gorilla/mux answers with a 301 to the cleaned path. The old default client silently followed the redirect; the hardened client returns the 301 unfollowed, so the tests saw an empty body / wrong status. Strip the leading slash so the URL is well-formed (single slash) and the request reaches the handler directly, as a real O-RAN consumer would. No production behavior change; the SSRF no-redirect safeguard stays intact. Co-Authored-By: Claude Opus 4.8 Signed-off-by: Jack Ding --- v2/server_test.go | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/v2/server_test.go b/v2/server_test.go index 6289344..74a8ad3 100644 --- a/v2/server_test.go +++ b/v2/server_test.go @@ -22,6 +22,7 @@ import ( "net/http" "net/url" "os" + "strings" "sync" "testing" "time" @@ -483,7 +484,7 @@ func TestServer_CreatePublisher(t *testing.T) { // 5.3.6.5 (1) Expected results: The return code is “200 OK”. func TestServer_GetCurrentState_OK(t *testing.T) { ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -511,7 +512,7 @@ func TestServer_GetCurrentState_KO_ResourceInvalid(t *testing.T) { // try getting event time.Sleep(2 * time.Second) - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, resourceInvalid, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(resourceInvalid, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -543,7 +544,7 @@ func onReceiveOverrideFnEmptyEventData(e cloudevents.Event, d *channel.DataChan) func TestServer_GetCurrentState_KO_EmptyEventData(t *testing.T) { server.SetOnStatusReceiveOverrideFn(onReceiveOverrideFnEmptyEventData) ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -579,7 +580,7 @@ func onReceiveOverrideFnInvalidEventData(e cloudevents.Event, d *channel.DataCha func TestServer_GetCurrentState_KO_InvalidEventData(t *testing.T) { server.SetOnStatusReceiveOverrideFn(onReceiveOverrideFnInvalidEventData) ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -614,7 +615,7 @@ func onReceiveOverrideFnEventNotFound(e cloudevents.Event, d *channel.DataChan) func TestServer_GetCurrentState_KO_EventNotFound(t *testing.T) { server.SetOnStatusReceiveOverrideFn(onReceiveOverrideFnEventNotFound) ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) @@ -650,7 +651,7 @@ func onReceiveOverrideFnPTPNotSet(e cloudevents.Event, d *channel.DataChan) erro func TestServer_GetCurrentState_KO_PTPNotSet(t *testing.T) { server.SetOnStatusReceiveOverrideFn(onReceiveOverrideFnPTPNotSet) ctx := context.Background() - req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, ObjSub.Resource, "CurrentState"), nil) + req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("http://localhost:%d%s%s/%s", port, apPath, strings.TrimPrefix(ObjSub.Resource, "/"), "CurrentState"), nil) assert.Nil(t, err) req.Header.Set("Content-Type", "application/json") resp, err := server.HTTPClient.Do(req) From ac22e28041a0011a4211c52a125c63cdf119aa9f Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Wed, 9 Sep 2026 21:04:20 -0400 Subject: [PATCH 12/15] Address PR #113 review: SSRF-harden initial POST, fail-closed CA, doc/swagger fixes Security and documentation fixes from CodeRabbit review on redhat-cne/rest-api#113: - routes.go: route the subscription initial-notification POST through the server's SSRF-hardened HTTPClient (resolve-then-validate dialer + no-redirect policy) via new restclient.NewWithClient, instead of the default client which follows redirects and dials arbitrary resolved addresses. restclient.New is left unchanged. - server.go: fail closed when mTLS is enabled but the CA certificate pool cannot be initialized (missing/invalid CACertPath) - Start() now refuses to serve TLS with a nil pool rather than continuing with unverifiable client certs. - swagger.json: schemes https-only; replace the misleading basic-auth security definition with an apiKey Bearer definition (Authorization header) noting mTLS is also required; add security + 401 to all protected GET operations. - AUTHENTICATION.md / OPENSHIFT_AUTHENTICATION.md / README.md: replace obsolete OAuth fields (oauthIssuer/oauthJWKSURL/requiredScopes/requiredAudience) with requiredAudiences and document that token issuer/signature/expiry/audience are validated by the Kubernetes TokenReview API; move the GET routes from "public" to "protected" to match the code. - examples/openshift-manifests.yaml: use requiredAudiences; add a TokenReview ClusterRole + ClusterRoleBinding for the server SA; source the CA bundle from the injected Service CA ConfigMap (service-ca.crt) rather than the serving-cert Secret, consistent with the fail-closed CA behavior. The mTLS ApplyTLSProfile floor and the health-check InsecureSkipVerify are intentionally unchanged (central TLS profile adherence per CNF-21982/21769/22665 and in-pod loopback health checks, respectively). Co-Authored-By: Claude Opus 4.8 Signed-off-by: Jack Ding --- AUTHENTICATION.md | 120 +++++++++++++++--------------- OPENSHIFT_AUTHENTICATION.md | 53 ++++--------- README.md | 12 +-- examples/openshift-manifests.yaml | 55 ++++++++++++-- pkg/restclient/client.go | 12 +++ v2/routes.go | 6 +- v2/server.go | 24 +++++- v2/swagger.json | 61 +++++++++------ 8 files changed, 207 insertions(+), 136 deletions(-) diff --git a/AUTHENTICATION.md b/AUTHENTICATION.md index fd85bb0..14908b7 100644 --- a/AUTHENTICATION.md +++ b/AUTHENTICATION.md @@ -7,37 +7,42 @@ This document describes how to configure mTLS (mutual TLS) and OAuth authenticat The REST API supports two authentication mechanisms that can be applied to specific endpoints: 1. **mTLS (Mutual TLS)**: Client certificate-based authentication using OpenShift Service CA -2. **OAuth**: Bearer token-based authentication using OpenShift's built-in OAuth server and JWT tokens with **strict validation** +2. **OAuth**: Bearer token-based authentication. Tokens are validated server-side via the Kubernetes **TokenReview** API, which verifies the token's issuer, signature, expiry, and audience. The REST API library itself does not parse JWTs or fetch a JWKS; it delegates verification to the cluster and only enforces the required audiences it is configured with. Both mechanisms can be enabled independently or together for enhanced security. This unified approach works seamlessly for both single node and multi-node OpenShift clusters, providing enterprise-grade security with minimal complexity. ### Security Guarantees -- **No Authentication Bypass**: When OAuth is enabled, 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 +- **No Authentication Bypass**: When OAuth is enabled, every non-loopback request must present a valid bearer token +- **Server-side Token Validation**: Issuer, signature, expiry, and audience are all validated by the Kubernetes TokenReview API +- **Audience Binding**: When `requiredAudiences` is configured, the token must be bound to one of those audiences - **Clear Error Messages**: Authentication failures return specific error codes without exposing sensitive information ## Protected vs Public Endpoints ### Protected Endpoints (Require Authentication) -The following endpoints require authentication when enabled: +When authentication is enabled, **every** data endpoint requires authentication for non-loopback requests. Only `GET /health` is exempt. (Requests originating from the pod's own loopback interface are treated as a trusted same-pod fast-path and skip authentication.) #### Subscription Management - `POST /subscriptions` - Create subscription +- `GET /subscriptions` - List all subscriptions +- `GET /subscriptions/{subscriptionId}` - Get subscription details - `DELETE /subscriptions/{subscriptionId}` - Delete specific subscription - `DELETE /subscriptions` - Delete all subscriptions - `PUT /subscriptions/status/{subscriptionId}` - Ping for subscription status #### Publisher Management - `POST /publishers` - Create publisher +- `GET /publishers` - List all publishers +- `GET /publishers/{publisherid}` - Get publisher details - `DELETE /publishers/{publisherid}` - Delete specific publisher - `DELETE /publishers` - Delete all publishers #### Event Management - `POST /create/event` - Publish event - `POST /log` - Log event +- `GET /{ResourceAddress}/CurrentState` - Get current state #### Test Endpoints - `POST /dummy` - Test endpoint @@ -45,14 +50,9 @@ The following endpoints require authentication when enabled: ### Public Endpoints (No Authentication Required) -These endpoints remain accessible without authentication: +Only the health endpoint is reachable 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 +- `GET /health` - Service health check (see the special mTLS behavior below) ### Health Endpoint Behavior @@ -108,15 +108,19 @@ type AuthConfig struct { 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 + // OAuth 2.0 / bearer-token configuration. Tokens are validated by the + // TokenValidator installed via Server.SetTokenValidator (cloud-event-proxy + // uses the Kubernetes TokenReview API), so no issuer/JWKS is configured here. EnableOAuth bool `json:"enableOAuth"` - 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) + RequiredAudiences []string `json:"requiredAudiences"` // Required token audiences (validated by TokenReview) + ServiceAccountName string `json:"serviceAccountName"` // ServiceAccount used by clients for authentication + ServiceAccountToken string `json:"serviceAccountToken"` // ServiceAccount token path (client side) + UseOpenShiftOAuth bool `json:"useOpenShiftOAuth"` // Client hint: obtain tokens from OpenShift OAuth + + // TLS profile - centrally managed by the cluster's TLSSecurityProfile and + // propagated by the operator. Nothing is hardcoded in this library. + TLSMinVersion string `json:"tlsMinVersion"` // e.g. "VersionTLS12", "VersionTLS13" + TLSCipherSuites []string `json:"tlsCipherSuites"` // IANA cipher suite names } ``` @@ -133,15 +137,14 @@ See `openshift-auth-config.json` for a complete configuration example that works "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", + "requiredAudiences": ["https://kubernetes.default.svc"], "serviceAccountName": "cloud-event-proxy-sa", "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" } ``` +> **Note:** There is no `oauthIssuer`, `oauthJWKSURL`, `requiredScopes`, or `requiredAudience` (singular) field. Token issuer, signature, and expiry are validated by the Kubernetes TokenReview API. The only OAuth policy this library enforces locally is `requiredAudiences` (an array): the presented token must be bound to one of the listed audiences. + ## OpenShift Integration ### Service CA (Recommended) @@ -174,20 +177,20 @@ spec: type: ClusterIP ``` -### OpenShift OAuth Server +### OpenShift OAuth / TokenReview -The OAuth implementation uses OpenShift's built-in OAuth server: +The OAuth implementation validates bearer tokens through the Kubernetes TokenReview API: #### Prerequisites - OpenShift cluster (single node or multi-node) -- ServiceAccount with appropriate RBAC permissions +- The server's ServiceAccount must be permitted to create `tokenreviews` (via the `system:auth-delegator` ClusterRole or an equivalent binding) - No additional operators required #### OAuth Configuration -- **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 +- **Token Validation**: The server calls the Kubernetes TokenReview API, which verifies issuer, signature, expiry, and audience server-side +- **ServiceAccount Tokens**: Clients present a projected ServiceAccount token bound to the required audience +- **Audience Binding**: `requiredAudiences` enforces that the token was minted for this service +- **RBAC**: The server SA needs `create` on `authentication.k8s.io/tokenreviews` #### Example ServiceAccount Configuration ```yaml @@ -291,16 +294,21 @@ curl -X DELETE https://localhost:9043/api/ocloudNotifications/v2/publishers/publ -H "Authorization: Bearer valid_your_jwt_token_here" ``` -### Public Endpoint Examples +### Read (GET) Endpoint Examples + +`GET` endpoints are protected too - when authentication is enabled they require the same mTLS client certificate and/or bearer token as the write endpoints. -#### List Subscriptions (no authentication required) +#### List Subscriptions ```bash -# Over HTTPS (when mTLS is enabled) +# With both mTLS and OAuth curl -X GET https://localhost:9043/api/ocloudNotifications/v2/subscriptions \ - --cacert ca.crt + --cert client.crt \ + --key client.key \ + --cacert ca.crt \ + -H "Authorization: Bearer valid_your_token_here" -# Over HTTP (when mTLS is disabled) +# When authentication is disabled (plain HTTP, no auth) curl -X GET http://localhost:9043/api/ocloudNotifications/v2/subscriptions ``` @@ -323,44 +331,40 @@ curl -X GET https://localhost:9043/api/ocloudNotifications/v2/health \ ## OAuth Security Implementation -### Strict Validation Features +### Validation via Kubernetes TokenReview -The OAuth implementation includes comprehensive security measures: +The OAuth implementation delegates all cryptographic token validation to the Kubernetes TokenReview API. The following checks are performed server-side by the cluster: -1. **Issuer 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 +1. **Issuer & Signature Validation**: + - The token's issuer and signature are verified by the cluster; tokens the API server does not recognize are rejected. + - No bypass mechanisms or fallbacks. 2. **Expiration Checking**: ``` Token expired ``` - - Expired tokens are rejected with clear error messages - - Time-based validation prevents replay attacks + - Expired tokens are rejected by TokenReview. 3. **Audience Validation**: ``` Token audience validation failed ``` - - Tokens must contain the required audience claim - - Prevents token misuse across different services + - When `requiredAudiences` is set, the token must be bound to one of those audiences. + - Prevents token misuse across different services. 4. **Missing Token Handling**: ``` Authorization header required Bearer token required ``` - - Clear error messages for missing or malformed tokens - - Proper HTTP status codes (401 Unauthorized) + - Clear error messages for missing or malformed tokens. + - Proper HTTP status codes (401 Unauthorized). -### Security Libraries +### Security Properties -- **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 +- **No local JWT parsing / JWKS fetching**: verification is performed by the Kubernetes API server via TokenReview. +- **Bounded token cache**: validated results are cached briefly with a short TTL to bound TokenReview load. +- **Memory Safety**: tokens are never logged or otherwise exposed. ## Security Considerations @@ -370,10 +374,10 @@ The OAuth implementation includes comprehensive security measures: - Use OpenShift Service CA for automated certificate management 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) + - **Server-side Validation**: All tokens are validated by the Kubernetes TokenReview API (issuer, signature, expiry, audience) + - **No Bypass Mechanisms**: Non-loopback requests without a valid token are rejected with 401 + - **Audience Binding**: Configure `requiredAudiences` so tokens minted for other services are rejected + - A short-TTL cache bounds TokenReview load without weakening validation 3. **TLS Configuration** - Use TLS 1.2 or higher diff --git a/OPENSHIFT_AUTHENTICATION.md b/OPENSHIFT_AUTHENTICATION.md index f0957b5..6751328 100644 --- a/OPENSHIFT_AUTHENTICATION.md +++ b/OPENSHIFT_AUTHENTICATION.md @@ -91,32 +91,16 @@ The same configuration works for both single node and multi-node clusters: "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", + "requiredAudiences": ["https://kubernetes.default.svc"], "serviceAccountName": "cloud-event-proxy-sa", "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" } ``` -### Dynamic Cluster Configuration +### Token Audience Configuration -For environments with multiple clusters or dynamic cluster names, use the `CLUSTER_NAME` environment variable: +Token issuer and JWKS discovery are handled entirely by the Kubernetes TokenReview API, so no cluster-specific OAuth URLs need to be templated. The only OAuth policy configured here is the set of accepted audiences: -#### 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, @@ -126,16 +110,13 @@ export CLUSTER_NAME="cnfdg4.sno.ptp.eng.rdu2.dc.redhat.com" "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", + "requiredAudiences": ["https://kubernetes.default.svc"], "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. +Clients should request a projected ServiceAccount token bound to one of the `requiredAudiences`; TokenReview then validates the token's issuer, signature, expiry, and audience server-side. ### Key Configuration Fields @@ -146,11 +127,8 @@ This ensures OAuth issuer URLs match your actual OpenShift cluster configuration - `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 +- `useOpenShiftOAuth: true` - Client hint to obtain tokens from OpenShift's built-in OAuth (recommended for all cluster sizes) +- `requiredAudiences` - Array of accepted token audiences (validated by TokenReview). There is no `oauthIssuer`, `oauthJWKSURL`, `requiredScopes`, or `requiredAudience` (singular) field; issuer/signature/expiry are validated by the Kubernetes API server. ## Deployment @@ -225,10 +203,7 @@ data: "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", + "requiredAudiences": ["https://kubernetes.default.svc"], "serviceAccountName": "cloud-event-proxy-sa", "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" } @@ -308,10 +283,7 @@ spec: "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", + "requiredAudiences": ["https://kubernetes.default.svc"], "serviceAccountName": "consumer-sa", "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" } @@ -322,7 +294,7 @@ spec: ### Common Issues: 1. **Certificate Not Found**: Ensure Service CA annotation is correct -2. **OAuth Validation Fails**: Check OAuth server URL and JWKS endpoint +2. **OAuth Validation Fails**: Verify the server SA can create `tokenreviews` and that the client token's audience matches `requiredAudiences` 3. **Permission Denied**: Verify ServiceAccount has proper RBAC permissions ### Debug Commands: @@ -334,8 +306,9 @@ 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 +# Verify the server SA is allowed to create TokenReviews +oc auth can-i create tokenreviews.authentication.k8s.io \ + --as=system:serviceaccount:openshift-ptp:cloud-event-proxy-sa # Check OAuth server HA status oc get deployment oauth-openshift -n openshift-authentication diff --git a/README.md b/README.md index b50afdd..f5044ee 100644 --- a/README.md +++ b/README.md @@ -16,16 +16,16 @@ This REST API supports enterprise-grade authentication using mTLS and OAuth with ### 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 +- **Server-side OAuth Validation**: Bearer tokens are validated by the Kubernetes TokenReview API (issuer, signature, expiry, audience) with no bypass mechanisms +- **Audience Binding**: `requiredAudiences` ensures tokens minted for other services are rejected +- **Expiration Checking**: Expired tokens are rejected by TokenReview - **mTLS Certificate Validation**: Client certificates are verified against the configured CA +- **SSRF Hardening**: Caller-supplied endpoint URIs are validated (resolve-then-connect, no redirects) before the server dials them ### Recent Security Improvements -- **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 +- **TokenReview-based OAuth**: Token validation is delegated to the Kubernetes API server; the library performs no local JWT parsing or JWKS fetching +- **Bounded Token Cache**: Validated results are cached briefly with a short TTL to bound TokenReview load - **Enhanced Error Handling**: Clear error messages for authentication failures without exposing sensitive information ## O-RAN Compliant REST API Specification diff --git a/examples/openshift-manifests.yaml b/examples/openshift-manifests.yaml index 9c5cf67..a562e54 100644 --- a/examples/openshift-manifests.yaml +++ b/examples/openshift-manifests.yaml @@ -52,10 +52,7 @@ data: "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", + "requiredAudiences": ["https://kubernetes.default.svc"], "serviceAccountName": "cloud-event-proxy-sa", "serviceAccountToken": "/var/run/secrets/kubernetes.io/serviceaccount/token" } @@ -102,6 +99,48 @@ roleRef: name: cloud-event-proxy-role apiGroup: rbac.authorization.k8s.io +--- +# ClusterRole granting permission to create TokenReviews. The server validates +# OAuth bearer tokens by calling the Kubernetes TokenReview API, which requires +# this cluster-scoped permission (equivalent to the built-in +# system:auth-delegator ClusterRole). +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cloud-event-proxy-tokenreview +rules: +- apiGroups: ["authentication.k8s.io"] + resources: ["tokenreviews"] + verbs: ["create"] + +--- +# ClusterRoleBinding binding the TokenReview ClusterRole to the server SA. +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: cloud-event-proxy-tokenreview +subjects: +- kind: ServiceAccount + name: cloud-event-proxy-sa + namespace: openshift-ptp +roleRef: + kind: ClusterRole + name: cloud-event-proxy-tokenreview + apiGroup: rbac.authorization.k8s.io + +--- +# ConfigMap that OpenShift's Service CA operator populates with the cluster's +# Service CA bundle (service-ca.crt). This is the CA that signs the serving +# certificate above, so it is what clients and the server's own mTLS pool must +# trust - NOT the serving-cert Secret (which holds tls.crt/tls.key, not a CA). +apiVersion: v1 +kind: ConfigMap +metadata: + name: cloud-event-proxy-ca-bundle + namespace: openshift-ptp + annotations: + service.beta.openshift.io/inject-cabundle: "true" + --- # DaemonSet configuration for cloud-event-proxy # Works on both single node and multi-node clusters @@ -151,9 +190,13 @@ spec: - name: server-certs secret: secretName: cloud-event-proxy-tls + # The CA bundle comes from the Service CA ConfigMap (service-ca.crt), + # not the serving-cert Secret. caCertPath above points at + # /etc/cloud-event-proxy/ca-bundle/service-ca.crt, which this ConfigMap + # provides. Without a valid CA the server fails closed and will not serve. - name: ca-bundle - secret: - secretName: cloud-event-proxy-tls + configMap: + name: cloud-event-proxy-ca-bundle - name: auth-config configMap: name: cloud-event-proxy-auth-config diff --git a/pkg/restclient/client.go b/pkg/restclient/client.go index bfbbaeb..a021049 100644 --- a/pkg/restclient/client.go +++ b/pkg/restclient/client.go @@ -47,6 +47,18 @@ func New() *Rest { } } +// NewWithClient returns a Rest client that uses the supplied *http.Client. This +// lets callers inject an SSRF-hardened client (resolve-then-validate dialer plus +// a no-redirect policy) when POSTing to caller-supplied endpoints, instead of +// the default client which follows redirects and dials arbitrary resolved +// addresses. A nil client falls back to the default configuration. +func NewWithClient(client *http.Client) *Rest { + if client == nil { + return New() + } + return &Rest{client: *client} +} + // PostEvent post an event to the give url and check for error func (r *Rest) PostCloudEvent(url *types.URI, e ce.Event) (status int, err error) { b, err := json.Marshal(e) diff --git a/v2/routes.go b/v2/routes.go index bd4d141..a3b9d19 100644 --- a/v2/routes.go +++ b/v2/routes.go @@ -127,7 +127,11 @@ func (s *Server) createSubscription(w http.ResponseWriter, r *http.Request) { return } - restClient := restclient.New() + // Use the server's SSRF-hardened HTTP client (resolve-then-validate dialer + // plus no-redirect policy) for the initial-notification POST to the + // caller-supplied EndpointURI, rather than the default client which would + // follow redirects and dial arbitrary resolved addresses. + restClient := restclient.NewWithClient(s.HTTPClient) // make sure event ID is unique out.Data.SetID(uuid.New().String()) status, err := restClient.PostCloudEvent(sub.EndPointURI, *out.Data) diff --git a/v2/server.go b/v2/server.go index ba2148b..3be9c46 100644 --- a/v2/server.go +++ b/v2/server.go @@ -307,10 +307,17 @@ func InitServer(port int, apiHost, apiPath, storePath string, } // Initialize the mTLS CA certificate pool first so the HTTPClient below - // can verify endpoint certificates against it. - if authConfig != nil && authConfig.EnableMTLS && authConfig.CACertPath != "" { - if err := ServerInstance.initMTLSCACertPool(); err != nil { - log.Errorf("failed to initialize mTLS CA certificate pool: %v", err) + // can verify endpoint certificates against it. When mTLS is enabled a + // usable CA pool is mandatory: without it client certificates cannot be + // verified and endpoint server certificates cannot be validated, so we + // must fail closed rather than silently fall back to an unverified + // configuration. The absence of a pool is enforced in Start(), which + // refuses to begin serving TLS when it is nil. + if authConfig != nil && authConfig.EnableMTLS { + if authConfig.CACertPath == "" { + log.Error("InitServer: mTLS enabled but CACertPath is empty; server will fail closed at Start()") + } else if err := ServerInstance.initMTLSCACertPool(); err != nil { + log.Errorf("InitServer: failed to initialize mTLS CA certificate pool: %v; server will fail closed at Start()", err) } } @@ -689,6 +696,15 @@ func (s *Server) Start() { return } + // Fail closed: without a CA pool, presented client certificates + // cannot be verified against a trusted authority, so an mTLS + // server must not begin listening. + if s.caCertPool == nil { + log.Error("mTLS enabled but CA certificate pool is not initialized; refusing to start (fail closed)") + s.SetStatus(failed) + return + } + // Load server certificate and key cert, err := tls.LoadX509KeyPair(s.authConfig.ServerCertPath, s.authConfig.ServerKeyPath) if err != nil { diff --git a/v2/swagger.json b/v2/swagger.json index 92fcfb8..44f707c 100644 --- a/v2/swagger.json +++ b/v2/swagger.json @@ -6,7 +6,6 @@ "application/json" ], "schemes": [ - "http", "https" ], "swagger": "2.0", @@ -26,20 +25,11 @@ "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" - } + "BearerToken": { + "type": "apiKey", + "name": "Authorization", + "in": "header", + "description": "OAuth 2.0 Bearer token supplied in the Authorization header, e.g. `Authorization: Bearer `. Tokens (OpenShift OAuth or Kubernetes ServiceAccount tokens) are validated server-side via the Kubernetes TokenReview API, which checks the issuer, signature, expiry and audience. NOTE: in addition to the Bearer token, every protected endpoint also requires mutual TLS - the client must present a certificate signed by the trusted CA. mTLS cannot be represented in the Swagger 2.0 security model but is enforced at the transport layer for all non-loopback requests." } }, "paths": { @@ -66,10 +56,18 @@ ], "summary": "(Extensions to O-RAN API) Get publishers.", "operationId": "getPublishers", + "security": [ + { + "BearerToken": [] + } + ], "responses": { "200": { "$ref": "#/responses/publishers" }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." + }, "404": { "description": "Publishers not found" } @@ -84,12 +82,20 @@ ], "summary": "Retrieves a list of subscriptions.", "operationId": "getSubscriptions", + "security": [ + { + "BearerToken": [] + } + ], "responses": { "200": { "$ref": "#/responses/subscriptions" }, "400": { "description": "Bad request by the client." + }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." } } }, @@ -102,8 +108,7 @@ "operationId": "createSubscription", "security": [ { - "mTLS": [], - "OAuth2": ["write"] + "BearerToken": [] } ], "parameters": [ @@ -143,8 +148,7 @@ "operationId": "deleteAllSubscriptions", "security": [ { - "mTLS": [], - "OAuth2": ["write"] + "BearerToken": [] } ], "responses": { @@ -165,6 +169,11 @@ ], "summary": "Returns details for a specific subscription.", "operationId": "getSubscriptionByID", + "security": [ + { + "BearerToken": [] + } + ], "parameters": [ { "type": "string", @@ -179,6 +188,9 @@ "200": { "$ref": "#/responses/subscription" }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." + }, "404": { "description": "Not Found. Subscription resources are not available (not created)." } @@ -193,8 +205,7 @@ "operationId": "deleteSubscription", "security": [ { - "mTLS": [], - "OAuth2": ["write"] + "BearerToken": [] } ], "parameters": [ @@ -228,6 +239,11 @@ ], "summary": "Pulls the event status notifications for specified ResourceAddress.", "operationId": "getCurrentState", + "security": [ + { + "BearerToken": [] + } + ], "parameters": [ { "type": "string", @@ -242,6 +258,9 @@ "200": { "$ref": "#/responses/eventResp" }, + "401": { + "description": "Unauthorized. Authentication required (mTLS and/or OAuth)." + }, "404": { "description": "Not Found. Event notification resource is not available on this node." } From 968890594f308c2300424dfdc4fcd4124fafa59d Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Thu, 10 Sep 2026 09:21:19 -0400 Subject: [PATCH 13/15] v2/server: remove unauthenticated debug echo handler at base path The base-path route (api.HandleFunc("/", ...)) echoed the raw *http.Request back to the caller via fmt.Fprintln(w, r). It was debug scaffolding from the original v2 API commit: no callers, tests, docs, or swagger operations reference it, and the health probe uses /health rather than the base path. It also reflected caller-supplied request contents back unauthenticated, which serves no purpose. Removing it; GET on the base path now returns 404. Co-Authored-By: Claude Opus 4.8 Signed-off-by: Jack Ding --- v2/server.go | 3 --- 1 file changed, 3 deletions(-) diff --git a/v2/server.go b/v2/server.go index 3be9c46..ccacd9a 100644 --- a/v2/server.go +++ b/v2/server.go @@ -675,9 +675,6 @@ func (s *Server) Start() { if err != nil { log.Println(err) } - api.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { - fmt.Fprintln(w, r) - }) log.Infof("starting v2 rest api server at port %d, endpoint %s", s.port, s.apiPath) go wait.Until(func() { From 18cd3edfc8fdab41afb3b2a247280775fd6d9916 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Thu, 10 Sep 2026 09:27:22 -0400 Subject: [PATCH 14/15] v2/server: add WriteTimeout, IdleTimeout, MaxHeaderBytes hardening The HTTP server only set ReadHeaderTimeout, leaving slow/stalled clients and idle keep-alive connections unbounded. Add: - WriteTimeout (30s): caps request-body read + response write; set above the 10s outbound initial-notification POST performed during createSubscription. - IdleTimeout (60s): bounds retention of idle keep-alive connections so a connection-hoarding flood cannot exhaust the listener. - MaxHeaderBytes (1 MiB): caps per-connection header memory. Defense-in-depth against connection-exhaustion DoS on the port; behavior for normal (small, fast) API traffic is unchanged. Co-Authored-By: Claude Opus 4.8 Signed-off-by: Jack Ding --- v2/server.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/v2/server.go b/v2/server.go index ccacd9a..3fee06c 100644 --- a/v2/server.go +++ b/v2/server.go @@ -70,6 +70,16 @@ type ServerStatus int const ( HTTPReadHeaderTimeout = 2 * time.Second + // HTTPWriteTimeout bounds the time to read the request body plus write the + // response, capping slow/stalled clients. It is set comfortably above the + // 10s timeout of the outbound initial-notification POST that + // createSubscription performs while handling a request. + HTTPWriteTimeout = 30 * time.Second + // HTTPIdleTimeout bounds how long an idle keep-alive connection is retained, + // so flooding the server with idle connections cannot exhaust it. + HTTPIdleTimeout = 60 * time.Second + // HTTPMaxHeaderBytes caps request header size to limit per-connection memory. + HTTPMaxHeaderBytes = 1 << 20 // 1 MiB ) const ( @@ -681,6 +691,9 @@ func (s *Server) Start() { s.SetStatus(started) s.httpServer = &http.Server{ ReadHeaderTimeout: HTTPReadHeaderTimeout, + WriteTimeout: HTTPWriteTimeout, + IdleTimeout: HTTPIdleTimeout, + MaxHeaderBytes: HTTPMaxHeaderBytes, Addr: fmt.Sprintf(":%d", s.port), Handler: api, } From c6e15b6ab89c04668a8a2e9f7964d477f7776844 Mon Sep 17 00:00:00 2001 From: Jack Ding Date: Thu, 10 Sep 2026 11:01:57 -0400 Subject: [PATCH 15/15] v2: bound request-body reads and clarify conditional auth in swagger Add ReadTimeout to the HTTP server. ReadHeaderTimeout only covers header reads and WriteTimeout does not bound request-body reads, so a client could dribble a POST body to pin a handler goroutine indefinitely (Slowloris on the request body, CWE-400). Request bodies are small JSON documents, so the read deadline is set to the same generous ceiling as the write side. Clarify the swagger BearerToken definition to state the security requirements are configuration-dependent: the Bearer token is required only when OAuth is enabled and mTLS only when mTLS is enabled, and loopback requests bypass both. Swagger 2.0 cannot express conditional security, so this is documented in the definition description. Co-Authored-By: Claude Opus 4.8 Signed-off-by: Jack Ding --- v2/server.go | 8 ++++++++ v2/swagger.json | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/v2/server.go b/v2/server.go index 3fee06c..83c1a57 100644 --- a/v2/server.go +++ b/v2/server.go @@ -70,6 +70,13 @@ type ServerStatus int const ( HTTPReadHeaderTimeout = 2 * time.Second + // HTTPReadTimeout bounds the total time to read the entire request, including + // a slowly-transmitted body. ReadHeaderTimeout only covers the headers and + // WriteTimeout does not bound request-body reads, so without this a client + // could dribble a POST body to pin a handler goroutine indefinitely + // (Slowloris on the request body). Request bodies here are small JSON + // documents, so this is set to the same generous ceiling as the write side. + HTTPReadTimeout = 30 * time.Second // HTTPWriteTimeout bounds the time to read the request body plus write the // response, capping slow/stalled clients. It is set comfortably above the // 10s timeout of the outbound initial-notification POST that @@ -691,6 +698,7 @@ func (s *Server) Start() { s.SetStatus(started) s.httpServer = &http.Server{ ReadHeaderTimeout: HTTPReadHeaderTimeout, + ReadTimeout: HTTPReadTimeout, WriteTimeout: HTTPWriteTimeout, IdleTimeout: HTTPIdleTimeout, MaxHeaderBytes: HTTPMaxHeaderBytes, diff --git a/v2/swagger.json b/v2/swagger.json index 44f707c..bffa065 100644 --- a/v2/swagger.json +++ b/v2/swagger.json @@ -29,7 +29,7 @@ "type": "apiKey", "name": "Authorization", "in": "header", - "description": "OAuth 2.0 Bearer token supplied in the Authorization header, e.g. `Authorization: Bearer `. Tokens (OpenShift OAuth or Kubernetes ServiceAccount tokens) are validated server-side via the Kubernetes TokenReview API, which checks the issuer, signature, expiry and audience. NOTE: in addition to the Bearer token, every protected endpoint also requires mutual TLS - the client must present a certificate signed by the trusted CA. mTLS cannot be represented in the Swagger 2.0 security model but is enforced at the transport layer for all non-loopback requests." + "description": "OAuth 2.0 Bearer token supplied in the Authorization header, e.g. `Authorization: Bearer `. Tokens (OpenShift OAuth or Kubernetes ServiceAccount tokens) are validated server-side via the Kubernetes TokenReview API, which checks the issuer, signature, expiry and audience. NOTE: in addition to the Bearer token, every protected endpoint also requires mutual TLS - the client must present a certificate signed by the trusted CA. mTLS cannot be represented in the Swagger 2.0 security model but is enforced at the transport layer for all non-loopback requests. CONFIGURATION-DEPENDENT: this document describes the fully-secured (strict) deployment. Each mechanism is applied only when enabled in the server's AuthConfig - the Bearer token is required only when OAuth is enabled (EnableOAuth) and mTLS only when mTLS is enabled (EnableMTLS); a deployment may enable either, both, or neither. Loopback (same-pod) requests bypass both checks." } }, "paths": {