Push értesítések bármilyen szkriptből: a készülék mint riasztási csatorna

A Notakey készüléket általában hitelesítési szerverként szokás bemutatni: történik egy bejelentkezés, a telefonra jóváhagyási kérés érkezik, a felhasználó jóváhagyja. Ugyanez a kézbesítési csatorna azonban egy második üzenettípust is elfogad, az egyszerű értesítést, és ettől a készülék valami sokkal általánosabbá válik: push üzenetküldő csatornává a szolgáltatásába regisztrált összes telefon felé, amely bármilyen szkriptből meghívható egyetlen curl paranccsal.

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

Az értesítés a hitelesítési kéréstől eltérően nem kér jóváhagyást: egyszerűen megjelenik a telefonon, felhasználónévre címezve, és a felhasználó összes regisztrált eszközére egyszerre érkezik meg. Így azonnal kiválthatja mindazt, amit egyébként SMS-sel (üzenetenkénti költség, hamisítható feladó) vagy e-maillel (hétfőig senki sem olvassa el) oldana meg: feladatfigyelés, ügyeleti jelzések, munkatársi közlemények.

Előfeltételek

• Egy működő Notakey készülék (felhőben vagy on-premise), rajta egy szolgáltatás és legalább egy felhasználó regisztrált telefonnal. Ha már használ VPN 2FA-t vagy SSO-t, mindez adott: az értesítések ugyanazon a szolgáltatáson mennek keresztül, mint a bejelentkezései, vagy egy különállón, ha eltérő megjelenést szeretne.
• API-hozzáférési adatok (kliensazonosító és klienstitok), amelyeket az irányítópult Access credentials menüjében hozhat létre (lásd az
  1. lépést).
• curl és jq bármin, ami eléri a készüléket. Ennyi a teljes függőséglista.

1. lépés: API-hozzáférési adatok létrehozása

Az irányítópulton nyissa meg az Access credentials menüt, és hozzon létre hozzáférést a szkriptjei számára. Két dolog fontos itt:

• Hatókörök (scope). Adja meg az urn:notakey:notify hatókört; ehhez az útmutatóhoz erre van szükség. Létezik az urn:notakey:auth is a hitelesítési (jóváhagyás/elutasítás) kérések létrehozásához; csak akkor vegye fel, ha ugyanez a hozzáférés mindkettőt végzi majd. Egy csak értesítésre jogosult hozzáféréssel nem lehet bejelentkezési jóváhagyást kiváltani, ezért tartsa a hatókörlistát olyan rövidnek, amilyet a feladat megenged.
• Kap egy kliensazonosítót (client ID) és egy klienstitkot (client secret). A titok birtokában a szolgáltatás bármely felhasználójának üzenet küldhető: kezelje úgy, mint egy root jelszót.

2. lépés: Váltsa a klienstitkot tokenre, és tartsa a tokent frissen

Maga az értesítő hívás nem a klienstitkot használja, hanem egy hozzáférési tokent (bearer access token), amelyet a szabványos OAuth 2.0 client credentials folyamattal szerez meg. A tokenek szándékosan rövid életűek: készüljön fel arra, hogy nagyjából óránként meg kell újítania őket, különben a szkriptjei egyszer csak engedélyezési hibákkal kezdenek elhasalni – azután, hogy 59 percen át kifogástalanul működtek.

A token megújítása tehát cron feladat, nem egyszeri beállítási lépés:

#!/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

A szkript tartalmazza a klienstitkot, és fájlba írja a tokent, ezért mindkettőt zárja el:

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

Ha az urn:notakey:auth hatókört is megadta, azt külön tokenként, külön fájlba kérje le (ugyanaz a hívás, scope=urn:notakey:auth), ne egyetlen, mindkét hatókört tartalmazó tokenként, így az értesítő szkriptek soha nem birtokolnak olyan tokent, amellyel bejelentkezési jóváhagyás hozható létre.

3. lépés: Egyetlen újrahasznosítható értesítő szkript

Az útmutató minden további része ezt az egy szkriptet hívja. Paraméterei egy felhasználónév, egy cím és egy üzenetszöveg:

#!/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"

Cserélje le az ntk.example.com címet a saját készüléke címére, a <service-id> helyére pedig írja be a szolgáltatás UUID-jét az irányítópultról. Próbálja ki:

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

A push a Notakey Authenticator alkalmazásban érkezik meg: ugyanabban az appban, amelyet a felhasználó már használ a bejelentkezésekhez, így nincs mit újonnan telepíteni, elmagyarázni vagy a mobileszköz-felügyeleten átvinni.

4. lépés: Hívja meg bárhonnan

Amint a csatorna egyetlen sorra egyszerűsödik, gyűlni kezdenek a felhasználási módok. Néhány, amely ma is éles környezetben fut:

Mentési feladat, amely visszajelez. A klasszikus néma hiba: a hónapokkal ezelőtt leállt mentés, amelyet senki sem vett észre. Két sor a feladat végén orvosolja:

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

Lemezterület, tanúsítványlejárat – bármi, amit a cron ellenőrizni tud:

#!/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

Közlemény minden munkatársnak. Az API hívásonként egy felhasználónevet címez, így a céges körüzenet nem más, mint egy ciklus a felhasználólistán: karbantartási ablakok, irodabezárások, incidensértesítések:

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

Áramtőzsdei árak kétóránként, két órára előre. Nem csak üzemzavarról érdemes push értesítést küldeni. Ez a szkript cronból fut, és megmondja a felhasználónak, mennyibe kerül majd az áram a következő órában; jól jön, amikor el kell dönteni, mikor menjen a mosogatógép:

#!/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

(A spot_price bármi lehet, ami lekéri a piaci adatokat: egy tőzsdei API, egy gyorsítótárazott CSV. A lényeg a kézbesítés, nem a forrás.)

Két dokumentált extra, amelyet érdemes ismerni az ilyen ismétlődő üzenetekhez: ha a kérésbe fingerprint mezőt tesz, az azonos fingerprinttel megismételt küldés a meglévő üzenetet frissíti, ahelyett hogy újat halmozna rá, így az árfigyelő egyetlen értesítés marad, nem napi negyven. A "type": "sms" pedig ugyanazt az üzenetet SMS-ként küldi el, ha a felhasználóhoz van rögzítve mobilszám: tartalék csatorna annak, akinek a telefonjáról eltűnt az app.

Elkészült a mosógép. Egy fogyasztást figyelő okoskonnektor, egy Home Assistant automatizálás, egy mérőórát lekérdező szkript: bármi is érzékeli a program végét, az értesítés ugyanaz az egysoros. Butaságnak hangzik, mégis valós szokás: amint a push küldése semmibe sem kerül, az ember mindenről értesítést küld.

Mire jó ez a csatorna – és mire nem

Az SMS-hez képest a fogadó oldal sokkal erősebb: az SMS arra a telefonra érkezik, amelyikben éppen a SIM-kártya van, olyan feladónévvel, amelyet bárki hamisíthat, míg a Notakey értesítés kizárólag az Authenticator alkalmazásban jelenik meg, olyan eszközökön, amelyek kriptográfiai regisztrációt végeztek az Ön szolgáltatásában. Senki sem iratkozhat fel magától az Ön riasztásaira, és a feladót sem hamisíthatja senki.

Egy őszinte korlát, egyenesen az API-dokumentációból: maga az értesítés szövege nincs végponttól végpontig titkosítva: mint minden mobil push, az Apple és a Google push szolgáltatásán keresztül továbbítódik, és az eszközön értesítési hozzáféréssel rendelkező appok számára olvasható. Az üzenet szövegét ezért kezelje úgy, mint egy személyhívós üzenetet, ne mint lepecsételt borítékot: a „Backup failed on host X” rendben van; egy jelszó vagy egy API-kulcs nem. Ha valóban titkos tartalmat kell kézbesítenie, használjon inkább hitelesítési kérést (urn:notakey:auth): ott a push csak kopogtatás az ajtón, a tartalmat pedig az app a tanúsítvánnyal hitelesített csatornáján kéri le, miután a felhasználó reagált.

Hová illeszkedik mindez

Ha a készülék már védi a VPN-jét vagy az alkalmazásait, az értesítés ingyen kapott, kihasználatlan képesség: ugyanaz a szolgáltatás, ugyanaz az app, ugyanazok az API-hozzáférési adatok, egyetlen plusz végpont. Ha pedig eddig SMS-átjáróért fizetett a belső riasztások miatt, azt minden olyan címzett esetében kiválthatja, aki regisztrált telefont hord magánál.

Kapcsolódó útmutatók

• VPN 2FA RADIUS-szal: az auth-proxy teljes beállítása – ugyanennek a készüléknek a hitelesítési oldala
• Linux SSH 2FA pam_radius-szal – telefonos jóváhagyás azokhoz a szerverekhez, amelyeken a szkriptjei futnak
• API-dokumentáció – a teljes REST felület, beleértve az eszközlekérdezéseket és a hitelesítési kéréseket