Eye-Fi OAuth

http://blog.apigee.com/detail/oauth_differences/

RESTful Web Services

John Calcote – A simple (but long-winded) guide to REST web services
John Calcote – PUT or POST: The REST of the Story
Sun Cloud API
NetFlix REST API Conventions
NetFlix REST API Reference

Eye-Fi OAuth Flow

1. Client obtains client_id and client_secret from EyeFi (api key/secret).
2. Client makes this call to give permissions to the app:
   https://api2.eye.fi/oauth/authorize.php?client_id=xxxx&scope=xxxx,xxxx,xxxx&redirect_uri=xxxx&response_type=code
3. Eyefi Server Send a “code” back to the redirect_uri:
   https://redirect_uri/?code=xxxxx
4. The client: Then makes a call to the access_token url with the code passed in from previous step:
   https://api2.eye.fi/oauth/access_token.php?code=xxxx&client_id=xxxx&client_secret=xxxx&grant_type=authorization_code

   And as a response eyefi sends a json response with access_token and refresh_token with corresponding expiration_time. Access token is now usable with our apis ( if the auth key is a part of the access token).

5. If the access token has expired the client refreshes the access_token:
   https://api2.eye.fi/oauth/access_token.php?refresh_token=xxxx&client_id=xxxx&client_secret=xxxx&grant_type=refresh_token

   And as a response eyefi sends a json response with new access_token and refresh_token with corresponding expiration_time.

OAuth 1.0

OAuth 1.0 was published in December 2007.
OAuth 1.0 Revision A was published in June 2008.
OAuth 1.0 was published as RFC 5849 in April 2010.

OAuth 2.0

27signals supports Draft 05.
Facebook and oauth2-ruby support Draft 00.

OAuth 2.0 Draft 26

   +--------+                               +---------------+
|        |--(A)- Authorization Request ->|   Resource    |
|        |                               |     Owner     |
|        |<-(B)-- Authorization Grant ---|               |
|        |                               +---------------+
|        |
|        |                               +---------------+
|        |--(C)-- Authorization Grant -->| Authorization |
| Client |                               |     Server    |
|        |<-(D)----- Access Token -------|               |
|        |                               +---------------+
|        |
|        |                               +---------------+
|        |--(E)----- Access Token ------>|    Resource   |
|        |                               |     Server    |
|        |<-(F)--- Protected Resource ---|               |
+--------+                               +---------------+

1.1 Roles

resource owner

An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.

resource server

The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

client

An application making protected resource requests on behalf of the resource owner and with its authorization. The term client does not imply any particular implementation characteristics (e.g. whether the application executes on a server, a desktop, or other devices).

authorization server

The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

4.0 Obtaining Authorization

1. Authorization Code Grant
2. Implicit Grant
3. Resource Owner Password Credentials Grant
4. Client Credentials Grant
5. OAuth 2.0 Authorization Protocol: Bearer Tokens
6. HTTP Authentication: MAC Access Authentication
7. OAuth 2.0 Threat Model and Security Considerations

4.1 Authorization Code Grant

• Authorization Code (OAuth 1.0 Request Token?)
• Implicit (primarily for in browser apps)
• Resource Owner Password Credentials (best used to store access token only)
• Client Credentials (expects prior arrangement or the client is also the resource owner)
• Access Token

+----------+
| resource |
|   owner  |
|          |
+----------+
     ^
     |
    (B)
+----|-----+          Client Identifier      +---------------+
|         -+----(A)-- & Redirection URI ---->|               |
|  User-   |                                 | Authorization |
|  Agent  -+----(B)-- User authenticates --->|     Server    |
|          |                                 |               |
|         -+----(C)-- Authorization Code ---<|               |
+-|----|---+                                 +---------------+
  |    |                                         ^      v
 (A)  (C)                                        |      |
  |    |                                         |      |
  ^    v                                         |      |
+---------+                                      |      |
|         |>---(D)-- Authorization Code ---------'      |
|  Client |          & Redirection URI                  |
|         |                                             |
|         |<---(E)----- Access Token -------------------'
+---------+       (w/ Optional Refresh Token)

response_type
	REQUIRED. Value MUST be set to "code".
client_id
	REQUIRED. The client identifier as described in Section 2.2.
redirect_uri
	OPTIONAL. As described in Section 3.1.2.
scope
	OPTIONAL. The scope of the access request as described by Section 3.3.
state
	RECOMMENDED. An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery as described in Section 10.12.

< http://www.eye.fi/oauth/registration.html?response_type=code&client_id=12344567890&sig=123412341234&state=auth_token&redirect_uri=http://api2.eye.fi/oauth/auth
|| SUCCESS
> HTTP/1.1 302 Found
> Location: http://api2.eye.fi/oauth/auth&code=URL_ENCODED_CODE&state=auth_token
|| FAILURE
> HTTP/1.1 302 Found
> Location: http://api2.eye.fi/oauth/auth&error=(invalid_request|unauthorized_client|etc.)&error_description=OPTIONAL_UTF-8_ENCODED_TEXT&error_uri=OPTIONAL_HUMAN-READABLE_WEB_PAGE_URI&state=auth_token
// REQUEST ACCESS TOKEN
< http://www.eye.fi/oauth/registration.html?grant_type=authorization_code&code=URL_ENCODED_AUTH_TOKEN&client_id=12344567890&sig=123412341234&state=auth_token&redirect_uri=http://api2.eye.fi/oauth/auth
|| SUCCESS
> HTTP/1.1 200 OK
> Content-Type: application/json;charset=UTF-8
> Cache-Control: no-store
> Pragma: no-cache
>
> {
>     "access_token":"2YotnFZFEjr1zCsicMWpAA",
>     "token_type":"example",
>     "expires_in":86400,
>     "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
>     "example_parameter":"example_value"
> }
|| FAILURE
> HTTP/1.1 400 Bad Request
> Content-Type: application/json;charset=UTF-8
> Cache-Control: no-store
> Pragma: no-cache
>
> {
> 	"error":"invalid_request"
> }

// REFRESH TOKEN //
< http://www.eye.fi/oauth/registration.html?grant_type=refresh_token&refresh_token=URL_ENCODED_REFRESH_TOKEN&client_id=12344567890&sig=123412341234&state=auth_token&redirect_uri=http://api2.eye.fi/oauth/auth

4.2 Implicit Grant

The implicit grant type is used to obtain access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI. These clients are typically implemented in a browser using a scripting language such as JavaScript.

+----------+
| Resource |
|  Owner   |
|          |
+----------+
     ^
     |
    (B)
+----|-----+          Client Identifier     +---------------+
|         -+----(A)-- & Redirection URI --->|               |
|  User-   |                                | Authorization |
|  Agent  -|----(B)-- User authenticates -->|     Server    |
|          |                                |               |
|          |<---(C)--- Redirection URI ----<|               |
|          |          with Access Token     +---------------+
|          |            in Fragment
|          |                                +---------------+
|          |----(D)--- Redirection URI ---->|   Web-Hosted  |
|          |          without Fragment      |     Client    |
|          |                                |    Resource   |
|     (F)  |<---(E)------- Script ---------<|               |
|          |                                +---------------+
+-|--------+
  |    |
 (A)  (G) Access Token
  |    |
  ^    v
+---------+
|         |
|  Client |
|         |
+---------+

4.3 Resource Owner Password Credentials Grant

1. Username and password sent to authorization server.
2. Authorization server returns access token and optional refresh token.

Access Token Request

+----------+
| Resource |
|  Owner   |
|          |
+----------+
     v
     |    Resource Owner
    (A) Password Credentials
     |
     v
+---------+                                  +---------------+
|         |>--(B)---- Resource Owner ------->|               |
|         |         Password Credentials     | Authorization |
| Client  |                                  |     Server    |
|         |<--(C)---- Access Token ---------<|               |
|         |    (w/ Optional Refresh Token)   |               |
+---------+                                  +---------------+

grant_type
	REQUIRED. Value MUST be set to "password".
username
	REQUIRED. The resource owner username, encoded as UTF-8.
password
	REQUIRED. The resource owner password, encoded as UTF-8.
scope
	OPTIONAL. The scope of the access request as described by Section 3.3.

4.4 Client Credentials Grant

+---------+                                  +---------------+
|         |                                  |               |
|         |>--(A)- Client Authentication --->| Authorization |
| Client  |                                  |     Server    |
|         |<--(B)---- Access Token ---------<|               |
|         |                                  |               |
+---------+                                  +---------------+

grant_type
	REQUIRED. Value MUST be set to "client_credentials".
scope
	OPTIONAL. The scope of the access request as described by Section 3.3.

3.3. Access Token Scope

The authorization and token endpoints allow the client to specify the scope of the access request using the “scope” request parameter. In turn, the authorization server uses the “scope” response parameter to inform the client of the scope of the access token issued.

The value of the scope parameter is expressed as a list of space-delimited, case sensitive strings. The strings are defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope.

scope = scope-token *( SP scope-token )
scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

The authorization server MAY fully or partially ignore the scope requested by the client based on the authorization server policy or the resource owner’s instructions. If the issued access token scope is different from the one requested by the client, the authorization server MUST include the “scope” response parameter to inform the client of the actual scope granted.

If the client omits the scope parameter when requesting authorization, the authorization server MUST either process the request using a pre-defined default value, or fail the request indicating an invalid scope. The authorization server SHOULD document its scope requirements and default value (if defined).

• [..]
• Eye-Fi_Code_Reference.textile
• Eye-Fi_Dev-API-Explorer.textile
• Eye-Fi_Dev-OAuth.textile
• Eye-Fi_Dev-WordPress.textile
• Eye-Fi_Notes.textile
• Eye-Fi_Server_Setup.textile
• OAuth-Spec_2012-07-10_1715.txt