Backpack Connect: Issuer Documentation

Backpack Connect: Issuer Documentation

Overview

Backpack Connect is an API, inspired by OAuth 2, which makes it possible for badge issuers to establish a persistent session with a user's backpack and perform actions on their behalf. Permissions can vary based on the authority granted by the user.

This is in contrast to the standard Issuer API, which doesn't maintain a persistent session, and thus requires the user's permission every time an issuer wants to push a badge to their backpack.

Federation

Note that, unlike a traditional OAuth model, we are planning for a world in which a user's backpack may be completely unknown to an issuer. For example, while Mozilla hosts a backpack at backpack.openbadges.org, it will eventually be one of many potential backpacks that can exist.

However, because backpack federation isn't yet implemented, Backpack Connect has a few workarounds to make it possible for us to "upgrade" to a federated world in the future, without forcing issuers to change things on their end.

Security

While not enforced, we strongly recommend that issuers host their websites over HTTPS. This is the only way to ensure that authorization credentials remain confidential.

Cross-Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests. You can read the CORS W3C working draft or the MDN HTTP Access Control page for more information.

Parameters

All POST requests should encode their parameters as JSON with a Content-Type of application/json.

Web Application Authorization Flow

The following example assumes that your website is located at https://issuer.org and wants to issue badges to a user, which requires the issue permission.

1. Include the Issuer API script in your site

First, include the Issuer API script in a webpage on your site:

<script src="https://beta.openbadges.org/issuer.js"></script>

2. Call OpenBadges.connect() to request access

When a user decides to connect your website to their backpack, you should call the OpenBadge.connect() function:

  OpenBadges.connect({
    callback: "https://issuer.org/callback",
    scope: ['issue']
  });

At this point, the user is redirected to their backpack, where they are asked if issuer.org should have permission to access their backpack.

3. The backpack redirects back to your site

Once the user has submitted their decision, their browser is redirected to https://issuer.org/callback with the following GET parameters:

• error - If the user denied the issuer access to their backpack, this will be set to access_denied.
• access_token - A string that can be used to access the user's backpack.
• refresh_token - A string that can be used to obtain a new access token whenever it expires.
• expires - The number of seconds that the access token is valid before it needs to be refreshed.
• api_root - The absolute URL pointing to the root of the user's backpack connect API endpoint. Note that this won't necessarily point to the openbadges.org domain, since a user's backpack may be located anywhere on the Web.

4. Use the access token to access the API

Unless otherwise specified, all backpack connect API endpoints require authentication, which is done via the Authorization HTTP header. Its value should be set to Bearer b64_access_token, where b64_access_token is the Base64 encoding of your access token.

For example, if your access token is 123456, the value of the header should be Bearer MTIzNDU2.

Refreshing Tokens

The access token is very short-lived. Eventually, you may make a request to the API with the following response:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="backpack",
                  error="invalid_token",
                  error_description="The access token expired"

To refresh the token, you should send a POST request to api_root/token with the following parameters:

• grant_type - This should be refresh_token, to indicate that you want to refresh your token.
• refresh_token - This should be the value of your refresh token.

The JSON response will contain the following keys:

• expires - The number of seconds that the access token is valid before it needs to be refreshed.
• access_token - A new access token.
• refresh_token - A new refresh token.

This API endpoint does not require the Authorization HTTP header.

Issuing Badges

Just send a POST request to api_root/issue with the badge parameter set to the absolute URL of your hosted assertion.

Obtaining Identity Information

You can send a GET request to the /api/identity endpoint to retrieve information about the user's hashed email address, which can be used to issue badges to the user even if you don't know their email address. This endpoint returns a JSON response with the following keys:

• recipient - Salted hash of the user's email address. Takes this form: <algorithm>$<hash(email + salt)>.
• salt - The salt used in the above hash construction.

As you may have guessed, these return values come ready to be inserted into a standard badge assertion.

Troubleshooting

Here are some tips to help you troubleshoot:

• When issuing, make sure your badge parameter is the URL of your BadgeAssertion object, not your BadgeClass object.
• Try validating your assertion object in the validator to see if there's a formatting problem.
• Check that the IssuerOrganization's URL property has the same origin as the domain for which your users approve access.