View source for Badges/infrastructure-tech-docs

<h2>Infrastructure Technical Documentation</h2>
<h3>STATUS</h3>
<ul><li> Currently in: <b>BETA1</b>, September 15th, 2011  [https://github.com/mozilla/openbadges/ Source Code]
</li><li> Next Up: <b>Public Beta</b>, April 2012
</li></ul>
<hr />
<h3> Mozilla Open Badge Infrastructure (OBI)  </h3>
<p><b>BACKGROUND / FRAMING</b> <br /> <i>Why Are We Doing This?</i> 
</p>
<ul><li>Learners are learning everywhere -- but most of that learning doesn't count 
</li><li>Exploring badges as an alternative accreditation/credentialing system 
</li><li>Must avoid more silos 
</li><li>To truly support learners learning everywhere == support badges issued from multiple issuers across the Web 
</li><li>To optimize the value of those badges, need to be remixable and shareable with many different audiences/sites 
</li><li>Need a supporting infrastructure to standardize the process and support each user collecting badges from multiple users and sharing subcollections out across various displayers. 
</li><li>This infrastructure needs to be open and as decentralized as possible to give learners control and support the entire ecosystem
</li></ul>
<p><i>Description</i> <br /> Enabling learners to earn badges wherever they're learning across the web requires support for multiple individual badge issuers. Empowering learners to use their badges as legitimate credentials requires support for sharing of badges across many display sites. The Open Badges framework is designed to allow any learner to collect badges from multiple sites, tied to a single identity, and then share them out across various sites -- from their personal blog or web site to social networking profiles. It is critical for this infrastructure to be open to give learners control over their own learning and credentials. allow anyone to issue badges, and for each learner to carry the badges with them across the web and other contexts. 
</p>
<hr />
<p><b>TECH SPECS</b> 
</p>
<ul><li>The OBI is built in node.js using express. 
</li><li>Badges are represented by JSON data blobs embedded in PNG files in the Backpack 
</li><li>Identity management is handled by Mozilla BrowserID
</li></ul>
<hr />
<p><b>DEFINITIONS</b> 
</p>
<ul><li><b>Badge</b> - The core currency of exchange. A single credential demonstrating a skill, achievement, quality or affiliation. Badges are represented as chunks of JSON data in the OBI Backpack. Badges may be stored in the Backpack as either Verified Badges or Unverified Badges. 
<ul><li><b>Badge Manifest</b> - User identity information (email address) plus badge information (JSON metadata) 
</li><li><b>Verified Badge</b> - Badges that have been signed by a third party. The Backpack verifies the signature against the signers public key and if confirmed, accepts the badge as a verified badge. The verification information is represented with the badge as a layer of trust on the badges validity. 
</li><li><b>Unverified Badge</b> - A badge that has not been signed by a third party but is issued as flat JSON data. Unverified does not mean invalid, but simply that there is no additional information with the badge to establish an additional layer of trust. Most badges issued into the OBI will be unverified badges. 
</li></ul>
</li><li><b>Open Badge Infrastructure (OBI)</b> - open infrastructure technology to support independent badge issuers and display sites. Includes the Badge Backpack(s), Metadata Spec, API and Authentication/Verification Framework. 
<ul><li><b>Badge Backpack</b> - The core authorized data store and management interface. Each learner has his/her own Backpack where all their badge data is stored. Mozilla will host the reference Backpacks, but the infrastructure will allow for users to develop and host their own Backpacks. NOTE: the Backpack is being combined with new iterations of the development. Each user will have their own Backpack that holds all of their badges and gives them an interface to manage, control and share their badges. 
</li><li><b>Metadata Spec</b> - The definition of what makes up a badge. Each badge is a chunk of metadata that describes the badge, including title, description, issuer, issue date, evidence URL, image, etc. Each issuer will need to conform their badges to the metadata spec for the badges to be accepted into the Backpack. Beyond the technical requirements, the metadata spec is essential for standardizing badges to ensure that badges can be transferred/ported without losing critical information to understand and verify the badge. Beyond the core spec, the metadata is extensible. 
</li><li><b>Badge Baking</b> - Embedding the JSON blob into a PNG file to make a fully robust, portable badge (with all of the metadata embedded) 
<ul><li><b>Badge Baking Service</b> - tool/software to embed the JSON blob in a PNG. Mozilla will build the reference baking service for beta 
</li></ul>
</li><li><b>API</b> - The interface specifications for pushing badges into the Backpack (issuers/users), as well as pulling them out (display sites/widgets). 
</li><li><b>Authentication Channel</b> - Communication channels and framework to support badge authentication (was this badge issued to this person on this date? Has it expired? etc.) 
</li><li><b>Verification/Endorsement Channel</b> - Communication channels and framework to support badge endorsement (was this badge signed? is the signature valid?) 
</li></ul>
</li><li><b>Users/Partners</b> 
<ul><li>User - a person storing their badges within the Open Badge Infrastructure. This user has had interactions with issuers to earn badges, then logs in via their Backpack to manage those badges, and can share out to various display sites as well. 
</li><li><b>Issuer</b> - Organization, consortium or individual who issues badges into the OBI. The OBI is open and supports any independent issuer that conforms to the necessary badge and issuing specifications. 
<ul><li><b>Issuer Tech</b> - Software that supports issuing of badges into the OBI and/or to users directly. The issuer tech must generate the JSON data chunks for each badge, and communicate with the Backpack(s) to pass badge data and authenticate badges. Many issuers will build their own issuer tech, although open generic or technology-specific tools could be built to support a wide range of issuers. 
</li></ul>
</li><li><b>Displayer</b> - Website, run by an organization, consortium or individual, that pulls badges from the OBI and displays them for a user. Displayers could range from social networking sites like Facebook or career social networks, to job search/application sites to personal blogs or sites. Each user manages which display sites can access their badges (and which subcollection of badges to display per display site) through the Backpack or directly on their own. 
<ul><li><b>Widget</b> - Software that supports the display of badges on a particular display site. Widgets will communicate with the Backpack to pull badges, as well as utilize the Authentication/Verification Framework to authenticate badges before displaying. For example, one could build a Facebook app that leverages both the OBI API to pull badge data, and the Facebook API to push badges into Facebook. 
</li></ul>
</li><li><b>Signer/Endorser</b> - An organization, consortium or individual who validates a badge by signing it with their private encryption key. Trusted third party signers may emerge. 
<ul><li><b>Signing Authority</b> - A third party that checks signed badges against the signers public encryption key and confirms or rejects verification. Backpack communicates with the signing authority to verify the badge if signing data is included with the badge (otherwise the badge is Unverified).
</li></ul>
</li></ul>
</li></ul>
<p><br /> 
</p>
<hr />
<p><b>WHAT MOZILLA IS BUILDING</b> 

[[Image:Tech-diagram-v3 updated.png|700px|Open Badges -- Tech-diagram-v3 updated.png]]'''<br>''' 
</p><p>Backpack + Metadata Spec + APIs + Authentication Channel + Endorsement/Verification Channel == Open Badge Infrastructure 
</p><p><i>Details</i> 
</p>
<ul><li>Backpack is authorized data storage plus a management interface for users 
</li><li>If applicable, the Backpack verifies badges by communicating with a signing authority via the verification channel 
</li><li>The Backpack is open source - users may decide to create and host their own Backpack so that they have complete control over their badges. Mozilla is building a reference/default Backpack. 
</li><li>Issuers push badges to the Mozilla baking service where the JSON blobs are embedded into PNG files 
</li><li>For beta: Badges are then pushed to the Backpack, as well as back to issuers to email directly to users. 
</li><li>Post beta: Issuers manage the user interface on their side to have users authorize badges sent directly to the OBI or just emailed to them 
</li><li>Displayers pull unpacked badges (JSON) out of the Backpack based on privacy settings and user action. 
</li><li>Public badges are discoverable by user email address 
</li><li>User can share badges through the Backpack, thus granting permission for a particular site to display that set of badges 
</li><li>Displayers authenticate badges with the issuer using the Authentication Channel
</li></ul>
<hr />
<p><b>METADATA SPEC</b> 
</p>
<ul><li>A badge is a JSON blob of metadata embedded in a PNG file. 
</li><li>This is the data presented at the Authentication URL on the issuer's server 
</li><li>The metadata should carry all the information needed to understand a badge. This ensures that badges can be fully understood and authenticated no matter where they are shared or used. 
</li><li>NOTE: trying to keep the spec as simple as possible while still carrying enough information to completely understand the badge/credential 
</li><li>The metadata spec is currently locked down for the beta launch (see link below). Fields:* <b>Badge Title</b> 
</li><li><b>Badge Image URL</b> (served from the issuer's site or cached?) 
</li><li>We are probably going to end up doing image caching on the Mozilla side 
</li><li><b>Short Badge Description</b> (plain text, hashtags, 140 characters?) 
</li><li><b>Badge Criteria</b> (URL, required - optional metadata at url?) 
</li><li><b>Issuer</b> (Human readable name) 
</li><li>'Organization name or just individual name 
</li><li><b>Issuer Contact</b> (email address) 
</li><li><b>Issue Date</b> 
</li><li><b>Badge Expiration Date</b> (optional; default none) 
</li><li><b>Badge Evidence URL</b> (optional; highly recommend?) 
</li><li>Maybe: <b>User-added field</b> (could provide URL or more context/text) (optional) 
</li><li>Push this off into the Backpack?
</li></ul>
<p><i>Finalized Badge Manifest/Spec:</i> <br /> <strike>http://openbadges.lighthouseapp.com/projects/80353/badge-manifest</strike> <br /> Updated 9/1: https://github.com/mozilla/openbadges Changes: 
</p>
<ul><li>Did not change the fields, just changed the order 
</li><li>This allows us to separate the static badge type information from the specific badge instance information. 
</li><li>This will make endorsements/signing easier since third parties can sign/endorse a badge without having to do so for each instance of it. (Inheritance.) For example, if MIT signs the P2PU Javascript badge (title, description, criteria, image, issuer info, etc.), each P2PU-issued Javascript badge carries that endorsement info with it. This allows post-issuance endorsement and results in up-to-date badges.
</li></ul>
<p><i>Badge Manifest Verifier:</i> <br /> Used to test the sending of your JSON blobs to Mozilla <br /> https://github.com/mozilla/openbadges 
</p>
<hr />
<p><b>PNG FILES / BADGE BAKING</b> <br /> 
</p>
<ul><li>Each badge will be a JSON blob of metadata embedded in a PNG file 
</li><li>This allows the badge to be more easily portable - an actual 'thing' that can be emailed around, carrying all the information with it 
</li><li>Ultimately, this is important for decentralization of the system - so that users have more control over where their badges live 
</li><li>For beta, Mozilla will be providing a 'baking' service to package the JSON into a PNG file 
</li><li>Issuers will still send the badge manifest to the Mozilla, just instead of sending it directly to the Hub, they will now send it to the Mozilla 'baking service' and Mozilla will package it into a PNG and: 
<ol><li>push it to the Backpack (for beta) 
</li><li>deliver back to the issuer who can then send to the user 
</li></ol>
</li><li>NOTE: step 1 is for beta only. We eventually want to get to #2 only and have the issuer manage the interaction and the user control the badge. This is A) to avoid SPAMing the user with unwanted badges (which we can control in beta) and B) to give the user ultimate control over where the badges go. 
</li><li>Mozilla will provide the 'tools' for unpacking the PNG file through the OBI 
</li><li>PNG files will be unpacked in the Backpack where each user can view, manage and organize their badges (and see all the metadata behind each badge) 
</li><li>PNG files will be unpacked for the displayer API so that displayers will just have the raw data to work with on their end.
</li></ul>
<p><i>Technical Specifics / API Specifics:</i> https://github.com/mozilla/openbadges 
</p>
<hr />
<p><b>BADGE IMAGE STANDARDS</b> 
</p>
<ul><li>Image must be a PNG (for beta). 
</li><li>Potentially: In later iterations, we can convert to a PNG (Why permit flexibility after launch? Why not stick with a default requirement?) 
</li><li>Other than that, we are only specifying that images should be square and not exceed 250K maximum size 
</li><li>Image is provided as a URL to the image on the issuer server in the metadata 
</li><li>Mozilla will cache the image in at least 2 sizes 
</li><li>When a badge is displayed, it will be loaded from the Mozilla cache to avoid extra burden on the issuer servers, also in case the issuer is not available or link is broken 
</li><li>Note: this is under consideration. Since the JSON is now embedded in the PNG file, we might not need this cache
</li></ul>
<hr />
<p><b>ISSUERS AND DISPLAYERS</b> 
</p><p>"ISSUE REQUIREMENTS / WHY &amp; HOW TO BECOME AN ISSUER" <i>"Independent Issuers" </i> 
</p>
<ul><li>Issuer badge systems are independent of the infrastructure - how you assess work, decide who earns badges, issue badges within your site, display badges within your site, etc. - that's all up to each issuer 
</li><li>We are intentionally pushing the innovation to the fringes/edges at this point - meaning the issuers have complete control over how their badge system works 
</li><li>We want to support innovation, not constrain it 
</li><li>The touchpoint with the OBI is pushing each badge into the designated Backpack for the user
</li></ul>
<p><i>Why Become an OBI Issuer</i> 
</p>
<ul><li>Openness - break badges out of a single silo 
</li><li>Learners can earn and share badges from multiple issuers 
</li><li>Learner portfolio or living transcript that they control 
</li><li>Display them across multiple sites (without getting stuck in those sites) 
</li><li>Maybe: Discoverability (allowing them, employers or other stakeholders to find people based on badges) 
</li><li>Maybe: Reporting/tracking (pushing out data about learning paths and experiences (in aggregate) for evaluation, effectiveness, etc.)
</li></ul>
<p><i>Requirements for issuers</i> 
</p>
<ul><li>Issuers must be able to communicate with the Mozilla baking service 
</li><li>Issuers must have email addresses for users and must be able to email users 
</li><li>Issuers must have badges (or be able to convert their badges) into the format (metadata spec) that the baking service expects. 
</li><li><strike>Users must be registered with whatever hub the issuer is trying to push badges to, or (for later versions) the Issuer must ask user which hub they want to push badges to and honor that request </strike> 
</li><li>Issuers must maintain a server with the badge manifest information (at the unique badge URL) to authenticate each badge 
</li><li>NOTE: unless the issuer signs the badge instance. If badge instances are signed with the issuers private key, then the OBI can verify the badge and it would not be necessary to maintain the authentication channel
</li></ul>
<p>NOTE: We have an example of issuer tech, built in python with the alpha version of the infrastructure in early July. This code is available for partners to explore/utilize for their own issuing: https://github.com/lmorchard/django-badger. We will also provide some assistance for beta partners if needed. This needs updating based on the new manifest changes - will be updated after 9/15 
</p><p><i><b>Function Flow For Issuers:</b></i> 
</p>
<ol><li>0. Issuer must have an email address for user. 
</li><li>1. Issuer provides a badge manifest (retrievable by GET request) to Mozilla baking service
</li></ol>
<ul><li>manifest contains email of user + badge information
</li></ul>
<ol><li>2. Verification of issuer and issuee is implicit 
<ul><li>badges are associated with issuers by fully qualified domain name (visual distinction in artifact) 
</li><li>email address == identity
</li></ul>
</li></ol>
<p>BETA: 
</p>
<ol><li>3. Mozilla baking service forwards embedded PNG to the Backpack. 
</li><li>4. Mozilla sends PNG back to the issuer 
</li><li>5. Issuer forwards the badge to the user (most likely via email)
</li></ol>
<p>POST BETA: 
</p>
<ol><li>3. Mozilla baking service sends PNG back to issuer 
</li><li>4. Issuer asks user how they want the badge: sent to the OBI or delivered via email 
</li><li>5. Issuer honors user's choice and sends to the OBI and/or to the user directly via email
</li></ol>
<p><i>DISPLAY REQUIREMENTS / HOW TO BECOME A DISPLAY SITE</i> 
</p>
<ul><li>Display of badges is where a significant part of the value lies - badges are not siloed or 'stuck' within one site but can be combined with badges from multiple issuers and then shared out for different audiences/purposes 
</li><li>Mozilla will provide the displayer APIs which will unpack the PNG files and present displayers with the raw badge data 
</li><li>The displayer API is not yet fully developed - we are still working through these specifics and will have this sometime soon after beta launch 
</li><li>User will control where badges are displayed through the Backpack 
</li><li>User can create groups of badges and share through the Backpack to issuers that have connected via the API 
</li><li>Users can also make badges public - in that case, those badges would be discoverable by displayers if they had the users email address 
</li><li>At its most basic: if a site has a user's email address, they will be able to query the Backpack for all a user's public badges. They will get back JSON representation of the badges 
</li><li>We are building the first widget for the beta - a Facebook widget 
</li><li>Also will provide the user with embed code in the Backpack so that they can embed badges into any personal websites 
</li><li>Other display partners we are currently working with: 
</li><li>InsideJobs - data analyis of badges and badges for job opportunities 
</li><li>Adecco - badges for job opportunities 
</li><li>Parchment - badges alongside formal education credentials 
</li><li>LinkedIn - badges included on the career profile (Possible)<br />
</li></ul>
<p><i><b>Functional Flow For Displayers:</b></i> <br /> PUBLIC BADGE DISCOVERY: 
</p>
<ol><li>User sets privacy controls on badges through the Backpack; sets some of the badges to Public 
</li><li>Displayer queries the Backpack via the user's email address 
</li><li>Mozilla unpacks badges and sends the JSON for all public badges for that user to the displayer
</li></ol>
<p>USER SHARE 
</p>
<ol><li>Displayer registers with the OBI as a displayer - meaning they will show up as an option for sharing in each Backpack 
</li><li>Users create subgroups of available badges through the Backpack 
</li><li>Users share subgroup(s) with displayer through the Backpack 
</li><li>Mozilla unpacks that user's badges and sends the JSON for all public badges to the displayer
</li></ol>
<p><i><b>Results:</b></i> 
</p>
<ol><li>User maintains control of their badges, can choose where they go 
</li><li>One backpack per user - <strike>personas (email addresses) get aggregated at the hub level<br /> </strike><strike></strike> 
<ul><li><strike>user doesn't have to have same email at every issuer</strike> 
</li></ul>
</li><li>Simple to implement 
</li><li>Difficult to spoof 
<ul><li>Issuers must keep badge manifest on their server. manifest data identifies recipient 
</li><li>Unintended recipients can't claim badge 
</li><li>Backpack identifies issuer implicitly: parses FQDN to identify issuer 
<ul><li>Bad issuers may "copy" another badge but it will be easy to spot 
</li><li>Artifact contains FQDN.
</li></ul>
</li></ul>
</li></ol>
<hr />
<p><b>IDENTITY</b> <br /> <i>Verified Email Identity</i> 
</p>
<ul><li>Identity is a critical part of the OBI because we need to know/recognize a user all across the web as s/he collects badges from different issuers/sites 
</li><li>Identity needs to be open and decentralized 
</li><li>Mozilla.com is working on a solution called Verified Email 
</li><li>https://wiki.mozilla.org/Identity 
</li><li>The idea behind verified email as identity 
</li><li>people understand email address (they don't understand OpenID) 
</li><li>many sites already use email for login 
</li><li>even those that don't generally collect it (for resetting password)
</li></ul>
<p><i>OBI Identity</i> 
</p>
<ul><li>We are using the first version of Mozilla Verified Email Identity, called BrowserID (https://browserid.org/) for the beta version of the OBI 
</li><li>Implement signup for Backpack as email-based usernames, do SMTP challenge (email user a token link they must click) to verify. 
</li><li>We will roll in future versions of Verified Email Identity as Mozilla Labs releases them
</li></ul>
<p><i>Functional Flows</i> <br /> <i><b>For Backpack:</b></i> 
</p>
<ol><li>1. User validates identity to Mozilla's Verified Email 
<ol><li>0. Moz ID. Act as a secondary authority. 
</li><li>1. User creates an account with mozilla (same as sync account) 
</li><li>2. and asserts which email addresses he or she owns. 
</li><li>3. do an SMTP challenge to prove ownership 
</li></ol>
</li><li>2. We don't need to retain any profile or personal information about the user, all we need is email address.
</li></ol>
<hr />
<p><b>USER BACKPACK CREATION/REGISTRATION</b> <br /> <i>Backpack creation</i> 
</p>
<ul><li>Mozilla is building a reference or default Backpack which will hold all of the badge manifests (user email+badge data) for each user 
</li><li>Users can create/build their own Backpack, giving them complete control over their badges/credentials* For beta, we will automatically forward badges to the Backpack to seed the ecosystem and work through other options 
</li><li>Ultimate goal is to allow users to have control over their badges and make it easier to maintain their own Backpack
</li></ul>
<p><i>Backpack registration</i> 
</p>
<ul><li>Issuers do not need to register with the OBI - they simply push badges to the baking service
</li></ul>
<hr />
<p><b>BADGE AUTHENTICATION</b> <br /> <i>Authentication</i> 
</p>
<ul><li>To avoid gaming and duplication, the OBI is built to support badge authentication. 
</li><li>This handles the questions of "Did this issuer issue this badge to this user on this date? Is this badge still valid or has it expired?" 
</li><li>The OBI provides the channel for this authentication to happen through the Backpack, but must communicate with the Issuer. 
</li><li>Issuer must be online to authenticate badges. (we are exploring a cache to cover authentication for x amount of time) 
</li><li>Most authentication will be done by the Displayers. Displayers should not display a badge that cannot be authenticated.
</li></ul>
<p><i>Functional Flow</i> 
</p>
<ol><li>0. Badge manifest exists in the Backpack 
</li><li>1. User attempts to display badge via a display site widget 
</li><li>2. Display site uses the Authentication Channel to communicate with the issuer to confirm that this badge was in fact issued to this user on this date, as well as if the badge has expired, needs updating, etc. 
</li><li>3. If authenticated, displayer shows the badge. If not authenticated, displayer should reject the badge.
</li></ol>
<hr />
<p><b>BADGE ENDORSEMENT (SIGNING / VERIFICATION)</b> <br /> <i>Badge Endorsement</i> 
</p>
<ul><li>We recognize a need for some badges to be validated or verified by authorities or trusted entities 
</li><li>The current solution we are working on is badge signing/verification functionality which would allow issuers to have their badges signed and the Backpack to verify that signature 
</li><li>Uses asymmetric encryption between a signer and signing authority. The signer may be anyone that an issuer feels can add a layer of trust to their badge. 
</li><li>This means there would be Verified Badges and Unverified Badges in the Backpack (a majority may be unverified) 
</li><li>Verification information is carried in the header of the badge manifest 
</li><li>Badge manifest is nested the way it is so that endorsers can sign the badge type ahead of time, or after the fact, and then all instances can carry that information with them. 
</li><li>We are still working out how the verification information is displayed to an end user.
</li></ul>
<p><i>Functional Flow</i> <br /> 
</p>
<ol><li>0. Issuer sends badge to signer 
</li><li>1. If accepted by signer*, signer sends badge back to issuer signed with signer's private key. 
<ul><li>If not accepted by signer, signer sends back back to issuer unsigned 
</li></ul>
</li><li>2. Issuer issues badge to user 
</li><li>3. Issuer/user pushes badge to Backpack 
</li><li>4. Backpack communicates with the signing authority to confirm the signature against the signers public key 
</li><li>5. If confirmed, Backpack accepts the badge. If unconfirmed, Backpack rejects badge.
</li></ol>
<hr />
<p><b>DEVELOPMENT ROADMAP</b> 
</p>
<ul><li><b>Prototype</b> - A prototype of the badge infrastructure was built at the Mozilla Drumbeat Festival in Barcelona. The prototype was updated and advanced in early January 2011, and a more complete and working prototype is now in use for the School of Webcraft badge p