Kako preklicati Open Badge (in kaj se zgodi s kopijo prejemnika)

Preklic v Open Badges: kako deluje, kaj se spremeni za prejemnika in kako pravilno ravnati pri „izdano pomotoma“, „poverilnica je potekla“ in „kršitev pravil“.

Nacho Coll Avtor Posodobljeno 9 min branja
Preklic v Open Badges: kako deluje, kaj se spremeni za prejemnika in kako pravilno ravnati pri „izdano pomotoma“, „poverilnica je potekla“ in „kršitev pravil“.

Prej ali slej mora vsak program, ki izdaja digitalne poverilnice, katero tudi preklicati. Certifikat je šel napačni osebi. Ugotovili ste, da je udeleženec goljufal pri zaključnem preverjanju. Pogodba s partnerjem se je iztekla, značke z napisom „Certified Partner“ pa ne bi smele več veljati. Izdajanje je lahka pot; preklic pa je del, ki odloča, ali lahko vašim poverilnicam res zaupamo.

Ta vodnik pojasnjuje, kako preklic deluje v Open Badges, kaj prejemnik po njem vidi in česa ne, ter kako na https://badges.ninja prekličete eno poverilnico ali nekaj sto naenkrat, z nadzorne plošče ali prek API-ja.

Kaj pomeni „preklicati“ v Open Badges

V specifikaciji Open Badges v2.0 je vsaka izdana značka trditev (assertion): majhen dokument JSON-LD na javnem naslovu URL, ki pravi: „ta izdajatelj je to značko na ta datum podelil temu prejemniku.“ Preklic je preprosto sprememba tega gostovanega dokumenta. Trditev dobi "revoked": true in po želji niz "revocationReason", ki pojasni razlog.

Ta zasnova ima pomembno posledico, ki marsikaterega skrbnika programa preseneti:

  • Gostovana trditev je vir resnice. Vsak, ki poverilnico preveri z branjem naslova trditve ali odpiranjem strani za preverjanje, takoj vidi preklicano stanje.
  • Kopije se ne prikličejo. Če je prejemnik prenesel sliko značke ali datoteko JSON ali jo pripel v portfolio, se ta datoteka ne spremeni. Še vedno vsebuje povezavo do vaše gostovane trditve, zato bo preverjevalec, ki ji sledi, videl, da je preklicana, oseba, ki le pogleda shranjeno sliko PNG, pa ne.

Preklic je torej izjava na končni točki za preverjanje, ne brisanje. Predstavljajte si ga kot žig „VOID“ na glavnem zapisu, ne kot lov na vsako fotokopijo.

Če si želite dokument ogledati od blizu, vas skozi vsako polje popelje naš pregled Open Badge JSON-LD.

Preklic, ponovna izdaja ali brisanje: izberite pravo dejanje

Preden karkoli kliknete, se odločite, katero od treh dejanj ustreza situaciji. Niso zamenljiva.

SituacijaNajboljše dejanjeZakaj
Poverilnica je bila izdana napačni osebi ali s tipkarsko napakoBrisanje (če ni bila poslana) ali preklic in nato ponovna izdajaBrisanje odstrani zapis v celoti; preklic ohrani revizijsko sled
Udeleženec je kršil pravila ali je bila poverilnica pridobljena nedovoljenoPreklic z razlogomZapis ostane preverljiv kot preklican, kar želite v primeru spora
Poverilnici je preprosto potekel rokNe storite ničesar; ob izdaji nastavite datum potekaPotek je običajen del življenjskega cikla, ne preklic
Program preklican, skupina razveljavljenaMnožični preklicEno opravilo, en razlog, uporabljen za vse
Podatki so bili napačni, a je poverilnica sicer veljavnaUredite pred pošiljanjem ali po pošiljanju prekličite in izdajte znovaPrejemnikova izkušnja ostane čista

Dve pravili:

  1. Za vse resnično raje prekličite kot izbrišite. Javna stran izbrisane poverilnice vrne napako „ni najdeno“. Preklicana se še vedno prikaže in jasno pove, da je preklicana, kar je veliko boljši dokaz, če kdo pozneje vpraša, kaj se je zgodilo.
  2. Preklica nikoli ne uporabljajte namesto poteka. Če poverilnica velja le dve leti, ob izdaji nastavite datum poteka. Značka, ki tiho poteče, se razlikuje od umaknjene, vaša stran za preverjanje pa mora povedati, katera od obeh je.

Preklic z nadzorne plošče

Za peščico poverilnic je nadzorna plošča najhitrejša pot in ne potrebuje kode.

  1. Prijavite se in v stranski vrstici odprite Awards.
  2. Poiščite poverilnico. Seznam prikazuje prejemnika, ime značke, datum izdaje in potek, iskati pa je mogoče po prejemniku.
  3. Kliknite vrstico (ali View), da odprete podrobnosti poverilnice.
  4. Kliknite Revoke.
  5. V potrditvenem oknu po želji vnesite razlog in po želji označite Email the recipient that their credential was revoked.
  6. Potrdite.

Award detail modal

Poverilnica ostane na vašem seznamu z rdečo oznako Revoked ob prejemniku, tako da vi in vaša ekipa vedno vidite, kaj je bilo umaknjeno. Preklic poverilnice ne povrne v kvoto vašega paketa. Izdali ste jo, zato se je štela.

Opomba o polju z razlogom

Razlog je neobvezen, a ga izpolnite. Shrani se s poverilnico, v javni trditvi Open Badges se pojavi kot revocationReason in je vključen v vsebino webhooka, ki jo prejmejo vaši sistemi. Ker je javen v trditvi, ga napišite, kot bi ga za zunanjega bralca. „Izdano pomotoma“ ali „Program preklican“ je v redu. „Jana je goljufala pri 14. vprašanju“ ni. Osebne podrobnosti hranite v lastnih evidencah, javni razlog pa naj ostane nevtralen.

Ali naj prejemniku pošljete e-pošto?

Običajno da. Udeleženec, ki za neveljavnost svoje poverilnice izve šele, ko delodajalec klikne povezavo za preverjanje, ima vso pravico biti nezadovoljen z vami. Obvestilo je izbirno ravno zato, ker nekateri preklici (na primer množično čiščenje testnih podelitev) nikogar ne bi smeli motiti. Naše priporočilo:

  • Pošljite e-pošto, ko preklic zadeva resnično osebo, ki poverilnico morda še vedno prikazuje.
  • E-pošte ne pošiljajte, ko urejate interne testne podatke ali razveljavljate poverilnice, ki niso bile nikoli poslane.

Preklic več poverilnic naenkrat

Programi redko potrebujejo preklic ene same poverilnice; pogosteje gre za celotno skupino. Na seznamu Awards:

  1. Označite potrditvena polja poverilnic, ki jih želite umakniti.
  2. V vrstici za množična dejanja kliknite Revoke selected.
  3. Dodajte razlog in se odločite, ali boste obvestili prejemnike, nato potrdite.

Množični preklic teče kot trajno opravilo v ozadju, zato se več sto poverilnic ne bo iztekalo v zavihku brskalnika. Že preklicane poverilnice se preskočijo, namesto da bi paket spodletel, delno prekinjeno opravilo pa je mogoče nadaljevati. Isti mehanizem poganja množično izdajanje iz preglednice, ki ga opisujemo v kako izdati Open Badges iz CSV.

Preklic prek API-ja

Če vaš učni sistem ali platforma za kadre odloča, kdo ni več certificiran, lahko prekličete programsko. Končna točka je POST /awards/{awardId}/revoke, overjena s ključem API (X-Api-Key: bws_<32-hex>) ali žetonom Bearer iz Cognito. ID podelitve gre v pot; reason in notify gresta v telo JSON in sta neobvezna.

Z curl:

curl -X POST https://api.badges.ninja/awards/<award-id>/revoke \
  -H "X-Api-Key: bws_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Issued to the wrong recipient","notify":true}'
# 200 -> {"revoked":true,"awardId":"<award-id>"}

V JavaScriptu:

const res = await fetch(`https://api.badges.ninja/awards/${awardId}/revoke`, {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ reason: "Program cancelled", notify: false }),
});
const { revoked } = await res.json(); // true

In v Pythonu:

import requests
res = requests.post(
    f"https://api.badges.ninja/awards/{award_id}/revoke",
    headers={"X-Api-Key": API_KEY},
    json={"reason": "Program cancelled", "notify": False},
)
print(res.json()["revoked"])  # True

Nekaj uporabnih podrobnosti:

  • Je idempotenten. Preklic že preklicane poverilnice vrne isti uspešni odgovor in ne pošlje drugega obvestila. Zato ga je varno klicati iz opravila s ponovnimi poskusi.
  • Razlogi se skrajšajo na 500 znakov.
  • notify je privzeto false. E-pošta se ne pošlje, razen če to zahtevate.
  • Množični preklic je na voljo prek množične končne točke z action: "revoke" in seznamom ID-jev podelitev; vrne ID opravila, ki ga lahko spremljate. Vsi parametri so v referenci API za awards.

API potrebujete le, kadar preklic poganja drug sistem. Za enkratno dejanje je nadzorna plošča hitrejša in ima potrditveni korak, ki vas varuje pred napačno natipkanim ID-jem.

Kaj vidita prejemnik in preverjevalec

Po preklicu se spremeni naslednje, in to takole hitro.

Na javni strani za preverjanje. Stran na https://badges.ninja/awards/<award-id> prikazuje poverilnico kot preklicano, naslov strani za deljenje na družbenih omrežjih pa ima predpono „[Revoked]“, da deljena povezava v predogledni kartici ne izgleda kot veljavna poverilnica.

V trditvi Open Badges v2.0. Gostovani JSON na https://api.badges.ninja/certify-badge/award/<award-id> zdaj vsebuje "revoked": true in "revocationReason", če ste ga podali. Preklicane trditve se predpomnijo le približno 30 sekund, veljavne pa pet minut, zato sprememba do preverjevalcev pride hitro.

V poverilnici Open Badges 3.0. Preklic prav tako preklopi bit poverilnice v W3C Bitstring Status List, po katerem denarnice preverljivih poverilnic in preverjevalci zaznajo preklic. Ta seznam se predpomni na kratko, zato pričakujte širjenje v približno minuti. Če tehtate med obema različicama, glejte Open Badges v2 proti v3.

V prejemnikovi lastni kopiji. Na datoteki, ki jo je prenesel, se nič ne spremeni. Slika značke na njegovem prenosniku izgleda enako. Spremeni se izid preverjanja: vsak, ki klikne povezavo ali poverilnico preveri programsko, dobi odgovor „preklicano“. Če ste ga obvestili, ima tudi e-pošto z razlago.

Na LinkedInu. Poverilnica, dodana na profil LinkedIn, je povezava z metapodatki, ki kaže nazaj na vašo stran za preverjanje. LinkedIn namesto vas ne preverja preklicev, zato lahko vnos ostane na profilu, vendar vsak, ki sledi povezavi, pristane na strani s preklicem. To je še en razlog, da pošljete obvestilo in prejemnika prosite, naj vnos odstrani.

Obvestite lastne sisteme: webhooki

Preklic je v vaši organizaciji redko konec zgodbe. Udeleženec morda izgubi dostop do skupnosti, treba bo posodobiti kadrovski zapis ali odstraniti oznako v CRM. Badges Ninja ob preklicu poverilnice odda dogodek webhooka credential.revoked z naslovom podelitve in razlogom:

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<award-id>",
  "reason": "Issued in error"
}

Naročite se nanj in vaši podrejeni sistemi ostanejo usklajeni, ne da bi se kdo spomnil na posodobitev. Podrobnosti nastavitve so v dokumentaciji webhookov, širši model dogodkov pa opisujemo v nastavitev webhookov za dogodke značk.

Preprosta politika preklica, ki jo lahko sprejmete še danes

Orodja so lažja polovica. Težja polovica je vnaprej določiti, kdaj boste preklicali in kdo sme. Kratka pisna politika prepreči poznejše spore. Uporaben predlog:

  1. Razlogi za preklic. Naštejte jih: izdano pomotoma, pridobljeno z nepoštenim ravnanjem, zahteva ni več izpolnjena (na primer članstvo je poteklo) ali program umaknjen.
  2. Kdo odloča. Poimenujte vlogo, ne osebe. Pravico do preklica omejite na to vlogo.
  3. Obvestilo. Navedite, da so prejemniki obveščeni po e-pošti z razlogom, razen če poverilnica ni bila nikoli dostavljena.
  4. Pritožba. Prejemnikom omogočite, da odločitev izpodbijajo, in povejte, v kolikšnem času boste odgovorili. Če je pritožba uspešna, izdajte novo poverilnico, namesto da bi poskušali razveljaviti preklic, in zgodovina ostane čista.
  5. Evidenca. Hranite interni zapis, kdo je kaj preklical in zakaj, ločeno od nevtralnega javnega razloga.

Politiko objavite na isti strani, kjer opisujete poverilnico, da pravila vedo že pred prijavo.

Pogoste napake, ki se jim izognite

  • Brisanje, ko ste želeli preklicati. Brisanje je trajno in ga ni mogoče razveljaviti, javna stran pa izgine. Uporabite ga za resnične napake pri poverilnicah, ki jih nihče ni videl.
  • Zasebne podrobnosti v razlogu. V trditvi je javen.
  • Pričakovanje, da se shranjene kopije spremenijo. Preklic živi na končni točki za preverjanje. Prejemnikom povejte, naj poverilnico odstranijo s profilov in iz portfeljev.
  • Preklic namesto poteka. Za časovno omejene poverilnice uporabite datum poteka.
  • Domneva o povračilu. Preklicane poverilnice se še vedno štejejo v kvoto vašega paketa.
  • Pozabljeni podrejeni sistemi. Povežite webhook, da dostopi in zapisi sledijo stanju poverilnice.

Pogosta vprašanja

Ali lahko preklic razveljavim? Ne prek vmesnika. Če ste preklicali pomotoma, prejemniku izdajte novo poverilnico. Preklicana ostane kot del revizijske sledi.

Ali mora prejemnik karkoli storiti? Ne. Če ste se odločili, da ga obvestite, prejme e-pošto. Sicer se sprememba tiho zgodi na strani za preverjanje.

Ali preklic deluje za poverilnice, ki niso bile poslane? Da, vendar pri neposlani poverilnici s preprosto napako morda raje uredite pred pošiljanjem ali jo izbrišete, če je nihče ni videl.

Ali je število preklicev omejeno? Množični preklic teče kot nadaljevalno opravilo v ozadju, zato se veliki paketi obdelajo z eno operacijo, ne eno za drugo.

Ali bodo delodajalci videli, da je bila poverilnica preklicana? Vsak, ki jo preveri prek javnega naslova ali trditve, vidi stanje preklica in razlog, če ste ga podali.

Zaključek

Preklic Open Badge je majhno dejanje z resnimi posledicami za zaupanje. Za eno poverilnico ga opravite z nadzorne plošče, za skupino uporabite množični preklic, API ali webhooke pa uporabite, kadar odločitev vodi drug sistem. Razlogi naj bodo nevtralni, obvestite ljudi, ki morajo vedeti, in ne pozabite: preklic spremeni, kaj vidijo preverjevalci, ne datotek, ki so že v rokah prejemnikov.

Ste pripravljeni izdati svojo prvo preverljivo poverilnico? Začnite brezplačno na badges.ninja — vizualni oblikovalnik, javna stran za preverjanje, PDF certifikat, izhod Open Badge v2.0. Kreditna kartica ni potrebna.

Nacho Coll

O avtorju

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

Nazaj na Blog

Povezani članki