Page Comparison

}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
* 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 web-based location application called *HotLocale* (H) that is a Host of a location resource 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, H, 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, H, 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 H uses a hypothetical standard location API that R1 and R2 are configured to understand, and that H exposes an API 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.

# H asks Alice to choose an AM to protect her location information in H
# Alice tells H her preferred AM
# H 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 H'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?_)
# Alice is redirected back to H to continue what she was doing before

{html}
<div class=wsd wsd_style="default"><pre>
Alice/browser->H: Visit and log in
Alice/browser->H: Introduce to chosen AM to protect location info
H->AM: Discover how to register and use AM
H->Alice/browser: Redirect to AM...
Alice/browser->AM: ...to log in, consent to introduction, set policies
AM->Alice/browser: Redirect back to H...
Alice/browser->H: ...with access token to continue using H
</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 H and logs in as Alice-on-H
# Alice decides to share access to her location information in H with R1 (if UC1 has not been done, it must be done at this time)
# Alice asks H 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 H and asks it to set up access to her location information there
# R1 attempts to access the URL and discovers H uses a location API that R1 understands
# H 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
# The 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: Visit and log in
opt
  note over Alice/browser, H, AM: Alice does H/AM introduction as in UC1
end
H->Alice/browser: Supply "share" URL for use at Requesters
Alice/browser->R1: Visit and log in
Alice/browser->R1: Give "share" URL
R1->H: Attempts access and discovers H's API information
H->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, 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

@@