Walkthrough

Markus Sabadello edited this page Nov 6, 2016 · 17 revisions
Clone this wiki locally

This is a description and walkthrough for the +leshop XDI2 demo.

Scenario

A business requesting authority (RA) issues a "connection request" to request a link contract for reading an email address from an individual authorizing authority (AA). This happens via an "XDI Connect" button on a webpage.

RA: +leshop / [+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87
AA: =markus / [=]!:uuid:91f28153-f600-ae24-91f2-8153f600ae24

Walkthrough

Step 1: The user (AA) views the RA's website in their browser.

The website has an "XDI Connect" button, which contains an XDI connection request. The purpose of the XDI connection request is to ask the AA to establish a new XDI link contract in the AA's XDI Cloud. The XDI link contract will allow $get operations on an e-mail address.

The user clicks the "XDI Connect" button.

The XDI connection request embedded in the "XDI Connect" button:

[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87[$msg]@0/$is()/({$to})
[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87[$msg]@0/$do/({$to}/[+]!:uuid:ca51aeb9-e09e-4305-89d7-87a944a1e1fa)[+]!:uuid:ca51aeb9-e09e-4305-89d7-87a944a1e1fa#community$do
[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87[$msg]@0$do/$do{}/[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87#newsletter{$do}
[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87[$msg]@0<#return><$uri>&/&/"https://leshop.xdi2.org/leshop-return"
[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87[$msg]@0<$sig>/$is#/$sha$256$rsa$2048
[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87[$msg]@0<$sig>&/&/"....."

Return URI of the RA:

https://leshop.xdi2.org/leshop-return

Address of the XDI link contract template:

[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87#newsletter{$do}

Address of the AA's XDI community link contract:

({$to}/[+]!:uuid:ca51aeb9-e09e-4305-89d7-87a944a1e1fa)[+]!:uuid:ca51aeb9-e09e-4305-89d7-87a944a1e1fa#community$do

XDI link contract template:

[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87#newsletter{$do}/$get/{$to}<#email>
([+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87#newsletter{$do}$if$and/$true){$from}/$is/[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87
([+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87#newsletter{$do}$if$and/$true){$msg}<$sig><$valid>&/&/true

Step 2: After clicking the "XDI Connect" button, the XDI connection request is submitted to the XDI Connect Service.

The sole purpose of this service is to find the user's XDI Auth Service. This intermediate step is necessary because XDI cloud names and cloud numbers are abstract identifiers that rely on a Discovery Service.

Possible alternatives to the XDI Connect Service may be: 1. Using an XDI-aware browser plugin to intercept the "XDI Connect" button, or 2. Using client-side JavaScript to fulfill the same purpose as the XDI Connect Service.

The user types their cloud name and clicks the "Continue" button. A cookie can be set to omit this step in subsequent flows.


Step 3: After clicking the "Continue" button, the XDI Connect Service discovers the user's XDI Auth Service. This is the component of the user's XDI Cloud responsible for processing XDI connection requests.

The user clicks the "Continue to your Personal Cloud" button. Note that in a production environment, steps 2 and 3 can be combined for better user experience.


Step 4: After clicking the "Continue to your Personal Cloud" button, the XDI connection request is submitted to the user's XDI Auth Service.

At this point, the user is asked to authenticate to their XDI Auth Service, before the XDI connection request can be processed.

The user types their password and clicks the "Continue" button. Additional authentication options may be possible depending on the configuration of the XDI Auth Service. A cookie can be set to omit this step in subsequent flows.


Step 5: After clicking the "Continue" button, the XDI Auth Service examines the XDI connection request and retrieves the XDI link contract template it references.

The details of the XDI connection request are presented to the user, who is asked to approve or reject it. An arrow on the screen indicates that personal data will flow from the user (AA) to the RA's website.

Note that this demo does not show certain advanced features of XDI, such as optional permissions or usage policies.


Step 6: Assuming the user approves, the XDI connection request is sent to their XDI Cloud, where a new XDI link contract is instantiated, based on the XDI link contract template.

A confirmation page is displayed. The confirmation page has a "Return to +leshop Website" button, which contains an XDI connection result. The purpose of the XDI connection result is to return to the RA's website the address of the new link contract instance.

The user clicks the "Return to +leshop Website" button.

The XDI connection result embedded in the "Return to +leshop Website" button:

[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87#newsletter{$do}/#/([=]!:uuid:91f28153-f600-ae24-91f2-8153f600ae24/[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87)[+]!:uuid:843085a3-0136-4bbb-b0a6-2f0e8d091c87#newsletter$do

Step 7: After clicking the "Return to +leshop Website" button, the XDI connection result is submitted to the RA's website.

The RA's website examines and validates the XDI connection result. It contains the address of the new XDI link contract, which the RA can use to retrieve the user's e-mail address.

A confirmation page is displayed. This constitutes the end of the XDI Connect flow.


Step 8: This is an "internal view" of the RA's website. It lists the most recent successful XDI Connect flows, and the users' e-mail addresses.


Step 9: After completing the XDI Connect flow, the AA may log in to their Cloud Manager (source) and view the XDI link contract that has been instantiated.


Step 10: In the Cloud Manager, the user may also change their e-mail address.


Step 11: The "internal view" of the RA's website always shows the users' current e-mail addresses. In this demo, no caching or notification service is implemented.


Step 12: In the Cloud Manager, the user may also delete the XDI link contract that has been instantiated.


Step 13: The "internal view" of the RA's website displays an error if a user's e-mail address cannot be retrieved.

Sequence Diagram

websequencediagrams.png

Source: websequencediagrams.txt