docfix: Mention Hydra.

Author: simonredfern

obp-api/src/main/resources/docs/introductory_system_documentation.md

@@ -24,11 +24,12 @@ For more detailed information or the sources of truths, please refer to the indi
    - 3.4 [Opey II (AI Agent)](#34-opey-ii-ai-agent)
    - 3.5 [OBP-OIDC (Development Provider)](#35-obp-oidc-development-provider)
    - 3.6 [Keycloak Integration (Production Provider)](#36-keycloak-integration-production-provider)
-   - 3.7 [OBP-Hola](#37-obp-hola)
-   - 3.8 [OBP-SEPA-Adapter](#38-obp-sepa-adapter)
-   - 3.9 [Connectors](#39-connectors)
-   - 3.10 [Adapters](#310-adapters)
-   - 3.11 [Message Docs](#311-message-docs)
+   - 3.7 [Ory Hydra (Production Provider)](#37-ory-hydra-production-provider)
+   - 3.8 [OBP-Hola](#38-obp-hola)
+   - 3.9 [OBP-SEPA-Adapter](#39-obp-sepa-adapter)
+   - 3.10 [Connectors](#310-connectors)
+   - 3.11 [Adapters](#311-adapters)
+   - 3.12 [Message Docs](#312-message-docs)
 4. [Standards Compliance](#standards-compliance)
 5. [Installation and Configuration](#installation-and-configuration)
 6. [Authentication and Security](#authentication-and-security)
@@ -836,7 +837,120 @@ docker pull openbankproject/obp-keycloak:main-themed
 
 ---
 
-### 3.7 OBP-Hola
+### 3.7 Ory Hydra (Production Provider)
+
+**Purpose:** Cloud-native OAuth2 and OpenID Connect server for production deployments
+
+**Overview:**
+
+Ory Hydra is a hardened, open-source OAuth 2.0 and OpenID Connect server optimized for low-latency, high-throughput, and low resource consumption. It integrates with OBP-API to provide enterprise-grade authentication and authorization.
+
+**Key Features:**
+
+- **OAuth2 & OIDC Compliance:** Full implementation of OAuth 2.0 and OpenID Connect specifications
+- **Cloud Native:** Designed for containerized deployments (Docker, Kubernetes)
+- **Performance:** Low latency and high throughput
+- **Separation of Concerns:** Hydra handles OAuth/OIDC flow; identity management delegated to custom Identity Provider
+- **Security Hardened:** Regular security audits and compliance certifications
+- **Storage Backend:** PostgreSQL, MySQL, CockroachDB support
+
+**Architecture:**
+
+```
+Client → Hydra (OAuth2 Server) → OBP Hydra Identity Provider → OBP-API
+                ↓
+           Database (PostgreSQL)
+```
+
+**Components:**
+
+- **Ory Hydra:** OAuth2/OIDC server
+- **OBP Hydra Identity Provider:** Custom login/consent UI and user management
+- **OBP-API:** Banking API with Hydra integration
+
+**OBP-API Configuration:**
+
+```properties
+# Enable Hydra login
+login_with_hydra=true
+
+# Hydra server URLs
+hydra_public_url=http://127.0.0.1:4444
+hydra_admin_url=http://127.0.0.1:4445
+
+# Consent scopes
+hydra_consents=ReadAccountsBasic,ReadAccountsDetail,ReadBalances,ReadTransactionsBasic,ReadTransactionsDebits,ReadTransactionsDetail
+
+# JWKS validation
+oauth2.jwk_set.url=http://127.0.0.1:4444/.well-known/jwks.json
+
+# Mirror consumers to Hydra clients
+mirror_consumer_in_hydra=true
+```
+
+**Hydra Identity Provider Configuration:**
+
+```properties
+# Server port
+server.port=8086
+
+# OBP-API URL
+obp.base_url=http://localhost:8080
+endpoint.path.prefix=${obp.base_url}/obp/v4.0.0
+
+# Hydra admin URL
+oauth2.admin_url=http://127.0.0.1:4445
+
+# Service account credentials
+identity_provider.user.username=serviceuser
+identity_provider.user.password=password
+consumer_key=your-consumer-key
+
+# mTLS configuration (optional)
+mtls.keyStore.path=file:///path/to/keystore.jks
+mtls.keyStore.password=keystore-password
+mtls.trustStore.path=file:///path/to/truststore.jks
+mtls.trustStore.password=truststore-password
+```
+
+**Docker Deployment:**
+
+```bash
+# Start Hydra with docker-compose
+docker-compose -f quickstart.yml \
+    -f quickstart-postgres.yml \
+    up --build
+
+# Verify Hydra is running
+curl http://127.0.0.1:4444/.well-known/openid-configuration
+```
+
+**Hydra quickstart.yml environment:**
+
+```yaml
+environment:
+  - URLS_CONSENT=http://localhost:8086/consent
+  - URLS_LOGIN=http://localhost:8086/login
+  - URLS_LOGOUT=http://localhost:8086/logout
+```
+
+**Use Cases:**
+
+- High-performance OAuth2/OIDC deployments
+- Microservices architectures requiring centralized authentication
+- Multi-tenant banking platforms
+- Open Banking TPP integrations
+- Cloud-native banking solutions
+
+**Repositories:**
+
+- Ory Hydra: https://github.com/ory/hydra
+- OBP Hydra Identity Provider: https://github.com/OpenBankProject/OBP-Hydra-Identity-Provider
+- Demo OAuth2 Client: https://github.com/OpenBankProject/OBP-Hydra-OAuth2
+
+---
+
+### 3.8 OBP-Hola
 
 **Purpose:** Reference implementation for OAuth2 authentication and consent flow testing
 
@@ -918,7 +1032,7 @@ docker run -p 8087:8087 \
 
 ---
 
-### 3.8 OBP-SEPA-Adapter
+### 3.9 OBP-SEPA-Adapter
 
 **Purpose:** Reference implementation for SEPA payment processing with OBP-API
 
@@ -1076,7 +1190,7 @@ sbt "runMain sepa.scheduler.ProcessIncomingFilesActorSystem"
 
 ---
 
-### 3.9 Connectors
+### 3.10 Connectors
 
 **Purpose:** Connectors provide the integration layer between OBP-API and backend banking systems or data sources.
 
@@ -1137,7 +1251,7 @@ sbt "runMain sepa.scheduler.ProcessIncomingFilesActorSystem"
 
 ---
 
-### 3.10 Adapters
+### 3.11 Adapters
 
 **Purpose:** Adapters are backend services that receive messages from OBP-API connectors and respond according to Message Doc definitions.
 
@@ -1176,7 +1290,7 @@ Adapters listen to message queues or remote calls, parse incoming messages accor
 
 ---
 
-### 3.11 Message Docs
+### 3.12 Message Docs
 
 **Purpose:** Message Docs define the structure and schema of messages exchanged between OBP-API connectors and backend adapters.