Open Badges Onboarding: Issuers
In the world of Open Badges, an issuer is an individual or organization who creates and awards badges to earners. If you're looking to get started as a badge issuer, this document will introduce you to the key concepts and technologies involved.
- TL;DR
- Who's Involved
- What does an Issuer do?
- Open Badge Infrastructure
- Concepts
- Open Badges
- Assertions
- Display
- Badge Issuing Flow
- Creating Badges
- Creating Assertions
- Requirements
- Verification
- BadgeKit
- Resources and Next Steps
The simplest implementation of issuing Open Badges involves the following tasks:
- host an issuer organization JSON file
- this describes the issuer
- host a badge class JSON file for each available badge
- describes what the badge represents
- links to the issuer file
- host an image for each available badge
- is linked from the badge class file
- host a badge assertion JSON file for each awarded badge
- this describes the earner, badge and detail of the award
- links to the badge class file
This is the essence of what an issuer does, but a number of additional steps/ variations may be involved, as you can see in the below sections.
Open Badges projects and applications can involve a range of individuals and organizations. The key participants are:
- earners
- issuers
- displayers
- consumers
Issuers create, publish and award the badges to earners. Displayers present an earner's badges in a digital context. Although not directly involved with the badging lifecycle, consumers are other people who might have an interest in an earner's badges (e.g. an employer or college admin).
An issuer is a person or organization who awards badges to earners. The issuer is responsible for:
- creating and defining the badges
- deciding who to issue them to
- hosting the data for the badges they award.
As an issuer, you can award badges to your community of earners in a variety of ways:
- directly, to the earner email address
- via an assessment process
- defining badge criteria
- accepting earner applications submitted with supporting evidence
- reviewing applications against criteria
- using claim codes
The issuer role can therefore involve a series of tasks - each of which is supported by OBI tools and resources.
The Open Badge Infrastructure (OBI) is a range of specifications, technologies and tools which support the badging ecosystem. It includes APIs and software to aid the process of adopting Open Badges within your own environment. There are many Open Badges projects on GitHub - of particular relevance to issuers is the Mozilla Backpack repo; it includes a selection of issuing resources, such the Issuer API, which allows earners to push badges they earned from you to their Mozilla Backpack.
Before we move on, let's make sure we have a clear understanding of a few key concepts you will encounter throughout the Open Badges projects.
An Open Badge is a digital representation of a skill or achievement. Each badge awarded to an earner comprises a digital image file and some metadata. The metadata describes what the badge represents, the identity of the earner and the issuing organization. The metadata conforms to the structure defined within the Open Badges specifications, which you can see on GitHub: https://github.com/mozilla/openbadges-specification
The specifications help to define the standards that guide Open Badges' creation and use. A range of technology projects also support badging - developed by Mozilla and a network of partner organizations including those in the Badge Alliance.
As an issuer, one of the key aspects of Open Badges you will be involved with is the assertion. An assertion represents a specific badge awarded to a specific earner. Think about a badge you define as an issuer - it involves a series of data items describing what the badge represents. The badge may potentially be awarded to multiple individual earners - we need a way to represent these badge instances in contrast to the generic representation of the badge: this is where the assertion comes in.
An assertion includes all of the information we need to implement the value of an Open Badge:
- the earner identity
- what the badge represents
- who issued the badge
Each assertion is represented as an image and three JSON metadata files: the badge assertion; the badge class; the issuer organization.
The badge assertion describes the specific instance of the badge awarded to the earner email address - and includes a link to the badge class. The badge class describes the generic badge which may be awarded to multiple earners - and includes a link to the issuer organization. The issuer organization includes data about whoever issued the badge.
The badge metadata can be embedded into the badge image file - this is referred to as a baked badge.
Assertions can be hosted (stored as hosted files) or signed (JSON Web Signatures).
For more on assertions see:
Note: Some proposed changes to the assertion specification are currently under discussion. See these threads in particular:
Once an earner has achieved one or more badges, they may naturally want a way to display or communicate these achievements. This is where badge displayers come in. Displayers are responsible for querying and verifying the information about an earner's badges (from the issuer) and presenting them within a digital context.
Displayers can use the Displayer API to query the Mozilla hosted Backpack for an earner's badges, by passing the earner email address, which is converted into a unique internal ID. Earners decide which of their backpack badges are public, determining whether or not a displayer can show them.
Issuers need to include the assertion information for a badge in a way that allows displayers to carry this task out, for example via verification data. The OBI tools are designed to give earners total control over where their badges are displayed.
A new federated Backpack is also under development: https://github.com/mozilla/badgekit-backpack/
For more badging concepts, see the Glossary.
As an issuer, you can design a badge issuing flow to suit your own organization and community of badge earners. The Open Badges tools and specifications support the creation, validation, publication, assessment, issuing and display of badges. The following is a typical scenario:
- issuer designs a badge and defines the metadata for it (including criteria for earning the badge)
- issuer makes the badge available for earner applications via a website
- earners apply for the badge, attaching evidence in support of their applications
- issuers review earner applications against criteria, making awarding decisions
- a badge is issued to an earner, at which point the issuer creates a badge assertion for the earner (optionally baking the assertion into the badge image)
- earner is offered the opportunity to push their new badge to a Backpack (where they can manage collections of badges they have made publicly discoverable)
When a badge is awarded to an earner, these typical steps may be carried out:
- Issuer creates and hosts a badge assertion
- 3 hosted JSON files OR a JSON Web Signature describing the badge award
- Metadata should not change after the badge is awarded
- Includes the earner identity info
-
Assertion includes badge class, either as a URL or an inline object
-
Badge class describes what the badge represents and includes issuer organization
- Issuer organization describes who issued the badge (can be a URL or inline object)
-
Badge class describes what the badge represents and includes issuer organization
- Issuer offers to push the earner's badge to their Mozilla Backpack
- here the earner can decide whether to make the badge part of a public collection
- Displayers query the earner's Mozilla Backpack (or another resource) for badge assertion info
- Displayers can only query for badges the earner has chosen to make public
- Identity can be verified, as can signatures where appropriate.
Before serving or displaying an assertion, issuers and displayers can use the Validator to check that the structure is correctly formed - the tool works for both signed and hosted assertions.
See also the Issuer Checklist.
The process of creating a badge will depend on the nature of the badge and on your own organization. How you make badges available to earners and decide whether to award them should also be tailored to your own community.
You may benefit from one of the available issuing platforms or BadgeKit.
Issuing a badge essentially means serving an image plus the three parts of the assertion from your server. Depending on the nature of your badge, this may involve relatively complex and lengthy JSON structures. You may also wish to bake your badges - embedding the metadata into the image file, which potentially allows the badge to be used outside of the OBI. If you plan on using the Issuer API to give earners the ability to push their badges to the Mozilla Backpack, your assertions do not need to be baked as it bakes them for you.
The Badge Lab tutorial walks you through the process of creating a badge assertion, including the image file and the three sets of JSON data: https://badgelab.herokuapp.com/
This tutorial shows you how to create a signed badge assertion: https://github.com/mozilla/openbadges/wiki/Creating-Signed-Assertions
If you do plan on baking your badges, see the current documentation: https://github.com/mozilla/openbadges-specification/blob/master/Badge-Baking/latest.md
To act as an issuer, you need:
- a Web server you can serve your assertions from at stable URLs
- the ability to make a POST request and read a JSON response
- earner email addresses (each assertion describes a badge issued to an email address)
Additionally, for signed assertions, you need to:
- generate a public/ private key pair and host the public key
- sign the badge assertions
The Mozilla Backpack APIs for issuers use JavaScript.
Issuers should consider the following guidelines on badge images:
- Images should be PNGs (or SVGs).
- Images should be square and not exceed 256kb. They should have dimensions not smaller that 90 x 90px. You are advised to view your badge images at 50px to ensure that the content remains legible when scaled.
- Images are linked to in assertions via URL to the image on the issuer server, stored within the metadata.
- For the Mozilla Backpack, image will be cached in at least two sizes.
- When a Mozilla Backpack badge is displayed, it will be loaded from the Mozilla cache to avoid extra burden on the issuer servers. This also helps if the issuer is not available or the link is broken.
- When using BadgeKit, issuers can design badges inside the Web app using a graphical tool, or can upload images prepared elsewhere.
Although as an issuer you may not be displaying earned badges, you will still need to include information for displayers in your badge assertions. This is so that displayers can verify the information regarding the badges you have awarded - displayers are expected to only display badges they have verified as belonging to the earner, using the data included in the assertion.
One of the key features making Open Badges valuable, as a method of representing achievements, is the ability to verify that a user did indeed earn a particular badge. Badges can also have expiry dates built into them, after which an awarded badge can be considered invalid.
The identity section of a badge assertion includes the earner email address, a hash of the earner email address or a salted hash of the earner email address. A displayer can compare this value to the (hashed) email of the earner claiming the badge to establish authenticity. This facilitates verification, while preventing the need to store the earner email explicitly within the badge assertion.
For signed assertions, the displayer can also use the public key to carry out a verification check. Issuers can also revoke badges, in which case a revocation list is created, including the UIDs for revoked badges - displayers can check this list in case a badge has been revoked - see Revoking Issued Badges.
If you plan on issuing multiple badges within your organization, you may benefit from BadgeKit. BadgeKit is an API and Web app issuers can use to automate several parts of the badge issuing process. The API manages the data for published and earned badges, as well as applications and reviews. The Web app aids the badge creation and assessment process.
If you host both the API and an instance of the Web app, you can focus on plugging your own earner-facing site into these resources. The only parts of the badging process not handled by BadgeKit relate to earner interaction, so that issuers can design this to suit their own communities.
The BadgeKit tools are built in node.js - see the installation guide
You can see an overview of what BadgeKit does in the tutorial
If you want to get started issuing badges straight away, head for the Badge Lab tutorial, BadgeKit or give yourself a badge.
For additional support:
- Post general questions in our Community Google Group and post technical questions in our Dev Google Group.
- Reach members of the Open Badges team directly on IRC (irc.mozilla.org) on the #badges channel.
- Email questions directly to badges@mozillafoundation.org and a member of the team will follow-up.
- Follow or tweet the Open Badges team @OpenBadges.
- Get involved or submit issues via the GitHub repos - feedback is always appreciated!