first
This commit is contained in:
JiriUhlir
@@ -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í.
|
||||
@@ -0,0 +1,54 @@
|
||||
# ČSOB PSD2 služba – přehled
|
||||
|
||||
Tato služba je tenký, **bezstavový multi-tenant proxy** mezi klientskými aplikacemi a produkčním
|
||||
**ČSOB PSD2 (Open Banking) API** (Czech Open Banking Standard – COBS). Vystavuje vlastní REST endpointy
|
||||
a každý request 1:1 přeloží na odpovídající ČSOB volání, přičemž doplní povinné COBS hlavičky a naváže
|
||||
mutual TLS pomocí certifikátu předaného v hlavičce.
|
||||
|
||||
## Klíčové principy
|
||||
|
||||
- **Žádné uložené secrets.** Certifikát, OAuth client id/secret, access token, APIKEY i TPP name přicházejí
|
||||
per-request v hlavičkách (viz [authentication.md](authentication.md)). V env jsou jen ne-secret URL a metadata.
|
||||
- **Věrný průchod dat.** Čtecí (GET) odpovědi a méně stabilní těla (consent, direct-debit, sign) se předávají
|
||||
jako surové JSON (`JsonNode`), takže se neztrácí žádné pole. Typovaná těla mají jen platba a trvalý příkaz
|
||||
(pro kvalitní Swagger), s `additionalData` pro forward-kompatibilitu.
|
||||
- **mTLS per-request.** Certifikát z `X-CSOB-Certificate` (Base64 PFX) se načte do paměti (nikdy na disk)
|
||||
a použije pro TLS handshake. `HttpClient` se cachuje podle thumbprintu certifikátu kvůli znovupoužití spojení.
|
||||
- **Reverse proxy.** OpenAPI `servers` se nastavuje z `ROOT_PATH`, takže Swagger „Try it out“ volá přes
|
||||
`/apps/csob/...` (Caddy `handle_path` prefix předtím odstraní).
|
||||
|
||||
## Mapování na ČSOB
|
||||
|
||||
| Tato služba | ČSOB PSD2 (relativně k `CSOB_API_BASE_URL`) |
|
||||
|---|---|
|
||||
| `GET /accounts` | `GET /my/accounts` |
|
||||
| `GET /accounts/{id}/balance` | `GET /my/accounts/{id}/balance` |
|
||||
| `GET /accounts/{id}/transactions` | `GET /my/accounts/{id}/transactions` |
|
||||
| `GET /accounts/{id}/transactions/awaiting` | `GET /my/accounts/{id}/transactions/awaiting` |
|
||||
| `GET /accounts/{id}/standing-orders` | `GET /my/accounts/{id}/standingorders` |
|
||||
| `GET /accounts/{id}/direct-debits` | `GET /my/accounts/{id}/directdebits` |
|
||||
| `POST /payments` | `POST /my/payments` |
|
||||
| `GET /payments/{id}` / `/status` | `GET /my/payments/{id}` / `/status` |
|
||||
| `POST|GET|PUT /payments/{id}/sign/{signId}` | `…/my/payments/{id}/sign/{signId}` |
|
||||
| `…/standing-orders…` | `…/my/standingorders…` |
|
||||
| `…/direct-debits…` | `…/my/directdebits…` |
|
||||
| `POST|GET|DELETE /consents…` | `…/consents…` |
|
||||
|
||||
Cesty jsou centralizované v `Client/CsobApiPaths.cs`.
|
||||
|
||||
## Co je vědomě mimo rozsah (zatím nenapojeno)
|
||||
|
||||
V souladu s philosophy sesterské služby `idoklad` (dokumentovat, co není napojeno):
|
||||
|
||||
- **Batch payments** (`/batchpayments`) a **co-signing list** (`/authorizations`) z COBS PISP.
|
||||
- **PIISP** balance check (`/balanceCheck`).
|
||||
- **Šifrování hlavičkových credentials** (jako v microsoft-365-service) – odloženo, spoléháme na TLS.
|
||||
|
||||
## Ověření a rizika
|
||||
|
||||
- Build je čistý (0 warnings). Lokálně ověřeno: `/health`, `/docs`, OpenAPI `servers`=`/apps/csob`,
|
||||
401 bez credentials, 400 při neplatném certifikátu, dokumentace credential hlaviček per operace.
|
||||
- **Reálné ČSOB volání** vyžaduje platnou PSD2 licenci + eIDAS QWAC certifikát, takže ho nelze otestovat bez
|
||||
produkčních údajů klienta.
|
||||
- **OAuth authorize/token URL** a přesný tvar `sign` sub-cest pocházejí z výzkumu COBS + ČSOB portálu;
|
||||
URL jsou env-konfigurovatelné a cesty centralizované – při odchylce ČSOB portálu je oprava jednoho místa.
|
||||
Reference in New Issue
Block a user