Revoking Issued Badges

If you issue Open Badges to your community of earners, you may find yourself in the position where you wish to revoke a badge you awarded. In such cases you can structure your badge assertion data to include information about revoked badges. Badge displayers can access the information when they query for an earner's public badges, knowing that revoked badges should not be displayed.

If you're new to badge assertions, see these pages first:

• Open Badges Onboarding: Issuers
• Assertion Information for the Uninitiated
• Assertion Specification

Contents

The process for marking an issued badge as revoked is different for signed and hosted badges:

• Revoking Hosted Badges
• Revoking Signed Badges
• Verification

Revoking Hosted Badges

A hosted badge assertion is represented by a URL - when a displayer carries out a request on the URL, they will typically receive the badge assertion JSON data. If you wish to revoke a hosted badge, instead make the URL respond with an HTTP status of 410 GONE and include the following JSON structure as the body:

{
	"revoked": true
}

How you implement this will depend on your site/ application technology and setup. The following simplified code demonstrates an approach you might take in a node.js app:

app.get('/assertion', function(req, res) {
	var gone = JSON.stringify({
		"revoked": true
	});
	res.status(410).send(gone);
});

Revoking Signed Badges

A signed badge is represented by a JSON Web Signature which includes the badge assertion. To revoke signed badges, you need to use a revocation list. Each badge assertion links to a badge class, which in turn links to the issuer organization info. The issuer organization JSON can include an optional revocationList field as follows:

{
	"name": "Badge Issuer",
	"url": "http://badgeissuer.org",
	"revocationList": "http://badge-issuer.org/revoked-badges.json"
}

The JSON data at the revocation list URL (revoked-badges.json in the example) should have the following structure:

{
	"abc123": "Issued in error",
	"123abc": "Violation of conditions",
	"def456": "Award reconsidered",
	...
}

Each entry represents a revoked badge, listed by its assertion uid and a string describing the reason for revoking it.

Display implementations should check the revocation list in case a badge has been revoked. The Mozilla Backpack uses the openbadges-validator for verification - if you check a badge signature for a badge that has been revoked the validator will return the reason for revocation:

Verification

To understand a bit more about the revocation information you can include as an issuer, see the following overview of what badge displayers are encouraged to do in order to verify that an awarded badge is genuine:

• displayer retrieves earner's public badges
• displayer attempts to retrieve a particular badge assertion
• displayer checks the verify object type field indicating whether the assertion is signed or hosted
• if the assertion is hosted:
• displayer performs a GET request on the url field of the verify object, which should be the URL of the badge assertion
• if the displayer does not receive a 200 OK response, the assertion is treated as invalid and should not be displayed
• otherwise the assertion is checked for structural validity
• if the assertion is signed:
• displayer unpacks the JWS payload and attempts to parse it, checking for structural validity
• displayer retrieves the verify.url field, which should be the location of the public key corresponding to the private key the assertion was signed with
• displayer carries out JWS verification
• displayer retrieves the revocation list from the URL in the issuer organization associated with the badge, then checks that the current assertion uid is not listed.