Sådan tilbagekalder du et Open Badge (og hvad der sker med modtagerens kopi)

Tilbagekaldelse i Open Badges: hvordan det virker, hvad der ændrer sig for modtageren, og den rette måde at håndtere »udstedt ved en fejl« kontra »legitimationen er udløbet« kontra »overtrædelse af regler«.

Nacho Coll Af Opdateret 10 min. læsning
Tilbagekaldelse i Open Badges: hvordan det virker, hvad der ændrer sig for modtageren, og den rette måde at håndtere »udstedt ved en fejl« kontra »legitimationen er udløbet« kontra »overtrædelse af regler«.

Før eller siden må ethvert program, der udsteder digitale legitimationer, tage en af dem tilbage. Et certifikat gik til den forkerte person. En kursist viste sig at have snydt til den afsluttende prøve. En partneraftale sluttede, og de badges, der sagde »Certified Partner«, bør ikke længere være gyldige. Udstedelse er den lette del; tilbagekaldelse er den del, der afgør, om dine legitimationer rent faktisk kan stoles på.

Denne guide forklarer, hvordan tilbagekaldelse fungerer i Open Badges, hvad modtageren ser og ikke ser bagefter, og hvordan du tilbagekalder én legitimation eller flere hundrede på https://badges.ninja, fra dashboardet eller via API’et.

Hvad »tilbagekald« betyder i Open Badges

I Open Badges v2.0-specifikationen er ethvert udstedt badge en assertion: et lille JSON-LD-dokument, der ligger på en offentlig URL og siger: »denne udsteder tildelte dette badge til denne modtager på denne dato.« Tilbagekaldelse er blot en ændring af det hostede dokument. Assertionen får "revoked": true og eventuelt en "revocationReason"-streng, der forklarer hvorfor.

Det design har en vigtig konsekvens, som overrasker mange programejere:

  • Den hostede assertion er sandhedskilden. Alle, der verificerer legitimationen ved at hente assertion-URL’en eller åbne verificeringssiden, ser den tilbagekaldte status med det samme.
  • Kopier kaldes ikke tilbage. Hvis modtageren har downloadet badge-billedet eller JSON-filen eller har fastgjort den i en portefølje, ændrer den fil sig ikke. Den indeholder stadig et link tilbage til din hostede assertion, så en verificerende part, der følger linket, kan se, at den er tilbagekaldt, men en person, der blot kaster et blik på en gemt PNG, kan ikke.

Tilbagekaldelse er derfor en erklæring afgivet ved verificeringsendepunktet, ikke en sletning. Tænk på det som at stemple »UGYLDIG« på masterposten i stedet for at jagte hver eneste fotokopi.

Hvis du vil se nærmere på selve dokumentet, gennemgår vores Open Badge JSON-LD-gennemgang hvert felt.

Tilbagekald, udsted igen eller slet: vælg den rette handling

Før du klikker på noget, skal du afgøre, hvilken af tre handlinger der passer til situationen. De er ikke udskiftelige.

SituationBedste handlingHvorfor
Legitimationen blev udstedt til den forkerte person eller med en tastefejlSlet (hvis aldrig sendt) eller Tilbagekald, og udsted derefter igenSletning fjerner posten helt; tilbagekaldelse bevarer et revisionsspor
Kursisten overtrådte en regel, eller legitimationen blev opnået på ukorrekt visTilbagekald, med en begrundelsePosten forbliver verificerbar som tilbagekaldt, hvilket er det, du ønsker i en tvist
Legitimationen nåede blot sin slutdatoGør ingenting; angiv en udløbsdato, når du udstederUdløb er en normal del af livscyklussen, ikke en tilbagekaldelse
Programmet aflyst, hold annulleretMasse-tilbagekaldelseÉt job, én begrundelse, anvendt på alle
Oplysningerne var forkerte, men legitimationen er ellers gyldigRedigér før afsendelse, eller tilbagekald og udsted igen efter afsendelseHolder modtagerens oplevelse ren

To tommelfingerregler:

  1. Foretræk tilbagekaldelse frem for sletning for alt, der er rigtigt. En slettet legitimations offentlige side returnerer en fejl om, at den ikke findes. En tilbagekaldt legitimation kan stadig åbnes og siger tydeligt, at den er tilbagekaldt, hvilket er langt bedre dokumentation, hvis nogen senere spørger, hvad der skete.
  2. Brug aldrig tilbagekaldelse som erstatning for udløb. Hvis en legitimation kun er gyldig i to år, skal du angive en udløbsdato, når du udsteder den. Et badge, der stille udløber, er noget andet end et, der blev trukket tilbage, og din verificeringsside bør sige, hvilket af dem det er.

Tilbagekaldelse fra dashboardet

Til en håndfuld legitimationer er dashboardet den hurtigste vej og kræver ingen kode.

  1. Log ind og åbn Awards i sidemenuen.
  2. Find legitimationen. Listen viser modtager, badge-navn, udstedelsesdato og udløb, og du kan søge efter modtager.
  3. Klik på rækken (eller View) for at åbne detaljevinduet for legitimationen.
  4. Klik på Revoke.
  5. I bekræftelsesdialogen kan du eventuelt angive en begrundelse og eventuelt sætte kryds ved Email the recipient that their credential was revoked.
  6. Bekræft.

Award detail modal

Legitimationen forbliver på din liste med en rød Revoked-markering ved siden af modtageren, så du og dit team altid kan se, hvad der er trukket tilbage. Tilbagekaldelse refunderer ikke legitimationen mod din plans kvote. Du udstedte den, så den talte med.

Et ord om begrundelsesfeltet

Begrundelsen er valgfri, men udfyld den. Den gemmes sammen med legitimationen, vises som revocationReason i den offentlige Open Badges-assertion og indgår i webhook-payloaden, som dine systemer modtager. Fordi den er offentlig på assertionen, skal du skrive den, som du ville skrive til en udenforstående læser. »Udstedt ved en fejl« eller »Program aflyst« er fint. »Jane snød i spørgsmål 14« er ikke. Hold personlige oplysninger i dine egne optegnelser, og hold den offentlige begrundelse neutral.

Skal du sende modtageren en e-mail?

Oftest ja. En kursist, der først opdager, at legitimationen er død, når en arbejdsgiver klikker på verificeringslinket, har al mulig ret til at være utilfreds med dig. Notifikationen er fravalgt som standard, netop fordi nogle tilbagekaldelser (for eksempel en masseoprydning af testawards) ikke behøver at forstyrre nogen. Vores anbefaling:

  • Send e-mail, når tilbagekaldelsen berører en rigtig person, som måske stadig viser legitimationen frem.
  • Spring e-mailen over, når du rydder op i interne testdata eller gør legitimationer ugyldige, der aldrig blev sendt.

Tilbagekald mange legitimationer på én gang

Programmer har sjældent brug for at tilbagekalde en enkelt legitimation isoleret; oftere er det et helt hold. I listen Awards:

  1. Sæt kryds ved de legitimationer, du vil trække tilbage.
  2. Klik på Revoke selected i handlingslinjen til massehandlinger.
  3. Tilføj en begrundelse, vælg om modtagerne skal underrettes, og bekræft.

Masse-tilbagekaldelse kører som et robust baggrundsjob, så et par hundrede legitimationer ikke får din browserfane til at time ud. Legitimationer, der allerede er tilbagekaldt, springes over i stedet for at lade hele batchen fejle, og et job, der blev afbrudt undervejs, kan genoptages. Det samme maskineri driver masseudstedelse fra et regneark, som vi gennemgår i sådan udsteder du Open Badges fra en CSV.

Tilbagekaldelse via API’et

Hvis dit læringssystem eller din HR-platform afgør, hvem der ikke længere er certificeret, kan du tilbagekalde programmatisk. Endepunktet er POST /awards/{awardId}/revoke, autentificeret med en API-nøgle (X-Api-Key: bws_<32-hex>) eller et Cognito Bearer-token. Award-ID’et står i stien; reason og notify står i JSON-body’en, og begge er valgfrie.

Med 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>"}

I JavaScript:

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

Og i Python:

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

Nogle praktiske detaljer, det er værd at kende:

  • Den er idempotent. Tilbagekaldelse af en legitimation, der allerede er tilbagekaldt, returnerer det samme succesrespons og sender ikke endnu en notifikation. Det gør det sikkert at kalde fra et job, der prøver igen.
  • Begrundelser afkortes til 500 tegn.
  • notify er som standard false. Der sendes ingen e-mail, medmindre du beder om det.
  • Masse-tilbagekaldelse er tilgængelig via masse-endepunktet med action: "revoke" og en liste af award-ID’er; det returnerer et job-ID, du kan følge. De fulde parametre findes i awards API-referencen.

Du har kun brug for API’et, når tilbagekaldelsen styres af et andet system. Til en enkeltstående sag er dashboardet hurtigere og har et bekræftelsestrin, der beskytter dig mod et forkert tastet ID.

Hvad modtageren og den verificerende part ser

Når du har tilbagekaldt, ændrer følgende sig, og så hurtigt sker det.

På den offentlige verificeringsside. Siden på https://badges.ninja/awards/<award-id> viser legitimationen som tilbagekaldt, og sidetitlen til deling på sociale medier får præfikset »[Revoked]«, så et delt link ikke ligner en gyldig legitimation i et forhåndsvisningskort.

I Open Badges v2.0-assertionen. Den hostede JSON på https://api.badges.ninja/certify-badge/award/<award-id> indeholder nu "revoked": true samt "revocationReason", hvis du angav en. Tilbagekaldte assertions caches kun i omkring 30 sekunder, mens gyldige caches i fem minutter, så ændringen når de verificerende parter hurtigt.

I Open Badges 3.0-legitimationen. Tilbagekaldelse vender også legitimationens bit i en W3C Bitstring Status List, som er den måde, wallets og verificerende parter til verifiable credentials registrerer den på. Listen caches kortvarigt, så regn med udbredelse inden for omkring et minut. Hvis du overvejer de to versioner, kan du læse Open Badges v2 vs v3.

I modtagerens egen kopi. Der ændrer sig intet i den fil, de downloadede. Badge-billedet på deres bærbare ser identisk ud. Det, der ændrer sig, er resultatet af verificeringen: alle, der klikker igennem eller tjekker legitimationen programmatisk, får det tilbagekaldte svar. Hvis du underrettede dem, har de også en e-mail, der forklarer hvorfor.

På LinkedIn. En legitimation, der er føjet til en LinkedIn-profil, er et link plus metadata, der peger tilbage på din verificeringsside. LinkedIn tjekker ikke for tilbagekaldelse på dine vegne, så posten kan blive stående på profilen, men alle, der følger linket, lander på den tilbagekaldte side. Det er endnu en grund til at sende notifikationen og bede modtageren om at fjerne posten.

Fortæl det til dine egne systemer: webhooks

Tilbagekaldelse er sjældent slutningen på historien i din organisation. Kursisten skal måske miste adgang til et community, en arbejdsgiverpost skal måske opdateres, eller et CRM-tag skal måske fjernes. Badges Ninja udsender en credential.revoked-webhook-hændelse, når en legitimation tilbagekaldes, med award-URL’en og begrundelsen:

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

Abonnér på den, så holder dine downstream-systemer trit uden at nogen skal huske at opdatere dem. Opsætningsdetaljer findes i webhook-dokumentationen, og den bredere hændelsesmodel gennemgår vi i webhook-opsætning til badge-hændelser.

En simpel tilbagekaldelsespolitik, du kan indføre i dag

Værktøjer er den nemme halvdel. Den sværere halvdel er på forhånd at afgøre, hvornår du tilbagekalder, og hvem der må. En kort skriftlig politik forebygger skænderier senere. En brugbar skabelon:

  1. Grunde til tilbagekaldelse. List dem: udstedt ved en fejl, opnået gennem uregelmæssigheder, krav ikke længere opfyldt (for eksempel et udløbet medlemskab) eller program trukket tilbage.
  2. Hvem beslutter. Angiv en rolle, ikke en person. Begræns tilbagekaldelsesrettigheden til den rolle.
  3. Underretning. Angiv, at modtagerne får besked på e-mail, med begrundelsen, medmindre legitimationen aldrig blev leveret.
  4. Klage. Giv modtagerne en måde at anfægte afgørelsen på, og angiv, hvor lang tid du tager om at svare. Hvis en klage får medhold, så udsted en ny legitimation i stedet for at forsøge at fortryde tilbagekaldelsen, så forbliver historikken ren.
  5. Registrering. Før en intern notits om, hvem der tilbagekaldte hvad og hvorfor, adskilt fra den neutrale offentlige begrundelse.

Udgiv politikken på den samme side, hvor du beskriver legitimationen, så deltagerne kender reglerne, før de tilmelder sig.

Almindelige fejl, du skal undgå

  • At slette, når du mente at tilbagekalde. Sletning er permanent og kan ikke fortrydes, og den får den offentlige side til at forsvinde. Brug den til ægte fejl på legitimationer, som ingen har set.
  • At lægge private oplysninger i begrundelsen. Den er offentlig på assertionen.
  • At forvente, at gemte kopier ændrer sig. Tilbagekaldelse lever ved verificeringsendepunktet. Bed modtagerne om at fjerne legitimationen fra profiler og porteføljer.
  • At tilbagekalde i stedet for at lade udløbe. Brug en udløbsdato til tidsbegrænsede legitimationer.
  • At gå ud fra en refundering. Tilbagekaldte legitimationer tæller stadig med i din plans kvote.
  • At glemme downstream-systemer. Sæt webhooken op, så adgang og optegnelser følger legitimationens status.

Ofte stillede spørgsmål

Kan jeg fortryde en tilbagekaldelse? Ikke via brugerfladen. Hvis du tilbagekaldte ved en fejl, skal du udstede en ny legitimation til modtageren. Den tilbagekaldte forbliver som en del af revisionssporet.

Skal modtageren gøre noget? Nej. Hvis du valgte at underrette dem, får de en e-mail. Ellers sker ændringen i stilhed på verificeringssiden.

Virker tilbagekaldelse for legitimationer, der aldrig blev sendt? Ja, men for en usendt legitimation med en simpel fejl foretrækker du måske at redigere den før afsendelse eller slette den, hvis ingen har set den.

Er der en grænse for, hvor mange jeg kan tilbagekalde? Masse-tilbagekaldelse kører som et genoptageligt baggrundsjob, så store batches håndteres i én operation i stedet for én ad gangen.

Kan arbejdsgivere se, at en legitimation blev tilbagekaldt? Alle, der verificerer den via dens offentlige URL eller assertion, ser den tilbagekaldte status og begrundelsen, hvis du angav en.

Konklusion

At tilbagekalde et Open Badge er en lille handling med reelle konsekvenser for tilliden. Gør det fra dashboardet, når det gælder en enkelt legitimation, brug masse-tilbagekaldelse til et helt hold, og tag API’et eller webhooks i brug, når et andet system ejer beslutningen. Hold begrundelserne neutrale, underret dem, der har brug for at vide det, og husk, at tilbagekaldelse ændrer, hvad de verificerende parter ser, ikke de filer, der allerede er i modtagernes hænder.

Klar til at udstede din første verificerbare legitimation? Kom i gang gratis på badges.ninja — visuel designer, offentlig verificeringsside, PDF-certifikat, Open Badge v2.0-output. Intet kreditkort påkrævet.

Nacho Coll

Om forfatteren

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.

Tilbage til Bloggen

Relaterede artikler