Page Comparison

----
h1. {anchor:location_scenario}Scenario: Controlling Two-Way Sharing of Location Information (Pending)

*Submitted by:* Eve Maler

h4. Actors

* Authorizing user Alice, who chooses to set and share her current location through various applications that she accesses with a commercial off-the-shelf browser
* An application that serves as an *Authorization Manager* (AM) on Alice's behalf, orchestrating which location applications can write to and read from other applications
* A webWeb-based location applicationapplications called *HotLocale* (HH1) and *HipHappeningPlace (H2) that isare a HostHosts of a location resourceinformation on Alice's behalf
* Web-based location applications called *RovingAround* (R1) and *RoadWarrior* (R2) that are Requesters of location information on Alice's behalf

h4. Short Description

Today's location services such as FireEagle, BrightKite, and Dopplr let Alice set her location within any one of several applications, and then use OAuth-enabled connections to propagate that information through other such services.  Since Alice can end up "chaining" services this way quite easily, with a thicket of pairwise connections, it's valuable for her to know and control where this information is flowing to.  In this scenario, a user of HotLocale and RovingRound wants to arrange to connect them up so that her location can be propagated among them, and she wants to get a global view through her AM about who's allowed to do what, so she can change and stop permissions in a coordinated way.

*Note:* This scenario is not exploring anything other than person-to-self sharing.  How Alice exposes her location to other people and companies should be the subject of a different scenario, as warranted.

h4. Dimensions

| *Nature of protected resource* | API endpoint.  For example, see the [FireEagle developer documentation|http://fireeagle.yahoo.net/developer/documentation/calling_the_api].  The resource being protected is a single endpoint URL, with different options and parameters possible for using it. The possible scopes in today's location services tend to include (a) whether the requesting app (client) can write the user's location, and (b) to what degree the client can read the user's location.  For example, see the [FireEagle scope permissions documentation|http://fireeagle.yahoo.net/developer/documentation/location]; the location-reading options include: no read access, as precise as possible, postal code level, neighborhood level, town level, regional level, state level, and country level. |
| *Sharing models* | Current OAuth-protected usage of location services such as FireEagle and BrightKite assumes a *person-to-self* sharing model, where Alice has login accounts at the various host and requester apps, and wants to instruct them to share her location among themselves on her own behalf; an UMA-enabled version of this would allow her to control such sharing centrally at her AM. |
| *Nature of policies and claims* | For person-to-self sharing, a typical policy might require the requesting party to be able to authenticate as Alice directly at the AM (that is, dictating a particular Step 2 web-server flow that uses normal OAuth user authentication), or might require a claim that it is an authenticated Alice asking for forge the connection. Further, a policy might set (unilateral) boundaries on which scopes can be accessed. |
| *Cardinality* | This scenario is 1:1. There is no need to aggregate multiple resources from multiple hosts, for example. | 
| *Colocation* | The same requester app might both read and write location data (by using different methods with the same API endpoint), which allows it to _write_ data to a host while still remaining a _requester_ (think "requester of API access"). With today's OAuth-enabled location services, the services act relatively "peer"-ish, in that they have each done the necessary integration to support any one of them serving as an initial host with the others being requesters. So it could be said that the same app might be a host for some users and a requester for others, and/or might be set up as both a host and a requester for the same user's location; however, the latter may be very confusing given current OAuth realities. | 
| *Host-AM relationship* | Today's OAuth-enabled apps require static introduction and configuration, but the light weight and low security of these Web 2.0 services suggest that dynamic introduction is a possibility as long as the location API is well-known/standardized. |
| *Protected resource discovery* | Today's OAuth-enabled apps advertise this location in the process of static introduction and configuration, but with a well-known/standardized location API, it seems possible that a location service host could advertise its endpoint through dynamic means such hostmeta/XRD. | 

h4. Scope Detail

Below is a screenshot showing that FireEagle and Dopplr have the capability today to have two-way location information flow.  Our user wants to be able to see this "combinatorily", for all connected location services and indeed for all such services on the web that she chooses to use for hosting any data or content.

!fireeagle-dopplr.png!

h4. Assumptions and Preconditions

This scenario assumes that Alice has an account at each of AM, H1, HH2, R1, and R2.  These accounts might or might not be driven off of federated login, for example, Alice might log in to HotLocale through Google and RoadWarrior through Facebook.

This scenario assumes that AM, HH1, H2, R1, and R2 are all UMA-enabled but have otherwise not met before.  (Simplified circumstances that assume prior introduction are described in their turn below.)

This scenario assumes that HH1 usesand H2 use a hypothetical standard location API that R1 and R2 are configured to understand, and that H1 Hand exposesH2 anexpose APIAPIs through URLs that differ per user in some fashion (e.g., through a URL query parameter or through a part of the URL path).

h2. Use Case 1: Alice Sets Up AM Protection Over Location Information at HotLocale

This flow can be embedded in other flows, or can be standalone.

# HH1 asks Alice to choose an AM to protect her location information in HH1
# Alice tells HH1 her preferred AM
# HH1 discovers how to get started connecting to the AM
# Alice is redirected to AM to log in as Alice-on-AM, consent to protection, and choose a policy that applies to HH1's endpoint for her
** The policy indicates that the requesting party must accept her chosen scope of access, which is "write, read-city"
** The policy indicates that the requesting party must be able to log in at the AM synchronously as Alice-on-AM and consent
** The policy does not otherwise discriminate against particular Requester apps (_note that we don't currently have a way to do this; do we need to?_)
** She labels the policy "location services policy" (outside the scope of the UMA protocol)
# Alice is redirected back to HH1 to continue what she was doing before

The identical sequence can be done with HipHappeningPlaces (H2).


{html}
<div class=wsd wsd_style="default"><pre>
Alice/browser->H>H1: Visit and log in
Alice/browser->H>H1: Introduce to chosen AM to protect location info
HH1->AM: Discover how to register and use AM
HH1->Alice/browser: Redirect to AM...
Alice/browser->AM: ...to log in, consent to introduction, set policies
AM->Alice/browser: Redirect back to HH1...
Alice/browser->H>H1: ...with access token to continue using HH1
</pre></div><script type="text/javascript" src="http://www.websequencediagrams.com/service.js"></script>
{html}

h2. Use Case 2: Alice Shares HotLocale Location Access with RovingAround and RoadWarrior

# Alice visits HH1 and logs in as Alice-on-HH1
# Alice decides to share access to her location information in HH1 with R1 (if use case UC1#1 has not been done, it must be done at this time)
# Alice asks HH1 to give her a "share" URL to use
# Alice visits R1 and logs in as Alice-on-R1
# Alice gives R1 the "share" URL from HH1 and asks it to set up access to her location information there
# R1 attempts to access the URL and discovers HH1 uses a location API that R1 understands
# HH1 redirects R1 to the AM as unauthorized
# The AM tells R1 it needs to provide a claim acknowledging the offered scope (_need to standardize this claim request/response_)
# R1 sends the claim #to TheAM
# AM tells R1 it needs to redirect its user (Alice) to the AM to authenticate (_add this as a special indicator/claim request to the protocol?_)
# R1 redirects Alice to the AM to authenticate and consent
# The AM concludes that Alice authenticated correctly as Alice-on-AM
# The AM issues an access token to R1 for location information access of the offered/accepted scope and redirects Alice back

{html}
<div class=wsd wsd_style="default"><pre>
Alice/browser->H>H1: Visit and log in
opt
  note over Alice/browser, HH1, AM: Alice does H/AM introduction as in UC1
end
HH1->Alice/browser: Supply "share" URL for use at Requesters
Alice/browser->R1: Visit and log in
Alice/browser->R1: Give "share" URL
R1->H>H1: Attempts access and discovers H's H1 uses an API informationR1 knows
HH1->R1: Redirect unauthorized requester to AM...
R1->AM: ...to get access token
AM->R1: Request claim acknowledging offered scope
R1->AM: Acknowledge offered scope
AM->R1: Request redirection of requesting user to AM
R1->Alice/browser: Redirect to AM...
Alice/browser->AM: ...to log in and consent
AM->AM: confirms correct authn
AM->Alice/browser: Redirect back to R1...
Alice/browser->R1: ...with access token
</pre></div><script type="text/javascript" src="http://www.websequencediagrams.com/service.js"></script>
{html}

The identical sequence can be done with RoadWarrior (R2), except that once HotLocale is introduced to the AM, it never needs to be introduced again, so the optional embedded UC1 block isn't ever done again unless Alice wants to switch AMs.

h2. Use Case 3: Alice Monitors Location Information Access from Her AM

This use case involves Alice interacting 
@@with value-added functionality provided at the "data-sharing relationship manager" application that serves as her AM endpoint; that is, this use case does not involve standardized UMA protocol behavior.  These interactions may include:

* Looking at a unified log for occasions when both RovingAround and RoadWarrior accessed HotLocale on her behalf, and what they did on those occasions
* Looking at a unified log for occasions when RovingAround accessed both HotLocale and Alice's calendar application (not part of this scenario) on her behalf
* Looking at a unified log for all hosts to whose resources she applied her "location services policy", including both HotLocale and HipHappeningPlaces

If the relationship manager application has special knowledge about the resources it is protecting, it may offer advanced functionality, such as:

* Showing a graph of location host and requester access relationships and their types