Notifiche push da qualsiasi script – l’appliance come canale di avvisi

Il Notakey Authentication Appliance viene di solito descritto come un server di autenticazione: si effettua un accesso, una richiesta push arriva sul telefono, l’utente approva. Ma lo stesso canale di consegna accetta un secondo tipo di messaggio, una semplice notifica, e questo trasforma l’appliance in qualcosa di più generale: un canale di messaggistica push verso ogni telefono registrato nel vostro servizio, richiamabile da qualsiasi script con un solo curl.

any script ──HTTPS──▶ appliance API ──push──▶ enrolled phone
 (cron, monitoring,    /notify                 Notakey Authenticator
  home automation…)

A differenza di una richiesta di autenticazione, una notifica non chiede alcuna approvazione: compare semplicemente sul telefono, indirizzata a un nome utente, e viene recapitata contemporaneamente a tutti i dispositivi registrati dell’utente. Diventa così un sostituto immediato per tutti i casi in cui altrimenti ricorrereste agli SMS (costo per messaggio, mittente falsificabile) o alle email (ignorate fino a lunedì): monitoraggio dei job, avvisi di reperibilità, comunicazioni al personale.

Requisiti

Un’appliance Notakey in funzione (in cloud o on-premise) con un servizio e almeno un utente con un telefono registrato. Se già utilizzate la 2FA per il VPN o l’SSO, avete tutto il necessario: le notifiche passano attraverso lo stesso servizio dei vostri accessi, oppure attraverso un servizio separato se desiderate un branding diverso.
Credenziali di accesso API (un client ID e un client secret), create nella dashboard alla voce Access credentials (il Passaggio 1 qui sotto).
curl e jq su una qualsiasi macchina in grado di raggiungere l’appliance. L’elenco delle dipendenze finisce qui.

Passaggio 1 – Create le credenziali di accesso API

Nella dashboard, aprite Access credentials e create una credenziale per i vostri script. Qui contano due aspetti:

Scope. Concedete urn:notakey:notify: è lo scope necessario per questa guida. Esiste anche urn:notakey:auth, per creare richieste di autenticazione (approve/deny); aggiungetelo solo se la stessa credenziale dovrà svolgere entrambi i compiti. Una credenziale limitata alle sole notifiche non può essere sfruttata per innescare approvazioni di accesso, quindi mantenete l’elenco degli scope ridotto al minimo indispensabile per il compito.
Ricevete un client ID e un client secret. Il secret autorizza l’invio di messaggi a chiunque nel servizio: trattatelo come una password di root.

Passaggio 2 – Scambiatelo con un token e mantenete il token valido

La chiamata di notifica in sé non utilizza il client secret, ma un bearer access token ottenuto tramite il flusso standard OAuth 2.0 client-credentials. Gli access token hanno volutamente una durata breve: prevedete di rinnovarli all’incirca una volta all’ora, altrimenti i vostri script inizieranno a fallire con errori di autorizzazione a un certo punto, dopo aver funzionato senza problemi per 59 minuti.

Il rinnovo del token è quindi un’operazione da affidare a cron, non un passaggio di configurazione una tantum:

#!/bin/bash
# /usr/local/bin/ntk-token-renew — cron: 0 * * * *

curl -s -X POST https://ntk.example.com/api/token \
  -d 'grant_type=client_credentials&client_id=<client-id>&client_secret=<client-secret>&scope=urn:notakey:notify' \
  | jq -r .access_token > /etc/notakey/api.token

Lo script incorpora il client secret e scrive il token, quindi proteggete entrambi:

chmod 700 /usr/local/bin/ntk-token-renew    # root-only, holds the secret
install -m 600 /dev/null /etc/notakey/api.token

Se avete concesso anche urn:notakey:auth, richiedetelo come token separato in un file separato (stessa chiamata, scope=urn:notakey:auth) anziché come un unico token con entrambi gli scope: in questo modo gli script di notifica non deterranno mai un token in grado di creare approvazioni di accesso.

Passaggio 3 – Un unico script di notifica riutilizzabile

Tutto il resto di questa guida richiama questo unico script, che riceve un nome utente, un titolo e il corpo del messaggio:

#!/bin/bash
# /usr/local/bin/ntk-notify <username> <title> <description>

token=$(cat /etc/notakey/api.token)

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -d '{ "username": "'"$1"'", "title": "'"$2"'", "description": "'"$3"'", "type": "notification" }' \
  "https://ntk.example.com/api/v3/services/<service-id>/notify"

Sostituite ntk.example.com con l’indirizzo della vostra appliance e <service-id> con lo UUID del servizio riportato nella dashboard. Provatelo:

ntk-notify j.doe "Test" "If you can read this on your phone, the channel works."

La notifica push arriva nell’app Notakey Authenticator: la stessa app che l’utente ha già per gli accessi, quindi non c’è nulla di nuovo da installare, da spiegare o da far approvare dal sistema di gestione dei dispositivi mobili.

Passaggio 4 – Richiamatelo da qualsiasi cosa

Una volta che il canale si riduce a una sola riga di comando, i casi d’uso si moltiplicano. Eccone alcuni già attivi in produzione:

Un job di backup che dà notizie di sé. Il classico guasto che passa inosservato: backup che hanno smesso di funzionare mesi fa senza che nessuno se ne accorgesse. Due righe alla fine del job risolvono il problema:

if ! /usr/local/bin/backup-run; then
  ntk-notify admin "Backup FAILED" "Nightly backup on $(hostname) exited with an error — check /var/log/backup.log"
fi

Spazio su disco, scadenza dei certificati, qualunque cosa cron sia in grado di controllare:

#!/bin/bash
# cron: 0 8 * * *
used=$(df --output=pcent / | tail -1 | tr -dc '0-9')
if [ "$used" -gt 90 ]; then
  ntk-notify admin "Disk warning" "Root filesystem on $(hostname) is at ${used}% — time to clean up."
fi

Una comunicazione a tutto il personale. L’API indirizza un nome utente per chiamata, quindi un messaggio esteso a tutta l’azienda è un ciclo sull’elenco degli utenti: finestre di manutenzione, chiusure degli uffici, avvisi di incidenti:

while read -r user; do
  ntk-notify "$user" "IT maintenance" "VPN unavailable Saturday 06:00–08:00 — planned appliance upgrade."
done < users.txt

Prezzi spot dell’energia elettrica, due volte ogni due ore. Non tutto ciò che vale la pena inviare è un guasto. Questo script viene eseguito da cron e comunica all’utente quanto costerà l’energia elettrica nell’ora successiva, comodo per decidere quando far partire la lavastoviglie:

#!/bin/bash
# cron: 5 * * * * — sends on even hours, 06–23 only
hour=$(( $(date +%H) + 1 ))
next=$(( hour + 1 ))

if [ "$hour" -gt 5 ] && [ "$hour" -lt 24 ] && (( $(date +%H) % 2 == 0 )); then
  ntk-notify "$1" "Electricity" \
    "Next hour: $(spot_price "$hour")€/kWh. After that: $(spot_price "$next")€/kWh."
fi

(spot_price è qualunque cosa recuperi i vostri dati di mercato: un’API di borsa, un CSV in cache. Il punto è la consegna, non la fonte.)

Per i messaggi ricorrenti come questo, vale la pena conoscere due funzionalità documentate. Aggiungendo un campo fingerprint al payload, un nuovo invio con lo stesso fingerprint aggiorna il messaggio esistente invece di accodarne uno nuovo: così un ticker dei prezzi resta un’unica notifica, non quaranta al giorno. E "type": "sms" invia lo stesso messaggio come SMS, se per l’utente è definito un numero di cellulare: un canale di riserva per chi ha perso l’app sul proprio telefono.

La lavatrice ha finito. Una presa smart che sorveglia l’assorbimento di corrente, un’automazione Home Assistant, uno script che interroga un contatore – qualunque cosa rilevi la fine del ciclo, la notifica è sempre la stessa riga di comando. Esempio banale, abitudine concreta: una volta che inviare una push non costa nulla, si finisce per notificare qualsiasi cosa.

A cosa serve questo canale (e a cosa non serve)

Rispetto agli SMS, il lato destinatario è molto più solido: un SMS arriva su qualunque apparecchio ospiti in quel momento la SIM, da un nome mittente che chiunque può falsificare, mentre una notifica Notakey compare solo nell’app Authenticator, sui dispositivi che hanno completato la registrazione crittografica nel vostro servizio. Nessuno può iscriversi da solo ai vostri avvisi e nessuno può falsificare il mittente.

Un limite da dichiarare con onestà, direttamente dalla documentazione dell’API: il corpo della notifica non è cifrato end-to-end: come qualsiasi push su dispositivi mobili, transita attraverso i servizi push di Apple e Google ed è leggibile dalle app che dispongono dell’accesso alle notifiche sul dispositivo. Trattate quindi il corpo del messaggio come il testo di un cercapersone, non come una busta sigillata: «Backup fallito sull’host X» va bene; una password o una chiave API no. Quando dovete recapitare qualcosa di realmente riservato, usate invece una richiesta di autenticazione (urn:notakey:auth): in quel caso la push è soltanto un bussare alla porta, e il payload viene recuperato dall’app attraverso il proprio canale autenticato con certificato dopo che l’utente ha risposto.

Dove si inserisce

Se l’appliance protegge già il vostro VPN o le vostre applicazioni, le notifiche sono una funzionalità già a vostra disposizione che non state sfruttando: stesso servizio, stessa app, stesse credenziali API, un solo endpoint in più. E se finora avete pagato un gateway SMS per gli avvisi interni, questo lo sostituisce per ogni destinatario che porta con sé un telefono registrato.

Guide correlate

2FA per il VPN con RADIUS – la configurazione completa dell’auth-proxy: il versante autenticazione della stessa appliance
2FA SSH per Linux con pam_radius: approvazioni sul telefono per i server su cui girano i vostri script
Documentazione dell’API: l’intera superficie REST, comprese le interrogazioni sui dispositivi e le richieste di autenticazione