[draft] Backpack Connect

Backpack Connect

Note: if you're an issuer, you may find the issuer documentation more helpful than this page.

For background, see #140.

Glossary

• RequestClient is the server or application that wants to use Backpack Connect.

• UserAgent is the user's Web browser.

• Intermediary is an as-of-yet unspecified intermediary that takes care of determining where the user's backpack is. Ultimately this might be a trusted website, or it could even be something built-in to the user's browser. For now, the intermediary is openbadges.org. For more information and discussion on this, see Brian's servicefederation gist.

• Backpack is the user's backpack.

Connecting

• [RequestClient → UserAgent] Initiate connection request

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

• [Intermediary] Discover user's backpack: https://backpack.openbadges.org

• [Intermediary] Discover backpack connect page: https://backpack.openbadges.org/access

• [Intermediary → UserAgent] Redirect to
  https://backpack.openbadges.org/access?callback=https%3A%2F%2Fexample.org%2Fcallback&scope=issue

• [Backpack] Ask user to sign in if they aren't already

  • At this point, the user should see a screen that looks something like this recent mockup:

• [Backpack] Confirm user grants issue permission to http://example.org (origin derived from callback)

• [Backpack] Generate & store access token, refresh token:

// represent this structure in the database somehow

{ user: "brian@mozillafoundation.org",
  origin: "https://example.org",
  permissions: ["issue"]
  accessToken: "qTVrO12y7ucEO5Jz8kYRP2G2",
  accessTimestamp: 1360362764
  refreshToken: "7UiDj13BjhQ5kXxqn/V45t87",
}

• [Backpack → UserAgent] Transfer tokens by redirecting the user's browser to the client callback URL at
  https://example.org/callback?access_token=qTVrO12y7ucEO5Jz8kYRP2G2&expires=3600&refresh_token=7UiDj13BjhQ5kXxqn&api_root=https%3A%2F%2Fbackpack.openbadges.org%2Fapi.

  • Note that this requires both client and backpack to operate over SSL, as eavesdropping/MITM can occur otherwise.
  • UserAgent is used for redirection to support cases where the client server is unreachable from the internet, e.g. behind a corporate firewall.

Making an authenticated request

• [RequestClient → Backpack] POST to issue endpoint. access_token should be Base64 encoded and included in the Authorization header.

POST /api/issue HTTP/1.1
Host: backpack.openbadges.org
Authorization: Bearer cVRWck8xMnk3dWNFTzVKejhrWVJQMkcy
Content-Type: application/json

{ "badge": <badge data> }

• [Backpack] Confirm token hasn't expired. If it has, respond with 401

  • If it has, respond with 401

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

• [Backpack] Award badge to user associated with the access token.
• [Backpack → RequestClient] Respond with success

Refreshing a token

• [RequestClient → Backpack] POST to token at the api_root. Note, Authorization header is not used here.

POST /api/token HTTP/1.1
Host: backpack.openbadges.org
Content-Type: application/json

{ "grant_type": "refresh_token",
  "refresh_token": "7UiDj13BjhQ5kXxqn/V45t87"
}

Further Reading

RFC6750: Bearer Token Usage. Even though we are not using the OAuth 2.0 Authorization Framework, we are using the equivalent of bearer tokens and as far as I can tell it makes sense to follow the OAuth 2.0 spec for them.