Open Badges 3.0 Implementation Guide

Open Badges Implementation Guide

Candidate Final Public
Spec Version 3.0
Candidate Final Public
Document Version: 1.0
Date Issued: March 1, 2023
Status: This document is for review and adoption by the 1EdTech membership.
This version: https://www.imsglobal.org/spec/ob/v3p0/impl/
Issue Tracker
https://github.com/1EdTech/openbadges-specification/issues

IPR and Distribution Notice

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights webpage: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf .

The following participating organizations have made explicit license commitments to this specification:

Org name Date election made Necessary claims Type
Concentric Sky October 24, 2019 No RF RAND (Required & Optional Elements)
Arizona State University June 21, 2022 No RF RAND (Required & Optional Elements)
Temple University June 10, 2022 No RF RAND (Required & Optional Elements)
Credly October 3, 2019 No RF RAND (Required & Optional Elements)
Workday, Inc. June 10, 2022 No RF RAND (Required & Optional Elements)
RANDA Solutions June 9, 2022 No RF RAND (Required & Optional Elements)
Anthology June 23, 2022 No RF RAND (Required & Optional Elements)
Unicon June 10, 202 No RF RAND (Required & Optional Elements)
Bowdoin College June 11, 2022 No RF RAND (Required & Optional Elements)

Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/speclicense.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources .

© 2023 1EdTech™ Consortium, Inc. All Rights Reserved.

Trademark information: http://www.imsglobal.org/copyright.html

Abstract

Conformance Statements

This document is an informative resource in the Document Set of the Open Badges Specification specification [OB-30]. As such, it does not include any normative requirements. Occurrences in this document of terms such as MAY, MUST, MUST NOT, SHOULD or RECOMMENDED have no impact on the conformance criteria for implementors of this specification.

1. Introduction

The 1EdTech digital credentials specifications, Open Badges and Comprehensive Learner Record (CLR) enable the recognition of learning achievements in many contexts that are cryptographically verifiable as the learners present them to unlock new opportunities across a lifetime of learning and employment. Key use cases include the recognition of skills and competencies, degrees, certificates and professional certifications, participation, and community engagement.

This implementation guide aims to inform product developers who are investigating or planning implementation of the Open Badges 3.0 and/or CLR 2.0 specifications about the available implementation options and how to situate a product within the ecosystem compatible with these specifications.

1.1 Overview

Each Open Badges OpenBadgeCredential is digitally signed by its issuing organization as Verifiable Credentials compatible with the Verifiable Credentials Data Model v1.1. Issuers may bundle together multiple related achievement credentials into transcripts and other longitudinal records for an individual learner in a CLR as a ClrCredential, which is also signed using the same technique as the individual credentials. Additionally, credentials can be augmented with an EndorsementCredential from a third party to lend the support of another individual or organization to the quality or relevance of an issuer or credential data.

A RESTful API, with dynamic client registration, is available to transport data in OpenBadgeCredential and ClrCredential format, under the control of the learner, between systems where they are issued, hosted on behalf of the learner, or verified by third parties in order to qualify the learner for job placement or other opportunities. Implementing systems can participate in a variety of roles

1.1.1 Spec documents (Normative References)

The full set of documents is comprised of the following documents:

1.1.2 Audiences

This implementation guide is intended for product developers across various implementation roles necessary for the operation of an ecosystem where digital credentials efficiently recognize achievements that matter and flow to the contexts where these achievements each need to be understood. Products may be situated to perform one or more roles within the ecosystem, such as issuing credentials, hosting credentials on behalf of learners, and verifying credentials.

1.2 OB Overview

An Open Badge (OpenBadgeCredential) is a individual achievement recognized about an individual learner. An Issuer makes a claim that a learner has met the criteria of a particular defined Achievement.

1.3 CLR Overview

A Comprehensive Learner Record allows many Open Badge achievement credentials to be bundled together, with some additional associations between them defined. This is like another onion layer wrapping the inner set of credentials that is also signed. Individual component credentials are verifiable, and the wrapping CLR is also verifiable. CLRs can contain achievements from multiple different issuers to show a learner's progression with multiple organizations or subdivisions of a large educational institution.

1.4 Use Cases

Use cases are outlined in each the Open Badges and Comprehensive Learner Record specifications. Use cases outline how each specification is intended to provide value to end users through interoperability between products.

Open Badges use cases include:

  • Assertion Issuance to Wallet
  • Assertion Issuance Without a Wallet
  • Recipient Presentation of Assertion
  • License Issuance
  • Single Skill Assertion
  • Mapping Skills
  • Verifying Continuing Education
  • Self-assertion
  • Endorsement
  • Re-issue an OB 2.0 Badge as an OB 3.0 Badge
  • Authorization to Issue Given by Creator to Issuer
  • Revocation of an Issued Credential
  • Badge Class Status

Comprehensive Learner Record use cases (not yet published) include:

  • Recent graduate wants to hold a copy of their own official transcript
  • Job applicant provides proof of degree and transcript to potential employer
  • Job applicant provides proof of degree and specific courses/engagements from the CLR
  • Higher Ed Competency-Based Education
  • Issuer Asserting All Student Achievements Comprehensively as a CLR
  • Issuer Asserting Partial Transcript at Intermediate Points in Learning Journey
  • Issuer Asserting Student Up to Date Partial Transcript of Achievements as CLR on Request
  • Internal Organizational Staff Development and Promotion
  • Upskilling with Higher Ed Professional/Continuing Education
  • Teacher Placement with a District
  • Professional Licensure Test Taker results
  • Students in Tutoring Program

1.5 OB/CLR in the 1EdTech Ecosystem

The core of both Open Badges and Comprehensive Learner Record is an assertion about an achievement. As defined in Open Badges Specification v3.0 and Comprehensive Learner Record Standard v2.0, an assertion is specific to one learner. It contains a claim that the learner has made a particular achievement and metadata about the achievement, the issuer, and the learner, including possible evidence that provides support for the claim.

These concepts are also present in some way in other specifications within 1EdTech, enabling connections between specifications.

Note
This section is purely informative. The scenarios described here does not define any additional requirements of the specification to conform to.

A clear connection to other specifications occurs through the alignment of achievements. An alignment of an Achievement to can refer to a IMS Competencies and Academic Standards Exchange (CASE) Service Version 1.0's CFItem for linking the achievement to a learning object in a CASE's Competency Framework Package.

Another possible connection with other 1EdTech's specifications is the issuer of the credential. Since it can be an organization or entity it can represent the same entity described as an Org in 1EdTech OneRoster® Specification v1.1 [OR-11] or Edu-API Specification Specification v1.0 [EDUAPI-10].

Moreover, the learner who the credential is issued to can have a relationship with the User entity in [OR-11] or the Person entity in [EDUAPI-10], as well.

Also, [OR-11] covers performance of the learner in a context such an assignment vi the Result entity. This can be related with the Result Definition of the issued Achievement, and the Result of an AchievementSubject.

Open Badges and Comprehensive Learner Record can be implemented by systems that use other specifications as well. For example, an Open Badges or CLR application be offered as a tool within an LMS using IMS Global Learning Tools Interoperability® Core Specification v1.3 to launching the OB or CLR-specific interfaces.

2. Getting Started (for Developers)

This section is non-normative.

It may seem like an overwhelming task to implement Open Badges 3.0 or CLR 2.0, but there are straightforward options that can take your product to a certified launch simply.

2.1 Relationship between VC and CLR/OB

New to this version of the specification, the data model of both CLR and OB adopts the convention of the [VC-DATA-MODEL].

Since Verifiable Credentials are extensible by design, CLR/OB defines a set of extensions (also called profile) for reflecting the domain both specifications cover: learning achievements, alignment with educational/workforce frameworks, etc. CLR/OB also defines the verification algorithm for these credentials, as well as a set of services for exchanging these credentials.

That means that ClrCredential and AchievementCredential are, in fact, Verifiable Credentials, and can be used wherever a Verifiable Credential can be. This assertion is not bidirectional, thus a Verifiable Credential might not be an CLR/OB Credential. Only those credentials with the extension set defined by the CLR/OB spec, and verifiable via CLR/Ob verification algorithm, can be treated as CLR/OB Credentials.

2.2 Issuer quickstart

Here is a quickstart tutorial to build an MVP of an Open Badges product that issues Open Badges to learners. It aims to sketch out a simple path to a successful conformant implementation of Open Badges 3.0 issuance. From this base, optional components of the specifications can be layered on to implement relevant APIs, package records in CLR format, implementing revocation or refresh services, and more. Products that complete all the user stories in this quickstart will potentially be eligible for issuer-only certification.

We can track the workflows that must be built through a set of user stories.

Issuer Profile:

As an institutional administrative agent, I can define an Issuer Profile that represents my organization.

See details on the selection of recipient and issuer identifiers, but for the purposes of a quickstart, hosting an issuer profile on an HTTPS url associated with a did:web Decentralized Identifier is an easy choice for a web application. See DID Web Method Specification For example, if the web application under development is running on the domain example.com, an issuer profile identifier might be did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774, which would resolve to a hosted resource available at https://example.com/issuers/540e388e-2735-4c3e-9709-80142801c774. But what is served at this URL when a client requests it? The most effective answer is to present a response that best matches what the client is requesting, as it indicates with the Accept HTTP header.

  • When a client requests Accept: application/json or application/ld+json or does not include an Accept header, a JSON-LD that includes the OB 3.0 context should be returned. It should include its own primary id, all required properties from Profile, and a representation of the public key component of the keypair this issuer uses to sign credentials in selected JWK or Ed25519VerificationKey2020 format. See Dereferencing the Public Key
  • When a client requests Accept: */* or application/html, an HTML representation of the Achievement should be presented. This should express information about the issuer using Open Graph meta tags, including at least name, description, and image tags for easy rendering of preview cards when the Achievement URL is shared to social media platforms, for instance.

In order to sign credentials, the issuer needs to have an associated key referenced from their profile, whether that profile is resolved via a DID or an HTTPS URL. Either a JWT stack using RSA 256 (or RSA with larger key sizes) or an EdDSA stack using a JSON-LD linked data signature must be used to achieve conformance certification as shown below. See Selecting proof methods and crypto algorithms for a detailed discussion on the management of keys and creation of signatures.

An example of a JSON-LD representation of an issuer profile follows, that uses the EdDSA Cryptosuite 2020 option for signing credentials:

{
    "@context": [
        "https://www.w3.org/ns/did/v1",
        "https://www.w3.org/2018/credentials/v1",
        "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
        "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
    "type": "Profile",
    "name": "Example Institution",
    "url": "https://example.com",
    "description": "An example of an educational institution, such as a University",
    "email": "info@example.com",
    "verificationMethod": [{
        "id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774#key-0",
        "type": "Ed25519VerificationKey2020",
        "controller": "https://example.com/issuer/123",
        "publicKeyMultibase": "z6Mkf5rGMoatrSj1f4CyvuHBeXJELe9RPdzo2PKGNCKVtZxP"
    }]
}

Achievement:

As an authorized institutional representative, I can define an Achievement on behalf of my organization, so that I can issue badges recognizing this achievement to learners.

Internally, an Achievement is a database record or document within an issuer system that can be presented using the required and optional properties of the Open Badges Achievement data model. For example, if your app uses a relational database, Achievements would be stored in a database table that has columns for each of the required fields and any supported optional fields. See Achievement Data Model for a listing of fields, noting those with [1] or [1..*] multiplicity are the required ones.

Open Badges Achievements are often associated with images that provide a visual representation of the achievement. Images are optional but are visually prominent components of badges and are often included. OpenBadgeCredentials are issued for many achievementTypes (see enumeration) that may not traditionally include an image, but OB 3.0 now enables this an image to be included for any type of achievement.

For an issuing system that operates a web application on a stable domain, an easy path forward is to select an HTTPS URL as the identifier for each defined Achievement in its database. For example, if the web application under development is running on the domain example.com, an achievement identifier might be https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6. See Publishing achievement definitions for a discussion of options for Achievement identifier. Again, is is best to present a response to requests made to this URL that best matches what the client is requesting, as it indicates with the Accept HTTP header.

  • When a client requests Accept: application/json or application/ld+json or does not include an Accept header, a JSON-LD that includes the OB 3.0 context should be returned.
  • When a client requests Accept: */* or application/html, an HTML representation of the Achievement should be presented. This should express information about the Open Graph meta tags including at least name, description, and image tags for easy rendering of preview cards when the Achievement URL is shared to social media platforms, for instance.

An example of the JSON-LD document that might be fetched from this endpoint follows:

 {
     "@context": "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
     "id": "https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6",
     "type": "",
     "name": "Advanced Shoe Tie",
     "description": "Experts at shoe tying can securely fasten laces with a balanced knot.",
     "achievementType": "Competency",
     "creator": {
         "id": "https://example.com/issuers/540e388e-2735-4c3e-9709-80142801c774",
         "type": "Profile",
         "name": "Example Institution",
         "url": "https://example.com",
         "description": "An example of an educational institution, such as a University",
         "email": "info@example.com"
     },
     "criteria": {
         "narrative": "# Requirements\nShoe tiers must complete..."
     },
     "image": {
         "id": "https://example.com//achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6/image",
         "type": "Image"
     },
     "tag": [
         "research",
         "computer science"
     ]
 }

Note that an image associated with the achievement is hosted at a related URL. This could be alternatively presented as a data URI within the Achievement.

Recipient Identifier:

As a learner, I am assigned a badge recipient identifier or can select one of my choosing.

See Selecting recipient and issuer identifiers for an in-depth discussion on how identifiers may be trusted within software to be associated with organizations or natural persons. A "Self-sovereign identity (SSI)" movement advocates for end user control over the identifiers that refer to users. OB and CLR are compatible with identifiers that support traditional or SSI approaches, including email addresses or student ID numbers on the traditional side and Decentralized Identifiers (DIDs) with varying SSI capabilities.

A workable approach that straddles the divide and can achieve good credential transferability to traditional and new verifiers (credential consumers, such as employers) is to deliver badges that target recipients by human-verifiable means at a minimum but then enable end users to present proof of control of a DID, at which point they may claim a version of the credential signed to that identifier instead.

Implementing this workflow varies for different organizations, depending on what identity management solutions they already use. For example, if an app that enables assessment and award of credentials connects to a Student Information System to gain access to course rosters and the student records in that system each include a student ID number and an email address, that application might choose the email address as the best recipient identifier to use in credentials, because it is easiest for target external consumers of those credentials to verify is associated with an individual. That learner might share their badge on a resume and the hiring manager they send it to can verify it matches them by sending them a six digit code and asking their job applicant to read it back to them.

Recommended options include:

  • If the platform supports integration with a wallet or other system where a learner can present and prove control of an identifier that is usable as a VC or VP issuer identifier, and the user has gone through this process, use their preferred identifier as credentialSubject.id.
  • If the badges will be delivered primarily for URL-based sharing or download, and the user has not presented a DID, do not include a credentialSubject.id property, and instead include an identifier property referencing a known identifier that may be verified by humans or other non-VC, such as an email address.

As an educator, I can assess a learner and trigger the award of an OpenBadgeCredential recognizing that the student has met the criteria of the previously defined Achievement.

Implementing this workflow may look like an educator accessing details about the credential, and then in an "award" section of those details, selecting a student from a roster list and confirming. The result of this action is typically to make a record in the product's database containing the metadata of the award, such as its creation time, the recipient and their identifier, and any other details such as what the educator may have entered in an evidence narrative text box. While it is possible to generate the signature on the credential in order to store it in the system as a signed document at this point, it is not necessary to sign the credential except when delivering it, via download, wallet integration, or OB/CLR REST API.

As a learner, I am notified that I have achieved the Achievement and that I can claim my badge.

Implementing this workflow may look like an email message sent to the recipient with a link into the issuing coordination system.

As a learner, I can access information about my badge in Open Badges 3.0 OpenBadgeCredential format, complete with a reference to my recipient identifier and a cryptographic proof.

Within a notification email, a learner might see a link into the issuing coordination system, where they are offered the chance to authenticate with their organizational single-sign-on (SSO) provider. After successfully authenticating, they can see options to access or share their badge. See recommended practices about sharing badges via URL, but those capabilities might be available within an Open Badges Host platform, not necessarily an issuer coordination app that produces signed OpenBadgeCredentials. Here, the recipient may see a download JSON option, which upon activation yields a signed verifiable credential like the following.

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
        "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "urn:uuid:a9fc82eb-416f-47c3-8786-de890331d4a5",
    "type": [
        "VerifiableCredential",
        "OpenBadgeCredential"
    ],
    "issuer": {
        "id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
        "type": "Profile",
        "name": "Example Institution",
        "url": "https://example.com",
        "description": "An example of an educational institution, such as a University",
        "email": "info@example.com"
    },
    "issuanceDate": "2010-01-01T00:00:00Z",
    "name": "Advanced Shoe Tie",
    "credentialSubject": {
        "type": "AchievementSubject",
        "identifier": {
            "type": "IdentityObject",
            "hashed": true,
            "identityHash": "sha256$658625b25ab3d75d613ca97d9a5a77f70e2192feca5557f4ad09a4d4f121f5fc",
            "identityType": "email",
            "salt": "FleurDeSel"
        },
        "achievement": {
            "id": "https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6",
            "type": "",
            "name": "Advanced Shoe Tie",
            "description": "Experts at shoe tying can securely fasten laces with a balanced knot.",
            "achievementType": "Competency",
            "creator": {
                "id": "https://example.com/issuers/540e388e-2735-4c3e-9709-80142801c774",
                "type": "Profile",
                "name": "Example Institution",
                "url": "https://example.com",
                "description": "An example of an educational institution, such as a University",
                "email": "info@example.com"
            },
            "criteria": {
                "narrative": "# Requirements\nShoe tiers must complete..."
            },
            "image": {
                "id": "https://example.com//achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6/image",
                "type": "Image"
            },
            "tag": [
                "research",
                "computer science"
            ]
        }
    },
    "proof": [{
        "type": "Ed25519Signature2020",
        "created": "2022-12-15T16:56:16Z",
        "verificationMethod": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774#key-0",
        "proofPurpose": "assertionMethod",
        "proofValue": "z4o2Pva6ksbXtCCzHv4VM8Ss9WJg2tnxgDbVwfZr1dq3i2jjzNHWPPpHHRw8s1AknGzL4XjBZVyh3BzSo59qz8NBp"
    }]
}

Several things to note about this credential.

  • There is no primary credential subject ID in this example. The recipient has not yet presented proof of control of a DID, so the credential identifies them by their email address. The identityHash is the SHA-256 hash of the concatenated student email address and credential salt jjefferson18@example.comFleurDeSel. This enables the student to present the credential and their institutional email address to a verifier who can check the hash to ensure the badge belongs to them.
  • The verificationMethod.id identifies the issuer's public signing key using a fragment identifier within the issuer's identifier. This is the same ID that appeared in the representation of the key in the issuer DID document itself.
  • This credential uses the id urn:uuid:a9fc82eb-416f-47c3-8786-de890331d4a5. Some implementers might choose an HTTPS URL on the same domain as the issuer DID Document and the Achievement, but is not assumed that the general public would be able to access data about this credential if they retrieved the id of the document. Other issuers may allow learners to rely on badge backpacks or mobile wallets to provide sharing capabilities that match the use case. See discussion: Sharing badge links to social media.

Follow the steps in the Conformance Certification Guide for the issuer role to submit a downloaded signed credential like the above for conformance checks.

2.3 API quickstart

The API of Open Badges 3.0 and Comprehensive Learner Record 2.0 is divided into four groups, wether the OB / CLR tool is a consumer or a provider of the API and wether the operations it consumes / provides are read operations or write operations.

Note
The API of Open Badges 3.0 and Comprehensive Learner Record 2.0 defines the exchange of credentials and update of the profile between two hosts. The API defines methods for revoking a previously allowed access, which prevents future exchange of credentials. That said, this revocation doesn't affect the already exchanged credentials. Open Badges Credentials and CLR Credentials have its own revocation methods.

Depending of your certification goals it must be necessary to implement one or more of these groups of API. For instance, if you're seeking the certification as an Issuer (not Issuer only) you'll need to implement the service-consumer-write group.

2.3.1 Consumer basics

Consumers of the OB / CLR API must acquire an OAuth 2.0 access token from an authorization server for making API calls. The acquisition of the token implies a set of steps:

Call the ServiceDescription endpoint. Once you know the base url of your authorization server, make a GET call to the well-know getServiceDescription endpoint. The response will contains all the endpoints needed for register your client application (x-imssf-registrationUrl) and acquiring and access token (authorizationUrl, tokenUrl and refreshUrl) with the desired scopes.

Example 1: Sample getServiceDescription request 
GET /ims/ob/v3p0/discovery HTTP/1.1
Host: example.edu
Accept: application/json
Example 2: Sample getServiceDescription response 
HTTP/1.1 200 OK
Content-Type: application/json

...
"components": {
    "securitySchemes": {
        "OAuth2ACG": {
            "type": "oauth2",
            "description": "OAuth 2.0 Authorization Code Grant authorization",
            "x-imssf-name": "Example Provider",
            "x-imssf-privacyPolicyUrl": "provider.example.com/privacy",
            "x-imssf-registrationUrl": "provider.example.com/registration",
            "x-imssf-termsOfServiceUrl": "provider.example.com/terms",
            "flows": {
                "authorizationCode": {
                    "tokenUrl": "provider.example.com/token",
                    "authorizationUrl": "provider.example.com/authorize",
                    "refreshUrl": "provider.example.com/token",
                    "scopes": {
                        "https://purl.imsglobal.org/spec/clr/v2p0/scope/delete" : "...",
                        "https://purl.imsglobal.org/spec/clr/v2p0/scope/readonly" : "...",
                        "https://purl.imsglobal.org/spec/clr/v2p0/scope/replace" : "..."
                    }
                }
            }
        }
    },
    "schemas": {
        ...
    }
}
...

Register your client using OAuth 2.0 Dynamic Client Registration Protocol [RFC7591]. To do that, make a POST call to the endpoint defined in the x-imssf-registrationUrl field from the previous step.

Example 3: Sample registration request 
POST /connect/register HTTP/1.1
Host: auth.1edtech.org
Accept: application/json
Content-Type: application/json; charset=utf-8

{
    "client_name": "Example Client Application",
    "client_uri": "https://client.1edtech.org/",
    "logo_uri": "https://client.1edtech.org/logo.png",
    "tos_uri": "https://client.1edtech.org/terms",
    "policy_uri": "https://client.1edtech.org/privacy",
    "software_id": "c88b6ed8-269e-448e-99be-7e2ff47167d1",
    "software_version": "v4.0.30319",
    "redirect_uris": [
        "https://client.1edtech.org/Authorize"
    ],
    "token_endpoint_auth_method": "client_secret_basic",
    "grant_types": [
        "authorization_code",
        "refresh_token"
    ],
    "response_types": [
        "code"
    ],
    "scope": "https://purl.imsglobal.org/spec/ob/v3p0/scope/delete https://purl.imsglobal.org/spec/ob/v3p0/scope/assertion.readonly https://purl.imsglobal.org/spec/ob/v3p0/scope/replace offline_access"
}

The response object will contain the details needed to perform the OAuth 2.0 Authorization Code Grant flow (client_id, client_secret, among others).

Acquire an access token following OAuth 2.0 Authorization Code Grant flow as described in then IMS Security Framework [SEC-11]. Briefly, it consists in building the authorizationUrl from the url defined in the authorizationUrl field gotten from step one with some query parameters. The use of Proof Key for Code Exchange (PKCE) [RFC7636] is recommended.

Once built, redirect the user to this url in order to start the OAuth 2.0 Authorization Code Grant flow.

Example 4: Sample ACG authorization request (line breaks for clarity) 
HTTP/1.1 302 Found
Location: https://auth.1edtech.org/authorize?
client_id=4ad36680810420ed
&response_type=code
&scope=https%3A%2F%2Fpurl.imsglobal.org%2Fspec%ob%2Fv3p0%2Fscope%2Fassertion.readonly%20offline_access
&redirect_uri=https%3A%2F%client.1edtech.org%2FAuthorize
&state=26357667-94df-4a14-bcb1-f55449ddd98d
&code_challenge=XeDw66i9FLjn7XaecT_xaFyUWWfUub02Kw118n-jbEs
&code_challenge_method=S256

Once the authorization is made, the authorization server will redirect the browser back to the specified redirect_uri with the code, scope, and state query string parameters.

Then, you have to acquire an access token by making a POST request to the tokenUrl gotten from the Service Description endpoint. The HTTP POST request MUST include a Basic authorization header with the client_id and client_secret provided in the registration response. The body of the token request MUST include the following form fields: grant_type, code, redirect_uri, scope and code_verifier.

Example 5: Sample ACG token request (line breaks for clarity) 
POST /token HTTP/1.1
Host: auth.1edtech.org
Authorization: Basic NDE2ZjI1YjhjMWQ5OThlODoxNWQ5MDA4NTk2NDdkZDlm
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
    &code=7c7a73263ee14b2b48073d0615f286ec74f6636689046cb8dbede0b5e87a1338
    &redirect_uri=https%3A%2F%client.1edtech.org%2FAuthorize
    &scope=https%3A%2F%2Fpurl.imsglobal.org%2Fspec%2Fob%2Fv3p0%2Fscope%2Fassertion.readonly+offline_access
    &code_verifier=mYUQfKNgI1lSbY8EqtvNHLPzu0x%2FcVKO3fpWnX4VE5I%3D

The response of this call will contain the access token to use in future calls to the API.

Example 6: Sample ACG token response 
HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, max-age=0
Pragma: no-cache
Content-Type: application/json; charset=UTF-8

{
    "access_token": "863DF0B10F5D432EB2933C2A37CD3135A7BB7B07A68F65D92",
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "https://purl.imsglobal.org/spec/ob/v3p0/scope/assertion.readonly offline_access"
}

2.3.2 User stories for an issuer (API consumer) and host (API provider)

Here are a selection of user stories covering how to add on support for the OB 3.0 API as an Issuer to a simple product after completing the issuer quickstart above. Completing the consumer-side portion of the will potentially qualify a product for conformance certification as an Open Badges Issuer (with API service-consumer-write support). This is a presentation of the experience of using the API from the user's perspective. Additional under-the-hood technical details for each procedure are described in the Specification section 6: Open Badges API.

As a badge holder, I can inform my issuer of my selected Open Badges host service.

Provide the base url or domain of the selected Open Badges host service to the issuer. This could utilize a text input where a user can paste a URL, or a consumer service could add known service providers to a list, presenting the manual input as an advanced option.

As an issuer service, I can discover information about an Open Badges host service.

The service consumer will call the getServiceDescription endpoint from the base url of the Open Badges service provider (host).

As an issuer service, I can register with a Open Badges host service provider.

By performing the OAuth 2.0 Client Dynamic Registration [RFC7591] to the endpoint defined in the x-imssf-registrationUrl field of the Open Badges Host service description.

As a badge holder, I can request and approve a connection between my issuer and my host account.

By following the OAuth 2.0 Authorization Code Grant flow in their browser, following redirects between the issuer and the host service.

As a badge holder, I can select one, some or all OpenBadgeCredentials to transmit to my host account.

A basic service consumer (write) integration would typically push all awarded badges to the host, and a more advanced service consumer may enable users to select a specific scope of credentials for transmission.

As a badge holder, I can see that new badges I am awarded are automatically transmitted to my host, even when I am not interacting with either the issuer or host services directly, if I have configured my issuer to send badges automatically.

As a badge holder, I can deauthorize my issuer from connection to my Open Badges host, so my issuer can't retrieve badges from my Open Badges host no more.

By revoking the access token granted to the issuer from within the Open Badges (service provider) interface.

As a user who has revoked consumer access to my host, I should see the broken connection within the consumer app and be able to initiate reauthorization.

While authenticated with a host service, one action users may take is to view the connected issuer(s) or displayer(s) they have authorized and to revoke some of those approvals. When a user takes this action, it invalidates any access tokens or refresh tokens the connected services, so that those services may no longer access API endpoints on the user's behalf. This should be handled in the issuer or displayer service as a potential expected outcome, after which the service may display an inactive status on the connection and/or prompt the user to reauthorize if they desire to continue sending badges to that host once again.

Your issuer service may discover that your access credentials no longer work as expected when you receive a 401 or 403 status response from the host when attempting to access a protected endpoint and then subsequently receive an error response when attempting token refresh.

2.3.3 Provider basics

The above description of a consumer implementation shows the requests that are made of a provider. This guide does not go into depth about how to accomplish the provider side of these interactions, but the API roughly follows common OAuth patterns for (a) dynamic client registration, authorization code access token grants, and protected resource endpoint access.

  • Provide the ServiceDescription endpoint with the right values for the OAuth2ACG's securitySchema. The urls there must point to your OAuth related endpoints.
  • Allow Registration of clients using Dynamic Registration.
  • Implement OAuth 2.0 Authorization Code Grant flow for granting tokens.
  • Enable access to protected resources to requests authenticated with an appropriately scoped access token.
  • Enable deauthorization of access tokens via user interface. Show a list of authorized applications and their associated access details and enable users to revoke authorizations from the service provider (host).

2.4 Supporting Technical Resources

4. Using Reference Implementations

This section is non-normative.

The Reference Implementation is an 1EdTech implementation of Open Badges 3.0 and Comprehensive Learner Record 2.0 which contains a Issuer, a Displayer and a Host. The reference implementation is written in Java. We provide source code and a hosted version of the tool. Our reference implementation has passed Conformance Certification and is complete with 100% automated tests. Developers can run it locally and develop against this tool. We are working to have this available in multiple languages and common functionality eventually available as libraries. From OB 3.0 and CLR 2.0 on, 1EdTech, with the support of the working group, will be keeping this implementation up-to-date, to have all versions supported.

  • Source Code is a member-only resource.
  • Hosted version will be available to the public, with services being a member-only resource.

5. Conformance and Certification

This section is non-normative.

The [OB-CERT-30] covers the specific requirements that implementers must cover in order to achieve certification for a successful implementation of Open Badges 3.0. An accompanying CLR 2.0 guide is forthcoming. Here is a quick summary of the types of services that can be certified.

5.1 Certified Roles in Open Badges

Services implementing Open Badges fall into one or more ecosystem roles, depending on their relationship to issued credentials. These roles are named "Issuer", "Host", and "Displayer". Issuer services may also add on API support as an additional optional certification level, whereas API support is required for the other two roles. This recognizes that some issuers deliver signed credentials directly to holders via file downloads or potential integrations with wallet

  • Issuer: A product that issues Open Badges and transmits them to learners. Certification as an issuer covers whether a well-formed signed OpenBadgeCredential is produced by the tested product.
    • Optional API support: Issuers can achieve an additional level of certification for Issuer API support if they can demonstrate successful registration with the reference Host system, authorization code grant flow execution for a test user, and transmission of signed Open Badge(s) to the reference Host system by posting them to the Host API.
  • Host: A product implementing the server side of the Open Badges API that holds badges on behalf of data subjects or holders and controls API access to them. The Resource Server responds to automatic registration requests, authorization grant flow initiations, and authenticated resource requests via the API endpoints.
  • Displayer: A product that implements the client side of the Open Badges API. Certification is granted that the product can demonstrate successful registration with the reference Host system, authorization code grant flow execution for a test user, and transmission of signed Open Badge(s) from the reference Host system by making a request for credentials held by a user who completed the authorization flow.

5.2 Certified Roles in CLR

Certified CLR 2.0 services require use of the API in the same roles as Open Badges, except that the credentials transmitted over the API must be ClrCredentials meeting the requirements displayed by the test system. Issuer-only certification without API support is not listed as an option for CLR.

5.3 Conformance Testing Process

Follow the conformance and certification guide listed in the specification for detailed instructions on conformance. A 1EdTech member organization wishing to submit their product for conformance certification will undergo a semi-automated process, following onscreen instructions to run the tests. Then they submit their test results for review by 1EdTech, and if they successfully meet the requirements, the product will appear in the TrustEd Apps Directory, where consumers may find it under filters for each of the implementation roles they are looking for a product to serve.

6. Migrating from OB 2.0, OB 2.1, and CLR 1.0

This section is non-normative.

Open Badges 3.0 and Comprehensive Learner Record 2.0 are major releases, and objects published under these versions are not backwards-compatible

Issuers who use Open Badges 2.0 typically make available standard-compliant endpoints for each Issuer Profile, BadgeClass, and Assertion. In addition to enabling verification of their badge awards, these endpoints often also serve to present human-readable information to clients in HTML when HTML is requested by browsers. Social media networks to which badge awards are shared gather information to display awards from these endpoints as Open Graph Protocol metadata. Exceptions to the pattern of one endpoint per Assertion or BadgeClass occur for implementers who have chosen to use OB 2.0 signed verification for assertions or ephemeral BadgeClass IDs in the urn:uuid namespace.

For any system already using hosted endpoints for these objects, use cases remain within the 3.0 ecosystem to continue that support in addition to delivering these objects compliant with 3.0. In OB 3.0 and CLR 2.0, assertions become OpenBadgeCredentials or AchievementCredentials (an alias), and BadgeClasses become Achievements, which may be more likely to use urn:uuid identifiers. As the ecosystem transitions to support OB 3.0 serialization of these objects, some products will continue to support OB 2.0 representations, so an efficient transition for issuer services likely involves a window of continued support for 2.0 with no breaking changes for clients who rely on it today.

The new OB 3.0 and CLR 2.0 specifications each define APIs over which credentials can be exchanged, from issuers, to holders and then to displayers, but as these standards implement Verifiable Credentials

As portable signed credentials, Open Badges and CLR will take advantage of newly expanded options for both the potential of these credentials to contribute to understanding of skills, qualifications and experience, but also expanded privacy options for learners to control how their data is used and shared. The OB 3.0 and CLR 2.0 releases represent a beginning, but these capabilities will take time and require the launch of new features and new products to deliver on their potential impact. A transition to this generation of specification should be non-destructive but should also move quickly to take advantage of new capabilities.

The recommendations in this guide are intended to identify opportunities for interoperable implementation of of the Open Badges and Comprehensive Learner Record specifications. This serves goals of enabling (a) immediate improvement of last-gen credentials due to next-gen thinking, and (b) gradual technology change.

6.1 How to support both OB 2.0 and OB 3.0 as an Issuer

The quickstart in this implementation guide provides an example implementation using a did:web issuer identifier, HTTPS Achievement identifier, and a urn:uuid in the OpenBadgeCredential. Meanwhile, an issuer may wish to avoid breaking support for OB 2.0 to ensure learners can still use their badges in tools that do not yet support the new version. This is possible and can work elegantly to express the relationships between related objects if a few steps are followed. The same achievement data may be exposed in OB 2.0 and OB 3.0/CLR 2.0 formats. It is not advisable to attempt to publish a combined expression of an entity that is compatible with OB 3.0/CLR 2.0 and the previous version formats, but it is possible to express the relationship between related objects using different IDs for the new versions of these specifications.

For example, a related association may be made within an Achievement and the OB 2.0 equivalent BadgeClass that represents the same achievement. The issuer service does not store the data in two separate formats, but it is capable of serializing the data into the relevant formats when requested at different endpoints. It is a helpful hint to include the IRI of the legacy BadgeClass type (but because the term BadgeClass doesn't appear in the OB 3.0 context and the two contexts are not compatible with one another to be applied to the same document, the full IRI https://w3id.org/openbadges#BadgeClass is used here).

  • There is an existing OB 2.0 endpoint for a BadgeClass at HTTPS id https://example.com/badgeclasses/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6
  • Implement the OB 3.0 serialization at an endpoint https://example.com/achievements/c3c1ea5b-9d6b-416d-ab7f-76da1df3e8d6
  • This example also shows another entry in the related array, to describe a Spanish translation of the achievement, serialized in OB 3.0 Achievement format.

An OB 2.0 related property could be implemented to make the reverse connection from the OB 2.0 BadgeClass:

  • Again, the type IRI is spelled out in full, because Achievement is not defined in the OB 2.0 context.

The issuer profile shown in the quickstart uses a did:web identifier, and the issuer must use an HTTPS identifier for the OB 2.0 hosted profile. Within the 3.0 Profile as embedded in a credential, an otherIdentifier property is described that may be used to link to the 2.0 representation.

Additionally, within the DID Document context, an alsoKnownAs property is available, that may express the HTTPS id of the OB 2.0 representation of the profile.

Example 11: Issuer profile relation between Open Badges 3.0 and Open Badges 2.0 
{
    "@context": [
        "https://www.w3.org/ns/did/v1",
        "https://www.w3.org/2018/credentials/v1",
        "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json",
        "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
    "alsoKnownAs": "https://example.com/issuers/v2p0/540e388e-2735-4c3e-9709-80142801c774",
    "otherIdentifier": [{
        "type": ["IdentifierEntry"],
        "identifier": "https://example.com/issuers/v2p0/540e388e-2735-4c3e-9709-80142801c774",
        "identifierType": "identifier"
    }]
    ...
}

Within the OB 2.0 representation of the issuer, a reverse link may be made with related, as was done with the BadgeClass

Example 12: Issuer profile relation between Open Badges 2.0 and Open Badges 3.0 
{
    "@context": "https://w3id.org/openbadges/v2",
    "id": "hhttps://example.com/issuers/v2p0/540e388e-2735-4c3e-9709-80142801c774",
    "type": "Profile",
    "name": "Example Institution",
    "url": "https://example.com",
    "email": "info@example.com",
    "related": [{
        "type": [
            "https://purl.imsglobal.org/spec/vc/ob/vocab.html#Profile"
        ],
        "id": "did:web:example.com:issuers:540e388e-2735-4c3e-9709-80142801c774",
        "version": "Open Badges v3p0"
    }]
}

6.2 How to migrate from CLR 1.0 to CLR 2.0

There is less of an ecosystem of consumption for CLR 1.0 than for OB 2.0, and the increased complexity of a CLR makes support for multiple versions more expensive than for Open Badges, so it is not likely to be worth the investment to maintain simultaneous serialization of both formats of packaged records. A CLR 2.0 platform that also serves as the issuer for the OpenBadgeCredentials packaged within the ClrCredential may choose to implement the above backwards-compatibility steps for increased visibility and shareability of the individual achievements. At the level of the CLR, it is likely that new consumption products coming on the scene will implement the capability to process CLR in the new 2.0 format rather than the legacy version.

Migrating to CLR 2.0 involves a replacement of endpoints where CLR 1.0 documents were available with the implementation of the CLR 2.0 API. If there are existing clients or relying parties on the CLR 1.0 representations, the best path is to work with those clients to upgrade to 2.0 representations and transfer via API and then remove the 1.0 endpoints once a 2.0 channel has been established.

7. Getting Help

This section is non-normative.

If you have questions or need help with implementing Open Badges 3.0 or Comprehensive Learning Record 2.0, or achieving conformance certification, here are some available resources:

  • Public Forum for all members of the 1EdTech community.
  • Affiliate Forum for Learning Tools and Content Alliance, Affiliate, and Contributing Members.
  • 1EdTech Contributing Members have access to private GitHub repositories and a Slack channel for Digital Credentials Project Group discussions and collaborations. Contact an 1EdTech staff member to gain access.
  • Digital Credentials and Open Badges FAQs If you have a question, an answer may already be waiting. If not, please contact us.

A. Revision History

This section is non-normative.

Version No. Document Version Release Date Comments
Version 3.1 IMS Candidate Final 1 November 10, 2022 Covers Issuer, Displayer, and Host conformance and certification.

B. References

B.1 Normative references

[CASE-10]
IMS Competencies and Academic Standards Exchange (CASE) Service Version 1.0. IMS Global Learning Consortium. July 7, 2017. IMS Final Release. URL: https://www.imsglobal.org/sites/default/files/CASE/casev1p0/information_model/caseservicev1p0_infomodelv1p0.html
[CLR-20]
Comprehensive Learner Record Standard v2.0. 1EdTech. IMS Base Document. URL: https://www.imsglobal.org/spec/clr/v2p0/
[CLR-CERT-20]
Comprehensive Learner Record Conformance and Certification Guide v2.0. 1EdTech. IMS Base Document. URL: https://www.imsglobal.org/spec/clr/v2p0/cert/
[EDUAPI-10]
Edu-API Specification Specification v1.0. 1EdTech. IMS Candidate Final. URL: https://imsglobal.org/spec/eduapi/v1p0/
[LTI-13]
IMS Global Learning Tools Interoperability® Core Specification v1.3. C. Vervoort; N. Mills. IMS Global Learning Consortium. April 2019. IMS Final Release. URL: https://www.imsglobal.org/spec/lti/v1p3/
[OB-30]
Open Badges Specification v3.0. 1EdTech. Candidate Final Public. URL: https://www.imsglobal.org/spec/ob/v3p0/
[OB-CERT-30]
Open Badges Specification Conformance and Certification Guide v3.0. 1EdTech. Candidate Final Public. URL: https://www.imsglobal.org/spec/ob/v3p0/cert/
[OR-11]
1EdTech OneRoster® Specification v1.1. 1EdTech. 1EdTech Final Release. URL: https://www.imsglobal.org/oneroster-v11-final-specification
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[VC-DATA-MODEL]
Verifiable Credentials Data Model v1.1. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog. W3C. 3 March 2022. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model/

B.2 Informative references

[LDS-ED25519-2020]
Ed25519 Signature 2020. W3C Credentials Community Group. Draft Community Group Report. URL: https://w3c-ccg.github.io/lds-ed25519-2020/
[RFC7591]
OAuth 2.0 Dynamic Client Registration Protocol. J. Richer, Ed.; M. Jones; J. Bradley; M. Machulak; P. Hunt. IETF. July 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7591
[RFC7636]
Proof Key for Code Exchange by OAuth Public Clients. N. Sakimura, Ed.; J. Bradley; N. Agarwal. IETF. September 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7636
[SEC-11]
IMS Global Security Framework v1.1. C. Smythe; C. Vervoort; M. McKell. IMS Global Learning Consortium. July 19th, 2021. IMS Final Release. URL: https://www.imsglobal.org/spec/security/v1p1/
[VC-DID-WEB-METHOD]
DID Web Method Specification. Credentials Community Group. CG-DRAFT. URL: https://w3c-ccg.github.io/did-method-web/
[VC-STATUS-2021]
Credential Status List 2021. W3C Credentials Community Group. W3C Editor's Draft. URL: https://w3c.github.io/vc-status-list-2021/
[VCCR-10]
1EdTech Credential Refresh Service. 1EdTech. Candidate Final Public. URL: https://imsglobal.org/spec/vccr/v1p0/
[VCRL-10]
1EdTech Revocation List Status Method. 1EdTech. Candidate Final Public. URL: https://imsglobal.org/spec/vcrl/v1p0/

C. List of Contributors

The following individuals contributed to the development of this document:

Name Organization Role
Nate OttoSkybridge SkillsInvited Expert
Justin PitcherAnthologyCo-chair, OB
Xavi Aracil1EdtechEditor
Rob Coyle1EdtechEditor

1EdTech™ Consortium, Inc. ("1EdTech") is publishing the information contained in this document ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

1EdTech makes no warranty or representation regarding the accuracy or completeness of the Specification.

This material is provided on an "As Is" and "As Available" basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

1EdTech would appreciate receiving your comments and suggestions.

Please contact 1EdTech through our website at www.1edtech.org.

Please refer to Document Name: Open Badges Implementation Guide 3.0

Date: March 1, 2023