Phase 1: Implement OAuth2/OIDC core infrastructure

Backend Implementation:
- Add arctic and jsonwebtoken dependencies
- Create PKCEUtils for OAuth2 PKCE flow (RFC 7636)
- Create OAuth2Service for OIDC provider integration
  * OIDC discovery (.well-known/openid-configuration)
  * Authorization URL generation with PKCE
  * Token exchange (code for access/refresh/ID tokens)
  * Token refresh flow
  * UserInfo endpoint integration
- Create OAuth2AuthorizationMiddleware (initiate auth flow)
- Create OAuth2CallbackMiddleware (handle provider callback)
- Create OAuth2ConnectController (/oauth2/connect endpoint)
- Create OAuth2CallbackController (/oauth2/callback endpoint)

Configuration:
- Add OAuth2 environment variables to env_ai
- Feature flag VITE_USE_OAUTH2 for gradual migration
- Support for OBP-OIDC provider

Features:
- PKCE (Proof Key for Code Exchange) support
- State parameter for CSRF protection
- Session-based token storage
- Comprehensive error handling
- Security best practices (token expiration, flow timeout)

Note: Backend infrastructure complete. Next phase: integrate with app.ts
and update UserController for dual auth support.

Author: simonredfern

env_ai

@@ -0,0 +1,54 @@
+### OBP-API mode ###################################
+# If OBP-API split to two instances, eg: apis,portal
+# Then API_Explorer need to set two api hosts: api_hostname and this api_portal_hostname, for all Rest Apis will call api_hostname
+# but for all the portal home page link, we need to use this props. If do not set this, it will use api_hostname value instead.
+VITE_OBP_API_PORTAL_HOST=http://127.0.0.1:8080
+
+
+VITE_OBP_API_HOST=http://127.0.0.1:8080
+VITE_OBP_API_VERSION=v5.1.0
+VITE_OBP_API_MANAGER_HOST=https://apimanagersandbox.openbankproject.com
+VITE_OBP_API_EXPLORER_HOST=http://localhost:5173
+VITE_OBP_CONSUMER_KEY=0xzsimlrhdguiiuuj1ncykcxzjrogxibjff3dthl
+VITE_OBP_CONSUMER_SECRET=ikf5wykke1oonykb33kmx3deh5ukbdak44ieg1l5
+VITE_OBP_REDIRECT_URL=http://localhost:5173/api/callback
+VITE_OPB_SERVER_SESSION_PASSWORD=asidudhiuh33875
+# The above code connects to localhost on port 6379.
+# To connect to a different host or port, use a connection string in the format
+# redis[s]://[[username][:password]@][host][:port][/db-number]
+# Be sure to secure your Redis instance
+VITE_OBP_REDIS_URL = redis://127.0.0.1:6379
+
+# Enable the chatbot interface "Opey"
+VITE_CHATBOT_ENABLED=true
+VITE_CHATBOT_URL=http://localhost:5000
+
+# Product styling setting
+#VITE_OBP_LINKS_COLOR="#52b165"
+#VITE_OBP_HEADER_LINKS_COLOR="#39455f"
+#VITE_OBP_HEADER_LINKS_HOVER_COLOR="#39455f"
+#VITE_OBP_HEADER_LINKS_BACKGROUND_COLOR="#eef0f4"
+#VITE_OBP_LOGO_URL=https://static.openbankproject.com/images/obp_logo.png
+
+# https://nodejs.org/en/learn/getting-started/nodejs-the-difference-between-development-and-production
+# The value could be: development, staging, production
+# NODE_ENV=development
+
+#DEBUG=express-session
+
+### OAuth2/OIDC Configuration (New - Phase 1 Implementation) ###
+# Set to 'true' to use OAuth2 instead of OAuth 1.0a
+VITE_USE_OAUTH2=false
+
+# OAuth2 Client Credentials (from OBP-OIDC)
+# These should match the values in OBP-OIDC/run-server.sh
+VITE_OBP_OAUTH2_CLIENT_ID=obp-explorer-ii-client
+VITE_OBP_OAUTH2_CLIENT_SECRET=CHANGE_THIS_TO_EXPLORER_SECRET_2024
+VITE_OBP_OAUTH2_REDIRECT_URL=http://localhost:5173/oauth2/callback
+
+# OIDC Well-Known Configuration URL
+# For local development with OBP-OIDC:
+VITE_OBP_OAUTH2_WELL_KNOWN_URL=http://127.0.0.1:9000/obp-oidc/.well-known/openid-configuration
+
+# Optional: Token refresh threshold (seconds before expiry)
+VITE_OBP_OAUTH2_TOKEN_REFRESH_THRESHOLD=300

package-lock.json

@@ -25,6 +25,7 @@
     "@highlightjs/vue-plugin": "^2.1.0",
     "@types/node-fetch": "^2.6.12",
     "ai": "^4.1.43",
+    "arctic": "^3.7.0",
     "axios": "^1.7.4",
     "cheerio": "^1.0.0",
     "class-transformer": "^0.5.1",
@@ -67,7 +68,7 @@
     "@testing-library/vue": "^8.1.0",
     "@types/jest": "^29.5.14",
     "@types/jsdom": "^21.1.7",
-    "@types/jsonwebtoken": "^9.0.6",
+    "@types/jsonwebtoken": "^9.0.10",
     "@types/markdown-it": "^14.1.1",
     "@types/node": "^20.5.7",
     "@types/oauth": "^0.9.6",

package.json

@@ -0,0 +1,98 @@
+/*
+ * Open Bank Project -  API Explorer II
+ * Copyright (C) 2023-2024, TESOBE GmbH
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Email: contact@tesobe.com
+ * TESOBE GmbH
+ * Osloerstrasse 16/17
+ * Berlin 13359, Germany
+ *
+ *   This product includes software developed at
+ *   TESOBE (http://www.tesobe.com/)
+ *
+ */
+
+import { Controller, Req, Res, Get, UseBefore } from 'routing-controllers'
+import { Request, Response } from 'express'
+import { Service } from 'typedi'
+import OAuth2CallbackMiddleware from '../middlewares/OAuth2CallbackMiddleware'
+
+/**
+ * OAuth2 Callback Controller
+ *
+ * Handles the OAuth2/OIDC callback from the identity provider.
+ * This controller receives the authorization code and state parameter
+ * after the user authenticates with the OIDC provider.
+ *
+ * The OAuth2CallbackMiddleware handles:
+ * - State validation (CSRF protection)
+ * - Authorization code exchange for tokens
+ * - User info retrieval
+ * - Session storage
+ * - Redirect to original page
+ *
+ * Endpoint: GET /oauth2/callback
+ *
+ * Query Parameters (from OIDC provider):
+ *   - code: Authorization code to exchange for tokens
+ *   - state: State parameter for CSRF validation
+ *   - error (optional): Error code if authentication failed
+ *   - error_description (optional): Human-readable error description
+ *
+ * Flow:
+ *   OIDC Provider → /oauth2/callback?code=XXX&state=YYY
+ *   → OAuth2CallbackMiddleware → Original Page (with authenticated session)
+ *
+ * Success Flow:
+ *   1. Validate state parameter
+ *   2. Exchange authorization code for tokens (access, refresh, ID)
+ *   3. Fetch user information from UserInfo endpoint
+ *   4. Store tokens and user data in session
+ *   5. Redirect to original page or home
+ *
+ * Error Flow:
+ *   1. Parse error from query parameters
+ *   2. Display user-friendly error page
+ *   3. Allow user to retry authentication
+ *
+ * @example
+ * // Successful callback URL from OIDC provider
+ * http://localhost:5173/oauth2/callback?code=abc123&state=xyz789
+ *
+ * // Error callback URL from OIDC provider
+ * http://localhost:5173/oauth2/callback?error=access_denied&error_description=User%20cancelled
+ */
+@Service()
+@Controller()
+@UseBefore(OAuth2CallbackMiddleware)
+export class OAuth2CallbackController {
+  /**
+   * Handle OAuth2/OIDC callback
+   *
+   * The actual logic is handled by OAuth2CallbackMiddleware.
+   * This method exists only as the routing endpoint definition.
+   *
+   * @param {Request} request - Express request object with query params (code, state)
+   * @param {Response} response - Express response object (redirected by middleware)
+   * @returns {Response} Response object (handled by middleware)
+   */
+  @Get('/oauth2/callback')
+  callback(@Req() request: Request, @Res() response: Response): Response {
+    // The middleware handles all the logic and redirects the user
+    // This method should never actually execute
+    return response
+  }
+}

server/controllers/OAuth2CallbackController.ts

@@ -0,0 +1,77 @@
+/*
+ * Open Bank Project -  API Explorer II
+ * Copyright (C) 2023-2024, TESOBE GmbH
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Email: contact@tesobe.com
+ * TESOBE GmbH
+ * Osloerstrasse 16/17
+ * Berlin 13359, Germany
+ *
+ *   This product includes software developed at
+ *   TESOBE (http://www.tesobe.com/)
+ *
+ */
+
+import { Controller, Req, Res, Get, UseBefore } from 'routing-controllers'
+import { Request, Response } from 'express'
+import { Service } from 'typedi'
+import OAuth2AuthorizationMiddleware from '../middlewares/OAuth2AuthorizationMiddleware'
+
+/**
+ * OAuth2 Connect Controller
+ *
+ * Handles the OAuth2/OIDC login initiation endpoint.
+ * This controller triggers the OAuth2 authorization flow by delegating to
+ * the OAuth2AuthorizationMiddleware which generates PKCE parameters and
+ * redirects to the OIDC provider.
+ *
+ * Endpoint: GET /oauth2/connect
+ *
+ * Query Parameters:
+ *   - redirect (optional): URL to redirect to after successful authentication
+ *
+ * Flow:
+ *   User clicks login → /oauth2/connect → OAuth2AuthorizationMiddleware
+ *   → OIDC Provider Authorization Endpoint
+ *
+ * @example
+ * // User initiates login
+ * <a href="/oauth2/connect?redirect=/messages">Login</a>
+ *
+ * // JavaScript redirect
+ * window.location.href = '/oauth2/connect?redirect=' + encodeURIComponent(window.location.pathname)
+ */
+@Service()
+@Controller()
+@UseBefore(OAuth2AuthorizationMiddleware)
+export class OAuth2ConnectController {
+  /**
+   * Initiate OAuth2/OIDC authentication flow
+   *
+   * The actual logic is handled by OAuth2AuthorizationMiddleware.
+   * This method exists only as the routing endpoint definition.
+   *
+   * @param {Request} request - Express request object
+   * @param {Response} response - Express response object (redirected by middleware)
+   * @returns {Response} Response object (handled by middleware)
+   */
+  @Get('/oauth2/connect')
+  connect(@Req() request: Request, @Res() response: Response): Response {
+    // The middleware handles all the logic and redirects the user
+    // This method should never actually execute
+    return response
+  }
+}