SSO passwordless con Notakey: guida alla configurazione passo dopo passo

Alla fine di questa guida i vostri utenti accedono a un’app con un’approvazione dal telefono: digitano un nome utente o scansionano un codice QR, poi confermano nell’app Notakey. Nessuna password nella pagina di login. La password esiste ancora, ma svolge un solo compito obbligatorio: viene richiesta una volta sola, alla registrazione del dispositivo, per generare la chiave dell’utente. Tutto quello che viene dopo è una vostra scelta di policy, e questa guida mostra esattamente dove si imposta ciascuna.

Ogni servizio Notakey — gli stessi che già usate per la 2FA su VPN, Windows o Wi-Fi — può funzionare anche da provider OpenID Connect. Non serve un prodotto a parte: attivate OIDC per un servizio dalla Dashboard, registrate l’app che lo userà come client e puntatela verso gli endpoint che Notakey vi fornisce. Niente certificati SAML, nessun server di identity provider separato da mantenere.

your app ──OIDC──▶ Notakey service (OIDC provider)
                        │
                        ├──▶ user repository: onboarded devices in this service
                        └──▶ push ──▶ user's phone: read, approve

(Le app aziendali classiche che parlano solo SAML — Google Workspace, AWS — hanno bisogno invece del SAML identity provider separato di Notakey; l’ultima sezione indica dove trovarlo.)

Come funziona davvero la password qui

Vale la pena essere precisi, perché di “passwordless” si parla spesso in modo vago:

L’onboarding è l’unica password obbligatoria. Impostata dalla Dashboard o recuperata da Active Directory, viene verificata una sola volta, quando l’utente registra il dispositivo, e la sua chiave viene generata nell’hardware sicuro del telefono.
L’accesso quotidiano non ne richiede nessuna. L’utente digita un nome utente o scansiona un codice QR; la pagina di login può ridursi alla sola scansione, senza nulla da digitare. La verifica dell’identità è l’approvazione firmata nell’app.
Tutto il resto è un’impostazione, non una regola fissa. Un’app può chiedere una conferma aggiuntiva nell’app, un’altra una password, una terza entrambe. Potete anche richiedere di nuovo la password a intervalli regolari, così nessuno se la dimentica del tutto. È tutto in un’unica schermata di configurazione, illustrata al passo 5.

Passo 1 – Scegliere un servizio

Usate un servizio Notakey già esistente se i suoi utenti coincidono già con quelli dell’app che state collegando, oppure createne uno nuovo (Services → Manage → New) se volete che questa app abbia una propria policy della password, indipendente da tutto il resto. La policy del passo 5 vale per l’intero servizio, non per il singolo client — è questo il criterio che decide.

Passo 2 – Attivare OpenID Connect

Aprite il servizio, poi andate su OpenID Connect configuration → Configure e spuntate Enabled. Lasciate il resto ai valori predefiniti per ora — imposterete Require password e Require mfa deliberatamente al passo 5, non per caso qui. Salvate.

Passo 3 – Copiare gli endpoint

Tornate su OpenID Connect configuration e cliccate Show. Notakey ha già generato un documento di discovery e i singoli endpoint che ci sono dietro:

https://<your-dashboard-host>/oidc/services/<access-id>/.well-known/openid-configuration

La maggior parte dei software compatibili con OIDC ha bisogno solo di questo URL: incollatelo in un campo “auto discovery” o “issuer” e l’app recupera da sola gli endpoint di authorization, token, userinfo e JWKS. <access-id> è lo stesso ID mostrato nella pagina del servizio.

Passo 4 – Registrare l’applicazione come client

Nel servizio, andate su OpenID Connect configuration → Clients → New client. Notakey genera per voi un Client ID e un Secret casuale.

Due cose da sapere prima di salvare: il campo Secret è mascherato e Notakey non ve lo mostrerà più una volta usciti dalla pagina, quindi copiatelo subito — oppure selezionate il campo e incollate un secret scelto da voi, che funziona altrettanto bene ed è più facile da tenere a mente. E il campo Redirect URIs deve corrispondere, carattere per carattere, all’URL che l’app rimanda indietro durante il login — basta una barra finale che l’app non invia per rompere tutto (vedi l’insidia più sotto).

Compilate:

Description — qualcosa che vi aiuti a riconoscerlo in seguito.
Secret — copiate quello generato, oppure sovrascrivetelo con uno vostro.
Redirect URIs — l’URL di callback OAuth dell’app. Separate con una virgola più indirizzi, se l’app è raggiungibile a più URL.
Logout URI — dove reindirizzare il browser dopo il logout. Facoltativo.

Una volta registrate un paio di app, l’elenco client del servizio ha questo aspetto:

Passo 5 – Puntare l’app verso Notakey

I passaggi esatti dipendono dall’app, ma lo schema è sempre lo stesso: un issuer o un discovery URL, un client ID, un client secret. Due esempi concreti da strumenti self-hosted reali:

Gitea mette a disposizione un comando da CLI per questo — nessun form web, nessun riavvio:

gitea admin auth add-oauth \
  --name notakey \
  --provider openidConnect \
  --key <client-id> \
  --secret <client-secret> \
  --auto-discover-url https://<dashboard-host>/oidc/services/<access-id>/.well-known/openid-configuration \
  --scopes openid --scopes profile --scopes email

La pagina di login di Gitea mostra subito un pulsante “Sign in with notakey”, accanto al form della password già esistente — non viene rimosso nulla.

Proxmox VE lo tratta come un authentication realm, che si aggiunge a quelli già presenti:

pveum realm add notakey --type openid \
  --issuer-url https://<dashboard-host>/oidc/services/<access-id> \
  --client-id <client-id> \
  --client-key <client-secret> \
  --username-claim sub \
  --scopes "openid email profile" \
  --autocreate 1

--issuer-url qui è il discovery URL senza la coda /.well-known/openid-configuration — è Proxmox stesso ad aggiungerla. --autocreate 1 crea un utente Proxmox corrispondente al primo login riuscito, senza permessi finché non li concedete esplicitamente: gli accessi non vengono regalati per sbaglio.

Passo 6 – Impostare la policy della password

È qui che la parte “a scelta dell’amministratore” diventa concreta, di nuovo su OpenID Connect configuration → Configure:

Require password deselezionato, con Require mfa selezionato: è il flusso passwordless descritto all’inizio di questa guida. L’accesso è nome utente (o QR) più approvazione dal telefono, nient’altro.
Require password selezionato, con Password cache lasciato a 0: password ogni volta, in aggiunta all’approvazione — la classica autenticazione a due fattori.
Require password selezionato con un Password cache espresso in secondi (per esempio 2592000 per 30 giorni): passwordless nell’uso quotidiano, con la password richiesta di nuovo una volta trascorsa quella finestra — solo per evitare che venga dimenticata del tutto. Mfa cache funziona allo stesso modo per il passaggio di approvazione, se volete mettere in cache anche quello.

Poiché questa impostazione vale per l’intero servizio, un’app che ha bisogno di una policy diversa dalle altre va messa in un servizio a sé — si torna alla scelta del passo 1.

Quando qualcosa non funziona

Un errore di redirect_uri mismatch quasi sempre nasconde una barra finale: alcune app inviano https://app.example.com, altre https://app.example.com/, e Notakey confronta la stringa esattamente. Controllate i log di accesso di nginx o dell’app per trovare il valore letterale di redirect_uri= inviato dall’app, e registrate esattamente quel valore.
Se il discovery URL restituisce 404, verificate che Enabled sia stato effettivamente salvato al passo 2 — una pagina di configurazione che sembra corretta ma non è mai stata inviata è l’errore più comune.
Il log Authentication activities del servizio mostra ogni tentativo arrivato fino a Notakey. Un tentativo che non compare lì significa che l’app non è mai arrivata all’authorization endpoint — controllate prima il client ID e il discovery URL.

Cosa questa guida tralascia deliberatamente

Le classiche integrazioni SAML 2.0 per le app che parlano solo SAML — Google Workspace, AWS e simili — passano dal SAML identity provider separato di Notakey, non dal percorso OIDC descritto sopra. Anche LDAP/Active Directory come user repository, le configurazioni multi-tenant e il branding personalizzato restano fuori da questa guida. Tutto questo si trova nel CLI and API reference, con le tabelle complete dei parametri; questa guida è la via rapida per arrivare da zero a un login passwordless funzionante.

Vedetelo prima di costruirlo

Il modo più rapido per farvi un’idea dell’esperienza di accesso è provare voi stessi il flusso di approvazione: provate la demo dal vivo e firmate una richiesta dal vostro telefono in circa due minuti, oppure richiedete una demo e mapperemo le vostre applicazioni e la vostra policy delle password su un progetto pilota sulla vostra infrastruttura.