Making Service Calls Using Browser-Based Authentication

Retrieving the User's Credentials

When Yahoo! redirects the user from the Yahoo! login page to your endpoint URL, the URL includes a token parameter. This token is valid for fourteen days, and represents the user's willingness to allow you to make web service calls on their behalf.

The next step is to retrieve the auth cookie and the WSSID, which comprise the credentials you need to make authenticated web service calls. When retrieving credentials, try to make the call in a manner that does not interrupt the user experience.

To retrieve the WSSID and auth cookie, make a request to the URL https://api.login.yahoo.com/WSLogin/V1/wspwtoken_login with these parameters:

Field	Description
appid	The application ID, which identifies the developer and the application. Obtained during initial application registration. You must pass this parameter in both the query string and your application's User-Agent.
ts	The timestamp in seconds as measured from Jan 1, 1970 GMT. To make sure that your clock is in sync with Yahoo! servers, use the Network Time Protocol Daemon (ntpd).
token	The token returned by the user from the Yahoo! login server.
sig	An MD5 hash of a carefully constructed relative URL: A login path (`/WSLogin/V1/wspwtoken_login`), plus Your application ID (`?appid=id`), plus The user's `token`, (`&token=token`), plus The timestamp (`&ts=seconds`), plus Your shared secret (`secret`).

Generating the Signature

The most complex parameter is the signature sig. The signature verifies that the request came from your application and helps prevent replay attacks.

Although constructing the signature might seem daunting, all the components are easy to obtain. The basic algorithm for generating the signature and the URL is:

$appid = "i%3DB%26p%3DUw70JGIdHWVRbpqYItcMw--";  // my application ID, obtained at registration
$token = "AKEaFUMk4BdbBcgMARGMFIjSrUWESUw70JGIdHWVRbpqYItcMw--";
                                                 // the user's token, obtained at user login
$ts = time();                                    // seconds since Jan 1, 1970 GMT
$secret = "a34f389cbd135de4618eed5e23409d34450"; // my shared secret, obtained at registration

$sig = md5( "/WSLogin/V1/wspwtoken_login?appid=$appid&token=$token&ts=$ts" . "$secret" );
$url = "https://api.login.yahoo.com/WSLogin/V1/wspwtoken_login?appid=$appid&token=$token&ts=$ts&sig=$sig";

Note that the shared secret is used to hash the URL and create the sig parameter, but it is not a query parameter itself. When hashing the URL, you append the shared secret without any sort of &secret=.

For a more general approach to signing URLs, refer to the example PHP function described under Constructing the Login URL.

Submitting the Request

Once you have the signature, you must add it as a parameter to the wspwtoken_login URL. A typical request might resemble (line breaks added for readability):

https://api.login.yahoo.com/WSLogin/V1/wslogin_token?appid=i%3DB%26p%3DUw70JGIdHWVRbpqYItcMw--&
ts=1128995236&token=AKEaFUMk4BdbBcgMARGMFIjSrUWESUw70JGIdHWVRbpqYItcMw--&
sig=827ccb0eea8a706c4c34a16891f84e7b

On success, the server returns an XML response containing the user's credentials, the WSSID and the auth cookie:

<BBAuthTokenLoginResponse
  xmlns:wsse='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
  xmlns:yahooauth='urn:yahoo:auth'>
  <Success>
    <Cookie>
      Y=kP229iUcnsFuiqrlQ_A9...
    </Cookie>
    <WSSID>RJC.2hSsIkd</WSSID>
    <Timeout>86400</Timeout>
    <YahooSOAPAuthHeader>
      <wsse:Security>
        <yahooauth:YahooAuthToken>
          <yahooauth:Cookies>
            Y=kP229iUcnsFuiqrlQ_A9...
          </yahooauth:Cookies>
          <yahooauth:AppID>
            Y8xBOUZfvOUBNZtbp1nvM646v0sL3g-
          </yahooauth:AppID>
          <yahooauth:WSSID>
            RJC.2hSsIkd
          </yahooauth:WSSID>
         </yahooauth:YahooAuthToken>
       </wsse:Security>
    </YahooSOAPAuthHeader>
  </Success>
</BBAuthTokenLoginResponse>

The two key parameters are Cookie and WSSID, which enable you to make repeated authenticated web service calls for the user. Parse these elements with your favorite XML parser and store them for later use. This example PHP function retrieves the Cookie, the WSSID, and the Timeout, storing these parameters in an array.

function get_credentials( $url ) {
  h = curl_init();
  curl_setopt( $ch, CURLOPT_URL, $url );
  curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
  $store = curl_exec( $ch );
  $xml = curl_exec( $ch );

  if (  preg_match( "/(Y=.*)/", $xml, $match_array ) == 1 ) {
    $COOKIE = $match_array[1];
  }
  if (  preg_match( "/<WSSID>(.+)<\/WSSID>/", $xml, $match_array ) == 1 ) {
    $WSSID = $match_array[1];
  }
  if (  preg_match( "/<Timeout>(.+)<\/Timeout>/", $xml, $match_array ) == 1 ) {
    $timeout = $match_array[1];
  }

  $rv = array();
  $rv["COOKIE"] = $COOKIE;
  $rv["WSSID"] = $WSSID;
  $rv["timeout"]   = $timeout;
  return $rv;
}

The Timeout element indicates the number of seconds before the WSSID and auth cookie expire. After one hour elapses, you must use the token to fetch new credentials. When you re-fetch the credentials, you should do so in a manner that is transparent to the user.

The YahooSOAPAuthHeader element and its children can be ignored.

On failure, the server returns an XML response containing an explanation of the error:

<wspwtoken_login_response>
  <Error>
    <ErrorCode>2001<ErrorCode>
     <ErrorDescription>The token is invalid</ErrorDescription>
  </Error>
</wspwtoken_login_response>

The list of possible error codes includes:

Error Code	Description
1000	The token (`token`) is expired. The user must reauthorize the application. Direct the user to the Yahoo! login screen and retrieve a new token.
2001	The token (`token`) is invalid. Verify that you are using the token that was returned for the user when he or she last logged in.
2002	The application's request used plain HTTP. Authenticated calls require HTTPS.
2003	The signature (`sig`) is invalid. Verify that you are generating the signature correctly.
2004	The timestamp (`ts`) is invalid. The timestamp may be out of sync with the Yahoo! login server clocks by at most ±600 seconds. To avoid clock skew issues, run ntpd.
2005	The length of appdata is too long. It cannot exceed 300 bytes.
3000	The application ID (`appid`) is invalid. Verify that you are using your application's proper application ID.
9000	The Yahoo! login server is temporarily unable to service your request. Try again later.

Regardless of success or failure, the service always returns an HTTP code of 200. If an error occurs, you must parse the response XML to determine the nature of the problem.

Using Credentials to Make Authenticated Service Calls

Now that you have a valid WSSID and auth cookie, you can make authenticated web service calls. All Yahoo! authenticated web services require three pieces of information:

The appid, passed as a REST parameter
The WSSID, passed as a REST parameter
The auth cookie, passed as an HTTP Cookie Header

For example, if this Yahoo! web service call requires authentication:

https://someproperty.yahooapis.com/webservice?
somepropertyParam1=foo
&somepropertyParam2=bar

You would add the appid and WSSID to the request:

https://someproperty.yahooapis.com/webservice?
somepropertyParam1=foo
&somepropertyParam2=bar
&appid=i%3DB%26p%3DUw70JGIdHWVRbpqYItcMw--
&WSSID=jsdaklj9a

and then insert the auth cookie into the HTTP headers, using the language of your choice. As an example, this PHP snippet uses curl to set the cookie:

$WS_API = // the web service URL with all parameters set
$AUTH_COOKIE = // the auth cookie

$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $WS_API );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array("Cookie: $AUTH_COOKIE"));
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
$result = curl_exec( $ch );

Once your application properly associates the authentication parameters with the request, the web service should authenticate your web service call. You must add the appid, WSSID, and auth cookie in this manner to every authenticated web service call you make.

Error Handling

Any web service call can potentially return an error. For example, your user's WSSID and auth cookie expire after one hour. After an hour elapses, the server returns an error indicating that the user's credentials are no longer valid. To handle this error, your application should fetch new user credentials, preferably without interrupting the user experience.

Although the errors returned can vary among different Yahoo! services, there are two HTTP errors that are common across all authenticated services:

401 - Unauthorized: The credentials are invalid for some reason, possibly because they have expired. Try to use the token to retrieve another WSSID and auth cookie for the user. If that fails, ask the user to try logging in again.
403 - Forbidden: The server understood the credentials, but rejected the request because those credentials are not permitted to execute the requested service. Other than asking the user to log in again under a different appid with different permissions, there is usually not much you can do about this error message.

For a more detailed list of errors, consult the documentation for the specific Yahoo! web service. You should design your application to handle these errors transparently whenever possible.

Support & Community

Browser-Based Authentication and related topics are discussed on the ydn-auth mailing list.