OAuth Documentation =================== Disneyland's implimentation of OAuth 2.0 is based on Draft 28 found at at http://tools.ietf.org/html/draft-ietf-oauth-v2-28 Protocol Endpoints ------------------ Authorization Endpoint https://api2.eye.fi/oauth/auth.php Token Endpoint https://api2.eye.fi/oauth/access.php Basic Steps: ------------ 1) Register Application/Client All applications that access the Disneyland API must be registered through the Developer App Manager at http://dev-staging.eye.fi/tools/app-manager 2) Obtain an Access Token Disneyland will initially be supporting the "Authorization Code Grant" and "Resource Owner Password Credentials Grant" noted in section 4 of the OAuth 2.0 Draft 28 - http://tools.ietf.org/html/draft-ietf-oauth-v2-28#section-4 and a custom Client Pre-Code Grant which largely follows the Authorization Code Grant flow but is utilized in a whay that doesn't required direct access to a web browers or other user-agent by the client. Though does require browser access by the resource-owner. 3) Access the Disneyland API http://api2.eye.fi/method/action 4) Refresh Access Token (optional) In Depth: --------- 1) Application/Client Registration All 3rd party clients must be registered with the Disneyland service and supply the following information * Client Type: Either confidential or public as noted by http://tools.ietf.org/html/draft-ietf-oauth-v2-28#section-2.1 * Redirection URIs: One or more URIs that will be utilized by the client and specified via the redirect_uri query parameter during OAuth. * Developer Name: The English name of the individual or organization who created the client. * Application Name: To be displayed to the resource owner during the client authorization phase and possibly elsewhere on the Disneyland site. * Application Home URL: (Optional) The URL dedicated to the client or the developer if a client specific page does not exist. Not having a URL may be construed as lacking credibility by those who might use it. * Application Logo URL: (Optional) The URL for the client or the developer if a client logo does not exist. The logo should have no dimention larger than 120px. This will all be handled by the developer app manager at http://dev-staging.eye.fi/tools/app-manager 2) Obtain an Access Token AUTHORIZATION CODE GRANT Your client will access the Authorization Endpoint with the required parameters of client_id, client_sig, response_type=code and redirect_uri (which must match a URI registered via the App Manager). You are also recommended you include state. All non-required parameters, including those unique to the client will be returned via the redirect_uri. Example Authorization Request: https://api2.eye.fi/oauth/auth.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &client_sig=3bb238f6cf3ab9ce06d25de73bb917e6 &response_type=code &redirect_uri=https%3A%2F%2Fexample.com%2Fauthcode.php A successful response will look much like the following: https://example.com/authcode.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &code=JDJ5JDA4JGJoMnllRWQ4OS9sTDhQdEppM1czYi5XSHJPOVNMWldpckFaS2FRR3E5TkdIdmFRN3Q2OHBx &redirect_uri=https%3A%2F%2Fexample.com%2Fauthcode.php A failed response will look similar to: https://example.com/authcode.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &error=invalid_request &redirect_uri=https%3A%2F%2Fexample.com%2Fauthcode.php Example Access Token Request: https://api2.eye.fi/oauth/access.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &client_sig=3bb238f6cf3ab9ce06d25de73bb917e6 &code=JDJ5JDA4JGJoMnllRWQ4OS9sTDhQdEppM1czYi5XSHJPOVNMWldpckFaS2FRR3E5TkdIdmFRN3Q2OHBx &grant_type=authorization_code &redirect_uri=https%3A%2F%2Fexample.com%2Fauthcode.php A successful JSON response will look much like the following: HTTP 200 Success { "access_token":"JDJ5JDA4JDh5WjFBai9vZjRUNlZVVHhLaFNvZ09TLkpNZVBta2dtbFR4NlMyc0JyNXd3a3F6VzdrM2sy", "expires_in":1340477765, "token_type":"bearer", "refresh_token":"JDJ5JDA4JDVKak9Vdkwyc29HanF0ckg5REhhaWVONkFuWFVCWm5kVGd1aFQyVDlWclpnSExvWWpndjRX" } A failure JSON response would look something like: HTTP 400 Bad Request { "error":"invalid_request", "error_description":"Your client_id was not specified." } After the access_token expires the client can utilize the refresh_token to request a new access_token and refresh_token pair. Example Refresh Token Request: https://api2.eye.fi/oauth/access.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &client_sig=8fdc5e11c0f16ec608cc89895c99c28d &refresh_token=JDJ5JDA4JDVKak9Vdkwyc29HanF0ckg5REhhaWVONkFuWFVCWm5kVGd1aFQyVDlWclpnSExvWWpndjRX &grant_type=refresh_token &redirect_uri=https%3A%2F%2Fexample.com%2Fauthcode.php CLIENT PRE-CODE GRANT (Not part of the OAuth spec) Example Pre-Code Request Client https://api2.eye.fi/oauth/auth.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &client_sig=8cb582b4e10e233757dfb42a2aac2dae &pre_code=503d4713d92e972d2754ad8d15bd34a2 &response_type=pre_code A successful response will look like the following HTTP 200 Success { "expires_in":1340477765, "pre_code":"503d4713d92e972d2754ad8d15bd34a2" } A failure response would look something like: HTTP 400 Bad Request { "error":"invalid_client", "error_description":"Your client_sig was not what was expected by the system." } Once the client received a successful response they would then direct the user visit https://api2.eye.fi/oauth/auth.php in their external web browser where they would fill out a form with the pre_code displayed by the client: FORM: pre_code = 503d4713d92e972d2754ad8d15bd34a2 Once again after the client received a successful response in requesting a pre_code they would (in addition to displaying the pre_code to the user) begin polling the autherization endpoint as follows: https://api2.eye.fi/oauth/auth.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &client_sig=9209997d4ce33af4d26f1cbce1dff34d &pre_code=503d4713d92e972d2754ad8d15bd34a2 &response_type=code_validation A successful response should look similar to: HTTP 200 Success { "code":"JDJ5JDA4JGJoMnllRWQ4OS9sTDhQdEppM1czYi5XSHJPOVNMWldpckFaS2FRR3E5TkdIdmFRN3Q2OHBx", "expires_in":1340477765, "pre_code":"503d4713d92e972d2754ad8d15bd34a2" } While waiting on the user to authorize the app HTTP 204 No Content A failure response when the request is incorrectly signed HTTP 401 Unauthorized { "error":"unauthorized_client" } A failure response when the user denied client authorization HTTP 403 Forbidden { "error":"authorization_denied" } The client would then access the token endpoint as per the normal Authorization Code Grant flow. Example Pre-Code Access Token Request https://api2.eye.fi/oauth/access.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &client_sig=08a9d7d839b569e7d8b5122423fc9edc &code=JDJ5JDA4JGJoMnllRWQ4OS9sTDhQdEppM1czYi5XSHJPOVNMWldpckFaS2FRR3E5TkdIdmFRN3Q2OHBx &grant_type=authorization_code &redirect_uri=https%3A%2F%2Fexample.com%2Fauthcode.php RESOURCE OWNER PASSWORD CREDENTIALS GRANT Our implimentation of the Resource Owner Password Credentials Grant will require the client_id, client_sig, grant_type=password, username, and password query parameters to be set and valid. We also recommend setting the state query parameter to help validate the response received by our service. Example Access Token Request (WWW Basic Authorization) Authorization: Basic dXNlcm5hbWUlNDB5b3VyZG9tYWluLmNvbSUzQVlvdXJEaXNuZXlsYW5kUGFzc3dvcmQ= https://api2.eye.fi/oauth/access.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &client_sig=87c0517e6c41a0d1b1495a6f66c55676 &grant_type=password &redirect_uri=https%3A%2F%2Fexample.com%2Fauthcode.php Example Access Token Request (Query Parameters) https://api2.eye.fi/oauth/access.php ?client_id=53a6f338e42b3971821d71b6d04e79e5 &client_sig=1cf19b79a9203d8cd1dc3f79b32c6510 &username=username@yourdomain.com &password=YourDisneylandPassword &grant_type=password &redirect_uri=https%3A%2F%2Fexample.com%2Fauthcode.php Request Signing --------------- Signing OAuth and API requests involves creating a base string which is comprised of the client_secret concatinated with all the key/value pairs of a key sorted query string. Then generating a standard MD5 hash based on the base string. The client_sig parameter is generated as follows (PHP code example) function generateSignature($params, $secret) { ksort($params); $base_str = $secret; foreach($params as $k => $d) { if(is_array($d)) { ksort($d); foreach($d as $p => $v) $base_str .= $k.'['.$p.']'.$v; } else { if(!is_null($d)) $base_str .= $k.(is_bool($d) ? (int) $d : $d); } } return md5($base_str); }