veil

Accedi con Veil

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.

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.

cURL
curl -fsS 'https://veil.rip/.well-known/openid-configuration'

Il flusso#

  1. 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).
  2. Manda il browser a /oidc/authorize con il flusso del codice e PKCE S256. PKCE è obbligatorio per ogni app, anche per quelle confidenziali.
  3. 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.
  4. 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.

Scope#

  • 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.

La tua app non riceve mai la chiave privata della persona, e non c'è una password: non ne ha.

Cosa verificare#

  1. 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).
  2. 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.
  3. 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.
  4. 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.

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.

Riferimento#

  • GET
    Leggi la configurazione OpenIDIl documento di discovery di Accedi con Veil: issuer https://veil.rip, gli endpoint, gli scope, gli algoritmi e i metodi.
    /.well-known/openid-configuration
  • GET
    Leggi le chiavi di firma del providerLe chiavi pubbliche che firmano i token ID: una Ed25519 (EdDSA) e una P-256 (ES256), più la coppia precedente per 30 giorni dopo una rotazione.
    /oidc/jwks
  • GET
    Comincia un accessoL'endpoint di autorizzazione. Controlla l'app e il suo redirect URI, tiene la richiesta 30 minuti e mostra la pagina di consenso, dove firma la chiave di dispositivo della persona.
    /oidc/authorize
  • POST
    Scambia un codice o un refresh tokenL'endpoint dei token: il codice con il verificatore PKCE, o un refresh token, per un token di accesso, un token ID e un nuovo refresh token.
    /oidc/token
  • GET
    Leggi i dati della personaGli stessi dati del token ID, dallo stato della scheda adesso: una chiave revocata, un subentro o una sospensione cambiano subito la risposta.
    /oidc/userinfo
  • POST
    Revoca un tokenRFC 7009: l'app revoca uno dei suoi token. Un refresh token chiude tutti i token del suo accesso.
    /oidc/revoke
  • POST
    Ispeziona un tokenRFC 7662, per le app confidenziali: se uno dei token dell'app è attivo adesso.
    /oidc/introspect
  • POST
    Registra un'app senza schedaRFC 7591, aperta: un'app di cui nessuna scheda risponde. La pagina di consenso la dice non verificata, e sparisce 30 giorni dopo la registrazione.
    /oidc/register
  • GET
    Esci da un'appLogout avviato dall'app. Con id_token_hint finiscono i token di quell'accesso; il browser torna solo a un indirizzo che l'app ha registrato esattamente.
    /oidc/logout
  • GET
    Elenca le app di una schedaLe app registrate da una scheda per Accedi con Veil, senza i segreti.
    /v1/developer/accounts/{n}/oidc-clients
  • POST
    Registra un'appUna persona o un proprietario dell'organizzazione firma la registrazione. Un'app confidenziale con client_secret_basic riceve il segreto una volta.
    /v1/developer/accounts/{n}/oidc-clients
  • GET
    Elenca le app in cui una persona è entrataLe app in cui la scheda è entrata, con gli ultimi cinque accessi di ognuna e il consenso firmato dalla sua chiave di dispositivo, così il proprietario controlla ogni accesso.
    /v1/identities/{n}/oidc-apps

Leggi questa voce in JSON