OAuthModule

OAuthModule is primarily a module to facilitate communications with external APIs that use OAuth 1.0a. Phil Windley has demonstrated an implementation of OAuth 1.0a in pure KRL.

Common Parameters

namespace

<namespace> generally refers to the <keyname> defined in the META block with the key keyword.  It is possible to dynamically bind OAuth tokens to a <namespace> so you can associate multiple tokens to an OAuth 1.0a provider; ie: "twitter_dev" and "twitter_user"

Predicates

has_token

Returns 1 if the user has an OAuth 1.0a token associated with <namespace>

needs_auth = oauthmodule:has_token("some_auth_provider");

Just because an account has an auth token does not mean that it is still valid or hasn't been revoked or timed out.  This is a convenience function so you don't have to make a protected resource request to determine if this is a new account.

Actions

The oauthmodule provides the following familiar HTTP methods as protected resource requests; ie: the request will provide the proper request signature and tokens for OAuth requests.

• post
• put
• get
• head
• delete
• patch

oauthmodule:<method>(<namespace>) with
  url = <url> and
  headers = <map> and
  params = <map> and
  body = <string> and
  response_headers = <array> and
  access_tokens = <map>;

url : the base url for the protected resource request; ie: for twitter ("https://api.twitter.com/1.1/statuses/user_timeline.json")

headers : some APIs require specific information passed in a header or require that the OAuth information is passed in the header; ie: for google ('GData-Version' : 2.0)

params : additional information required by the source API

ie: for twitter's user_timeline

'params' : {
            'include_entities' : 'true',
            'include_rts' : 'true',
            'screen_name' : "kynetx_test",
            'count' : 2
        }

body : where the particular HTTP method specifies that parameters are sent in the body, provide a properly encoded string; ie: form-multipart

req_body = <<
{
    "data" : {
        "title" : "Appointment title",
        "details" : "Meeting like a boss",
        "transparency" : "opaque",
        "status" : "confirmed",
        "location" : "San Peete, UT",
        "when" : [
            {
                "start" : "2012-06-12T19:07:32Z",
                "end"   : "2012-06-12T20:07:32Z"
            }
        ]
    }
}
>>;

response_headers : Some services will return a redirect.  In that case, rather than try to parse the response content, you can request the 'Location' response header be included in the result

access_tokens : This value will pre-empt any values that might have been defined in the META block.  This can be useful if you would like to make a request with your developer credentials rather than the user tokens, or if you have user tokens from an alternative source

Here is an example of a complete request to the Twitter v1.1 API that uses access_tokens to provide OAuth authentication

pre {
  myParams = {
    'include_entities' : 'true',
    'include_rts' : 'true',
    'screen_name' : "kynetx_test",
    'count' : 2
  };
  myTokens = {
    'access_token' : '100844323-sldflsdfoopsdfop',
    'access_token_secret' : 'ksdfoiso9foisdfoksdfoij'
  };
}
oauthmodule:get('twitter') 
  with
        url = 'https://api.twitter.com/1.1/statuses/user_timeline.json' and
        params = myParams and 
        access_tokens = myTokens;

Functions

The oauthmodule provides the following familiar HTTP methods as protected resource requests; ie: the request will provide the proper request signature and tokens for OAuth requests.

• post
• put
• get
• head
• delete
• patch

The format is just like the comparable actions, but, instead of passing parameters using the modifier syntax, you place the parameters in a hash/map as the second argument

result = oauthmodule:get('twitter', {
  'url' : 'https://api.twitter.com/1.1/statuses/user_timeline.json',
  'params' : {
    'include_entities' : 'true',
    'include_rts' : 'true',
    'screen_name' : "kynetx_test",
    'count' : 2
  },
  'access_tokens' : {
    'access_token' : '100844323-sldflsdfoopsdfop',
    'access_token_secret' : 'ksdfoiso9foisdfoksdfoij'
  }} );

get_auth_url

The authorization url is the url that the developer presents to the user to initiate the OAuth 1.0a dance.  For Twitter and Google, the OAuth urls are well known so you can skip providing the OAuth URLs by using 'twitter' or 'google' as your namespace.  In other cases, as a developer, you need to provide the 3 URLs specified by the OAuth protocol

auth_url_defaults = oauthmodule:get_auth_url('twitter');

explicit_oauth_url = oauthmodule:get_auth_url('v1.0a',{
  'request_token_url' => 'https://api.twitter.com/oauth/request_token',
  'authorization_url' => 'https://api.twitter.com/oauth/authorize',
  'access_token_url' => 'https://api.twitter.com/oauth/access_token'
};

Google added the concept of 'scope' to their implementation of OAuth 1.0a, so a get_auth_url request for Google access to the Calendar API would look like

google_auth_url = oauthmodule:get_auth_url('google',{
  'params' : {
    'scope' : 'https://www.google.com/m8/feeds/'
   }
} );

You can force the authorization url to use HTTPS (for the callback) by specifying

secure_auth_url = oauthmodule:get_auth_url('twitter',{
  'use_https' : 1
});

You can also modify the behavior of KRL when the OAuth provider redirects the user to the KRL callback

Raise a blue event

google_auth_url = oauthmodule:get_auth_url('google',{
  'raise_callback_event' => 'RCA',
  'app_id'=>'a144x123'} );

Redirect to a specific page

google_auth_url = oauthmodule:get_auth_url('google',{
  'type' => 'redirect',
  'url' => 'http://www.windley.com/'} );