Walkthrough

Markus Sabadello edited this page Jan 28, 2015 · 20 revisions
Clone this wiki locally

This is a description and walkthrough for the connector plugin for the XDI2 server that maps personal data from Facebook to XDI.

Scenario

This is a connector plugin for the XDI2 server. It can map personal data from the Facebook Graph API to XDI. This personal data can subsequently be integrated with all features and applications of XDI such as link contracts, $ref relations, cloud cards, etc.

Walkthrough

Step 1: The XDI2 Facebook connector plugin comes with a built-in demo application. The first step is to authorize an XDI graph to access a Facebook account. This involves a standard OAuth 2.0 flow (Authorization Code Grant) to obtain an access token, which is then stored in the user's XDI graph for later use.

From the perspective of the Facebook API, the XDI2 Facebook connector plugin is a client app like any other.


Step 2: During the OAuth 2.0 flow, the user is asked to approve the permissions requested by the XDI2 Facebook connector plugin.


Step 3: Assuming the user approves the permissions, the demo application obtains a valid OAuth 2.0 access token.

The OAuth 2.0 access token as well as the Facebook user ID are stored in the XDI graph as follows:

(https://facebook.com/)[=]!1111/$ref/(https://facebook.com/)[=]!588183713
(https://facebook.com/)[=]!588183713<$oauth><$token>&/&/"....."

Note that there is a $ref equivalence link that relates the user's XDI cloud number to the Facebook user ID.


Step 4: From now on, XDI clients can request attributes in a branch of the XDI graph that is mapped to the user's Facebook account.

Example attributes from Facebook:

(https://facebook.com/)[=]!588183713#(user)<#(email)>&/&/"markus@projectdanube.org"
(https://facebook.com/)[=]!588183713#(user)<#(first_name)>&/&/"Markus"
(https://facebook.com/)[=]!588183713#(user)<#(gender)>&/&/"male"
(https://facebook.com/)[=]!588183713#(user)<#(last_name)>&/&/"Sabadello"

Step 5: The Facebook OAuth 2.0 access token may be revoked. At this point it is also deleted from the user's XDI graph.


Step 6: Besides using the built-in demo application that comes with the XDI2 Facebook connector plugin, the Cloud Manager (source) application can also be used to request and revoke Facebook OAuth 2.0 access tokens.


Step 7: The functionality of connectors becomes especially interesting when combined with Cloud Cards and other XDI applications. For example, it is possible to use $ref relations to link an attribute on a Cloud Card to a corresponding Facebook attribute.

In a "normal" Cloud Card, the attributes on the card are simply stored in the XDI graph itself. In this case however, the "first name" and "last name" attributes on the =peacekeeper#facebook Cloud Card are linked to their corresponding attributes in the user's Facebook account.

Example attributes on the Cloud Card:

[=]!:uuid:f3e998b9-dfef-49b9-9f44-0b8a98e31a1f[$card]!:uuid:ff98ec9f-6571-4282-b577-2c402a1a8c02$public<#first><#name>&/$ref/(https://facebook.com/)[=]!588183713#(user)<#(first_name)>&
[=]!:uuid:f3e998b9-dfef-49b9-9f44-0b8a98e31a1f[$card]!:uuid:ff98ec9f-6571-4282-b577-2c402a1a8c02$public<#last><#name>&/$ref/(https://facebook.com/)[=]!588183713#(user)<#(last_name)>&

Step 8: The Cloud Card can be accessed by a visitor using the web-based Cloud Card Viewer (source). The attributes on the Cloud Card come from the user's Facebook account rather than being stored in the XDI graph itself.

Depending on whether $ref or $rep equivalence links are used in the XDI graph, the fact that attributes on the Cloud Card come from Facebook may or may not be transparent to an XDI client.

In this case, all attributes are public, i.e. can be viewed without a link contract. If they were private, an XDI Connect flow would be needed to initiate a connection request to the Cloud Card and establish a link contract.


Step 9: The Cloud Card may also be viewed by the XDI Ninja! browser plugin (source) browser plugin. Again, the attributes on the Cloud Card come from the user's Facebook account rather than being stored in the XDI graph itself.


Step 10: Since the XDI Ninja! browser plugin periodically checks cloud cards for updates, a popup window would appear if a Facebook attribute in the Cloud Card changes.

Sequence Diagram 1

Obtaining a Facebook OAuth 2.0 access token:

websequencediagrams-xdi-get-request-handled-by-facebookcontributor.png

Source: websequencediagrams-obtaining-facebook-oauth-access-token.txt

Sequence Diagram 2

Requesting attributes in a branch of the XDI graph that is mapped to the user's Facebook account:

websequencediagrams-xdi-get-request-handled-by-facebookcontributor.png

Source: websequencediagrams-xdi-get-request-handled-by-facebookcontributor.txt