Skip to content

Commit

Permalink
mention group accounts as well as single-user accounts
Browse files Browse the repository at this point in the history
  • Loading branch information
@michielbdejong
michielbdejong committed Dec 10, 2014
1 parent c74bc6e commit a3e261d
Show file tree
Hide file tree
Showing 3 changed files with 75 additions and 74 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
* Servers may now offer any extension features they want.
* Several mistakes in the text and wire examples were fixed.
* Several confusing formulations in the text were improved.
* Mention "group accounts", to which multiple human users have access.

# draft-dejong-remotestorage-03.txt

Expand Down
96 changes: 48 additions & 48 deletions draft-dejong-remotestorage-04.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,17 +72,17 @@ Table of Contents
12.1. WebFinger................................................12
12.2. OAuth dialog form........................................13
12.3. OAuth dialog form submission.............................14
12.4. OPTIONS preflight........................................14
12.4. OPTIONS preflight........................................15
12.5. Initial PUT..............................................15
12.6. Subsequent PUT...........................................15
12.6. Subsequent PUT...........................................16
12.7. GET......................................................16
12.8. DELETE...................................................17
13. Distributed versioning........................................17
14. Security Considerations.......................................19
15. IANA Considerations...........................................20
16. Acknowledgments...............................................20
17. References....................................................20
17.1. Normative References.....................................20
17. References....................................................21
17.1. Normative References.....................................21
17.2. Informative References...................................21
18. Authors' addresses............................................22

Expand Down Expand Up @@ -147,15 +147,14 @@ Internet-Draft remoteStorage December 2014
* content type
* content length


For a document, the server stores, and should be able to produce:


de Jong [Page 3]

Internet-Draft remoteStorage December 2014


For a document, the server stores, and should be able to produce:

* current version
* content type
Expand Down Expand Up @@ -198,14 +197,14 @@ Internet-Draft remoteStorage December 2014
that content length is measured in octets (bytes), not in
characters.

A folder description is a map containing a string-valued 'ETag'


de Jong [Page 4]

Internet-Draft remoteStorage December 2014


A folder description is a map containing a string-valued 'ETag'
field, representing the folder's current version.

A successful GET request to a folder MUST be responded to with a
Expand Down Expand Up @@ -248,14 +247,14 @@ Internet-Draft remoteStorage December 2014
the full document contents in the body, the document's content type
in a 'Content-Type' header, its content length in octets (not in
characters) in a 'Content-Length' header, and the document's current
version as a strong ETag in an 'ETag' header.


de Jong [Page 5]

Internet-Draft remoteStorage December 2014


version as a strong ETag in an 'ETag' header.

Note that the use of strong ETags prohibits changing the response
body based on request headers; in particular, the server will not be
Expand Down Expand Up @@ -300,6 +299,7 @@ Internet-Draft remoteStorage December 2014




de Jong [Page 6]

Internet-Draft remoteStorage December 2014
Expand Down Expand Up @@ -329,7 +329,7 @@ Internet-Draft remoteStorage December 2014
existing folder's name at the same level.
* 412 for a conditional PUT or DELETE request whose pre-condition
fails (see "Versioning" below),
* 507 in case the user's account is over its storage quota,
* 507 in case the account is over its storage quota,
* 4xx for all malformed requests (e.g. foreign characters in the
path), as well as for all PUT and DELETE requests to
folders,
Expand Down Expand Up @@ -459,8 +459,9 @@ Internet-Draft remoteStorage December 2014
10. Application-first bearer token issuance

To make a remoteStorage server available as 'the remoteStorage of
<user> at <host>', exactly one link of the following format SHOULD
be added to the WebFinger record [WEBFINGER] of <user> at <host>:
<account> at <host>', exactly one link of the following format
SHOULD be added to the WebFinger record [WEBFINGER] of <account> at
<host>:

{
"href": <storage_root>,
Expand All @@ -478,9 +479,11 @@ Internet-Draft remoteStorage December 2014
presented.

If <auth-dialog> is a URL, the user can supply their credentials
there (how, is out of scope), and allow or reject a request by the
connecting application to obtain a bearer token for a certain list
of access scopes.
for accessing the account (how, is out of scope), and allow or
reject a request by the connecting application to obtain a bearer
token for a certain list of access scopes. Note that an account
will often belong to just one human user, but may also belong to a
group of multiple users (the remoteStorage of <group> at <host>).

If <auth-dialog> is null, the client will not have a way to obtain
an access token, and SHOULD send all requests without Authorization
Expand All @@ -496,15 +499,15 @@ Internet-Draft remoteStorage December 2014
token in the URI query parameter as per section 2.3 of [BEARER],
instead of in the request header.

Another example is "http://tools.ietf.org/html/rfc7233" with a
string value of "GET" if Content-Range headers are supported for


de Jong [Page 10]

Internet-Draft remoteStorage December 2014



Another example is "http://tools.ietf.org/html/rfc7233" with a
string value of "GET" if Content-Range headers are supported for
GET requests as per [RANGE], "PUT" if they are supported for PUT
requests, and "GET,PUT" if supported for both.

Expand All @@ -528,7 +531,6 @@ Internet-Draft remoteStorage December 2014
client_id parameter in favor of relying on the redirect_uri
parameter for client identification.


11. Storage-first bearer token issuance

The provider MAY also present a dashboard to the user, where they
Expand All @@ -546,21 +548,22 @@ Internet-Draft remoteStorage December 2014
When the user gestures they want to use a certain application whose
manifest is present on the dashboard, the dashboard SHOULD redirect
to the application or open it in a new window. To mimic coming back
from the OAuth dialog, it MAY add 'access_token' and 'scope'
fields to the URL fragment.


de Jong [Page 11]

Internet-Draft remoteStorage December 2014


from the OAuth dialog, it MAY add 'access_token' and 'scope'
fields to the URL fragment.

Regardless of whether 'access_token' and 'scope' are specified, it
SHOULD add a 'remotestorage' field to the URL fragment, with a
value of the form <user> '@' <host>. When the application detects
this parameter, it SHOULD resolve the WebFinger record for <user> at
<host> and extract the <storage_root> and <storage_api> information.
value of the form <account> '@' <host>. When the application detects
this parameter, it SHOULD resolve the WebFinger record for <account>
at <host> and extract the <storage_root> and <storage_api>
information.

If no access_token was given, then the application SHOULD also
extract the <auth_endpoint> information from WebFinger, and continue
Expand All @@ -569,10 +572,10 @@ Internet-Draft remoteStorage December 2014
Note that whereas a remoteStorage server SHOULD offer support for
the application-first flow with WebFinger and OAuth, it MAY choose
not to support the storage-first flow, provided that users will
easily remember their <user> '@' <host> WebFinger address at that
easily remember their <account> '@' <host> WebFinger address at that
provider. Applications SHOULD, however, support both flows, which
means checking the URL for a 'remotestorage' parameter, but giving
the user a way to specify their WebFinger address if there is none.
the user a way to specify the WebFinger address if there is none.

If a server provides an application manifest dashboard, then it
SHOULD merge the list of applications there with the list of
Expand All @@ -596,15 +599,15 @@ Internet-Draft remoteStorage December 2014
In application-first, an in-browser application might issue the
following request, using XMLHttpRequest and CORS:

GET /.well-known/webfinger?resource=acct:michiel@michielbdejon\
g.com HTTP/1.1


de Jong [Page 12]

Internet-Draft remoteStorage December 2014



GET /.well-known/webfinger?resource=acct:michiel@michielbdejon\
g.com HTTP/1.1
Host: michielbdejong.com

and the server's response might look like this:
Expand Down Expand Up @@ -644,17 +647,17 @@ motestorage-04",
end-point, it will typically redirect the user to this URL, in
order to obtain a bearer token. Say the application is hosted on
https://drinks-unhosted.5apps.com/ and wants read-write access to
the user's "myfavoritedrinks" scope:

GET /oauth/michiel?redirect_uri=https%3A%2F%2Fdrinks-unhosted.5\
apps.com%2F&scope=myfavoritedrinks%3Arw&client_id=https%3A%2F%2Fdrinks-\
the account's "myfavoritedrinks" scope:


de Jong [Page 13]

Internet-Draft remoteStorage December 2014



GET /oauth/michiel?redirect_uri=https%3A%2F%2Fdrinks-unhosted.5\
apps.com%2F&scope=myfavoritedrinks%3Arw&client_id=https%3A%2F%2Fdrinks-\
unhosted.5apps.com&response_type=token HTTP/1.1
Host: 3pp.io

Expand All @@ -668,7 +671,6 @@ unhosted.5apps.com&response_type=token HTTP/1.1
<title>Allow access?</title>
...


12.3. OAuth dialog form submission

When the user submits the form, the request would look something
Expand Down Expand Up @@ -696,15 +698,15 @@ XjzzzHNjkd1CJxoQubA1o%3D&token_type=bearer&state=

12.4. OPTIONS preflight

When an in-browser application makes a cross-origin request which
may affect the server-state, the browser will make a preflight


de Jong [Page 14]

Internet-Draft remoteStorage December 2014


When an in-browser application makes a cross-origin request which
may affect the server-state, the browser will make a preflight
request first, with the OPTIONS verb, for instance:

OPTIONS /storage/michiel/myfavoritedrinks/ HTTP/1.1
Expand All @@ -722,7 +724,6 @@ Internet-Draft remoteStorage December 2014
Access-Control-Allow-Headers: Authorization, Content-Length, Co\
ntent-Type, Origin, X-Requested-With, If-Match, If-None-Match


12.5. Initial PUT

An initial PUT may contain an 'If-None-Match: *' header, like this:
Expand All @@ -749,12 +750,12 @@ ntent-Type, Origin, X-Requested-With, If-Match, If-None-Match
12.6. Subsequent PUT



de Jong [Page 15]

Internet-Draft remoteStorage December 2014



A subsequent PUT may contain an 'If-Match' header referring to the
ETag previously returned, like this:

Expand Down Expand Up @@ -797,14 +798,14 @@ e.io/spec/modules/myfavoritedrinks/drink"}
Or a 200 OK status, plus a response body:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com


de Jong [Page 16]

Internet-Draft remoteStorage December 2014


Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com
Content-Type: application/json; charset=UTF-8
Content-Length: 106
ETag: "1382694048000"
Expand Down Expand Up @@ -847,14 +848,14 @@ charset=UTF-8","Content-Length":106}}}
Referer: https://drinks-unhosted.5apps.com/?
If-Match: "1382694045000"

And the server may respond with a 412 Conflict or a 200 OK status:


de Jong [Page 17]

Internet-Draft remoteStorage December 2014


And the server may respond with a 412 Conflict or a 200 OK status:

HTTP/1.1 412 Conflict
Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com
Expand Down Expand Up @@ -897,14 +898,14 @@ Internet-Draft remoteStorage December 2014
to the root folder, it is not necessary to poll each document for
changes individually.

As an example, the root folder may contain 10 directories,


de Jong [Page 18]

Internet-Draft remoteStorage December 2014


As an example, the root folder may contain 10 directories,
each of which contain 10 directories, which each contain 10
documents, so their paths would be for instance '/0/0/1', '/0/0/2',
etcetera. Then one GET request to the root folder '/' will be
Expand All @@ -930,11 +931,11 @@ Internet-Draft remoteStorage December 2014
application launch dashboard.

A malicious party could link to an application, but specifying a
remoteStorage user address that it controls, thus tricking the user
into using a trusted application to send sensitive data to the wrong
remoteStorage server. To mitigate this, applications SHOULD clearly
display to which remoteStorage server they are sending the user's
data.
remoteStorage account address that it controls, thus tricking the
user into using a trusted application to send sensitive data to the
wrong remoteStorage server. To mitigate this, applications SHOULD
clearly display to which remoteStorage server they are sending the
user's data.

Applications could request scopes that the user did not intend to
give access to. The user SHOULD always be prompted to carefully
Expand All @@ -947,14 +948,14 @@ Internet-Draft remoteStorage December 2014
therefore NOT be used for anything else, and the user SHOULD be
warned not to visit any web pages on that origin. In particular, the
OAuth dialog and launch dashboard or token revokation interface
SHOULD be on a different origin than the remoteStorage interface.


de Jong [Page 19]

Internet-Draft remoteStorage December 2014


SHOULD be on a different origin than the remoteStorage interface.

Where the use of bearer tokens is impractical, a user may choose to
store documents on hard-to-guess URLs whose path after
Expand Down Expand Up @@ -999,12 +1000,12 @@ Internet-Draft remoteStorage December 2014
Levels", BCP 14, RFC 2119, March 1997.



de Jong [Page 20]

Internet-Draft remoteStorage December 2014



[IRI]
Duerst, M., "Internationalized Resource Identifiers (IRIs)",
RFC 3987, January 2005.
Expand All @@ -1017,7 +1018,6 @@ Internet-Draft remoteStorage December 2014
"Section 4.2: Implicit Grant", in: Hardt, D. (ed), "The OAuth
2.0 Authorization Framework", RFC6749, October 2012.


17.2. Informative References

[HTTPS]
Expand Down
Loading

0 comments on commit a3e261d

Please sign in to comment.