OAuth

Oauth library handles OAuth-1.0a and OAuth-2.0. It acts as a client.

class Oauth.Client(opts)

Arguments

• opts (object()) – Client construction parameters

Options varies depending on target OAuth version.

Common options are:

version

"1.0" or "2.0"

use_authorization_header

Whether to use request header rather than querystring encoding

http_transaction_factory

Transaction factory to use for authentication, and functional transaction creation.

authorization_url

URL pointing to authorization endpoint

access_token_url

URL pointing to access token endpoint

callback_url

URL pointing to callback endpoint, may be "oob" for out-of-band callback.

access_token

Existing access token for session restoration

OAuth-1.0a options are:

request_token_url

URL pointing to request token endpoint

consumer_key

Consumer key, as given by service

consumer_secret

Consumer secret, as given by service

access_token_secret

Existing access token secret for session restoration

signature_method

Signature method to use, only “HMAC-SHA1” is supported by this client.

force_request_token_get

Quirk mode: Whether to force use of a GET transaction to retrieve the request token.

OAuth-2.0 options are:

client_id

Client id, as given by service

client_secret

Client secret, as given by service

body_client_authenticate

Whether to force in-body client_secret passing on access_token_url (instead of Authorization header). OAuth-2 says server MUST support Authorization: Basic header, but most servers don’t.

Example of use with a webview for user-interaction:

//Create a client
var authz = new Oauth.Client({
  version: ...
  ...
});

Once client created, the API flow is exactly the same for v1 and v2:

// use a webview for client login
WebView {
  id: login_view
  // Time passes, client authorizes application, we get callback
  // through an URL or a verifier.  If solely a verifier (oob mode),
  // use verifier as URL.
  onUrlChanged: {
    if (url.indexOf(my_callback_url) == 0) {
      authz.authorizationCallbackHandle(url).then(function(data) {
        console.log("Client now authenticated !");
      });
    }
  }
}

var permission = "abcde";
// Retrieve authorization URL for client
authz.authorizationUrlQuery(permission).then(function (url) {
  console.log("Redirecting client to", url);
  login_view.url = url;
});

Then, use client transaction factory to issue authorized API calls:

authz.http_transaction_factory({
    url: "https://api.example.com/1.0/myresource/"
}).send().then(function(response){
    return response.jsonParse();
}).then(function(jsonResponse){
    console.log(jsonResponse.data);
});

Or user may use stacked HTTP Transaction factory provided by the instance to stack other libraries:

var jsonRpcClient = new JsonRpc.Client("https://api.example.com/jsonrpc.bf", [
    'my_scope.my_call',
    'my_scope.my_other_call',
], {
    http_transaction_factory: authz.http_transaction_factory
});

// Issue a OAuth-authenticated JSONRPC call
jsonRpcClient.my_scope.my_call().then(function(response) {
    console.log(response);
});

Client methods are:

Oauth.Client.Oauth.Client.authorizationUrlQuery(scope, response_type)

Arguments

• scope (string()) – service-specific permissions to ask for.

• response_type (string()) – Oauth response type: "code" (default) or "token".

Returns

A Deferred.Deferred() returning an URL to point the client to for authorization.

Oauth.Client.Oauth.Client.authorizationCallbackHandle(url)

Arguments

• url (string()) – URL the client got redirected to, or a verifier code.

Returns

A Deferred.Deferred() resolved if authenticated.

Oauth.Client.Oauth.Client.http_transaction_factory(args)

Arguments

• args (object()) – HTTP transaction factory arguments, see Http.Transaction.factory().

Returns

An HTTP transaction with built-in authentication with the client credentials.

Oauth.Client.Oauth.Client.resourceOwnerCredentialsQuery(username, password)

This call is OAuth-2.0 specific.

Arguments

• username (string()) – User name

• password (string()) – User password

Returns

A Deferred.Deferred() resolved if OAuth client manages to authenticate user through its credentials.

This implements an optional part of OAuth-2.0 where OAuth client obtains an access token directly with user credentials. Most of the time, this is reserved for privileged clients.

Oauth.Client.Oauth.Client.clientCredentialsQuery()

This call is OAuth-2.0 specific.

Returns

A Deferred.Deferred() resolved if OAuth client manages to authenticate itself through its own credentials.

This implements an optional part of OAuth-2.0 where OAuth client obtains an access token directly for itself. Most of the time, this is reserved for privileged clients.

Oauth.Client.Oauth.Client.refreshTokenQuery()

This call is OAuth-2.0 specific.

Returns

A Deferred.Deferred() resolved when the token refreshing succeeded.

This renews the access token using the refresh token.

Returned Deferred.Deferred() yields optional data returned by the server with the access token.