Come creare un'app mobile per pass digitali e tessere di accesso

Chiarisci il caso d'uso e le metriche di successo

Prima di scegliere QR vs NFC — o Apple Wallet vs un pass in-app — definisci con precisione cosa significa “pass digitale” nel tuo progetto. Una singola app può emettere badge di accesso per dipendenti, tessere membri, biglietti per eventi o pass visitatori a tempo, e ciascuno richiede controlli d'identità, revoca e frequenza di aggiornamento differenti.

Definisci il tipo di pass (e il workflow nel mondo reale)

Scrivi cosa succede end-to-end, includendo chi approva e cosa significa “successo” alla porta.

Per esempio:

• Badge di accesso: legato a una persona; serve sblocco rapido; revoca immediata al termine del rapporto di lavoro.
• Pass membro: può privilegiare iscrizione e rinnovo semplici rispetto a un controllo accessi stringente.
• Biglietti: scansione ad alto rendimento, anti-duplicazione, finestra di validità breve.
• Pass visitatore: sponsorizzato da un dipendente; scade automaticamente; può essere limitato ad aree specifiche.

Identifica gli utenti principali (non solo gli “end user”)

Elenca le persone che interagiscono con il sistema e i loro obiettivi:

• Dipendenti/clienti/visitatori: configurazione semplice, ingresso affidabile, bassa frizione.
• Admin/personale di sicurezza: emettere, revocare, auditare, gestire eccezioni (telefono perso, ingresso negato).
• Personale reception/eventi: verifica rapida e troubleshooting in momenti di afflusso.

Scegli metriche di successo misurabili

Seleziona metriche che mappano sia l'esperienza utente che le operazioni:

• Tasso di attivazione: % di utenti invitati che aggiungono/abilitano il pass.
• Tasso di apertura porta al primo tentativo: unlock/scan che riescono al primo tentativo.
• Tempo di emissione: da richiesta/approvazione a credenziale utilizzabile.
• Ticket di supporto: volume, cause principali e tempo di risoluzione.

Decidi presto l'accesso offline (e i suoi limiti)

Se porte o scanner devono funzionare senza connettività, definisci per quanto tempo l'accesso offline rimane valido (minuti, ore, giorni) e cosa succede quando un pass viene revocato mentre è offline. Questa scelta influenza il design della credenziale, la configurazione del lettore e il modello di sicurezza.

Scegli come verrà presentato il pass: QR, NFC e fallback

Il tuo “pass digitale” vale tanto quanto il momento in cui viene scansionato o tappato. Prima di costruire schermate, decidi cosa il lettore accetterà e cosa gli utenti possono presentare in condizioni reali (folla, connettività scarsa, freddo, guanti).

Opzioni comuni di presentazione (e a cosa servono)

I codici QR sono universali ed economici: qualsiasi scanner a fotocamera — o anche la fotocamera del telefono per verifica visiva — può funzionare. Sono più lenti per persona rispetto al tap e più facili da copiare se usi codici statici.

NFC (tap) sostituisce la tessera fisica. È veloce e familiare, ma dipende da lettori compatibili e dal supporto dispositivo. Ha anche vincoli di piattaforma (ad esempio, se puoi emulare una carta o devi usare credenziali basate su Wallet).

Bluetooth (hands-free) può migliorare accessibilità e velocità, ma è più complesso da tarare (portata, interferenze) e può generare momenti “perché non si è aperto?”.

Link one-time / codici in-app (codici rotanti, token firmati) sono fallback solidi e possono ridurre il rischio di clonazione. Richiedono logica in-app e, a seconda del design, potrebbero chiedere connettività periodica.

Mappa la tecnologia ai tuoi vincoli

Abbina ogni metodo a: hardware lettore esistente, throughput (persone/minuto), necessità offline, budget e carico di supporto. Esempio: tornelli ad alto traffico spesso richiedono la velocità di NFC; ingressi temporanei per eventi possono tollerare QR.

Scegli un metodo primario e un fallback deliberato

Un pattern pratico è NFC primario + QR fallback. NFC gestisce la velocità; QR copre telefoni più vecchi, NFC rotto o siti senza lettori NFC.

Pianifica gli scenari di “giornata storta”

Documenta esattamente cosa succede quando:

• Telefono bloccato: il pass può essere presentato dalla lock screen (Wallet) o gli utenti devono sbloccare l'app?
• Nessuna rete: la credenziale è verificabile offline (token firmato, diritto memorizzato), e per quanto tempo?
• Batteria bassa / telefono morto: offri un QR stampato temporaneo, override in loco o una tessera fisica di backup?

Queste decisioni influenzano l'integrazione dei lettori, la postura di sicurezza e il playbook di supporto.

Decide: pass in-app vs Apple Wallet e Google Wallet

Scegliere dove “vive” la credenziale è una decisione precoce perché influisce su integrazione lettori, UX e vincoli di sicurezza.

Opzione A: pass in-app (dentro la tua app)

Un pass in-app è reso e gestito dalla tua app. Ti dà il massimo controllo su UI, autenticazione, analytics e flussi personalizzati.

Pro: pieno branding e schermate personalizzate, autenticazione flessibile (biometria, step-up), contesto ricco (mappe sito, istruzioni) e supporto più semplice per tipi multipli di credenziali.

Contro: gli utenti devono aprire la tua app (o usare un widget/azione rapida che costruisci), l'accesso dalla lock-screen è limitato a livello OS e il comportamento offline è completamente tua responsabilità.

Opzione B: Apple Wallet / Google Wallet

I pass Wallet (per esempio, PKPass su iOS) sono familiari e pensati per una presentazione rapida.

Pro: alta fiducia e discoverability, accesso dalla lock-screen/quick access, gestione OS robusta per la presentazione e comportamento rapido “mostra il codice”.

Contro: vincoli di piattaforma più stretti (formati barcode/NFC supportati, UI limitata), gli aggiornamenti seguono le regole del Wallet e potresti aver bisogno di configurazioni specifiche Apple/Google (certificati, configurazione issuer e talvolta revisione). La telemetria approfondita è inoltre più difficile.

Una regola pratica di decisione

Usa Wallet quando contano velocità, familiarità e presentazione “sempre disponibile” (visitatori, eventi, workflow con barcode). Usa in-app quando ti servono controlli d'identità più forti, workflow complessi o logiche di credenziale avanzate (accesso staff multi-sito, approvazioni, ruoli).

Tipi multipli di pass, template e branding

Se servi più organizzazioni, pianifica template per organizzazione: loghi, colori, istruzioni e campi dati diversi. Alcune squadre rilasciano entrambe le cose: un pass Wallet per ingresso rapido e una credenziale in-app per amministrazione e supporto.

Ciclo di vita del pass che devi supportare

Indipendentemente dal contenitore, definisci le azioni di ciclo di vita che puoi innescare:

• Issue (prima iscrizione)
• Update (nome, livello di accesso, scadenza, modifiche visive)
• Suspend (sospensione temporanea)
• Revoke (rimozione permanente)
• Re-issue (nuovo dispositivo, telefono perso, sospetto compromesso)

Mantieni queste operazioni coerenti tra in-app e Wallet così il team operativo può gestire l'accesso senza workaround manuali.

Progetta il modello dati e il ciclo di vita del pass

Un modello dati pulito rende il resto del sistema prevedibile: emettere un pass, validarlo su un lettore, revocarlo e indagare su incidenti dovrebbero essere query semplici, non congetture.

Entità core da modellare

Inizia con un piccolo set di oggetti “first-class” e cresci solo quando necessario:

• Utente: la persona che deve ottenere l'accesso.
• Organizzazione / Sito: chi possiede il sistema (e dove si applica l'accesso).
• Pass: la “carta” visibile all'utente (ciò che l'app o il wallet mostra).
• Credenziale: il token presentato a un lettore (credenziale NFC, payload QR, ecc.). Un pass può avere più credenziali nel tempo.
• Dispositivo: l'istanza del telefono che detiene o mostra la credenziale.
• Lettore / Porta: l'endpoint fisico (ID lettore, ID porta, posizione).
• Policy di accesso: regole che collegano utenti/gruppi a porte e orari.

Questa separazione aiuta quando un utente cambia telefono: il pass può restare concettualmente lo stesso mentre credenziali ruotano e dispositivi cambiano.

Stati del pass e ciclo di vita

Definisci stati espliciti e permetti solo transizioni deliberate:

• pending (invitato/registrazione)
• active (utilizzabile)
• suspended (bloccato temporaneamente)
• expired (scadenza temporale)
• revoked (invalidato permanentemente)

Esempi di transizioni: pending → active dopo verifica; active → suspended per violazioni di policy; active → revoked alla fine del rapporto di lavoro; suspended → active dopo ripristino admin.

Identificatori e mappatura ai lettori

Pianifica ID unici a due livelli:

• Un pass_id stabile (interno) per ciclo di vita e supporto.
• Uno o più valori credential_id / token_id che i lettori possono convalidare.

Decidi come i lettori mappano i token alle regole di accesso: lookup diretto (token → utente → policy) o token → gruppo policy (più veloce al margine). Mantieni gli identificatori non indovinabili (random, non sequenziali).

Log di audit: cosa registrare e dove

Tratta i log di audit come append-only e separati dalle tabelle di stato corrente. Registra almeno:

• issue (chi ha emesso, a chi, dispositivo, orario)
• scan (lettore, risultato, codice motivo)
• deny (mismatch policy, scaduto, revocato, errore offline)
• revoke/suspend/reactivate (attore, giustificazione, orario)

Questi eventi diventano fonte di verità per troubleshooting, compliance e rilevamento abusi.

Costruisci il flusso di iscrizione utente e di emissione del pass

Un progetto di pass digitale vince o fallisce nei “primi 5 minuti”: quanto velocemente una persona reale può iscriversi, ricevere una credenziale e capire cosa fare dopo.

Percorsi di iscrizione (scegli 1–2 principali)

La maggior parte dei team supporta una combinazione di questi passaggi, a seconda di sicurezza e dimensione del deployment:

• Link di invito: un admin (o sistema HR) genera un link a tempo limitato. L'utente lo apre sul telefono e arriva direttamente nel flusso corretto.
• Verifica Email/SMS: invia un codice usa e getta per confermare il numero di telefono o l'email legata al record d'identità.
• SSO: per dipendenti, usa SAML/OIDC così il pass viene emesso solo dopo il login corporate.
• Approvazione admin: per siti ad alta sicurezza, metti la richiesta in una coda di revisione (con codici motivo, timestamp e audit trail).

Un pattern pratico è: link di invito → verifica email/SMS → (opzionale) SSO → emissione pass.

Come viene aggiunto il pass (e come guidare gli utenti)

Progetta l'emissione in modo che gli utenti non debbano “capirlo” da soli:

• Pass in-app: la credenziale vive dentro la tua app; controlli aggiornamenti e UI. Buono quando servono autenticazioni personalizzate, regole offline o comportamenti speciali del lettore.
• Aggiunta al Wallet: mostra un pulsante “Add to Apple Wallet” / “Add to Google Wallet” dopo la verifica. Supporta anche deep link che aprono la schermata di aggiunta al wallet dall'invito.
• Fallback QR per inviti on-site: in reception, consenti a un chiosco di mostrare un QR che apre il link di iscrizione (utile quando l'utente non trova l'email).

Mantieni i testi estremamente chiari: a cosa serve il pass, dove apparirà (app vs wallet) e cosa fare alla porta.

Cambi di dispositivo e regole di riemissione

Pianifica presto per evitare ticket di supporto:

• Nuovo telefono: fornisci un flusso di riautenticazione self-serve che riautentica l'identità e riemette il pass.
• Dispositivi multipli: decidi se permetterlo. Se sì, limita il numero e mostra i dispositivi attivi nelle impostazioni.
• Dispositivo perso: abilita revoca remota istantanea, poi consenti la riemissione dopo nuova verifica.

Messaggi utente per guasti reali

Scrivi messaggi amichevoli e specifici per:

• Accesso negato (e il passo successivo: “Contatta la sicurezza” vs “Riprova dopo aggiornamento”)
• Pass scaduto (includi data di scadenza e azione di rinnovo)
• Problemi di connettività (spiega cosa funziona ancora offline e come recuperare quando online)

Una buona emissione non è solo “creare un pass”: è un percorso completo e comprensibile con vie di recupero prevedibili.

Autenticazione e Autorizzazione per Utenti e Admin

I pass digitali sono affidabili quanto l'identità e i permessi che li governano. Tratta autenticazione (chi sei) e autorizzazione (cosa puoi fare) come funzionalità di prodotto, non solo come impiantistica.

Scegliere un approccio di autenticazione

Scegli il metodo di login che corrisponde al tuo pubblico e al livello di rischio:

• Email + one-time passcode (OTP): semplice per i consumatori, meno reset password.
• Passwordless “magic link”: ottimo per bassa frizione, ma richiede delivery email affidabile.
• SSO / identity enterprise (SAML/OIDC): migliore per dipendenti, contractor e campus; lega l'accesso alle policy HR/IT esistenti.

Se supporti più tenant (organizzazioni diverse), decidi presto se un utente può appartenere a più tenant e come switchare contesti.

Autorizzazione: ruoli, scope e auditabilità

Definisci ruoli in linguaggio semplice (per esempio, Titolare Pass, Reception, Security Admin, Auditor), poi mappali ai permessi:

• Chi può emettere, riemettere, revocare o sospendere i pass
• Chi può vedere i log di accesso ed esportare report
• Chi può cambiare le regole di facility (gruppi porte, orari)

Mantieni i controlli di autorizzazione sul server (non solo nella UI) e registra ogni azione sensibile con chi, cosa, quando, dove (IP/dispositivo), più un campo motivo per azioni admin manuali.

Sessioni, trust del dispositivo e comodità utente

Usa token di accesso a vita breve con refresh token e supporta il rientro sicuro via biometria (Face ID/Touch ID) per mostrare il pass.

Per deployment ad alta sicurezza, aggiungi device binding così che una credenziale sia valida solo sui dispositivi registrati. Questo rende anche più difficile l'uso di token copiati altrove.

Salvaguardie admin che riducono errori e abusi

Gli strumenti admin hanno bisogno di guardrail extra:

• Workflow di approvazione per emissioni bulk o pass privilegiati
• Rate limit sugli endpoint di emissione/riemissione
• Alert per pattern insoliti (es. molti pass emessi allo stesso dominio email, picchi fuori orario)

Documenta queste policy in un runbook interno e linkalo dall'UI admin (per esempio, /docs/admin-security) così le operazioni restano coerenti.

Modello di sicurezza: prevenire clonazione, screenshot e replay

La sicurezza dei pass digitali è meno “nascondere il QR” e più decidere cosa un lettore è autorizzato a fidarsi. Il modello giusto dipende da connettività, capacità del lettore e rapidità con cui devi revocare accessi.

Cosa valida il lettore?

Di solito hai tre pattern:

• Payload firmato (validazione offline): QR/NFC contiene un payload firmato dal tuo sistema. I lettori verificano la firma localmente, quindi le porte funzionano offline. È veloce, ma la revoca è legata agli aggiornamenti dei lettori.
• Controllo server (validazione online): il lettore invia il token scansionato al tuo backend per approvare/negare in tempo reale. La revoca è immediata, ma dipendi dalla rete e dalla latenza.
• Ibrido: i lettori verificano prima una firma (per bloccare falsi evidenti), poi chiamano opzionalmente il server per aree a rischio o quando è disponibile la connettività.

Codici QR: ridurre rischio screenshot e replay

I QR statici sono facili da condividere e fotografare. Preferisci codici rotanti o a tempo limitato:

• Usa un token a breve validità (es. 15–60 secondi).
• Legalo a dispositivo/sessione quando possibile (così uno screenshot inoltrato non verrà accettato altrove).
• Includi dati anti-replay (timestamp + nonce) e fai rifiutare dal backend token già usati quando serve “ingresso one-time”.

Se devi supportare validazione QR offline, rendi il QR time-boxed e firmato, accettando che la revoca in tempo reale non sarà possibile senza sync dei lettori.

Credenziali NFC: proteggi le chiavi sul dispositivo

Per NFC, progetta dove risiedono i segreti e come vengono usati:

• Conserva le chiavi in secure storage hardware-backed (Secure Enclave/Keystore dove disponibile).
• Evita di esporre identificatori long-lived via NFC; usa challenge-response o chiavi di sessione derivate se il lettore lo supporta.
• Assumi che dispositivi rootati/jailbroken esistano; affidati a chiavi protette hardware e regole di rischio server-side piuttosto che all'offuscamento dell'app.

Velocità di revoca: definisci il requisito operativo

Decidi in anticipo quanto velocemente un pass revocato deve smettere di funzionare (secondi, minuti, ore). Questo requisito guida l'architettura:

• Secondi: servono controlli online (o lettori sempre connessi).
• Minuti: sync frequenti dei lettori + token a breve validità può bastare.
• Ore: aggiornamenti periodici possono essere accettabili per aree a basso rischio.

Annotalo come SLO di sicurezza e operazioni perché influisce su configurazione lettori, disponibilità backend e risposta agli incidenti.

Integra con lettori di porte e sistemi ACS

Qui i pass digitali incontrano il mondo reale: tornelli, controller di porta, lettori in ascensore e scanner alla reception. Le scelte di integrazione influenzano affidabilità, velocità e cosa succede quando la rete cade.

Scegli il percorso di validazione del lettore

I percorsi comuni includono:

• Lettore → la tua API (validazione cloud): il lettore (o il suo controller) chiama il tuo endpoint di validazione per ogni tap/scan. Flessibile, ma dipende dalla qualità della rete e richiede rate limiting attento.
• Lettore → ACS esistente: la tua app emette una credenziale che l'ACS comprende, e l'ACS decide allow/deny. Meno logica custom alle porte, ma può limitare i dati che puoi codificare.
• Lettore → gateway locale (validazione edge): i lettori parlano a un servizio on-site che valida localmente le credenziali e si sincronizza col backend. Migliora resilienza e mantiene latenza prevedibile.

Imposta target di tempo di risposta e comportamento offline

Definisci target presto (per esempio, “decisione di sblocco sotto 300–500 ms”). Documenta anche cosa “offline” significa per ogni sito:

• Se la rete cade, fai fail closed (nega tutto) o fail open per porte specifiche?
• Supporti allowlist cache al gateway/controller con scadenze brevi?
• Come registrerai eventi e li sincronizzerai dopo senza duplicati?

Documenta i punti di integrazione (non saltare i dettagli scomodi)

Annota i sistemi e i dati da allineare:

• Provisioning badge: chi crea il record persona e quando (sistema HR, sistema visitatori, portale admin)?
• Gruppi di accesso e orari: mappatura ruoli → porte, piani, finestre temporali e regole festività.
• Inventario porte e lettori: ID porta canonici, posizioni, tipi lettore (NFC, QR) e vincoli firmware controller.

Un semplice diagramma “single source of truth” nei docs interni salva settimane in seguito.

Pianifica monitoring e diagnostica

Tratta i lettori come infrastruttura di produzione. Monitora:

• Salute lettore: last seen, versione firmware, stato batteria/alimentazione (se disponibile).
• Rate di fallimento e latenza: p95 tempi di validazione, timeout e retry.
• Motivi di accesso negato: pass scaduto, credenziale revocata, fuori orario, porta sconosciuta, sospetto replay.

Rendi questi visibili in una dashboard ops e invia issue critiche in on-call. Un workflow rapido “perché mi è stato negato?” riduce il carico support durante il rollout.

Architettura backend: API, firma e scalabilità

Un sistema di pass digitali vive o muore dal suo backend: emette credenziali, controlla validità e registra cosa è successo — rapidamente e affidabilmente — mentre le persone stanno alla porta.

API core (semplici e versionate)

Inizia con un piccolo set di endpoint che puoi evolvere:

• POST /v1/passes/issue — crea un pass per un utente, restituisce un link di attivazione o il payload del pass
• POST /v1/passes/refresh — ruota identificatori / aggiorna diritti, restituisce dati pass aggiornati
• POST /v1/passes/validate — verifica un token QR/NFC presentato a un lettore (lettori online)
• POST /v1/passes/revoke — invalida immediatamente un pass (telefono perso, accesso terminato)
• POST /v1/events — registra tentativi di ingresso ed esiti (accepted/denied/error)

Anche se alcune validazioni avvengono su device o lettore, mantieni un'API di validazione server-side per audit, revoca remota e operazioni “break glass”.

Firma e gestione chiavi (e come ruotare in sicurezza)

Se supporti Apple Wallet (PKPass) o altri payload firmati, tratta le chiavi di firma come segreti di produzione:

• Conserva chiavi private in KMS/HSM gestiti; mai su server app o log CI.
• Ruota chiavi periodicamente e dopo incidenti; supporta più chiavi pubbliche attive così i pass vecchi funzionano durante la transizione.
• Audita ogni operazione di firma (chi/cosa ha emesso, per chi, quando e con quale versione chiave).

Un pattern pratico è un servizio di “signing” dedicato con interfaccia ristretta (es. “sign pass payload”), isolato dal resto dell'applicazione.

Progettare per la scalabilità nei picchi di ingresso

I picchi di ingresso sono prevedibili (9:00, inizio evento). Pianifica letture bursty:

Usa cache per liste di revoca e lookup di entitlement, aggiungi retry con idempotency per l'emissione e coda lavoro non critico (analytics, notifiche) così la validazione resta veloce. Se i lettori sono online, mantieni bassa la latenza evitando dipendenze chatty.

Privacy e retention log

Minimizza dati personali memorizzati: preferisci ID utente interni a nomi/email nei record pass e negli eventi. Definisci retention in anticipo (es. mantiene log di ingresso 30–90 giorni salvo richieste legali) e separa log operativi da log di sicurezza/audit con controlli accesso più severi.

Sviluppare più velocemente (senza vincolarsi all'architettura)

Se iteri rapidamente — portale admin, API emissione e una prima esperienza mobile — strumenti come Koder.ai possono aiutare a prototipare e spedire un sistema end-to-end via chat mantenendo stack engineering-grade sotto il cofano (React per web, Go + PostgreSQL per backend, Flutter per mobile). È utile per un pilot funzionante (inclusi deployment/hosting, domini custom e snapshot con rollback) e poi per esportare il codice sorgente quando sei pronto a integrarti con un ACS o gateway on-prem.