Implement JWT bearer token authentication

[nam20485]

Will likely have to be a custom implementation, as I do not of a library that can add it in C++ to the crow http library.

[traycerai]

Plan

Observations

The codebase already has a well-structured authentication framework with RequestAuthenticationBase as the base class and BasicRequestAuthentication implementing HTTP Basic authentication. OpenSSL is already a dependency, which is essential for JWT signature verification. Authentication is actively used in controllers like DesignsController, FileModelController, and FileUploadController. The authentication mechanism can be swapped by creating a new implementation and setting it in OdbDesignServerApp::preServerRun().

Approach

The implementation will follow the existing authentication pattern by creating a new JwtRequestAuthentication class that extends RequestAuthenticationBase. We'll use the jwt-cpp library (header-only, OpenSSL-compatible) available via vcpkg. The JWT authentication will extract Bearer tokens from the Authorization header, validate the token signature, verify claims (expiration, issuer, audience), and return appropriate HTTP responses. Configuration will be handled through environment variables similar to the existing BasicRequestAuthentication pattern.

Implementation Steps

1. Add JWT Library Dependency

Update file:vcpkg.json to include the jwt-cpp library:

• Add "jwt-cpp" to the dependencies array
• This library is header-only and works with the existing OpenSSL dependency

2. Create JWT Authentication Class Files

Create two new files in file:OdbDesignLib/App/:

file:OdbDesignLib/App/JwtRequestAuthentication.h

• Inherit from RequestAuthenticationBase
• Declare AuthenticateRequest() override method
• Define private helper methods:
  • ExtractBearerToken() - extract token from Authorization header
  • ValidateToken() - validate JWT signature and claims
  • GetJwtSecret() - retrieve secret from environment variable
• Define environment variable constants:
  • JWT_SECRET_ENV_NAME - for the signing secret
  • JWT_ISSUER_ENV_NAME - for expected issuer (optional)
  • JWT_AUDIENCE_ENV_NAME - for expected audience (optional)
• Include necessary headers: jwt-cpp/jwt.h, RequestAuthenticationBase.h

file:OdbDesignLib/App/JwtRequestAuthentication.cpp

• Implement constructor accepting disableAuthentication flag
• Implement AuthenticateRequest():
  • Call base class method first (handles debug/local bypass)
  • If base returns non-OK, extract Authorization header
  • Verify header starts with "Bearer "
  • Extract token substring after "Bearer "
  • Call ValidateToken() with extracted token
  • Return appropriate crow::response based on validation result
• Implement ExtractBearerToken():
  • Check if Authorization header exists
  • Verify "Bearer " prefix (case-insensitive)
  • Return token string or empty string on failure
• Implement ValidateToken():
  • Create jwt-cpp verifier with HS256 algorithm (or RS256 if using public/private keys)
  • Set secret from environment variable
  • Add issuer verification if configured
  • Add audience verification if configured
  • Verify expiration claim
  • Catch jwt-cpp exceptions and return appropriate error responses
  • Return 200 OK if valid, 401 Unauthorized if invalid/expired, 403 Forbidden if claims don't match
• Implement GetJwtSecret():
  • Read from environment variable ODBDESIGN_JWT_SECRET
  • Return default value for development if not set (with warning log)
  • Throw exception in production if not set

3. Update CMakeLists.txt

Update file:OdbDesignLib/CMakeLists.txt:

• Add JwtRequestAuthentication.h and JwtRequestAuthentication.cpp to the add_library() source list (around line 41 where authentication files are listed)
• Add jwt-cpp package finding:

  find_package(jwt-cpp CONFIG REQUIRED)
  target_link_libraries(OdbDesign PRIVATE jwt-cpp::jwt-cpp)

• Place this after the OpenSSL find_package section (after line 70)

4. Integrate JWT Authentication

Update file:OdbDesignServer/OdbDesignServerApp.cpp:

• Add include: #include <App/JwtRequestAuthentication.h>
• In preServerRun() method (around line 68-71), add logic to choose authentication type:
  • Add command-line argument check for JWT mode (or use environment variable)
  • Replace BasicRequestAuthentication instantiation with conditional logic:
    • If JWT mode enabled: create JwtRequestAuthentication instance
    • Otherwise: keep existing BasicRequestAuthentication
  • Example structure:

    bool disableAuth = args().disableAuthentication();
    if (useJwtAuth) {
        auto jwtAuth = std::make_unique<JwtRequestAuthentication>(disableAuth);
        request_auth(std::move(jwtAuth));
    } else {
        auto basicAuth = std::make_unique<BasicRequestAuthentication>(disableAuth);
        request_auth(std::move(basicAuth));
    }
    

5. Add Command-Line Argument for JWT Mode (Optional)

Update file:OdbDesignLib/App/OdbDesignArgs.h and file:OdbDesignLib/App/OdbDesignArgs.cpp:

• Add useJwtAuth() method declaration in header
• Add DEFAULT_USE_JWT_AUTH constant (default: false)
• Implement useJwtAuth() method: return boolArg("use-jwt-auth", DEFAULT_USE_JWT_AUTH);
• Update getUsageString() to document the --use-jwt-auth flag

6. Environment Variables Configuration

Document the following environment variables (update file:docs/SECURITY.md or README):

• ODBDESIGN_JWT_SECRET - Secret key for HS256 signature verification (required)
• ODBDESIGN_JWT_ISSUER - Expected issuer claim (optional)
• ODBDESIGN_JWT_AUDIENCE - Expected audience claim (optional)
• For RS256 (public/private key):
  • ODBDESIGN_JWT_PUBLIC_KEY - Path to public key file
  • ODBDESIGN_JWT_ALGORITHM - Algorithm to use (HS256, RS256, etc.)

7. Create JWT Token Generation Utility (Optional)

Create file:OdbDesignLib/App/JwtTokenGenerator.h and file:OdbDesignLib/App/JwtTokenGenerator.cpp:

• Static utility class for generating test tokens
• Method GenerateToken(subject, expirationMinutes)
• Uses same secret from environment variable
• Useful for testing and development
• Can be exposed via a separate admin endpoint or CLI tool

Architecture Diagram

sequenceDiagram
    participant Client
    participant CrowServer
    participant Controller
    participant JwtRequestAuthentication
    participant jwt-cpp
    participant OpenSSL

    Client->>CrowServer: HTTP Request with Authorization: Bearer <token>
    CrowServer->>Controller: Route to handler
    Controller->>JwtRequestAuthentication: AuthenticateRequest(req)
    JwtRequestAuthentication->>JwtRequestAuthentication: ExtractBearerToken()
    JwtRequestAuthentication->>JwtRequestAuthentication: ValidateToken(token)
    JwtRequestAuthentication->>jwt-cpp: Create verifier with secret
    jwt-cpp->>OpenSSL: Verify signature
    OpenSSL-->>jwt-cpp: Signature valid/invalid
    jwt-cpp->>jwt-cpp: Verify claims (exp, iss, aud)
    jwt-cpp-->>JwtRequestAuthentication: Validation result
    JwtRequestAuthentication-->>Controller: crow::response (200/401/403)
    alt Authentication successful
        Controller->>Controller: Process request
        Controller-->>CrowServer: Response with data
    else Authentication failed
        Controller-->>CrowServer: 401/403 response
    end
    CrowServer-->>Client: HTTP Response

Loading

Component Structure

Component	File Path	Purpose
JWT Authentication	OdbDesignLib/App/JwtRequestAuthentication.{h,cpp}	Main JWT validation logic
Base Authentication	OdbDesignLib/App/RequestAuthenticationBase.{h,cpp}	Abstract base class (existing)
Server App	OdbDesignServer/OdbDesignServerApp.cpp	Authentication initialization
Command Args	OdbDesignLib/App/OdbDesignArgs.{h,cpp}	CLI argument handling
Dependencies	vcpkg.json	Package management
Build Config	OdbDesignLib/CMakeLists.txt	Build system integration

Testing Considerations

• Test with valid JWT tokens (correct signature, unexpired)
• Test with expired tokens (should return 401)
• Test with invalid signatures (should return 401)
• Test with missing Authorization header (should return 401)
• Test with malformed Bearer token format (should return 401)
• Test with incorrect issuer/audience claims (should return 403)
• Test with --disable-authentication flag (should bypass JWT validation)
• Test in debug/local mode (should bypass authentication per base class logic)
• Generate test tokens using the optional JwtTokenGenerator utility

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase already has a well-structured authentication framework with `RequestAuthenticationBase` as the base class and `BasicRequestAuthentication` implementing HTTP Basic authentication. OpenSSL is already a dependency, which is essential for JWT signature verification. Authentication is actively used in controllers like `DesignsController`, `FileModelController`, and `FileUploadController`. The authentication mechanism can be swapped by creating a new implementation and setting it in `OdbDesignServerApp::preServerRun()`.

## Approach

The implementation will follow the existing authentication pattern by creating a new `JwtRequestAuthentication` class that extends `RequestAuthenticationBase`. We'll use the `jwt-cpp` library (header-only, OpenSSL-compatible) available via vcpkg. The JWT authentication will extract Bearer tokens from the Authorization header, validate the token signature, verify claims (expiration, issuer, audience), and return appropriate HTTP responses. Configuration will be handled through environment variables similar to the existing `BasicRequestAuthentication` pattern.

## Implementation Steps

### 1. Add JWT Library Dependency

Update `file:vcpkg.json` to include the `jwt-cpp` library:
- Add `"jwt-cpp"` to the dependencies array
- This library is header-only and works with the existing OpenSSL dependency

### 2. Create JWT Authentication Class Files

Create two new files in `file:OdbDesignLib/App/`:

**file:OdbDesignLib/App/JwtRequestAuthentication.h**
- Inherit from `RequestAuthenticationBase`
- Declare `AuthenticateRequest()` override method
- Define private helper methods:
  - `ExtractBearerToken()` - extract token from Authorization header
  - `ValidateToken()` - validate JWT signature and claims
  - `GetJwtSecret()` - retrieve secret from environment variable
- Define environment variable constants:
  - `JWT_SECRET_ENV_NAME` - for the signing secret
  - `JWT_ISSUER_ENV_NAME` - for expected issuer (optional)
  - `JWT_AUDIENCE_ENV_NAME` - for expected audience (optional)
- Include necessary headers: `jwt-cpp/jwt.h`, `RequestAuthenticationBase.h`

**file:OdbDesignLib/App/JwtRequestAuthentication.cpp**
- Implement constructor accepting `disableAuthentication` flag
- Implement `AuthenticateRequest()`:
  - Call base class method first (handles debug/local bypass)
  - If base returns non-OK, extract Authorization header
  - Verify header starts with "Bearer "
  - Extract token substring after "Bearer "
  - Call `ValidateToken()` with extracted token
  - Return appropriate crow::response based on validation result
- Implement `ExtractBearerToken()`:
  - Check if Authorization header exists
  - Verify "Bearer " prefix (case-insensitive)
  - Return token string or empty string on failure
- Implement `ValidateToken()`:
  - Create jwt-cpp verifier with HS256 algorithm (or RS256 if using public/private keys)
  - Set secret from environment variable
  - Add issuer verification if configured
  - Add audience verification if configured
  - Verify expiration claim
  - Catch jwt-cpp exceptions and return appropriate error responses
  - Return 200 OK if valid, 401 Unauthorized if invalid/expired, 403 Forbidden if claims don't match
- Implement `GetJwtSecret()`:
  - Read from environment variable `ODBDESIGN_JWT_SECRET`
  - Return default value for development if not set (with warning log)
  - Throw exception in production if not set

### 3. Update CMakeLists.txt

Update `file:OdbDesignLib/CMakeLists.txt`:
- Add `JwtRequestAuthentication.h` and `JwtRequestAuthentication.cpp` to the `add_library()` source list (around line 41 where authentication files are listed)
- Add jwt-cpp package finding:
  ```cmake
  find_package(jwt-cpp CONFIG REQUIRED)
  target_link_libraries(OdbDesign PRIVATE jwt-cpp::jwt-cpp)
  ```
- Place this after the OpenSSL find_package section (after line 70)

### 4. Integrate JWT Authentication

Update `file:OdbDesignServer/OdbDesignServerApp.cpp`:
- Add include: `#include <App/JwtRequestAuthentication.h>`
- In `preServerRun()` method (around line 68-71), add logic to choose authentication type:
  - Add command-line argument check for JWT mode (or use environment variable)
  - Replace `BasicRequestAuthentication` instantiation with conditional logic:
    - If JWT mode enabled: create `JwtRequestAuthentication` instance
    - Otherwise: keep existing `BasicRequestAuthentication`
  - Example structure:
    ```
    bool disableAuth = args().disableAuthentication();
    if (useJwtAuth) {
        auto jwtAuth = std::make_unique<JwtRequestAuthentication>(disableAuth);
        request_auth(std::move(jwtAuth));
    } else {
        auto basicAuth = std::make_unique<BasicRequestAuthentication>(disableAuth);
        request_auth(std::move(basicAuth));
    }
    ```

### 5. Add Command-Line Argument for JWT Mode (Optional)

Update `file:OdbDesignLib/App/OdbDesignArgs.h` and `file:OdbDesignLib/App/OdbDesignArgs.cpp`:
- Add `useJwtAuth()` method declaration in header
- Add `DEFAULT_USE_JWT_AUTH` constant (default: false)
- Implement `useJwtAuth()` method: `return boolArg("use-jwt-auth", DEFAULT_USE_JWT_AUTH);`
- Update `getUsageString()` to document the `--use-jwt-auth` flag

### 6. Environment Variables Configuration

Document the following environment variables (update `file:docs/SECURITY.md` or README):
- `ODBDESIGN_JWT_SECRET` - Secret key for HS256 signature verification (required)
- `ODBDESIGN_JWT_ISSUER` - Expected issuer claim (optional)
- `ODBDESIGN_JWT_AUDIENCE` - Expected audience claim (optional)
- For RS256 (public/private key):
  - `ODBDESIGN_JWT_PUBLIC_KEY` - Path to public key file
  - `ODBDESIGN_JWT_ALGORITHM` - Algorithm to use (HS256, RS256, etc.)

### 7. Create JWT Token Generation Utility (Optional)

Create `file:OdbDesignLib/App/JwtTokenGenerator.h` and `file:OdbDesignLib/App/JwtTokenGenerator.cpp`:
- Static utility class for generating test tokens
- Method `GenerateToken(subject, expirationMinutes)` 
- Uses same secret from environment variable
- Useful for testing and development
- Can be exposed via a separate admin endpoint or CLI tool

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Client
    participant CrowServer
    participant Controller
    participant JwtRequestAuthentication
    participant jwt-cpp
    participant OpenSSL

    Client->>CrowServer: HTTP Request with Authorization: Bearer <token>
    CrowServer->>Controller: Route to handler
    Controller->>JwtRequestAuthentication: AuthenticateRequest(req)
    JwtRequestAuthentication->>JwtRequestAuthentication: ExtractBearerToken()
    JwtRequestAuthentication->>JwtRequestAuthentication: ValidateToken(token)
    JwtRequestAuthentication->>jwt-cpp: Create verifier with secret
    jwt-cpp->>OpenSSL: Verify signature
    OpenSSL-->>jwt-cpp: Signature valid/invalid
    jwt-cpp->>jwt-cpp: Verify claims (exp, iss, aud)
    jwt-cpp-->>JwtRequestAuthentication: Validation result
    JwtRequestAuthentication-->>Controller: crow::response (200/401/403)
    alt Authentication successful
        Controller->>Controller: Process request
        Controller-->>CrowServer: Response with data
    else Authentication failed
        Controller-->>CrowServer: 401/403 response
    end
    CrowServer-->>Client: HTTP Response
```

## Component Structure

| Component | File Path | Purpose |
|-----------|-----------|---------|
| JWT Authentication | `OdbDesignLib/App/JwtRequestAuthentication.{h,cpp}` | Main JWT validation logic |
| Base Authentication | `OdbDesignLib/App/RequestAuthenticationBase.{h,cpp}` | Abstract base class (existing) |
| Server App | `OdbDesignServer/OdbDesignServerApp.cpp` | Authentication initialization |
| Command Args | `OdbDesignLib/App/OdbDesignArgs.{h,cpp}` | CLI argument handling |
| Dependencies | `vcpkg.json` | Package management |
| Build Config | `OdbDesignLib/CMakeLists.txt` | Build system integration |

## Testing Considerations

- Test with valid JWT tokens (correct signature, unexpired)
- Test with expired tokens (should return 401)
- Test with invalid signatures (should return 401)
- Test with missing Authorization header (should return 401)
- Test with malformed Bearer token format (should return 401)
- Test with incorrect issuer/audience claims (should return 403)
- Test with `--disable-authentication` flag (should bypass JWT validation)
- Test in debug/local mode (should bypass authentication per base class logic)
- Generate test tokens using the optional JwtTokenGenerator utility

---

Execution Information

Branch: development
Commit: e7a1e9d

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[Scherlac]

Hi,
I found your ODB++ backend recently and going through and see the Incredible progress you have. 👍
Without understanding the current status, one idea would be to use the oauth2-proxy as a middleware for authentication.