first

2026-06-18 11:05:46 +02:00
parent f44ffae9fc
commit 09db30a3ca
84 changed files with 3952 additions and 15 deletions
@@ -0,0 +1,86 @@
+# Autentizace a OAuth2 / SCA flow
+
+ČSOB PSD2 vyžaduje tři vrstvy:
+
+1. **Mutual TLS** s eIDAS QWAC certifikátem (na transportní vrstvě).
+2. **APIKEY** identifikující registrovanou TPP aplikaci.
+3. **OAuth2 Bearer access token** prokazující souhlas (consent) PSU – získaný Authorization Code flow.
+
+Tato služba je multi-tenant a **neukládá nic** – všechny tři vrstvy dostává per-request v hlavičkách.
+
+## Credential hlavičky
+
+| Hlavička | Povinná pro | Předáno do ČSOB jako |
+|---|---|---|
+| `X-CSOB-Certificate` (Base64 PFX) | vše (mTLS) | TLS klientský certifikát |
+| `X-CSOB-Certificate-Password` | volitelné | – |
+| `X-Access-Token` | AISP/PISP/consents | `Authorization: Bearer` |
+| `X-API-Key` | AISP/PISP/consents | `APIKEY` |
+| `X-TPP-Name` | AISP/PISP/consents | `TPP-Name` |
+| `X-CSOB-Client-Id` | `/oauth/*` | OAuth `client_id` |
+| `X-CSOB-Client-Secret` | `/oauth/token`, `/oauth/refresh` | OAuth `client_secret` |
+
+`X-Request-ID` (UUID) a `Date` (RFC 7231) doplňuje služba sama.
+
+### Příprava Base64 PFX
+
+```bash
+base64 -w0 client_qwac.pfx        # Linux/macOS  -> hodnota X-CSOB-Certificate
+certutil -encode client_qwac.pfx out.txt   # Windows (odstranit hlavičky/řádky)
+```
+
+Heslo k PFX jde do `X-CSOB-Certificate-Password`. Hodnoty posílej **výhradně přes HTTPS**.
+
+## OAuth2 Authorization Code flow
+
+```
+1. GET /oauth/authorization-url?redirect_uri=...&scope=...&state=...
+   hlavičky: X-CSOB-Client-Id
+   -> { "authorizationUrl": "...", "state": "..." }
+
+2. Klient přesměruje PSU na authorizationUrl. PSU se přihlásí a udělí souhlas v ČSOB.
+   ČSOB přesměruje zpět na redirect_uri s parametrem ?code=...&state=...
+
+3. POST /oauth/token   { "code": "...", "redirectUri": "..." }
+   hlavičky: X-CSOB-Certificate (+password), X-CSOB-Client-Id, X-CSOB-Client-Secret
+   -> { "access_token": "...", "refresh_token": "...", "expires_in": ... }
+
+4. AISP/PISP volání s hlavičkami:
+   X-CSOB-Certificate, X-Access-Token, X-API-Key, X-TPP-Name
+
+5. Obnova: POST /oauth/refresh { "refreshToken": "..." } (stejné hlavičky jako krok 3)
+```
+
+### Scopes (COBS)
+
+`aisp.accounts`, `aisp.balances`, `aisp.transactions`, `aisp.standingorders`, `aisp.directdebits`,
+`aisp.notifications`, `pisp.payments`, `pisp.standingorders`, `pisp.directdebits`, `pisp.accounts`.
+
+## PISP autorizace platby (SCA / sign flow)
+
+```
+1. POST /payments (body s platbou)
+   -> odpověď obsahuje signInfo.signId a instructionStatus
+
+2. POST /payments/{id}/sign/{signId}
+   -> autorizační detaily pro PSU (např. authorizationType, href.url pro redirect SCA)
+
+3. (volitelně) GET /payments/{id}/sign/{signId} – stav autorizace
+   (volitelně) PUT /payments/{id}/sign/{signId} – finalizace
+
+4. GET /payments/{id}/status – konečný stav (ACTC, ACSC, RJCT, …)
+```
+
+Stejný sign flow platí pro `/standing-orders` a `/direct-debits`.
+
+## Chybové odpovědi
+
+Služba vrací `application/problem+json`:
+
+- `401` – chybí povinná credential hlavička (`missingHeaders`).
+- `400` – neplatný Base64 PFX nebo špatné heslo certifikátu.
+- upstream status (4xx/5xx) – chyba z ČSOB; pole `csobErrorCodes` a `upstreamBody` nesou originální payload.
+- `502` – ČSOB nedostupné nebo selhal mTLS handshake (např. neplatný/expirovaný certifikát).
+- `504` – timeout.
+
+Secrets se nikdy nelogují ani nevracejí.