Push pranešimai iš bet kurio skripto – įrenginys kaip įspėjimų kanalas

Notakey įrenginys paprastai apibūdinamas kaip autentifikacijos serveris: įvyksta prisijungimas, į telefoną atkeliauja push užklausa, naudotojas ją patvirtina. Tačiau tas pats pristatymo kanalas priima ir antrą žinučių tipą, paprastą pranešimą, o tai paverčia įrenginį kur kas universalesniu įrankiu: push pranešimų kanalu į kiekvieną jūsų servise registruotą telefoną, pasiekiamu iš bet kurio skripto vienu curl kvietimu.

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

Skirtingai nei autentifikacijos užklausa, pranešimas neprašo patvirtinimo: jis tiesiog pasirodo telefone, adresuotas naudotojo vardui, ir vienu metu pristatomas į visus registruotus naudotojo įrenginius. Todėl jis tiesiogiai pakeičia sprendimus ten, kur kitu atveju jungtumėte SMS (mokestis už kiekvieną žinutę, suklastojamas siuntėjas) ar el. paštą (ignoruojamas iki pirmadienio): užduočių stebėjimas, budinčio personalo informavimas, pranešimai darbuotojams.

Ko prireiks

• Veikiančio Notakey įrenginio (debesyje ar savoje infrastruktūroje) su servisu ir bent vienu naudotoju, turinčiu registruotą telefoną. Jei jau naudojate VPN 2FA ar SSO, visa tai jau turite: pranešimai keliauja per tą patį servisą kaip ir jūsų prisijungimai, arba per atskirą, jei norite kitokio prekės ženklo pateikimo.
• API prisijungimo duomenų (kliento ID ir kliento paslapties), sukuriamų valdymo skydelio skiltyje Access credentials (žr. 1 žingsnį).
• curl ir jq bet kurioje mašinoje, iš kurios pasiekiamas įrenginys. Tai visas priklausomybių sąrašas.

1 žingsnis: sukurkite API prisijungimo duomenis

Valdymo skydelyje atverkite Access credentials ir sukurkite prisijungimo duomenis savo skriptams. Čia svarbūs du dalykai:

• Teisės (scopes). Suteikite urn:notakey:notify. Būtent šios teisės reikia šiame vadove. Egzistuoja ir urn:notakey:auth, skirta autentifikacijos (patvirtinti / atmesti) užklausoms kurti; pridėkite ją tik tuo atveju, jei tie patys prisijungimo duomenys darys abu darbus. Vien pranešimams skirtų prisijungimo duomenų neįmanoma piktnaudžiaujant panaudoti prisijungimo patvirtinimams inicijuoti, todėl teisių sąrašą laikykite tokį trumpą, kokį tik leidžia užduotis.
• Gausite kliento ID ir kliento paslaptį. Paslaptis suteikia teisę siųsti žinutes visiems serviso naudotojams, todėl saugokite ją kaip root slaptažodį.

2 žingsnis: iškeiskite juos į prieigos raktą ir nuolat jį atnaujinkite

Pats pranešimo kvietimas kliento paslapties nenaudoja. Jis naudoja prieigos raktą (token), gaunamą standartine OAuth 2.0 client credentials procedūra. Prieigos raktai sąmoningai galioja trumpai: planuokite atnaujinti maždaug kartą per valandą, antraip jūsų skriptai, sklandžiai veikę 59 minutes, tam tikru momentu ims grąžinti autorizacijos klaidas.

Taigi token atnaujinimas yra cron užduotis, o ne vienkartinis sąrankos žingsnis:

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

Skripte įrašyta kliento paslaptis, o jo rezultatas yra token failas, todėl apribokite prieigą prie abiejų:

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

Jei suteikėte ir urn:notakey:auth, gaukite jį kaip atskirą token į atskirą failą (tas pats kvietimas, tik scope=urn:notakey:auth), o ne vieną token su abiem teisėmis; tuomet pranešimų skriptai niekada neturės token, kuriuo būtų galima kurti prisijungimo patvirtinimus.

3 žingsnis: vienas daugkartinio naudojimo pranešimų skriptas

Visa kita šiame vadove kviečia šį vieną skriptą. Jis priima naudotojo vardą, antraštę ir žinutės tekstą:

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

Pakeiskite ntk.example.com savo įrenginio adresu, o <service-id> pakeiskite serviso UUID iš valdymo skydelio. Išbandykite:

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

Push pranešimas atkeliauja į Notakey Authenticator programėlę, tą pačią, kurią naudotojas jau turi prisijungimams, todėl nieko naujo nereikia nei diegti, nei aiškinti, nei derinti su mobiliųjų įrenginių valdymo sistema.

4 žingsnis: kvieskite jį iš bet kur

Kai kanalas tampa viena komandos eilute, panaudojimo scenarijai kaupiasi savaime. Keli, šiandien veikiantys gamybinėje aplinkoje:

Atsarginių kopijų užduotis, kuri praneša apie rezultatą. Klasikinė tyli nesėkmė: atsarginės kopijos, nustojusios veikti prieš kelis mėnesius, kurių niekas nepasigedo. Tai išsprendžia dvi eilutės užduoties pabaigoje:

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

Vieta diske, sertifikatų galiojimo pabaiga, viskas, ką gali patikrinti 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

Pranešimas visiems darbuotojams. API vienu kvietimu adresuoja vieną naudotojo vardą, todėl žinutė visai įmonei yra ciklas per jūsų naudotojų sąrašą (priežiūros langai, biuro nedarbo dienos, pranešimai apie incidentus):

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

Elektros biržos kainos, po dvi kas dvi valandas. Ne viskas, ką verta siųsti, yra avarija. Šis skriptas paleidžiamas iš cron ir praneša naudotojui, kiek kainuos ateinančios valandos elektra, praverčia sprendžiant, kada paleisti indaplovę:

#!/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 yra tai, kas parsiunčia jūsų rinkos duomenis: biržos API, podėlyje laikomas CSV failas. Esmė čia yra pristatymas, o ne šaltinis.)

Dvi dokumentuotos papildomos galimybės, vertos dėmesio tokioms pasikartojančioms žinutėms: pridėjus prie užklausos turinio fingerprint lauką, pakartotinis siuntimas su tuo pačiu fingerprint atnaujina esamą žinutę, užuot pridėjęs naują; taip kainų švieslentė lieka vienu pranešimu, o ne keturiasdešimčia per dieną. O "type": "sms" tą pačią žinutę išsiunčia SMS žinute, jei naudotojas turi nurodytą mobiliojo telefono numerį: atsarginis kanalas tam, kurio telefone programėlės nebeliko.

Skalbimo mašina baigė darbą. Energijos suvartojimą stebintis išmanusis kištukas, Home Assistant automatika, skaitiklį apklausiantis skriptas – kad ir kas aptiktų ciklo pabaigą, pranešimas yra ta pati viena eilutė. Juokingas pavyzdys, bet tikras įprotis: kai push siuntimas nieko nekainuoja, imate pranešinėti apie viską.

Kam šis kanalas tinka ir kam netinka

Palyginti su SMS, gavėjo pusė gerokai stipresnė: SMS atkeliauja į bet kurį telefoną, kuriame tuo metu yra SIM kortelė, nuo siuntėjo vardo, kurį gali suklastoti bet kas, o Notakey pranešimas pasiekia tik Authenticator programėlę įrenginiuose, atlikusiuose kriptografinę registraciją jūsų servise. Niekas negali pats užsiprenumeruoti jūsų įspėjimų ir niekas negali suklastoti siuntėjo.

Vienas sąžiningas apribojimas, tiesiai iš API dokumentacijos: pats pranešimo turinys nėra šifruojamas ištisinio šifravimo principu: kaip ir bet kuris mobilusis push, jis persiunčiamas per Apple ir Google push paslaugas ir yra įskaitomas programėlėms, įrenginyje turinčioms prieigą prie pranešimų. Todėl žinutės turinį traktuokite kaip pranešimų gaviklio žinutę, o ne kaip užklijuotą voką: „atsarginė kopija serveryje X nepavyko“ tinka; slaptažodis ar API raktas – ne. Kai reikia perduoti ką nors iš tiesų slapto, naudokite autentifikacijos užklausą (urn:notakey:auth). Ten push tėra beldimas į duris, o turinį programėlė parsisiunčia savo sertifikatu autentifikuotu kanalu jau po to, kai naudotojas atsako.

Kur tai pritampa

Jei įrenginys jau saugo jūsų VPN ar programas, pranešimai yra nemokama galimybė, kurios dar nenaudojate: tas pats servisas, ta pati programėlė, tie patys API prisijungimo duomenys, vienas papildomas galinis taškas. O jei už vidinius įspėjimus iki šiol mokėjote SMS tinklų sąsajai, šis kanalas ją pakeičia kiekvienam gavėjui, nešiojančiam registruotą telefoną.

Susiję vadovai

• VPN 2FA su RADIUS – visa autentifikacijos tarpinio serverio sąranka: to paties įrenginio autentifikacijos pusė
• Linux SSH 2FA su pam_radius: prisijungimų tvirtinimas telefonu serveriams, kuriuose veikia jūsų skriptai
• API dokumentacija: visa REST sąsaja, įskaitant įrenginių užklausas ir autentifikacijos užklausas