Push paziņojumi no jebkura skripta — iekārta kā brīdinājumu kanāls

Notakey iekārtu parasti raksturo kā autentifikācijas serveri: notiek pieteikšanās, tālrunī pienāk push pieprasījums, lietotājs to apstiprina. Taču pa to pašu piegādes kanālu var nosūtīt arī otru ziņojumu veidu: vienkāršu paziņojumu (notification), un līdz ar to iekārta kļūst par universālu push kanālu: ar vienu curl komandu no jebkura skripta var aizsūtīt ziņu uz ikvienu jūsu servisā reģistrēto tālruni.

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

Atšķirībā no autentifikācijas pieprasījuma paziņojumam apstiprinājums nav vajadzīgs: tas vienkārši parādās tālrunī. Adresāts ir konkrēts lietotājvārds, un ziņa uzreiz nonāk visās lietotāja reģistrētajās ierīcēs. Tāpēc paziņojumi lieliski aizstāj SMS (maksa par katru ziņojumu, viltojams sūtītāja vārds) un e-pastu (kas nereti tiek izlasīts tikai pirmdien) visur, kur tie līdz šim kalpojuši brīdinājumiem: darbu uzraudzībā, dežūru izsaukumos, ziņās darbiniekiem.

Prasības

Strādājoša Notakey iekārta (mākonī vai lokāli) ar izveidotu servisu un vismaz vienu lietotāju, kuram reģistrēts tālrunis. Ja jau izmantojat VPN divfaktoru autentifikāciju (2FA) vai SSO, tas viss jums jau ir: paziņojumus var sūtīt caur to pašu servisu, ko izmanto pieteikšanās, vai caur atsevišķu, ja vēlaties citu noformējumu.
API piekļuves dati (klienta ID un klienta noslēpums), ko izveido vadības paneļa sadaļā Access credentials (kā tos izveidot, aprakstīts
1. solī).
curl un jq jebkurā vidē, kas var sasniegt iekārtu. Citu atkarību nav.

1. solis — izveidojiet API piekļuves datus

Vadības panelī atveriet Access credentials un izveidojiet saviem skriptiem piekļuves datus. Šeit svarīgas divas lietas:

Tvērumi (scopes). Piešķiriet urn:notakey:notify. Ar to šai instrukcijai pietiek. Otrs tvērums, urn:notakey:auth, ļauj veidot autentifikācijas (apstiprināt/noraidīt) pieprasījumus; pievienojiet to tikai tad, ja tie paši piekļuves dati tiešām kalpos abiem mērķiem. Piekļuves datus, kas ļauj sūtīt tikai paziņojumus, nevar ļaunprātīgi izmantot pieteikšanās apstiprinājumu izraisīšanai, tāpēc turiet tvērumu sarakstu tik īsu, cik vien uzdevums ļauj.
Jūs saņemsiet klienta ID un klienta noslēpumu (client secret). Noslēpums ļauj sūtīt ziņojumus visiem servisa lietotājiem, tāpēc glabājiet to tikpat rūpīgi kā root paroli.

2. solis — apmainiet piekļuves datus pret tokenu un atjaunojiet to regulāri

Pats paziņojuma izsaukums klienta noslēpumu neizmanto. Tam vajadzīgs bearer piekļuves tokens (access token), ko iegūst ar standarta OAuth 2.0 client-credentials plūsmu. Piekļuves tokeni ir apzināti īslaicīgi: ieplānojiet to atjaunošanu aptuveni reizi stundā, citādi skripti, kas 59 minūtes strādājuši bez aizķeršanās, kādā brīdī sāks saņemt autorizācijas kļūdas.

Tāpēc tokena atjaunošana ir cron uzdevums, nevis vienreizējs iestatīšanas solis:

#!/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ā glabājas klienta noslēpums, un tas raksta tokena failu, tāpēc jāaizsargā abi:

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

Ja piešķīrāt arī urn:notakey:auth, pieprasiet to kā atsevišķu tokenu atsevišķā failā (tas pats izsaukums, tikai scope=urn:notakey:auth), nevis vienu tokenu ar abiem tvērumiem; tā paziņojumu skriptu rīcībā nekad nenonāks tokens, ar ko var izveidot pieteikšanās apstiprinājumus.

3. solis — viens atkārtoti izmantojams paziņojumu skripts

Visi turpmākie piemēri izsauc tieši šo vienu skriptu. Tam padod lietotājvārdu, virsrakstu un ziņojuma tekstu:

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

Aizstājiet ntk.example.com ar savas iekārtas adresi un <service-id> ar servisa UUID no vadības paneļa. Izmēģiniet:

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

Push paziņojums pienāk lietotnē Notakey Authenticator, tajā pašā lietotnē, ko lietotājs jau izmanto pieteikšanās vajadzībām, tāpēc nekas jauns nav jāinstalē, jāizskaidro vai jāsaskaņo ar mobilo ierīču pārvaldības (MDM) risinājumu.

4. solis — izsauciet to no jebkuras vietas

Kad kanāls ir sasniedzams ar vienu komandrindas izsaukumu, jauni pielietojumi rodas paši no sevis. Daži piemēri, kas jau šodien darbojas reālās sistēmās:

Dublēšanas uzdevums, kas pats ziņo par neveiksmi. Klasiska klusā kļūme: dublēšana jau mēnešiem nestrādā, un neviens to nav pamanījis. To novērš divas rindiņas uzdevuma beigās:

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

Diska vieta, sertifikāta derīguma termiņš vai jebkas cits, ko var pārbaudīt ar 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

Ziņa visiem darbiniekiem. API vienā izsaukumā adresē vienu lietotājvārdu, tāpēc ziņu visam uzņēmumam izsūta ar ciklu pa lietotāju sarakstu (apkopes logi, biroja slēgšana, incidentu paziņojumi):

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

Elektrības biržas cena ik pa divām stundām. Ne viss, ko vērts sūtīt, ir avārija. Šis piemērs darbojas no cron un pastāsta, cik maksās nākamā elektrības stunda, noderīgi, izlemjot, kad ieslēgt trauku mazgājamo mašīnu:

#!/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 šeit apzīmē jebkuru veidu, kā iegūstat tirgus datus: biržas API vai kešatmiņā noglabātu CSV failu. Būtiskais te ir piegāde, nevis datu avots.)

Atkārtotiem ziņojumiem noder divas dokumentētas papildiespējas. Ja ziņojumam pievieno lauku fingerprint, nākamais sūtījums ar to pašu vērtību atjaunina jau esošo ziņojumu, nevis pievieno jaunu, tāpēc cenu rādītājs tālrunī paliek viens paziņojums, nevis četrdesmit dienā. Savukārt "type": "sms" to pašu ziņojumu nosūta kā SMS, ja lietotājam norādīts mobilā tālruņa numurs: rezerves ceļš gadījumiem, kad lietotne no tālruņa pazudusi.

Veļas mašīna ir beigusi mazgāt. Viedā kontaktligzda, kas seko strāvas patēriņam, Home Assistant automatizācija vai skripts, kas nolasa skaitītāju — lai kas konstatētu cikla beigas, paziņojuma nosūtīšana ir tā pati viena komandas rindiņa. Piemērs sadzīvisks, taču ieradums īsts: kad push ziņojuma nosūtīšana neko nemaksā, pamazām sākat ziņot par visu.

Kam šis kanāls der (un kam ne)

Saņēmēja pusē šis kanāls ir krietni drošāks par SMS. Īsziņa nonāk jebkurā ierīcē, kurā tobrīd ielikta attiecīgā SIM karte, un tās sūtītāja vārdu var viltot ikviens; Notakey paziņojums turpretī nonāk tikai Authenticator lietotnē tajās ierīcēs, kas jūsu servisā izgājušas kriptogrāfisku reģistrāciju. Neviens nevar nedz pats pierakstīties uz jūsu brīdinājumiem, nedz uzdoties par sūtītāju.

Viens ierobežojums, kas godīgi jāpiemin un ir norādīts arī API dokumentācijā: paziņojuma teksts nav šifrēts no gala līdz galam (end-to-end): tāpat kā jebkurš mobilais push ziņojums tas ceļo caur Apple un Google push pakalpojumiem un ir pieejams lietotnēm, kurām ierīcē atļauta piekļuve paziņojumiem. Tāpēc izturieties pret ziņojuma tekstu kā pret peidžera ziņu, nevis aizzīmogotu aploksni: “Backup failed on host X” ir pieņemami; parole vai API atslēga nav. Ja jānodod kaut kas patiešām konfidenciāls, izmantojiet autentifikācijas pieprasījumu (urn:notakey:auth). Tur push ziņojums ir tikai klauvējiens pie durvīm, un datus lietotne pēc lietotāja atbildes saņem pa savu ar sertifikātu autentificēto kanālu.

Kā tas iekļaujas kopainā

Ja iekārta jau aizsargā jūsu VPN vai lietotnes, paziņojumi ir iespēja, kas jums jau pieder, tikai vēl netiek izmantota: tas pats serviss, tā pati lietotne, tie paši API piekļuves dati un tikai viens papildu galapunkts (endpoint). Un, ja par iekšējiem brīdinājumiem līdz šim maksājāt SMS vārtejai, šis kanāls to aizstāj visiem saņēmējiem, kuriem reģistrēts tālrunis.

Saistītie ceļveži

VPN divfaktoru autentifikācija (2FA) ar RADIUS — pilna autentifikācijas starpniekservera (auth-proxy) uzstādīšana: tās pašas iekārtas autentifikācijas puse
Linux SSH divfaktoru autentifikācija (2FA) ar pam_radius: tālruņa apstiprinājumi serveriem, kuros darbojas jūsu skripti
API dokumentācija: pilns REST API klāsts, tostarp ierīču vaicājumi un autentifikācijas pieprasījumi