Open Badge を失効させる方法(受領者の手元のコピーはどうなる?)

Open Badges における失効の仕組み、受領者側で何が変わるのか、そして「誤発行」「資格の期限切れ」「規約違反」それぞれの正しい扱い方を解説します。

Nacho Coll 著者: 更新日 22 分で読了
Open Badges における失効の仕組み、受領者側で何が変わるのか、そして「誤発行」「資格の期限切れ」「規約違反」それぞれの正しい扱い方を解説します。

デジタル資格情報を発行するプログラムなら、遅かれ早かれ一度は取り消しが必要になります。証明書を間違った人に送ってしまった。最終試験で不正をした学習者が見つかった。パートナー契約が終了し、「Certified Partner」と書かれたバッジがもう有効ではなくなった。発行はうまくいくときの話で、失効こそが資格情報を本当に信頼できるかどうかを左右します。

このガイドでは、Open Badges における失効の仕組み、失効後に受領者に見えるもの・見えないもの、そして https://badges.ninja のダッシュボードまたは API で 1 件から数百件までまとめて失効させる方法を説明します。

Open Badges における「失効」とは

Open Badges v2.0 仕様では、発行されたバッジはすべてアサーションです。これは公開 URL でホストされる小さな JSON-LD ドキュメントで、「この発行者が、この日付にこの受領者へこのバッジを授与した」ことを示します。失効とは、このホストされたドキュメントを変更するだけのことです。アサーションに "revoked": true が付き、理由を説明する "revocationReason" 文字列を任意で付けられます。

この設計には、多くのプログラム運営者が驚く重要な帰結があります。

  • ホストされたアサーションが唯一の正です。 アサーション URL を取得したり検証ページを開いたりして資格情報を検証する人には、失効状態がすぐに表示されます。
  • コピーは回収されません。 受領者がバッジ画像や JSON をダウンロードしたり、ポートフォリオに固定したりしていても、そのファイルは変わりません。ファイルにはホストされたアサーションへのリンクが含まれているため、リンクをたどる検証者には失効が分かりますが、保存された PNG をちらっと見るだけの人には分かりません。

つまり失効は、削除ではなく、検証エンドポイントで行う宣言です。すべてのコピーを追いかけるのではなく、原本に「VOID」のスタンプを押すようなものだと考えてください。

ドキュメント自体を詳しく見たい方は、各フィールドを順に解説した Open Badge JSON-LD ウォークスルーをご覧ください。

失効・再発行・削除:適切な操作を選ぶ

何かをクリックする前に、3 つの操作のうち状況に合うものを決めましょう。これらは互換ではありません。

状況最適な操作理由
資格情報を別の人に、または誤字のまま発行した削除(未送信の場合)または失効してから再発行削除は記録を完全に消し、失効は監査証跡を残す
学習者が規約に違反した、または不正に資格を取得した理由を付けて失効失効済みとして検証可能な記録が残り、紛争時に望ましい
資格情報が単に終了日を迎えた何もしない。発行時に有効期限を設定する有効期限は通常のライフサイクルであり、失効ではない
プログラムの中止、コホートの無効化一括失効1 つのジョブ、1 つの理由を全員に適用
内容は誤っているが、資格情報自体は有効送信前に編集、送信後なら失効して再発行受領者の体験をきれいに保てる

2 つの目安です。

  1. 実際に発行したものは、削除より失効を選びましょう。 削除された資格情報の公開ページは not-found エラーを返します。失効したものはページが引き続き表示され、失効していることが明記されるため、後で何があったか問われたときの証拠としてはるかに優れています。
  2. 失効を有効期限の代わりに使わないでください。 資格情報の有効期間が 2 年なら、発行時に有効期限を設定しましょう。静かに失効するバッジと、取り下げられたバッジは別物であり、検証ページはどちらなのかを示すべきです。

ダッシュボードから失効させる

数件であれば、ダッシュボードが最も速く、コードも不要です。

  1. サインインし、サイドバーの Awards を開きます。
  2. 資格情報を探します。一覧には受領者、バッジ名、発行日、有効期限が表示され、受領者で検索できます。
  3. 行(または View)をクリックして、資格情報の詳細モーダルを開きます。
  4. Revoke をクリックします。
  5. 確認ダイアログで、必要に応じて理由を入力し、Email the recipient that their credential was revoked にチェックを入れることもできます。
  6. 確定します。

Award detail modal

資格情報は一覧に残り、受領者の横に赤い Revoked チップが表示されるため、チームは何が取り下げられたかをいつでも確認できます。失効してもプランのクォータは返却されません。発行した時点でカウントされています。

理由フィールドについて

理由は任意ですが、入力することをおすすめします。理由は資格情報とともに保存され、公開される Open Badges アサーションの revocationReason として表示され、システムが受け取る Webhook ペイロードにも含まれます。アサーションでは公開されるため、外部の読者に向けて書いてください。「誤発行」や「プログラム中止」は問題ありません。「Jane は問 14 で不正をした」は NG です。個人に関する詳細は自社の記録に残し、公開する理由は中立的にしましょう。

受領者にメールを送るべき?

たいていは送るべきです。資格情報が無効になったことを、雇用主が検証リンクをクリックして初めて知った学習者が、あなたに不満を持つのは当然です。通知がオプトインなのは、テスト用アワードの一括整理のように、誰にも知らせる必要のない失効もあるからです。目安は次のとおりです。

  • メールを送る場合: 失効が、その資格情報をまだ掲示しているかもしれない実在の人物に影響するとき。
  • メールを送らない場合: 社内のテストデータを整理するとき、または一度も送信していない資格情報を無効にするとき。

複数の資格情報をまとめて失効させる

1 件だけを単独で失効させることはあまりなく、コホート全体であることのほうが多いでしょう。Awards 一覧で次のように操作します。

  1. 取り下げたい資格情報のチェックボックスにチェックを入れます。
  2. 一括操作バーの Revoke selected をクリックします。
  3. 理由を追加し、受領者に通知するかどうかを選んで確定します。

一括失効は耐久性のあるバックグラウンドジョブとして実行されるため、数百件でもブラウザのタブがタイムアウトすることはありません。すでに失効済みの資格情報は、バッチを失敗させずにスキップされ、途中で中断したジョブは再開できます。同じ仕組みがスプレッドシートからの一括発行も支えています。詳しくは CSV から Open Badges を発行する方法をご覧ください。

API で失効させる

学習システムや HR プラットフォームが誰の認定を解除するかを決める場合は、プログラムから失効させられます。エンドポイントは POST /awards/{awardId}/revoke で、API キー(X-Api-Key: bws_<32-hex>)または Cognito Bearer トークンで認証します。award ID はパスに指定し、reason と notify は JSON ボディに指定します(どちらも任意)。

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

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

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

知っておくと役立つ実践的なポイントです。

  • 冪等です。 すでに失効済みの資格情報を失効させても同じ成功レスポンスが返り、2 通目の通知は送信されません。リトライするジョブから呼び出しても安全です。
  • 理由は 500 文字に切り詰められます。
  • notify のデフォルトは false です。 指定しない限りメールは送信されません。
  • 一括失効は、action: "revoke" と award ID のリストを指定して bulk エンドポイントから実行でき、追跡可能なジョブ ID が返されます。パラメータの詳細は awards API リファレンスをご覧ください。

API が必要になるのは、失効が別のシステムによって判断される場合だけです。単発ならダッシュボードのほうが速く、ID の入力ミスを防ぐ確認ステップもあります。

受領者と検証者に見えるもの

失効後に何がどれくらい速く変わるのかを説明します。

公開検証ページ。 https://badges.ninja/awards/<award-id> のページに資格情報が失効済みと表示され、ソーシャル共有用のページタイトルには「[Revoked]」が付くため、共有リンクがプレビューカードで有効な資格情報のように見えることはありません。

Open Badges v2.0 アサーション。 https://api.badges.ninja/certify-badge/award/<award-id> でホストされる JSON に "revoked": true が付き、理由を指定していれば "revocationReason" も付きます。失効済みアサーションのキャッシュは約 30 秒のみで、有効なものは 5 分間キャッシュされるため、変更は検証者にすばやく届きます。

Open Badges 3.0 資格情報。 失効すると、W3C Bitstring Status List 内のその資格情報のビットも切り替わります。検証可能な資格情報(Verifiable Credential)のウォレットや検証者はこれで失効を検知します。このリストは短時間キャッシュされるため、反映までは約 1 分を見込んでください。2 つのバージョンを比較検討中なら、Open Badges v2 と v3 の違いをご覧ください。

受領者自身のコピー。 ダウンロードしたファイルには何も起きません。ノートパソコンにあるバッジ画像は以前と同じに見えます。変わるのは検証の結果です。リンクをクリックした人や、プログラムで資格情報を確認した人には、失効したという答えが返ります。通知していれば、理由を説明するメールも受領者の手元に届きます。

LinkedIn。 LinkedIn プロフィールに追加された資格情報は、検証ページを指すリンクとメタデータです。LinkedIn が代わりに失効をポーリングすることはないため、プロフィール上にエントリが残り続けることがありますが、リンクをたどった人は失効ページにたどり着きます。これも、通知を送って受領者にエントリの削除を依頼したほうがよい理由のひとつです。

自社システムへの連携:Webhook

失効は、組織内ではそこで終わらないことがほとんどです。学習者がコミュニティへのアクセスを失う、雇用主の記録を更新する、CRM のタグを外すといった対応が必要になるかもしれません。Badges Ninja は、資格情報が失効すると、award の URL と理由を含む credential.revoked Webhook イベントを発行します。

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

これを購読しておけば、誰かが更新を忘れずに済み、下流のシステムも同期されます。セットアップの詳細は Webhook のドキュメントに、イベントモデル全体については バッジイベントの Webhook 設定にまとめています。

今日から使えるシンプルな失効ポリシー

ツールは簡単なほうの半分です。難しいのは、いつ失効させるか、誰が失効させてよいかを事前に決めておくことです。短い文書化されたポリシーがあれば、後の争いを防げます。使いやすいテンプレートは次のとおりです。

  1. 失効の根拠。 列挙します:誤発行、不正行為による取得、要件を満たさなくなった(例:会員資格の失効)、プログラムの終了。
  2. 決定者。 個人ではなく役割を指定し、失効権限をその役割に限定します。
  3. 通知。 資格情報が未配信だった場合を除き、受領者には理由を添えてメールで通知することを明記します。
  4. 異議申し立て。 受領者が決定に異議を唱える方法と、対応にかかる期間を示します。異議が認められた場合は、失効を取り消そうとせず新しい資格情報を再発行すれば、履歴をきれいに保てます。
  5. 記録。 誰が何をなぜ失効させたかを、中立的な公開理由とは別に社内メモとして残します。

ポリシーは資格情報を説明するページと同じ場所に公開し、取得者が申し込む前にルールを知れるようにしましょう。

よくある間違い

  • 失効のつもりで削除してしまう。 削除は恒久的で元に戻せず、公開ページも消えます。誰も見ていない資格情報の本当のミスにだけ使いましょう。
  • 理由に非公開の情報を書く。 理由はアサーションで公開されます。
  • 保存されたコピーが変わると期待する。 失効は検証エンドポイントにあります。受領者にはプロフィールやポートフォリオから資格情報を削除するよう伝えましょう。
  • 有効期限の代わりに失効を使う。 期間限定の資格情報には有効期限を使いましょう。
  • 返金されると思い込む。 失効した資格情報もプランのクォータにカウントされたままです。
  • 下流のシステムを忘れる。 Webhook を設定して、アクセス権や記録が資格情報のステータスに追従するようにしましょう。

よくある質問

失効を取り消せますか? インターフェースからはできません。誤って失効させた場合は、受領者に新しい資格情報を発行してください。失効したものは監査証跡の一部として残ります。

受領者は何かする必要がありますか? いいえ。通知を選んだ場合はメールが届き、そうでなければ検証ページで静かに変更が反映されます。

未送信の資格情報でも失効できますか? はい。ただし、未送信で単純なミスの場合は、送信前に編集するか、誰も見ていなければ削除するほうがよいかもしれません。

失効できる件数に上限はありますか? 一括失効は再開可能なバックグラウンドジョブとして実行されるため、大量のバッチも 1 件ずつではなく 1 回の操作で処理されます。

雇用主には資格情報が失効したことが分かりますか? 公開 URL やアサーションで検証した人には、失効ステータスと、指定した場合はその理由が表示されます。

まとめ

Open Badge の失効は小さな操作ですが、信頼には大きな影響があります。1 件ならダッシュボードから、コホートなら一括失効を使い、別のシステムが判断を握っている場合は API や Webhook を活用しましょう。理由は中立的に書き、知るべき人には通知し、失効が変えるのは検証者に見えるものであって、受領者の手元にあるファイルではないことを忘れないでください。

最初の検証可能な資格情報を発行する準備はできましたか? badges.ninja で無料で始める — ビジュアルデザイナー、公開検証ページ、PDF 証明書、Open Badge v2.0 出力。クレジットカードは不要です。

Nacho Coll

著者について

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.

ブログに戻る

関連記事