# OIDC / SIOP v2 Integration Guide ForTrust oferă un bridge **SIOP v2 peste OpenID4VP** pentru Relying Parties terți. Aplicația ta vorbește OIDC clasic (`/authorize`, `/userinfo`) — portofelul EUDI al utilizatorului face prezentarea VP-ului cu credențialele lui. Tu nu atingi mdoc, COSE, trust chain sau SD-JWT VC; primești pur și simplu un JSON cu claim-urile verificate. ## TL;DR (2 minute) ```bash # 1. Inițiază o sesiune OIDC curl "https://issuer.example.org/oidc/authorize/?\ client_id=my-app&\ redirect_uri=https://my-app/callback&\ nonce=$(openssl rand -hex 16)&\ scope=openid+profile+eudi_pid&\ state=$(openssl rand -hex 16)&\ format=json" # → { "session_id": "...", "wallet_uri": "mdoc-openid4vp://...", # "userinfo_uri": ".../oidc/userinfo//", # "expires_at": "..." } # 2. Arată QR-ul din wallet_uri utilizatorului. Când scanează, # backend-ul ForTrust procesează VP-ul asincron. # 3. Poll pe userinfo sau așteaptă callback la redirect_uri curl "https://issuer.example.org/oidc/userinfo//" # → 202 pending, apoi 200 cu claims când e completed ``` ## Arhitectura flow-ului ``` ┌──────────┐ 1 /authorize ┌──────────────┐ 2 request_uri ┌──────────┐ │ RP (tu) │─────────────────▶│ ForTrust │◀────────────────│ wallet │ │ │ │ OIDC bridge │ │ (phone) │ │ │ 5 callback + │ │ 3 vp_token │ │ │ │ userinfo │ │◀────────────────│ │ │ │◀─────────────────│ │ 4 verify + │ │ └──────────┘ └──────────────┘ store claims└──────────┘ ``` 1. RP → `GET /oidc/authorize/` cu client_id, redirect_uri, nonce, scope, state 2. Wallet fetch-uiește JWT request_object de la `/oidc/request//` 3. Wallet prezintă VP-ul via `POST /oidc/response/` (signed ECDSA) 4. Bridge-ul verifică semnătura + trust chain + policy + nonce match 5. RP este notificat la `redirect_uri?code=&state=` și preia claim-urile la `GET /oidc/userinfo//` ## Endpoints | Endpoint | Metodă | Cine apelează | Scop | |---|---|---|---| | `/.well-known/openid-configuration` | GET | oricine | Discovery metadata (RFC 8414) | | `/oidc/authorize/` | GET | RP | Inițiază o sesiune, returnează QR + IDs | | `/oidc/request//` | GET | wallet | Signed JWT request_object pentru VP | | `/oidc/response/` | POST | wallet | direct_post cu `vp_token` + `presentation_submission` | | `/oidc/userinfo//` | GET | RP | Claim-uri verificate (JSON) | | `/oidc/jwks.json` | GET | oricine | Cheile publice ES256 | | `/oidc/demo/` | GET | dev/debug | Playground vizual end-to-end | | `/admin/oidc/oidcsession/` | GET | staff | Inspectare sesiuni | ## Scope reference Scope-ul OIDC trimis la `/oidc/authorize/` controlează **două** lucruri: (a) ce atribute cere wallet-ul din credențial (minimization), și (b) ce atribute returnează `/userinfo/` la RP. | Scope | Flow wallet | Atribute returnate | |---|---|---| | `openid` (min) | identity (PID complet) | toate | | `openid profile` | identity | family_name, given_name, birth_date, birth_place, nationality, sex, portrait | | `openid profile address` | identity | + resident_address | | `openid eudi_pid` | identity | toate PID-urile standard EUDI | | `openid age_over_18` | age-only | **doar** `age_over_18` (boolean) | Echivalența cu verifier-ul mdoc: - `scope=openid+profile+eudi_pid` ≡ `/verifier/v1/identity/` - `scope=openid+age_over_18` ≡ `/verifier/v1/age/` ## Parametrii `/oidc/authorize/` | Param | Obligatoriu | Notă | |---|---|---| | `client_id` | da | identificator al RP-ului (orice string, e vizibil în admin) | | `redirect_uri` | da | URL unde utilizatorul e trimis după verificare | | `nonce` | da | random unic per sesiune, prevenire replay | | `scope` | no (default `openid`) | vezi tabelul de mai sus | | `state` | no | CSRF token al RP-ului, e echoat în callback | | `response_type` | no (default `vp_token`) | `vp_token` sau `id_token vp_token` | | `format` | no | `json` → răspuns JSON în loc de HTML cu QR | ## Exemple ### Python (RP backend) ```python import secrets, requests, urllib.parse ISSUER = "https://issuer.example.org" def start_login(redirect_uri): nonce = secrets.token_urlsafe(24) state = secrets.token_urlsafe(24) r = requests.get(f"{ISSUER}/oidc/authorize/", params={ "client_id": "my-app", "redirect_uri": redirect_uri, "nonce": nonce, "scope": "openid profile eudi_pid", "state": state, "response_type": "vp_token", "format": "json", }) r.raise_for_status() data = r.json() # Persistă state+nonce+session_id în session-ul web al utilizatorului. return data # { session_id, wallet_uri, userinfo_uri, ... } def handle_callback(code, state, expected_state): assert state == expected_state, "CSRF state mismatch" r = requests.get(f"{ISSUER}/oidc/userinfo/{code}/") if r.status_code == 202: return {"pending": True} r.raise_for_status() info = r.json() claims = info["claims"] # ex: claims["given_name"], claims["family_name"], claims["birth_date"] return info ``` ### Node.js (RP backend) ```js import crypto from "crypto"; const ISSUER = "https://issuer.example.org"; export async function startLogin(redirectUri) { const nonce = crypto.randomBytes(24).toString("base64url"); const state = crypto.randomBytes(24).toString("base64url"); const u = new URL(`${ISSUER}/oidc/authorize/`); u.searchParams.set("client_id", "my-app"); u.searchParams.set("redirect_uri", redirectUri); u.searchParams.set("nonce", nonce); u.searchParams.set("scope", "openid profile eudi_pid"); u.searchParams.set("state", state); u.searchParams.set("response_type", "vp_token"); u.searchParams.set("format", "json"); const r = await fetch(u); if (!r.ok) throw new Error(`authorize ${r.status}`); return await r.json(); } export async function fetchUserinfo(code) { const r = await fetch(`${ISSUER}/oidc/userinfo/${code}/`); if (r.status === 202) return { pending: true }; if (!r.ok) throw new Error(`userinfo ${r.status}`); return await r.json(); } ``` ### Browser JS (redirect flow, fără backend) ```html ``` În `callback.html`: ```js const params = new URLSearchParams(location.search); const code = params.get("code"); const state = params.get("state"); if (state !== sessionStorage.getItem("oidc_state")) { document.body.textContent = "CSRF state mismatch"; } else { fetch(`${ISSUER}/oidc/userinfo/${code}/`) .then(r => r.json()) .then(info => console.log("claims:", info.claims)); } ``` ## Răspunsul `/oidc/userinfo//` ```json { "sub": "sha256:7a2e5c8f...", "iss": "https://issuer.example.org", "aud": "my-app", "nonce": "...", "scope": "openid profile eudi_pid", "verified_at": "2026-04-21T08:45:33+00:00", "claims": { "family_name": "MINEU", "given_name": "MIHAELA ELENA", "birth_date": "1980-07-19", "age_over_18": true, "nationality": ["RO"], "issuing_country": "RO", "document_number": "103113", "portrait": "b64:/9j/4AAQSkZJRg..." } } ``` Note: - `sub` este un hash pairwise (SHA-256 din `family_name|given_name|birth_date|client_id`). Se păstrează stabil pentru același utilizator + aceeași aplicație, diferă între RP-uri. - `portrait` vine base64-encoded cu prefix `b64:`. Pentru afișare, strip-uiește `b64:` și folosește ca `data:image/jpeg;base64,...`. - `age_over_18` e boolean. Pentru flow-ul age-only (scope `age_over_18`) e singurul claim prezent. ## Coduri de răspuns | Endpoint | Status | Când | |---|---|---| | `/authorize/` | 400 `invalid_request` | lipsesc params obligatorii | | `/authorize/` | 400 `invalid_scope` | scope-ul nu conține `openid` | | `/userinfo/` | 202 `authorization_pending` | sesiunea e încă PENDING | | `/userinfo/` | 200 | sesiunea e COMPLETED | | `/userinfo/` | 400 `verification_failed` | VP verification a picat | | `/userinfo/` | 410 `session_expired` | a depășit `OIDC_SESSION_TTL_SECONDS` | | `/userinfo/` | 404 `session_not_found` | session_id necunoscut | | `/response/` | 400 `invalid_request` | lipsesc vp_token+state | | `/response/` | 400 `nonce_mismatch` | wallet-ul n-a folosit nonce-ul așteptat | | `/response/` | 409 `session_already_terminal` | s-a mai primit un VP | ## Discovery ```bash curl https://issuer.example.org/.well-known/openid-configuration | jq ``` Returnează un document standard OIDC core cu `issuer`, `authorization_endpoint`, `userinfo_endpoint`, `jwks_uri`, `scopes_supported`, `claims_supported`, `vp_formats_supported` (mso_mdoc, vc+sd-jwt). ## Rulează demo-ul local După pornirea backend-ului (`python manage.py runserver 0.0.0.0:8000`): 1. Deschide **http://:8000/oidc/demo/** — o pagină fictivă "ACME Travel" cu buton "Sign in with ForTrust". 2. Alege scope-ul (identity / age / profile). 3. Apasă butonul → pagina cu QR din `/oidc/authorize/`. 4. Scanează QR cu portofelul EUDI. 5. La completare, browser-ul afișează claim-urile live, iar demo-RP-ul primește callback la `/oidc/demo/callback/?code=&state=`. Pentru inspectare: `/admin/oidc/oidcsession/`. ## Securitate & operare - **Verificare semnătură:** bridge-ul refolosește `verifier.views._verify_standard_v1`, care validează COSE_Sign1 cu cheia din MSO, verifică trust chain-ul x5c împotriva trust registry-ului, rulează revocation check pe status list, și aplică limit_disclosure (ARF §6). - **Nonce:** nonce-ul OIDC trimis de RP este folosit ca session transcript nonce pentru mdoc. Dacă wallet-ul reutilizează un nonce vechi → FAIL. - **Policy check:** claim-urile prezentate sunt comparate cu `RelyingParty.allowed_attributes` al client_id-ului. RP-ul trebuie înregistrat în `/admin/rp_registry/relyingparty/` ca să scape de policy warnings. - **TTL:** `OIDC_SESSION_TTL_SECONDS` (default 600). Setează în `.env` pentru a-l schimba. - **HTTPS:** în producție (`DEPLOY_PROFILE=prod`) toate endpoint-urile sunt HTTPS-only (`SECURE_SSL_REDIRECT`, HSTS preload, CSRF secure cookies). ## Network access via PID (ARF 2.8.0 §3.11) `scope=openid network_access` este alternativa **ARF-compliant** la `wifi`: nu cere un credențial dedicat WiFi, ci doar **atribute PID** pe care RP-ul (hotspot-ul, operatorul rețelei) le folosește ca bază pentru a acorda acces. Modelul se bazează pe §3.11 — *"Relying Parties request attributes; based on those, they make access decisions"*. Soluția rezolvă direct gap-ul §4.4.3.1 "Wallet Unit Selection": dacă utilizatorul are două wallet-uri (unul mdoc-PID, altul cu Pas WiFi), OS-ul nu are cum să rute-eze `mdoc-openid4vp://` pentru doctype WiFi la wallet-ul potrivit. Cu `network_access` wallet-ul mdoc răspunde direct — nu e nevoie de un Pas WiFi separat. **Flow:** 1. RP: `GET /oidc/authorize/?scope=openid network_access&...` 2. Bridge cere PID (`family_name`, `given_name`, `birth_date`, `age_over_18`, `nationality`, `issuing_country`). 3. Wallet-ul mdoc prezintă PID → bridge verifică semnătura. 4. Bridge rulează `settings.NETWORK_ACCESS_POLICY` asupra claim-urilor. 5. Dacă politica e PASS → bridge sintetizează `{ssid, password}` și construiește URI-ul `WIFI:...`. Dacă e FAIL → răspunsul include `network_access_granted=false` și motivul. **Configurare policy (`.env` / `settings.py`):** ```jsonc NETWORK_ACCESS_POLICY='{ "ssid": "acasa24", "password": "parola-reala", "require_age_over_18": true, "allowed_nationalities": ["RO"], "allowed_issuing_countries": ["RO"] }' ``` Policy-check e server-side, ceea ce înseamnă că parola nu iese niciodată pe telefon în clear până când bridge-ul nu a verificat PID-ul ARF-valid. **Claim-uri returnate la `/userinfo/`** pentru `scope=openid network_access`: ```json { "claims": { "family_name": "MINEU", "given_name": "MIHAELA ELENA", "birth_date": "1980-07-19", "age_over_18": true, "nationality": ["RO"], "issuing_country": "RO", "network_access_granted": true, "network_access_reason": "granted by PID policy", "ssid": "acasa24", "wifi_uri": "WIFI:T:WPA;S:acasa24;P:...;H:false;;", "wifi_qr_b64": "..." } } ``` ## WiFi auto-connect flow `scope=openid wifi` cere o prezentare a credențialului WiFi (doctype `ro.fortrust.wifi.access.1`). Bridge-ul verifică VP-ul, extrage SSID-ul + perioada de valabilitate, și construiește un URI de forma: ``` WIFI:T:;S:;P:;H:false;; ``` Parola **nu** se ia din credențial (ARF-aligned: credentialul certifică drepturi de acces, nu parolă WPA). Sursele, în ordinea priorității: 1. **`claims["password"]`** — dacă credențialul conține un atribut custom `password` (rar). 2. **`WIFI_ACCESS_PASSWORDS={"ssid": "..."}`** — map JSON în `.env`/settings; recomandat pentru demo multi-SSID. 3. **`WIFI_ACCESS_DEFAULT_PASSWORD=...`** — fallback single-SSID. 4. **Fără parolă** → `T:nopass` (wallet-ul se autentifică EAP out-of-band sau rețeaua e deschisă). Răspunsul `/userinfo/` pentru flow-ul WiFi include câmpul derivat `wifi_password_source` pe una dintre valorile: `wallet_credential`, `server_map`, `server_default`, `none_eap_or_open`. Aplicația RP poate afișa un badge operatorului ("parolă configurată de server"). În producție, omite ambele variabile — deployment-urile reale folosesc EAP-TLS/Passpoint, iar `WIFI:` QR-ul cu `T:nopass` e suficient pentru a pre-umple SSID-ul pe telefon, autentificarea făcându-se prin credențialul prezentat (WPA2-Enterprise EAP). ## BBS+ unlinkable presentations (ARF §7.4.3.5.2) Pentru maximum-privacy flows (ex. guest WiFi hotspot care nu trebuie să poată corela vizitatori cross-sesiune), wallet-ul poate prezenta VP-uri în format `ldp_vp` cu `BbsBlsSignatureProof2020`. Backend-ul expune: - `POST /bbs/issue/` — emitere VC semnat BBS+ (rulează în Node sidecar) - `POST /bbs/derive/` — derivarea unui proof ZKP unlinkable din VC - `POST /bbs/verify/` — verificare proof la RP - `GET /bbs/supported-ciphersuites/` — ciphersuite enumeration `/.well-known/openid-configuration` advertizează `ldp_vp` în `vp_formats_supported` ca al treilea format pe lângă `mso_mdoc` și `vc+sd-jwt`. Wallet-ul alege ce format cere verificatorul per request_object prin `client_metadata.vp_formats`. Environment: `BBS_SERVICE_URL=http://127.0.0.1:3001` (default) — fără sidecar-ul Node, endpoint-urile /bbs/* returnează 503. ## Vezi și - **Verifier mdoc QR (fără OIDC):** `/verifier/v1/identity/`, `/verifier/v1/age/` - **Trust registry:** `/admin/trust_registry/trustedentity/` - **RP policy:** `/admin/rp_registry/relyingparty/` - **Deploy readiness:** `/admin/deploy-status/` (vezi ce mai lipsește pentru prod) - **Spec:** OpenID Connect Core 1.0, OID4VP Draft 22, SIOP v2 (OpenID4VC)