{"revision":"9f11a31dd2951db0","language":"it","entry":{"id":"sign-in-with-veil","kind":"guide","group":"guides","title":"Accedi con Veil","summary":"Fai entrare le persone nella tua app con la loro scheda Veil. L'accesso è una firma della loro chiave di dispositivo, e puoi controllarla da solo sul registro pubblico.","sections":[{"kind":"paragraph","text":"Accedi con Veil è un provider OpenID Connect con issuer https://veil.rip. Funziona qualunque libreria OpenID Connect, a partire dal documento di discovery. L'identità è la scheda: sub è il numero della scheda, lo stesso per tutta la sua vita."},{"kind":"code","language":"shell","code":"curl -fsS 'https://veil.rip/.well-known/openid-configuration'"},{"kind":"heading","text":"Il flusso"},{"kind":"steps","items":["Registra l'app su /developers (una scheda ne risponde, e la pagina di consenso dice Verificata quando la scheda prova il dominio dell'app) o con POST /oidc/register (non verificata, 30 giorni).","Manda il browser a /oidc/authorize con il flusso del codice e PKCE S256. PKCE è obbligatorio per ogni app, anche per quelle confidenziali.","Sulla pagina di consenso la chiave di dispositivo della persona firma un testo che nomina il tuo client_id, il redirect URI, gli scope, il nonce, l'hash del tuo state e il tuo code_challenge. Quella firma è l'accesso. Un browser senza scheda ne fa una o si aggiunge, e torna.","Al tuo redirect URI controlla state e iss, poi scambia il codice su /oidc/token con il verificatore. I token di accesso durano 10 minuti; i refresh token ruotano a ogni uso."]},{"kind":"heading","text":"Scope"},{"kind":"list","items":["openid: il numero della scheda (sub).","profile: il nome, l'immagine, l'alias (preferred_username, o u<n>) e l'indirizzo della scheda.","veil: veil_version e veil_log (con cosa è stato controllato l'accesso), veil_good_standing con i motivi, e veil_consent, il consenso firmato.","veil:accounts: gli account verificati, [{platform, id, handle, url, verified_at}].","veil:orgs: le organizzazioni, [{n, name, role}]. veil:keys: le chiavi di dispositivo attive e le impronte delle chiavi pubbliche di altri sistemi."]},{"kind":"paragraph","text":"La tua app non riceve mai la chiave privata della persona, e non c'è una password: non ne ha."},{"kind":"heading","text":"Cosa verificare"},{"kind":"steps","items":["Il token ID: la firma con la chiave del JWKS che il kid nomina e l'alg di quella chiave (EdDSA o ES256; imposta id_token_signed_response_alg nella tua libreria), iss https://veil.rip, aud e azp il tuo client_id, exp e il tuo nonce. Molte librerie saltano la firma di un token che arriva diretto dal token endpoint, quindi accendi il controllo (in openid-client, enableNonRepudiationChecks).","Senza fidarti del server per l'accesso (scope veil): veil_consent.text comincia con veil-rubrica:oidc-consent:v1; il suo JSON nomina il tuo client_id, il tuo nonce, lo SHA-256 del tuo state, il tuo code_challenge, card uguale a sub e key uguale a veil_consent.key; la sua firma Ed25519 si verifica con quella chiave.","Sul registro pubblico: GET /v1/keys/{key} dice quale versione ha aggiunto la chiave, e GET /v1/identities/{sub} dà il token della scheda e la sua versione corrente. Per ogni versione da quella alla corrente, GET /v1/identities/{sub}/versions/{v}/proof deve avere una voce che nomina il token della scheda e la versione, si lega alla precedente e sta sotto un checkpoint firmato dal registro e controfirmato dai testimoni. La prima aggiunge la chiave come dispositivo, nessuna dopo la revoca, e la voce di veil_version sta a veil_log.index. Il codice è nella guida.","Prima di fidarti della persona adesso, leggi userinfo: veil_good_standing diventa subito false per una sospensione, un subentro in corso, una scheda in chiusura o una chiave d'accesso revocata."]},{"kind":"paragraph","text":"CORS copre solo il documento di discovery e il JWKS. Un'app nel browser scambia il codice attraverso il proprio server. Le chiavi API qui non c'entrano."},{"kind":"heading","text":"Riferimento"},{"kind":"links","ids":["oidc-discovery","oidc-jwks","oidc-authorize","oidc-token","oidc-userinfo","oidc-revoke","oidc-introspect","oidc-register","oidc-logout","oidc-clients","oidc-client-create","oidc-apps"]}],"related":["api-keys","signed-requests","proofs"],"errors":[],"documentationUrl":"https://veil.rip/docs/sign-in-with-veil?lang=it"}}