View source for Badges/Onboarding-Displayer

== Mozilla Open Badge Infrastructure (OBI) ==  

NOTE: For a general introduction to badge displaying with the Mozilla OBI, read on. For more technical documentation, please see our [https://github.com/mozilla/openbadges/wiki/Displayer-API github pages].

=== Background === 
 
==== Why Are We Doing This? ====  
Learning happens everywhere. Yet it's often difficult to be recognized for skills and achievements that are gained outside of school. Mozilla's Open Badges project is working to solve that problem by making it easy for anyone anywhere to issue, earn, and display badges. The results: broad recognition of 21st century skills and experiences, unlocking of career and educational opportunities, and learners everywhere being able to level up in their lives and work.

==== Goals ====
* Develop badges as a system for alternative accreditation, credentialing, and recognition;
* Help badges expand beyond siloed environments to be broadly shareable;
* Truly support earners learning everywhere;
* Optimize the value of these representations by allowing badges to be remixable and shareable with different audiences;
* Develop a supporting infrastructure to standardize the process and support each earner;
* Create an infrastructure that is open and as decentralized as possible to give earners control and support of the entire ecosystem;
* Provide software and development tools to help organizations implement badging systems.

==== Description ==== 

The Open Badges framework is designed to make badging flexible enough to represent the full range of learning and experience in online and offline life. This requires support for multiple, potentially significantly varied, badge issuers. Empowering earners to use their badges as legitimate credentials also requires support for sharing of badges across many display sites. 

Earners can share badges across such varied online environments as personal blogs and social networking channels, tying a variety of achievements to a single identity. It is critical for the infrastructure to be open, to give earners control over how they represent their own learning and experiences, to allow anyone to issue badges, and for each earner to be able to carry their badges with them throughout their online life.

The participants in a badging system are characterized using a few broad groups:
* Issuers - they create badges, make them available to earners and award them.
* Earners - they apply for badges and decide where to display them.
* Displayers - they display badges earned by particular earners (this also involves verifying badges).

You will see these roles described throughout the material you read on Open Badges. This page is aimed at providing an overview of badging for ''displayers'', with an introduction to the technical aspects of displaying.

Last but not least, although not involved directly in badging systems, let's not forget this group of people:
* Consumers - they include anyone looking at a badge (or badges) earned
** examples include potential employers, college admin and peers.  

=== Tech Specs ===
* The OBI is built in node.js using express.  
* Badges are represented by JSON data blobs embedded in PNG files in the [http://beta.openbadges.org/backpack/ Backpack]
* Identity management is handled by [http://identity.mozilla.com/ Mozilla Persona]

=== Open Badges Ecosystem === 
 
[[Image:Tech-diagram-v3 updated.png|700px|Open Badges -- Tech-diagram-v3 updated.png]]'''<br>'''

Here's an overview of how badging works:
* An issuer makes a badge available to their community of earners on their website. When awarded the badge, an earner sends it to their Backpack.
** The badge becomes portable through the [https://github.com/mozilla/openbadges/wiki/Issuer-API Issuer API] script, presenting the earner with a modal dialog that requests their consent to add the badge to their Backpack.
** If the issuer wants the earner to be able to store the badge outside the OBI, they can optionally push it to the [https://github.com/mozilla/openbadges/wiki/Badge-Baking Mozilla Baking Service] where the assertion URL representing JSON blobs is embedded into PNG files. Otherwise badge baking is handled through the Issuer API.
* Displayers pull unpacked badges (JSON) out of the Backpack based on earner action and privacy settings.  
* Public badges are discoverable based on earner’s email address, optionally through the [https://github.com/mozilla/openbadges/wiki/Displayer-API Displayer API].
* Earners can share their badges through their Backpack and grant permission for a particular site to display that collection of badges.  
* Displayers authenticate badges with the issuer using a verification check.

=== Definitions and Concepts ===

'''Badge'''

A digital representation of a skill, learning achievement or experience. Badges can represent competencies and involvements recognized in online or offline life. Each badge is associated with an image and some metadata. The metadata provides information about what the badge represents and the evidence used to support it.

'''Open Badge Infrastructure (OBI)'''

Open infrastructure technology supports independent badge issuers and displayers. Includes the metadata specification, APIs, verification framework, Backpack and software tools.


'''''ROLES'''''

'''Earner'''

Someone who earns a badge (either by applying or being directly issued with it). The earner can use their Backpack to manage and share their badges.

'''Issuer'''

Organization or individual who issues Open Badges to their community. The issuer is responsible for defining badges, making them available to earners and handling applications for them.
* Badge issuing can involve participants with various specific roles, such as application assessors, badge creators and administrators. 

'''Displayer'''

A website, organization, or person who accesses publicly shared Open Badges and displays them for badge earners. 


'''''TOOLS'''''

'''Mozilla Backpack'''

The core authorized data store and management interface of Mozilla’s reference implementation of the Backpack. Each earner has their own Backpack where their badge data is stored. 

'''[https://github.com/mozilla/openbadges-specification/blob/master/Assertion/latest.md Assertion Specification]'''

Badge metadata is represented as an [https://wiki.mozilla.org/Badges/Onboarding-Issuer#Metadata assertion]. The assertion specification defines the information within a badge. An assertion includes multiple items of data, such as: badge name and description, issuer, date, criteria URL, evidence URL and badge image URL. The assertion should carry all the information needed to process a badge. This ensures that badges can be fully understood and verified no matter where they are shared.

'''[https://github.com/mozilla/openbadges/wiki/Badge-Baking Badge Baking]'''

A badge is an image combined with assertion data - badge baking embeds assertion data into an image to produce a portable badge.

'''[https://github.com/mozilla/openbadges/wiki/Issuer-API Issuer API]'''

The Issuer API provides a script for issuers to let earners send badges to the Backpack. 

'''[https://github.com/mozilla/openbadges/wiki/Displayer-API Displayer API]'''

The Displayer API provides specifications for displaying badges beyond the Backpack.

'''[https://wiki.mozilla.org/Badges/Onboarding-Issuer#Verification Verification]

Displayers are responsible for verifying badges, i.e. checking that a badge is valid and was issued to the person claiming it.

'''[[Badges/badgekit|BadgeKit]]'''

A new set of tools to simplify badging for issuers - provides an interface for creating and managing badges/ assessing badge applications. The BadgeKit API lets issuers control interaction with their own community of badge earners while supporting much of the badge admin process through a Web app.

See also the [https://github.com/mozilla/openbadges-badgekit/wiki/BadgeKit-and-Open-Badges-Resources BadgeKit and Open Badges Resource list]

To explore the concepts and terms in badging and badge issuing, check out the [https://github.com/mozilla/openbadges-badgekit/wiki/Glossary Badging and BadgeKit Glossary]

== Badge Issuing == 

Badge issuing and displaying are two complementary actions within the badging framework. To understand badge displaying, it's therefore worth first understanding a little about badge issuing. 

An issuer is an organization or individual who designs and issues badges within the ecosystem. Issuers determine the badging approach that will work best for their communities, using Open Badges JavaScript interfaces to send badges to Backpacks, and optionally creating their badges using BadgeKit.

Badge issuers store badges online either as hosted or signed assertions. This allows displayers to retrieve and present badges within Web and software user interfaces. Issuers store badge data using the standard assertion structures, so that displayers can process this data and present it in a consistent way. 

Displayers are responsible for verifying badges - issuers are required to take the following steps in order to facilitate this:
** For Hosted Assertions - issuers must maintain a server with the Badge Assertion information (at the unique badge URL) to verify each badge.  
** For Signed Assertions:
*** Issuers must generate public/private key pair and maintain the hosted public key.
*** Issuers must sign the badges themselves, sign the whole package, and push badges to earner backpacks through the Issuer JavaScript API. 
* Issuers can opt to use [[Badges/badgekit|BadgeKit]] to automate parts of this process.

== Backpack == 

The Mozilla Backpack is an authorized data storage space and management interface for earners of Open Badges. Each earner can access their own Backpack - that lets them manage and share their badges.    
* The Backpack is open source and federated. Earners or issuers can take the [https://github.com/mozilla/openbadges code] and fork it.
* Earners may decide to create and host their own Backpack so that they have complete control over their badges.
* Mozilla has built a reference or default Backpack (the "Mozilla Backpack") which holds all of the badge assertions (hashed user email + badge data) for each earner.

== Metadata == 

Badge metadata is defined as an assertion, which contains multiple required and optional fields. The structure has evolved over time - see the [https://github.com/mozilla/openbadges-specification/blob/master/Assertion/latest.md assertion specification] for complete details.

Issuers can put a reasonable amount of extra material into a badge, but that material must be static - once the badge is issued, any change to the information must not change. This is to prevent someone from issuing one badge, then sneakily changing it later to another badge unbeknownst to the earner. 

Badge displayers can utilize any technology capable of parsing JSON data to process badge metadata, presenting it in a way that reflects the display context.

== Displayers == 

Displayers are key to the value of Open Badges for earners. The OBI is designed to support display of badges acquired in various different types of context, letting earners paint a more detailed, complete picture of their skills and experiences. 

* Badges are not siloed or limited to one site but can be combined with badges from multiple issuers and then shared for different audiences and purposes.  
* Each earner controls where their badges are displayed through the Backpack.  
* Each earner can create groups/ collections of badges and share with displayers that have connected to the [https://github.com/mozilla/openbadges/wiki/Displayer-API Displayer API].  
* Earners can also make badges public; those badges are discoverable by displayers if they have the earner's email address.  
* If a site has an earner's email address, they can query that person's Backpack for all of that earner's public badges. The response is a JSON representation of the badges.

=== Requirements === 

The following requirements apply to displayers:
* A Web server capable of serving requests to the general internet.
* The ability to make a GET request from their server backend and read a JSON response.
* Access to earners' backpack ID.
** Displayer can convert from earner’s email to backpack ID using this [http://beta.openbadges.org/displayer/convert/email converter] 
* Ability to communicate with the Mozilla [https://github.com/mozilla/openbadges/wiki/Displayer-API Displayer API].

=== Displayer API === 

The [https://github.com/mozilla/openbadges/wiki/Displayer-API Displayer API] returns on a JSON feed of badges the earner has made public. The displayer retrieves the list with the earner’s Backpack ID. Displayers can convert earner email addresses to user IDs, including those IDs in their API calls. Displayers can request badges using REST queries. The API provides endpoints to query for available groups of badges (that the user has made public), then to request badge data for a particular group using the group ID. The list of badges in a group is returned, including the assertion data for each badge. Displayers can then parse the assertion metadata for each badge and present it within their own site.

=== Public Badge Discovery Flow === 

# Earner sets privacy controls on badges through the Backpack, setting some badges to Public.
# Displayer has an identifier (email address/ Backpack ID) for the Backpack owner.
# Displayer queries the Backpack via the Displayer API, using the earner's Backpack ID (can be converted from earner’s email address).
# Mozilla unpacks the badges and sends the JSON for all public badges for that earner to the displayer.
# Displayer processes and presents the resulting badges.

=== Mozilla Display Support - Next Steps ===

Ongoing developments to be announced through 2014 include a number of tools to aid the earning, collecting, displaying, discovering and sharing processes.

* Provide Earner with embed code in the Backpack so that they can embed badges into any personal websites  
* Display sites that have an API, eg. Facebook, Twitter
** Build Facebook widget
** Provide documentation so that community can be empowered to be proactive in building additional widgets for sites with available APIs. 
* Display sites that don’t have an API, e.g. InsideJobs, LinkedIn
** Possible workflow
*** (1) Displayer comes to openbadges.org site
*** (2) Displayer agrees to be a Displayer
**** (2.1) Agrees to ToS
*** (3) Displayer gets the widget
*** (4) Displayer provides a button or UI component for Earner to import badges from the Backpack
*** (5) If Earner clicks yes, Displayer makes javascript call to get badges
*** (6) Displayer must reconcile email addresses if they are different - Earner must provide email address or Backpack ID associated with their Backpack
** n.b. Displayer cannot query Backpacks or discover badges without Earner interaction.
** n.b. It may be possible to display displayer buttons in the Backpack interface. TBD
* API for anonymized data.

== Verification == 

Badge verification involves checking that a badge was issued to the person displaying it, using their email address. Verification affects both issuers and displayers.

* To avoid gaming and duplication, the OBI is built to support badge verification.  
* This is essential to allow earners to prove the authenticity and validity of their badges. Badges can also have expiry dates, allowing organizations to issue badges for skills which are only valid for a set period of time.
* The OBI provides the channel for this verification to happen through the Backpack, by communicating with the issuer.    
* Verification is typically carried out by displayers, who should not display a badge that cannot be verified.

=== Verification Method === 

The OBI currently supports verification of badges through hosted and signed assertions. The assertion data for a badge contains verification information. For hosted assertions, this includes a URL field representing the assertion hosted on the issuer's server. For signed assertions, it includes a link to the issuer's public key. Displayers can utilize this data to verify badge earners.

The verification process is as follows:

'''''For hosted assertions''''':
# Displayer carries out a GET request on the verification URL from the assertion. 
#* If the response is not 200 OK or if the data at the URL is not structurally valid, the badge is treated as invalid.
# Displayer analyses content of data at assertion verification URL, which includes recipient email address.
#* Verification can now be achieved by comparing the salted hash value for the recipient (according to the verification data) to the salted hash for the email of the person claiming the badge.
# The displayer can optionally check further information in the verification data, including an expiry date if there is one. 

'''''For signed assertions''''':
# Displayer unpacks JWS object specified in the assertion verification fields.
#* If the data fails to parse as JSON data, verification fails.
# Displayer extracts the verify.url property from the JSON, carries out a GET request on it and stores the public key.
#* If the HTTP status is not 200 OK, verification fails.
# Displayer uses the public key to perform JWS verification on the JWS object - if this fails, the badge is considered invalid.
# Displayer retrieves the revocation list and checks that the badge ID is not included.

For more about assertions and verification, see the [https://github.com/mozilla/openbadges-specification/blob/master/Assertion/latest.md Specification].

''Note: for baked badges, verification also involves extracting the assertion URL from the badge image - see the [https://github.com/mozilla/openbadges-verifier Verifier] for more on this.''

=== Functional Flow ===  

# Badge (including assertion) exists in the Backpack.  
# User attempts to display badge via a display site widget.  
# Display site takes the earner’s email and puts it through a salted hash function. 
#* eg. hash (‘hipjoe@example.com’ + salt) 
# Display site compares the resulting value with the value indicated for the recipient in the badge metadata. 
# If values match, badge is verified and displayer displays the badge. If not, displayer should reject the badge.

== Identity ==

* Identity is a critical component because we need to recognize earners as they collect badges from different issuers.
* It's important to us that identity be open and decentralized.  
* We are utilizing verified email as a form of identity through the Mozilla product Persona. 
** Additional info: https://wiki.mozilla.org/Identity  
* Many sites already use email addresses for logins, even those that don't generally collect them.
* We don't need to retain any profile or personal information about the earner; all we need is their email address. 

=== Verifying Identity in Backpack ===  

# User validates identity to Mozilla's Verified Email.  
# User creates an account with Mozilla (same as sync account).  
# User asserts which email addresses he or she owns.  
# User does an SMTP challenge (system emails user a token link they must click) to prove ownership.