Authentication & Authorization with JWT and RBAC

[bburda]

Summary

Implement a comprehensive authentication and authorization system for the ros2_medkit gateway using JWT (JSON Web Tokens) with Role-Based Access Control (RBAC). This aligns with SOVD specification requirements REQ_INTEROP_086 and REQ_INTEROP_087.

---

Background

The ros2_medkit gateway currently exposes REST endpoints without authentication, making it suitable only for isolated development environments. For production deployments, proper access control is essential to:

• Prevent unauthorized access to vehicle/robot diagnostics
• Control who can modify configurations or trigger operations
• Audit access to sensitive data
• Support multi-tenant scenarios

---

Proposed Solution

1. Authentication Endpoints

POST /api/v1/auth/authorize (REQ_INTEROP_086)

• Accept client credentials (client_id, client_secret, or OAuth2 flows)
• Support multiple authentication methods:
  • Basic credentials
  • API keys
  • Optional: OAuth2 authorization code flow

POST /api/v1/auth/token (REQ_INTEROP_087)

• Issue JWT access tokens with configurable expiration
• Support token refresh via refresh tokens
• Return standard OAuth2 token response format

2. Role-Based Access Control (RBAC)

Define permission levels for different operations. For example:

Role	Permissions
viewer	Read-only access: GET on areas, components, data, faults
operator	Viewer + trigger operations, acknowledge faults
configurator	Operator + modify configurations
admin	Full access

3. JWT Implementation

• Use standard JWT claims (iss, sub, exp, iat)
• Custom claims for roles and permissions
• Support RS256 (asymmetric) and HS256 (symmetric) signing
• Token validation middleware for all protected endpoints

4. Configuration Parameters

ros2_medkit_gateway:
  ros__parameters:
    auth:
      enabled: false  # Default disabled for local development
      jwt_secret: ""  # For HS256, or path to private key for RS256
      jwt_algorithm: "HS256"  # HS256 or RS256
      token_expiry_seconds: 3600
      refresh_token_expiry_seconds: 86400
      require_auth_for:
        - "write"  # Require auth only for write operations
        # - "all"  # Or require for all operations

---

Implementation Tasks

• Add JWT library dependency (e.g., jwt-cpp)
• Create AuthManager class for token generation/validation
• Implement /auth/authorize endpoint
• Implement /auth/token endpoint
• Create authentication middleware for REST server
• Add RBAC permission checks to existing endpoints
• Add configuration parameters
• Unit tests for auth flows
• Integration tests for protected endpoints
• Update documentation with auth configuration

---

Acceptance Criteria

• Unauthorized requests to protected endpoints return 401
• Valid JWT tokens grant access based on role permissions
• Expired tokens return 401 with appropriate error message
• Token refresh works correctly before expiration
• Backward compatible: auth disabled by default
• CORS configuration supports Authorization header

---

Additional Context

• Reference: SOVD 1.0.0 Specification sections on Authorization
• cpp-httplib supports middleware patterns for auth checks
• Consider future integration with external identity providers (OAuth2/OIDC)