Unofficial Badge Connect Guide

A developer resource for implementers of Open Badges 2.1

Badge Connect API, released as Open Badges 2.1 brings the concept of a Federated backpack to the Open Badges ecosystem. A backpack is a service that acts as an agent for a recipient of Open Badges. The full Badge Connect specification is available for participants in the IMS workgroup and will be published by IMS Global on its finalization in early 2020. Badge Connect was developed in 2018-19 by members of the IMS Global Open Badges Workgroup, based on years of thinking and advocacy for an open ecosystem by members of the Open Badges project founded by Mozilla.

You can view code examples of each section of the guide. (In Progress)

This guide is sponsored by the Badgr Team at Concentric Sky and licensed openly under Apache 2.0. Contributions welcome on GitHub.

Editor: Nate Otto (Concentric Sky / Badgr - USA)

Application Types

Applications in the Badge Connect-enabled Open Badges ecosystem fall into two main roles. Host (Backpack) and Relying Party. Relying Party applications typically serve functions as either an Issuer of badges, which provides recognition to recipients, or a Displayer of badges, which helps make badges meaningful or translate them back into some kind of real world value or new opportunity for their earners.

What is a Host (Backpack)?

A Host is the official role name in the Open Badges Specification, commonly called a Backpack, which stores badge award data on behalf of recipients, making it possible for those recipients to organize and manage the badges they have earned. Backpacks may allow sharing to social media sites as a means of transmitting information about the achievements that a learner has gained.

Examples of Issuer-role Applications

There are numerous reasons why an application would award badges. Badges can be used to recognize any achievement, large or small. Some example use cases include:

• Peer to Peer competency recognition
• Badgebot: award badges based on Twitter posts
• Instant quiz app like Badgr Web Explorer
• Stack Exchange proxy issuer: get all the achievements for a user on Stack Exchange and issue them as Open Badges and push to backpack.
• Conversational systems for recognition: Define a badge collectively, as in a wiki, and trigger awards to peers.

Examples of Displayer-role Applications

The first thing to understand about applications in the role of Displayer, is that Displayer is a clearly understood term for a vast category of applications that could make use of credentials earned by individuals, processing that credential data on behalf of badge recipients to provide them and others information about the meaning of these awards.

Examples of simple Displayer applications include:

• A credential-based Apply to Job on Seek.com API connector or profile modifier
• LinkedIn Badge Connector: Convert from Open Badges to post to LinkedIn certifications, skills, profile
• Conversational systems post-recognition: Talk pages about badgeclasses related to awards in a user’s backpack

Farther-reaching Displayer applications include:

• A “collective backpack”: A community pushes all their badges from individual backpacks into one common backpack to represent the achievements of a group within a single space, as opposed to only achievements earned by one individual.
• Europass Wallet Pusher: translate your OB credentials into format for visualization in Europass wallet

These examples were provided by the participants of a Badge Connect workshop at the 2019 ePIC Conference in Lille, France and by contributors to this guide.

Badge Connect Applications

This section of the guide will explain how to get started with a relying party application for Badge Connect. Both Issuer apps and Displayer apps need to go through several common processes before the workflows for their specific needs diverge. Here we will explain these steps, including:

1. Backpack Selection
2. Dynamic Client Registration
3. The OAuth Dance: Authorization Code & Token Exchange
4. Refreshing Tokens

Then the remaining sections of the guide will provide step-by-step instructions for accessing the API endpoints necessary to build Issuer and Displayer applications.

Issuer Applications: What you Need to Know

Here is a guide for how to build a prototypical issuer application that awards Open Badges and pushes them to a recipient’s backpack of choice.

Issuer Apps step by step

• A user starts on an issuing application and earns a badge. For example, they successfully complete a quiz.
• An Open Badges Assertion is published, linked to a BadgeClass and Issuer Profile, according to the Open Badges 2.0 Specification.
• The user is offered the opportunity to claim the badge by accepting it into a backpack of their choice.
• A choice of backpacks is offered, including perhaps some suggestions known to the issuer application already as well as an advanced option to select a domain of their choice.
• If this is the first time the issuer application has encountered the backpack on the chosen domain, information about the backpack is read from the backpack’s manifest file, and a server to server connection is established using Dynamic Client Registration
• The “OAuth Dance” is initiated, directing the user to the backpack for authorization.
• The user accepts the issuer app’s requested permissions from within the backpack interface.
• The user is redirected back to the issuer application with a code in the query parameters portion of the URL.
• The issuer application exchanges the code for an access token (including a refresh token for later).
• The issuer application makes a request to the GET /profile endpoint to confirm that the awarded recipient identifier appears within the user’s backpack profile.
• The issuer application makes a call to the POST /assertions endpoint to add the awarded badge to the user’s backpack. The backpack responds with a successful result.
• The issuer application may now push badges to the user’s backpack at any time.
• After some time, typically 1 hour, the access token expires. The next time the issuer app needs to contact the backpack on the behalf of this user, it will need to refresh its access token. At the time of its issue, the issuer application also obtained a refresh token. The refresh token is used to exchange the expired access token for a new one with an expiration date in the future.

Displayer Applications: What you Need to Know

Here is a guide for how to build a prototypical displayer application that pulls badge awards from a recipient’s backpack of choice and does something interesting with them. This example use case will be to display badges on a timeline to the user.

Displayer Apps step by step

• A user starts on an badge displayer application and sees they have the opportunity to use the app by connecting their backpack.
• A choice of backpacks is offered, including perhaps some suggestions known to the displayer application already as well as an advanced option to select a domain of their choice.
• If this is the first time the displayer application has encountered the backpack on the chosen domain, information about the backpack is read from the backpack’s manifest file, and a server to server connection is established using Dynamic Client Registration
• The “OAuth Dance” is initiated, directing the user to the backpack for authorization.
• The user accepts the displayer app’s requested permission scopes from within the backpack interface.
• The user is redirected back to the displayer application with a code in the query parameters portion of the URL.
• The displayer application exchanges the code for an access token (including a refresh token for later).
• The displayer application makes a request to the GET /profile endpoint to see the identifiers registered on the user’s profile.
• The displayer application makes a call to the GET /assertions endpoint to read the badges in a user’s backpack. The backpack responds with a successful result.
• The displayer application processes the badges. This may include submitting each badge to the validator for re-verification. As needed, the assertions are mapped to the recipient identifiers found in the profile.
• Badges are displayed to the user and/or become part of the user’s experience on the displayer app.
• The displayer application may now pull updated badges to the user’s backpack at any time.
• After some time, typically 1 hour, the access token expires. The next time the displayer app needs to contact the backpack on the behalf of this user, it will need to refresh its access token. At the time of its issue, the displayer application also obtained a refresh token. The refresh token is used to exchange the expired access token for a new one with an expiration date in the future.