Push notifikace z libovolného skriptu – zařízení jako kanál pro upozornění

Zařízení Notakey (appliance) se obvykle popisuje jako autentizační server: proběhne přihlášení, na telefon dorazí požadavek push, uživatel jej schválí. Stejný doručovací kanál ale přijímá i druhý typ zprávy, prostou notifikaci, a ta dělá ze zařízení něco obecnějšího: kanál push zpráv na každý telefon registrovaný ve vaší službě, dostupný z libovolného skriptu jediným voláním curl.

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

Na rozdíl od autentizačního požadavku notifikace o žádné schválení nežádá: prostě se objeví na telefonu, adresovaná uživatelskému jménu, a doručí se najednou na všechna registrovaná zařízení uživatele. Díky tomu je přímou náhradou všude tam, kde byste jinak zapojovali SMS (cena za každou zprávu, podvrhnutelný odesílatel) nebo e-mail (ignorovaný až do pondělí): sledování úloh, pohotovostní upozornění, oznámení zaměstnancům.

Co budete potřebovat

Běžící zařízení Notakey (v cloudu nebo on-premise) se službou a alespoň jedním uživatelem s registrovaným telefonem. Pokud už provozujete 2FA pro VPN nebo SSO, tohle všechno máte: notifikace jdou přes stejnou službu jako vaše přihlašování, případně přes samostatnou, chcete-li odlišný branding.
Přihlašovací údaje k API (client ID a client secret), vytvořené v dashboardu v sekci Access credentials (viz krok 1 níže).
curl a jq na čemkoli, co se k zařízení dostane po síti. Tím seznam závislostí končí.

Krok 1 – Vytvořte přihlašovací údaje k API

V dashboardu otevřete Access credentials a vytvořte přihlašovací údaje pro své skripty. Důležité jsou dvě věci:

Rozsahy oprávnění (scopes). Udělte urn:notakey:notify. To je rozsah, který tento návod potřebuje. Existuje i urn:notakey:auth, určený k vytváření autentizačních požadavků (schválit/zamítnout); přidejte jej jen tehdy, mají-li tytéž údaje dělat obojí. Údaje omezené pouze na notifikace nelze zneužít k vyvolání schválení přihlášení, proto udržujte seznam rozsahů tak krátký, jak to úloha dovolí.
Obdržíte client ID a client secret. Secret opravňuje k zasílání zpráv všem uživatelům služby, proto s ním zacházejte jako s rootovským heslem.

Krok 2 – Vyměňte údaje za token a pravidelně jej obnovujte

Samotné volání pro odeslání notifikace client secret nepoužívá. Používá přístupový token (bearer) získaný standardním OAuth 2.0 grantem client_credentials. Přístupové tokeny mají záměrně krátkou životnost: počítejte s obnovou zhruba jednou za hodinu, jinak vaše skripty znenadání začnou selhávat s chybou autorizace poté, co 59 minut běžely bez potíží.

Obnova tokenu je proto úloha pro cron, ne jednorázový instalační krok:

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

Skript obsahuje client secret a zapisuje token, proto obojí řádně zabezpečte:

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

Pokud jste udělili i urn:notakey:auth, vyžádejte si jej jako samostatný token do samostatného souboru (stejné volání, scope=urn:notakey:auth), nikoli jako jeden token s oběma rozsahy; notifikační skripty pak nikdy nedrží token, kterým by šlo vytvářet schválení přihlášení.

Krok 3 – Jeden univerzální notifikační skript

Vše ostatní v tomto návodu volá tento jediný skript. Přijímá uživatelské jméno, titulek a text zprávy:

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

Nahraďte ntk.example.com adresou svého zařízení a <service-id> UUID služby z dashboardu. Vyzkoušejte:

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

Push dorazí do aplikace Notakey Authenticator, tedy téže aplikace, kterou už uživatel používá pro přihlašování, takže není třeba nic nového instalovat, vysvětlovat ani protlačovat přes správu mobilních zařízení.

Krok 4 – Volejte jej odkudkoli

Jakmile je celý kanál otázkou jednoho řádku, začnou se případy použití množit samy od sebe. Několik takových, které dnes běží v produkci:

Zálohovací úloha, která se hlásí. Klasické tiché selhání: zálohy, které přestaly fungovat před měsíci, a nikdo si toho nevšiml. Napraví to dva řádky na konci úlohy:

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

Místo na disku, expirace certifikátů, cokoli, co dokáže zkontrolovat cron:

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

Oznámení všem zaměstnancům. API adresuje jedno uživatelské jméno na volání, takže celofiremní zpráva je smyčka přes seznam uživatelů (servisní okna, uzavření kanceláří, informace o incidentech):

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

Spotové ceny elektřiny, dvě ceny každé dvě hodiny. Ne vše, co stojí za push, je havárie. Tento skript běží z cronu a říká uživateli, kolik bude stát elektřina v příští hodině, což se hodí při rozhodování, kdy pustit myčku:

#!/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 je cokoli, co obstará vaše tržní data: API burzy, CSV uložené v mezipaměti. Podstatné je doručení, ne zdroj.)

U opakovaných zpráv, jako je tato, stojí za to znát dvě zdokumentované drobnosti: přidáte-li do payloadu pole fingerprint, opakované odeslání se stejným otiskem aktualizuje existující zprávu, místo aby vršilo nové; cenový ticker tak zůstane jedinou notifikací, ne čtyřiceti denně. A "type": "sms" odešle tutéž zprávu jako SMS, pokud má uživatel vyplněné mobilní číslo – záložní kanál pro někoho, komu z telefonu zmizela aplikace.

Pračka doprala. Chytrá zásuvka sledující odběr, automatizace v Home Assistantu, skript vyčítající měřič – ať konec cyklu detekuje cokoli, notifikace je pořád stejný jednořádkový příkaz. Banální příklad, ale skutečný návyk: jakmile odeslání push zprávy nic nestojí, začnete oznamovat všechno.

K čemu se tento kanál hodí (a k čemu ne)

Ve srovnání s SMS jsou záruky na straně příjemce mnohem silnější: SMS dorazí na jakýkoli přístroj, ve kterém je zrovna zasunutá SIM karta, a jméno odesílatele může kdokoli podvrhnout, zatímco notifikace Notakey přistane pouze v aplikaci Authenticator na zařízeních, která dokončila kryptografickou registraci ve vaší službě. Nikdo si vaše upozornění nemůže sám objednat a nikdo nemůže podvrhnout odesílatele.

Jedno omezení, které dokumentace API otevřeně přiznává: samotné tělo notifikace není šifrováno end-to-end. Jako každá mobilní push zpráva prochází push službami Applu a Googlu a na zařízení si je mohou přečíst aplikace s přístupem k notifikacím. S textem zprávy proto zacházejte jako se zprávou na pager, ne jako se zalepenou obálkou: „Záloha na hostu X selhala“ je v pořádku; heslo nebo API klíč nikoli. Když potřebujete doručit něco skutečně tajného, použijte místo toho autentizační požadavek (urn:notakey:auth). Tam je push jen zaklepáním na dveře a samotný obsah si aplikace po reakci uživatele stáhne přes svůj kanál ověřený certifikátem.

Kam to zapadá

Pokud zařízení už chrání vaši VPN nebo aplikace, jsou notifikace funkce, kterou máte zdarma a zatím ji nevyužíváte: stejná služba, stejná aplikace, stejné přihlašovací údaje k API, jeden endpoint navíc. A pokud jste dosud platili SMS bránu za interní upozornění, tohle ji nahradí u každého příjemce, který nosí registrovaný telefon.

Související návody

2FA pro VPN přes RADIUS – kompletní nastavení auth-proxy: autentizační strana téhož zařízení
2FA pro SSH na Linuxu s pam_radius: schvalování telefonem pro servery, na kterých vaše skripty běží
Dokumentace API: kompletní REST rozhraní včetně dotazů na zařízení a autentizačních požadavků