Kako opozvati Open Badge (i što se događa s primateljevom kopijom)

Opoziv u Open Badgesu: kako funkcionira, što se mijenja za primatelja i kako ispravno postupiti u slučajevima «izdano greškom», «vjerodajnica je istekla» i «kršenje pravila».

Nacho Coll Autor: Ažurirano 9 min čitanja
Opoziv u Open Badgesu: kako funkcionira, što se mijenja za primatelja i kako ispravno postupiti u slučajevima «izdano greškom», «vjerodajnica je istekla» i «kršenje pravila».

Prije ili kasnije svaki program koji izdaje digitalne vjerodajnice mora neku povući. Certifikat je otišao pogrešnoj osobi. Otkriveno je da je polaznik varao na završnoj provjeri. Ugovor s partnerom je završio, a značke na kojima piše «Certificirani partner» više ne bi trebale vrijediti. Izdavanje je sretan put; opoziv je dio koji odlučuje mogu li se vašim vjerodajnicama doista vjerovati.

Ovaj vodič objašnjava kako opoziv funkcionira u Open Badgesu, što primatelj nakon toga vidi, a što ne, te kako opozvati jednu vjerodajnicu ili nekoliko stotina na https://badges.ninja, putem nadzorne ploče ili API-ja.

Što «opozvati» znači u Open Badgesu

U specifikaciji Open Badges v2.0 svaka izdana značka je tvrdnja (assertion): mali JSON-LD dokument smješten na javnom URL-u koji kaže «ovaj izdavatelj dodijelio je ovu značku ovom primatelju na ovaj datum». Opoziv je jednostavno promjena tog dokumenta. Tvrdnja dobiva "revoked": true i, po želji, tekst "revocationReason" koji objašnjava razlog.

Taj dizajn ima važnu posljedicu koja iznenađuje mnoge voditelje programa:

  • Smještena tvrdnja izvor je istine. Svatko tko provjerava vjerodajnicu dohvaćanjem URL-a tvrdnje ili otvaranjem stranice za provjeru odmah vidi opozvano stanje.
  • Kopije se ne povlače. Ako je primatelj preuzeo sliku značke ili JSON, ili ju je prikvačio u portfelj, ta se datoteka ne mijenja. I dalje sadrži poveznicu na vašu smještenu tvrdnju, pa će provjeravatelj koji slijedi poveznicu vidjeti da je opozvana, ali osoba koja samo pogleda spremljeni PNG neće.

Opoziv je dakle izjava dana na točki provjere, a ne brisanje. Zamislite to kao pečat «PONIŠTENO» na izvornom zapisu umjesto traženja svake fotokopije.

Ako želite izbliza vidjeti sam dokument, naš prolaz kroz Open Badge JSON-LD prolazi kroz svako polje.

Opozvati, ponovno izdati ili izbrisati: odaberite pravu radnju

Prije nego što bilo što kliknete, odlučite koja od tri radnje odgovara situaciji. Nisu zamjenjive.

SituacijaNajbolja radnjaZašto
Vjerodajnica je izdana pogrešnoj osobi ili s greškom u tipkanjuIzbrisati (ako nikad nije poslana) ili Opozvati pa ponovno izdatiBrisanje u potpunosti uklanja zapis; opoziv čuva revizijski trag
Polaznik je prekršio pravila ili je vjerodajnica pribavljena na nepropisan načinOpozvati, uz razlogZapis ostaje provjerljiv kao opozvan, što je ono što želite u sporu
Vjerodajnici je jednostavno istekao rokNe činite ništa; postavite istek pri izdavanjuIstek je uobičajen događaj životnog ciklusa, a ne opoziv
Program otkazan, kohorta poništenaSkupni opozivJedan posao, jedan razlog, primijenjen na sve
Podaci su bili pogrešni, ali je vjerodajnica inače valjanaUredite prije slanja, ili opozovite i ponovno izdajte nakon slanjaPrimateljevo iskustvo ostaje čisto

Dva praktična pravila:

  1. Za sve stvarno radije opozovite nego izbrišite. Javna stranica izbrisane vjerodajnice vraća grešku «nije pronađeno». Opozvana se i dalje otvara i jasno kaže da je opozvana, što je puno bolji dokaz ako netko kasnije pita što se dogodilo.
  2. Nikada ne koristite opoziv kao zamjenu za istek. Ako vjerodajnica vrijedi samo dvije godine, postavite datum isteka pri izdavanju. Značka koja tiho istječe nije isto što i povučena značka, a vaša stranica za provjeru treba reći koja je od to dvoje.

Opoziv s nadzorne ploče

Za nekoliko vjerodajnica nadzorna ploča je najbrži put i ne treba kod.

  1. Prijavite se i u bočnoj traci otvorite Awards.
  2. Pronađite vjerodajnicu. Popis prikazuje primatelja, naziv značke, datum izdavanja i istek, a možete pretraživati po primatelju.
  3. Kliknite redak (ili View) da otvorite modalni prozor s detaljima vjerodajnice.
  4. Kliknite Revoke.
  5. U dijalogu za potvrdu po želji unesite razlog i po želji označite Email the recipient that their credential was revoked.
  6. Potvrdite.

Award detail modal

Vjerodajnica ostaje na vašem popisu s crvenom oznakom Revoked pokraj primatelja, tako da vi i vaš tim uvijek možete vidjeti što je povučeno. Opoziv ne vraća vjerodajnicu u kvotu vašeg paketa. Vi ste je izdali, ona se računa.

Napomena o polju za razlog

Razlog je neobavezan, ali ga ispunite. Pohranjuje se uz vjerodajnicu, pojavljuje se kao revocationReason u javnoj Open Badges tvrdnji i uključen je u sadržaj webhooka koji primaju vaši sustavi. Budući da je javan na tvrdnji, pišite ga kao za vanjskog čitatelja. «Izdano greškom» ili «Program otkazan» je u redu. «Jana je varala na 14. pitanju» nije. Osobne pojedinosti čuvajte u vlastitim evidencijama, a javni razlog neka bude neutralan.

Treba li primatelju poslati e-poštu?

Obično da. Polaznik koji sazna da mu je vjerodajnica poništena tek kad poslodavac klikne poveznicu za provjeru ima puno pravo biti nezadovoljan vama. Obavijest je opcionalna upravo zato što neki opozivi (primjerice skupno čišćenje testnih nagrada) ne trebaju nikoga uznemiravati. Naš savjet:

  • Pošaljite e-poštu kad opoziv pogađa stvarnu osobu koja bi vjerodajnicu još mogla isticati.
  • Preskočite e-poštu kad čistite interne testne podatke ili poništavate vjerodajnice koje nikad nisu poslane.

Opoziv mnogo vjerodajnica odjednom

Programi rijetko trebaju opozvati jednu vjerodajnicu zasebno; češće je riječ o cijeloj kohorti. Na popisu Awards:

  1. Označite potvrdne okvire vjerodajnica koje želite povući.
  2. Kliknite Revoke selected na traci za skupne radnje.
  3. Dodajte razlog, odlučite hoćete li obavijestiti primatelje i potvrdite.

Skupni opoziv izvodi se kao trajan pozadinski posao, pa nekoliko stotina vjerodajnica neće isteći u kartici vašeg preglednika. Vjerodajnice koje su već opozvane preskaču se umjesto da ruše cijelu seriju, a posao prekinut na pola puta može se nastaviti. Isti mehanizam pokreće i skupno izdavanje iz proračunske tablice, o čemu pišemo u kako izdati Open Badges iz CSV-a.

Opoziv putem API-ja

Ako vaš sustav za učenje ili HR platforma odlučuje tko više nije certificiran, možete opozivati programski. Krajnja točka je POST /awards/{awardId}/revoke, autentificirana API ključem (X-Api-Key: bws_<32-hex>) ili Cognito Bearer tokenom. ID nagrade ide u putanju; reason i notify idu u JSON tijelo i oba su neobavezna.

Pomoću 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>"}

U 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

I u 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

Nekoliko praktičnih pojedinosti koje vrijedi znati:

  • Idempotentan je. Opoziv vjerodajnice koja je već opozvana vraća isti uspješan odgovor i ne šalje drugu obavijest. Zato je siguran za pozivanje iz posla s ponovnim pokušajima.
  • Razlozi se skraćuju na 500 znakova.
  • notify je prema zadanim postavkama false. Ništa se ne šalje e-poštom osim ako to ne zatražite.
  • Skupni opoziv dostupan je preko skupne krajnje točke s action: "revoke" i popisom ID-jeva nagrada; vraća ID posla koji možete pratiti. Svi parametri nalaze se u referenci API-ja za nagrade.

API vam treba samo kad opoziv pokreće drugi sustav. Za jednokratni slučaj nadzorna ploča je brža i ima korak potvrde koji vas štiti od pogrešno upisanog ID-ja.

Što vide primatelj i provjeravatelj

Nakon opoziva, evo što se mijenja i koliko brzo.

Na javnoj stranici za provjeru. Stranica na https://badges.ninja/awards/<award-id> prikazuje vjerodajnicu kao opozvanu, a naslov stranice za dijeljenje na društvenim mrežama dobiva prefiks «[Revoked]» kako podijeljena poveznica u kartici pregleda ne bi izgledala kao aktivna vjerodajnica.

U Open Badges v2.0 tvrdnji. Smješteni JSON na https://api.badges.ninja/certify-badge/award/<award-id> sada nosi "revoked": true, plus "revocationReason" ako ste ga naveli. Opozvane tvrdnje se u predmemoriji drže samo oko 30 sekundi, dok se aktivne drže pet minuta, pa promjena brzo stiže do provjeravatelja.

U Open Badges 3.0 vjerodajnici. Opoziv također preokreće bit vjerodajnice u W3C Bitstring Status List, čime je otkrivaju novčanici i provjeravatelji provjerljivih vjerodajnica. Taj se popis nakratko sprema u predmemoriju, pa računajte na propagaciju unutar otprilike jedne minute. Ako odvagujete između dviju verzija, pogledajte Open Badges v2 vs v3.

U primateljevoj vlastitoj kopiji. Na datoteci koju je preuzeo ništa se ne mijenja. Slika značke na njegovu prijenosniku izgleda identično. Mijenja se ishod provjere: svatko tko klikne poveznicu ili programski provjeri vjerodajnicu dobiva odgovor da je opozvana. Ako ste ga obavijestili, ima i e-poštu koja objašnjava razlog.

Na LinkedInu. Vjerodajnica dodana na LinkedIn profil je poveznica s metapodacima koja pokazuje na vašu stranicu za provjeru. LinkedIn umjesto vas ne provjerava opoziv, pa unos može ostati na profilu, ali svatko tko slijedi poveznicu doći će na stranicu opozvane vjerodajnice. To je još jedan razlog da pošaljete obavijest i zamolite primatelja da ukloni unos.

Javite vlastitim sustavima: webhookovi

Opoziv je rijetko kraj priče unutar vaše organizacije. Polaznik će možda morati izgubiti pristup zajednici, zapis kod poslodavca treba ažurirati ili oznaku u CRM-u ukloniti. Badges Ninja šalje webhook događaj credential.revoked kad se vjerodajnica opozove, s URL-om nagrade i razlogom:

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

Pretplatite se i vaši daljnji sustavi ostat će usklađeni, a da se nitko ne mora sjetiti ažurirati ih. Pojedinosti postavljanja nalaze se u dokumentaciji webhookova, a širi model događaja obrađujemo u postavljanje webhookova za događaje značaka.

Jednostavna politika opoziva koju možete usvojiti danas

Alati su lakši dio. Teži dio je unaprijed odlučiti kada ćete opozivati i tko to smije. Kratka pisana politika sprječava kasnije rasprave. Predložak koji funkcionira:

  1. Razlozi za opoziv. Navedite ih: izdano greškom, pribavljeno neprimjerenim postupanjem, uvjet više nije ispunjen (primjerice, članstvo je isteklo) ili program povučen.
  2. Tko odlučuje. Navedite ulogu, a ne osobu. Dozvolu za opoziv ograničite na tu ulogu.
  3. Obavijest. Navedite da se primatelji obavještavaju e-poštom, s razlogom, osim ako vjerodajnica nikad nije isporučena.
  4. Žalba. Primateljima omogućite osporavanje odluke i recite koliko ćete dugo odgovarati. Ako žalba uspije, izdajte novu vjerodajnicu umjesto da pokušavate poništiti opoziv, i povijest ostaje čista.
  5. Evidencija. Vodite internu bilješku tko je što opozvao i zašto, odvojeno od neutralnog javnog razloga.

Objavite politiku na istoj stranici na kojoj opisujete vjerodajnicu, kako bi stjecatelji znali pravila prije prijave.

Česte pogreške koje treba izbjegavati

  • Brisanje kad ste htjeli opozvati. Brisanje je trajno i ne može se poništiti, a javna stranica nestaje. Koristite ga za prave greške na vjerodajnicama koje nitko nije vidio.
  • Privatni podaci u razlogu. Razlog je javan na tvrdnji.
  • Očekivanje da će se spremljene kopije promijeniti. Opoziv živi na točki provjere. Recite primateljima da vjerodajnicu uklone s profila i portfelja.
  • Opoziv umjesto isteka. Za vjerodajnice ograničenog trajanja koristite datum isteka.
  • Pretpostavka povrata. Opozvane vjerodajnice i dalje se računaju u kvotu vašeg paketa.
  • Zaboravljanje daljnjih sustava. Povežite webhook kako bi pristupi i evidencije slijedili status vjerodajnice.

Često postavljana pitanja

Mogu li poništiti opoziv? Ne putem sučelja. Ako ste opozvali greškom, izdajte primatelju novu vjerodajnicu. Opozvana ostaje kao dio revizijskog traga.

Mora li primatelj što učiniti? Ne. Ako ste ga odlučili obavijestiti, dobiva e-poštu. Inače se promjena tiho događa na stranici za provjeru.

Radi li opoziv za vjerodajnice koje nikad nisu poslane? Da, iako za neposlanu vjerodajnicu s jednostavnom greškom možda radije želite urediti je prije slanja ili je izbrisati ako ju nitko nije vidio.

Postoji li ograničenje koliko ih mogu opozvati? Skupni opoziv izvodi se kao pozadinski posao koji se može nastaviti, pa se velike serije obrađuju u jednoj operaciji umjesto jedna po jedna.

Hoće li poslodavci vidjeti da je vjerodajnica opozvana? Svatko tko je provjeri putem njezina javnog URL-a ili tvrdnje vidi opozvani status i razlog, ako ste ga naveli.

Zaključak

Opoziv Open Badgea mala je radnja s velikim posljedicama za povjerenje. Radite to s nadzorne ploče kad je riječ o jednoj vjerodajnici, koristite skupni opoziv za kohortu, a API ili webhookove upotrijebite kad odluku donosi drugi sustav. Razloge držite neutralnima, obavijestite one koji trebaju znati i zapamtite da opoziv mijenja ono što vide provjeravatelji, a ne datoteke koje su već u rukama primatelja.

Spremni izdati svoju prvu provjerljivu vjerodajnicu? Počnite besplatno na badges.ninja — vizualni dizajner, javna stranica za provjeru, PDF certifikat, izlaz Open Badge v2.0. Bez kreditne kartice.

Nacho Coll

O autoru

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.

Natrag na Blog

Povezani članci