9. juuli 2026

Tõukemärguanded igast skriptist – seade teavituskanalina

Saatke registreeritud telefonidele tõukemärguandeid ühe curl-käsuga: serverihoiatused, valveteavitused, hinnajälgijad, koduautomaatika.

Notakey seadet kirjeldatakse tavaliselt autentimisserverina: toimub sisselogimine, telefonile saabub kinnituspäring, kasutaja kinnitab. Kuid sama edastuskanal võtab vastu ka teist tüüpi sõnumi, lihtsa teavituse, ja see teeb seadmest midagi üldisemat: tõukemärguannete (push) kanali igasse teie teenusesse registreeritud telefoni, välja kutsutav igast skriptist üheainsa curl-käsuga.

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

Erinevalt autentimispäringust ei küsi teavitus kinnitust: see lihtsalt ilmub telefoni, adresseerituna kasutajanimele, ja jõuab korraga kõikidesse kasutaja registreeritud seadmetesse. Nii sobib see otse asendama kohti, kuhu muidu ühendaksite SMS-i (iga sõnum maksab, saatjat saab võltsida) või e-posti (jääb esmaspäevani lugemata): tööde seire, valves oleva inseneri teavitamine, teadaanded töötajatele.

Eeldused

  • Töötav Notakey seade (pilves või teie oma taristus), milles on teenus ja vähemalt üks kasutaja, kelle telefon on liidestatud. Kui kasutate juba VPN-i 2FA-d või SSO-d, on kõik see olemas: teavitused liiguvad läbi sama teenuse, mida kasutavad teie sisselogimised, või eraldi teenuse kaudu, kui soovite teistsugust kujundust.
  • API sisselogimisandmed (kliendi ID ja kliendisaladus), mis luuakse haldusliideses jaotises Access credentials (vt 1. samm allpool).
  • curl ja jq ükskõik millises masinas, mis seadmeni ulatub. Sellega on sõltuvuste nimekiri ammendatud.

1. samm – looge API sisselogimisandmed

Avage haldusliideses Access credentials ja looge oma skriptide jaoks sisselogimisandmed. Kaks asja on siin olulised:

  • Õiguste ulatus (scope). Andke õigus urn:notakey:notify. See ongi ulatus, mida see juhend vajab. Olemas on ka urn:notakey:auth, mis on mõeldud autentimispäringute (kinnita/keeldu) loomiseks; lisage see ainult siis, kui samade sisselogimisandmetega tehakse mõlemat. Ainult teavitusõigusega sisselogimisandmeid ei saa kuritarvitada sisselogimiskinnituste vallandamiseks, seega hoidke õiguste nimekiri nii lühike, kui töö vähegi lubab.
  • Saate kliendi ID ja kliendisaladuse. Saladus annab õiguse saata sõnumeid kõigile teenuse kasutajatele, seega käsitlege seda nagu juurkasutaja parooli.

2. samm – vahetage see tokeni vastu ja hoidke tokenit värskena

Teavituskutse ise kliendisaladust ei kasuta. See kasutab pääsutõendit (token), mis hangitakse standardse OAuth 2.0 client credentials meetodiga. Tokenid on teadlikult lühikese elueaga: plaanige uuendamist umbes kord tunnis, muidu hakkavad teie skriptid mingil hetkel autoriseerimisvigadega ebaõnnestuma, pärast seda, kui need on 59 minutit laitmatult töötanud.

Seega on tokeni uuendamine cron-i töö, mitte ühekordne seadistussamm:

#!/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 sisaldab kliendisaladust ja kirjutab tokeni faili, seega piirake ligipääs mõlemale:

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

Kui andsite ka õiguse urn:notakey:auth, küsige see eraldi tokenina eraldi faili (sama kutse, scope=urn:notakey:auth), mitte ühe mõlemat ulatust hõlmava tokenina; nii ei ole teavitusskriptide käes kunagi tokenit, millega saaks luua sisselogimiskinnitusi.

3. samm – üks korduvkasutatav teavitusskript

Kõik ülejäänu selles juhendis kutsub välja sedasama skripti. See võtab argumentideks kasutajanime, pealkirja ja sõnumi sisu:

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

Asendage ntk.example.com oma seadme aadressiga ja <service-id> haldusliideses näidatud teenuse UUID-ga. Proovige järele:

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

Tõukemärguanne saabub Notakey Authenticatori rakendusse, samasse rakendusse, mis kasutajal on sisselogimiste jaoks juba olemas, nii et pole midagi uut paigaldada, selgitada ega mobiilseadmete halduses kooskõlastada.

4. samm – kutsuge seda välja kust tahes

Kui kanal mahub ühte ritta, hakkab see kasutusjuhte külge tõmbama. Mõned, mis juba täna töökeskkonnas jooksevad:

Varukoopiatöö, mis endast teada annab. Klassikaline vaikne tõrge: varundus, mis lakkas töötamast kuude eest, ilma et keegi oleks märganud. Kaks rida töö lõpus lahendavad selle:

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

Kettaruum, sertifikaadi aegumine, ükskõik mis, mida cron kontrollida oskab:

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

Teadaanne kõigile töötajatele. API adresseerib ühe kutsega ühe kasutajanime, nii et üleettevõtteline sõnum on tsükkel üle kasutajate nimekirja (hooldusaknad, kontori sulgemised, intsidenditeated):

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

Elektri börsihinnad, kaks hinda iga kahe tunni tagant. Kõik, mida tasub telefoni saata, pole rike. See skript jookseb cron-ist ja ütleb kasutajale, mis järgmine tund elektrit maksma hakkab, mugav, kui otsustate, millal nõudepesumasin käima panna:

#!/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 on ükskõik milline käsk, mis teie turuandmed pärib: börsi API, puhverdatud CSV-fail. Mõte on kohaletoimetamises, mitte allikas.)

Selliste korduvate sõnumite puhul tasub teada kahte dokumenteeritud lisavõimalust: kui lisate saadetavatele andmetele välja fingerprint, siis sama väärtusega korduv saatmine uuendab olemasolevat sõnumit, selle asemel et uut virna lisada, nii jääb hinnateavitus üheks märguandeks, mitte neljakümneks päevas. Ja "type": "sms" saadab sama sõnumi hoopis SMS-ina, kui kasutajal on mobiilinumber määratud: varukanal juhuks, kui kellegi telefonist on rakendus kadunud.

Pesumasin sai valmis. Voolutarvet jälgiv nutipistik, Home Assistanti automaatika, arvestit pärivi skript – ükskõik mis tsükli lõpu tuvastab, teavitus on ikka seesama üks rida. Naljakas näide, aga päris harjumus: kui tõukemärguande saatmine ei maksa midagi, hakkate teavitama kõigest.

Milleks see kanal sobib (ja milleks mitte)

SMS-iga võrreldes on vastuvõtja pool palju tugevam: SMS jõuab suvalisse telefoni, kus SIM-kaart parasjagu asub, ja saatja nime saab igaüks võltsida; Notakey teavitus aga jõuab ainult Authenticatori rakendusse seadmetes, mis on teie teenuses läbinud krüptograafilise registreerimise. Keegi ei saa end ise teie teavituste saajaks lisada ega saatjana esineda.

Üks aus piirang otse API dokumentatsioonist: teavituse sisu ise ei ole otspunktkrüpteeritud: nagu iga mobiilne tõukemärguanne, liigub see läbi Apple’i ja Google’i tõukemärguandeteenuste ning on loetav rakendustele, millel on seadmes ligipääs märguannetele. Käsitlege sõnumi sisu seega nagu piipariteadet, mitte nagu pitseeritud ümbrikku: „varundus ebaõnnestus hostis X“ sobib, parool või API võti mitte. Kui vaja on edastada midagi tõeliselt salajast, kasutage hoopis autentimispäringut (urn:notakey:auth). Seal on tõukemärguanne vaid koputus uksele ning sisu laadib rakendus pärast kasutaja vastust alla oma sertifikaadiga autenditud kanali kaudu.

Kuhu see sobitub

Kui seade kaitseb juba teie VPN-i või rakendusi, on teavitused tasuta võimekus, mida te veel ei kasuta: sama teenus, sama rakendus, samad API sisselogimisandmed, üksainus lisanduv otspunkt. Ja kui olete seni maksnud SMS-lüüsile ettevõttesiseste hoiatuste eest, asendab see selle iga saaja jaoks, kelle taskus on registreeritud telefon.

Seotud juhendid

← Kõik postitused

Esimene paroolivaba sisselogimine juba sel nädalal

30-minutiline vestlus inseneriga, mitte müügiesitlus. Paneme koos paika, kuidas teie VPN-i, SSO või Windowsi keskkonnas töötav pilootprojekt käima saab.

Telli demoProovi demopanka