|
| 1 | +# Open Bank Project — Brief Documentation |
| 2 | + |
| 3 | +_System Architecture, Workflows, Security, and API Reference_ |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 1) System Architecture Description |
| 8 | + |
| 9 | +**High‑level components** |
| 10 | + |
| 11 | +- **OBP‑API** (Scala): core REST API supporting multiple versions (v1–v5), pluggable data connectors, views/entitlements, payments, metadata, KYC, etc. |
| 12 | +- **API Explorer / API Explorer II**: interactive Swagger/OpenAPI front‑ends for testing and discovery. |
| 13 | +- **API Manager** (Django): manage consumers, roles, metrics, and selected resources. |
| 14 | +- **Connectors**: northbound to OBP APIs; southbound to data sources (core banking, caches). Kafka/RabbitMQ and Akka remote supported for decoupling and scale. |
| 15 | +- **Consent & OAuth helpers**: example apps (e.g., OBP‑Hola) to demonstrate OAuth2/OIDC, consents, mTLS/JWS profiles. |
| 16 | +- **Persistence**: PostgreSQL (production), H2 (dev); optional caches. |
| 17 | +- **Runtime options**: Jetty (war), Docker, Kubernetes. |
| 18 | + |
| 19 | +**Reference deployment views** |
| 20 | + |
| 21 | +- _Monolith + DB_: OBP‑API on Jetty/Tomcat with PostgreSQL. |
| 22 | +- _Containerised_: OBP‑API image + Postgres; optional API Explorer/Manager containers. |
| 23 | +- _Kubernetes_: OBP‑API Deployment + Service, Postgres Stateful workload, optional Ingress & secrets, externalized config. |
| 24 | +- _Decoupled storage_: OBP‑API (stateless) + Akka Remote storage node with DB access; optional Kafka/RabbitMQ between API and core adapters. |
| 25 | + |
| 26 | +**Key integration points** |
| 27 | + |
| 28 | +- **AuthN/AuthZ**: OAuth 1.0a (legacy), OAuth 2.0, OIDC, DirectLogin; role‑based entitlements; fine‑grained _Views_ for account/transaction level access; Consents for OB/PSD2 style access. |
| 29 | +- **Standards**: UK OB, Berlin Group, Bahrain OBF mapping via endpoints/consents; JWS signatures, mTLS where required. |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## 2) Core Workflows (step‑by‑step) |
| 34 | + |
| 35 | +### A. Developer onboarding & first call |
| 36 | + |
| 37 | +1. Register user in sandbox / local. |
| 38 | +2. Create application → obtain consumer key. |
| 39 | +3. Choose auth method (DirectLogin for dev, OAuth2/OIDC for production patterns). |
| 40 | +4. Call `/obp/vX.X.X/root` to confirm version & status; explore endpoints in API Explorer. |
| 41 | + |
| 42 | +### B. Entitlements (roles) & access |
| 43 | + |
| 44 | +1. Admin (or super user during bootstrap) grants roles via `add entitlement` endpoints. |
| 45 | +2. Typical roles: `CanCreateEntitlementAtAnyBank`, `CanCreateSandbox`, bank‑scoped operational roles, etc. |
| 46 | +3. Apps consume bank/system resources according to entitlements. |
| 47 | + |
| 48 | +### C. Views (fine‑grained account access) |
| 49 | + |
| 50 | +1. Account owner uses default `owner` view. |
| 51 | +2. Create custom views (e.g., `accountants`, `auditors`, `tagging-application`). |
| 52 | +3. Grant/revoke a user’s access to a view; client calls read endpoints with a specific view. |
| 53 | + |
| 54 | +### D. OAuth2/OIDC + Consent (OB/PSD2 style) |
| 55 | + |
| 56 | +1. TPP/Client registers (with certs if mTLS is used). |
| 57 | +2. User authN via authorisation server; client requests consent (scopes/accounts/permissions). |
| 58 | +3. Consent resource & access token are returned (optionally JWS‑signed, certificate‑bound). |
| 59 | +4. Client calls accounts/balances/transactions/payments with proof (mTLS/JWS), consent id, and token. |
| 60 | + |
| 61 | +### E. Transaction Requests (PIS) |
| 62 | + |
| 63 | +1. Create payment request with account + amount + creditor. |
| 64 | +2. Strong customer authentication (SCA) if required. |
| 65 | +3. Execute/submit and poll status. |
| 66 | + |
| 67 | +--- |
| 68 | + |
| 69 | +## 3) Diagrams (text sketches) |
| 70 | + |
| 71 | +**High-Level System Architecture** |
| 72 | + |
| 73 | +See the detailed architecture diagram in [introductory_system_documentation.md](introductory_system_documentation.md#21-high-level-architecture) (Section 2.1). |
| 74 | + |
| 75 | +**Views & Entitlements** |
| 76 | + |
| 77 | +``` |
| 78 | +User ──(has roles/entitlements)──► Bank/System actions |
| 79 | + │ |
| 80 | + └─(granted view)──► Account/Transaction subset (e.g., accountants) |
| 81 | +``` |
| 82 | + |
| 83 | +--- |
| 84 | + |
| 85 | +## 4) Component Logic |
| 86 | + |
| 87 | +- **Views**: declarative access lists (what fields/transactions are visible, what actions permitted) bound to an account. Grants are user↔view. |
| 88 | +- **Entitlements**: role assignments at _system_ or _bank_ scope; govern management operations (create banks, grant roles, etc.). |
| 89 | +- **Connectors**: adapter pattern; map OBP domain to underlying core data sources. Kafka/RabbitMQ optional for async decoupling; Akka Remote to separate API and DB hosts. |
| 90 | +- **Security**: OAuth2/OIDC (with JWKS), optional mTLS + certificate‑bound tokens; JWS for request/response signing as required by OB/FAPI profiles. |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +## 5) Installation, Configuration & Updates |
| 95 | + |
| 96 | +### Option A — Quick local & development (IntelliJ / `mvn`) |
| 97 | + |
| 98 | +- Clone `OBP-API` → open in IntelliJ (Scala/Java toolchain). |
| 99 | +- Create `default.props` (dev) and choose connector (`mapped` for demo) and DB (H2 or Postgres). |
| 100 | +- `mvn package` → produce `.war`; run with Jetty or use IntelliJ runner. |
| 101 | + |
| 102 | +### Option B — Docker (recommended for evaluation) |
| 103 | + |
| 104 | +- Pull `openbankproject/obp-api` image. |
| 105 | +- Provide config via env vars: prefix `OBP_`, replace `.` with `_`, uppercase (e.g., `openid_connect.enabled=true` → `OBP_OPENID_CONNECT_ENABLED=true`). |
| 106 | +- Wire Postgres; expose 8080. |
| 107 | + |
| 108 | +### Option C — Kubernetes |
| 109 | + |
| 110 | +- Apply manifest (`Deployment`, `Service`, `ConfigMap`/`Secret` for props, `StatefulSet` for Postgres, optional `Ingress`). |
| 111 | +- Externalise DB creds, JWT/keystore, and OAuth endpoints; configure probes. |
| 112 | + |
| 113 | +### Databases |
| 114 | + |
| 115 | +- **Dev**: H2 (enable web console if needed). |
| 116 | +- **Prod**: PostgreSQL recommended; set SSL if required; grant schema/table privileges.\ |
| 117 | + Any JDBC-compliant DB is supported (e.g. MS SQL, Oracle DB, etc.) |
| 118 | + |
| 119 | +### Updating |
| 120 | + |
| 121 | +- Track OBP‑API tags/releases; OBP supports multiple API versions simultaneously. For minor updates, roll forward container with readiness checks; for major schema changes, follow release notes and backup DB. |
| 122 | + |
| 123 | +--- |
| 124 | + |
| 125 | +## 6) Access Control & Security Mechanisms |
| 126 | + |
| 127 | +- **Authentication**: OAuth 1.0a (legacy), OAuth 2.0, OIDC, DirectLogin (automation/dev only). |
| 128 | +- **Authorisation**: Role‑based **Entitlements** (system/bank scope) + account‑level **Views**. |
| 129 | +- **Consents**: OB/PSD2 style consent objects with permissions/scopes, linked to tokens. |
| 130 | +- **Crypto**: JWS request/response signing where profiles demand; JWKS for key discovery. |
| 131 | +- **mTLS / PoP**: Certificate‑bound tokens for higher assurance profiles (FAPI/UK OB), TLS client auth at gateway. |
| 132 | +- **Secrets**: JKS keystores for SSL and encrypted props values. |
| 133 | + |
| 134 | +--- |
| 135 | + |
| 136 | +## 7) Monitoring, Logging & Troubleshooting |
| 137 | + |
| 138 | +**Logging** |
| 139 | + |
| 140 | +- Copy `logback.xml.example` to `logback.xml`; adjust levels (TRACE/DEBUG/INFO) per environment. |
| 141 | +- In Docker/K8s, logs go to stdout/stderr → aggregate with your stack (e.g., Loki/Promtail, EFK). |
| 142 | + |
| 143 | +**Health & metrics** |
| 144 | + |
| 145 | +- K8s liveness/readiness probes on OBP‑API root/version or lightweight GET; external synthetic checks via API Explorer smoke tests. |
| 146 | + |
| 147 | +**Troubleshooting checklist** |
| 148 | + |
| 149 | +- **Auth failures**: verify JWKS URL reachability, clock skew, audience/scope, mTLS cert chain. |
| 150 | +- **Permissions**: confirm entitlements vs. views; bootstrap `super_admin_user_ids` only for initial admin then remove. |
| 151 | +- **DB issues**: check Postgres grants; enable SSL and import server cert into JVM truststore if needed. |
| 152 | +- **Connector errors**: raise logging for connector package; verify message bus (Kafka/RabbitMQ) SSL settings if enabled. |
| 153 | + |
| 154 | +--- |
| 155 | + |
| 156 | +## 8) Service Documentation (operators’ quick sheet) |
| 157 | + |
| 158 | +**Day‑1** |
| 159 | + |
| 160 | +- Provision Postgres; create db/user; load props via Secret/ConfigMap; start OBP‑API. |
| 161 | +- Create first admin: set `super_admin_user_ids`, login, grant `CanCreateEntitlementAtAnyBank`, then remove bootstrap prop. |
| 162 | + |
| 163 | +**Day‑2** |
| 164 | + |
| 165 | +- Rotate keys (JKS) and tokens; manage roles & views via API Manager; enable audit trails. |
| 166 | +- Backups: nightly Postgres dump + config snapshot; test restore monthly. |
| 167 | +- Upgrades: blue/green or rolling on K8s; verify `/root` endpoints across versions. |
| 168 | + |
| 169 | +**Incident runbook (snippets)** |
| 170 | + |
| 171 | +- Increase log level via `logback.xml` reload or environment toggle; capture thread dumps. |
| 172 | +- Check API error payloads for `error_code` and `bank_id` context; correlate with gateway logs. |
| 173 | +- For SSL issues to DB or brokers, use `SSLPoke` and `openssl s_client` to diagnose. |
| 174 | + |
| 175 | +--- |
| 176 | + |
| 177 | +## 9) Quick Commands & Config Snippets |
| 178 | + |
| 179 | +```bash |
| 180 | +docker run -p 8080:8080 \ |
| 181 | + -e OBP_DB_DRIVER=org.postgresql.Driver \ |
| 182 | + -e OBP_DB_URL='jdbc:postgresql://db:5432/obpdb?user=obp&password=******&ssl=true' \ |
| 183 | + -e OBP_OPENID_CONNECT_ENABLED=true \ |
| 184 | + openbankproject/obp-api:latest |
| 185 | +``` |
| 186 | + |
| 187 | +```bash |
| 188 | +kubectl apply -f obpapi_k8s.yaml # Deployment, Service, Postgres PVC |
| 189 | +``` |
| 190 | + |
| 191 | +```properties |
| 192 | +JAVA_OPTIONS="-Drun.mode=production -Xmx768m -Dobp.resource.dir=$JETTY_HOME/resources -Dprops.resource.dir=$JETTY_HOME/resources" |
| 193 | +``` |
| 194 | + |
| 195 | +```sql |
| 196 | +GRANT USAGE, CREATE ON SCHEMA public TO obp_user; |
| 197 | +GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO oobp_userbp; |
| 198 | +GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO obobp_userp; |
| 199 | +ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO obp_user; |
| 200 | +ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO obp_user; |
| 201 | +``` |
| 202 | + |
| 203 | +--- |
| 204 | + |
| 205 | +## 10) Pointers to Further Docs (by topic) |
| 206 | + |
| 207 | +- API Explorer & endpoints (roles, views, consents) |
| 208 | +- OBP‑API README (install, DB, Jetty, logging, production options) |
| 209 | +- API Manager (roles/metrics) |
| 210 | +- OBP‑Hola (OAuth2/mTLS/JWS consent flows) |
| 211 | +- Docker images & tags |
| 212 | +- K8s quickstart manifests |
| 213 | +- ReadTheDocs guide (auth methods, connectors, concepts) |
| 214 | + |
| 215 | +--- |
| 216 | + |
| 217 | +© TESOBE GmbH 2025 AGPL V3 |
0 commit comments