<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="15. Web Services" />
<meta name="dc.subject" content="15. Web Services" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="webservices.html" title="Chapter Contents" />
<link rel="prev" href="vfoafssl.html" title="WebID Protocol Support" />
<link rel="next" href="vwsssupport.html" title="WS-Security (WSS) Support in Virtuoso SOAP Server" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>15. Web Services</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="voauth" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>15. Web Services</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="webservices.html">Chapter Contents</a> | <a class="link" href="vfoafssl.html" title="WebID Protocol Support">Prev</a> | <a class="link" href="vwsssupport.html" title="WS-Security (WSS) Support in Virtuoso SOAP Server">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div class="selected">
<a href="webservices.html">Web Services</a>
</div>
<br />
<div>
<a href="soap.html">SOAP</a>
</div>
<div>
<a href="wsdl.html">WSDL</a>
</div>
<div>
<a href="vfoafssl.html">WebID Protocol Support</a>
</div>
<div class="selected">
<a href="voauth.html">OAuth Support</a>
<div>
<a href="#voauthtokens" title="OAuth Access Tokens">OAuth Access Tokens</a>
<a href="#voauthserver" title="Virtuoso OAuth server">Virtuoso OAuth server</a>
<a href="#voauthimplods" title="OAuth Implementation in OpenLink Data Spaces">OAuth Implementation in OpenLink Data Spaces</a>
<a href="#voauthcontrollers" title="OAuth Generate Keys for ODS Controllers (Web Services)">OAuth Generate Keys for ODS Controllers (Web Services)</a>
<a href="#voauthubc" title="ODS Ubiquity Commands">ODS Ubiquity Commands</a>
<a href="#voauthtool" title="OAuth Test Tool for ODS Controllers">OAuth Test Tool for ODS Controllers</a>
<a href="#voauthqa" title="OAuth QA">OAuth QA</a>
</div>
</div>
<div>
<a href="vwsssupport.html">WS-Security (WSS) Support in Virtuoso SOAP Server</a>
</div>
<div>
<a href="ws-routing.html">Web Services Routing Protocol (WS-Routing)</a>
</div>
<div>
<a href="warm.html">Web Services Reliable Messaging Protocol (WS-ReliableMessaging)</a>
</div>
<div>
<a href="vwstrust.html">Web Services Trust Protocol (WS-Trust)</a>
</div>
<div>
<a href="xmlxmla.html">XML for Analysis Provider</a>
</div>
<div>
<a href="xmlrpc.html">XML-RPC support</a>
</div>
<div>
<a href="syncml.html">SyncML</a>
</div>
<div>
<a href="uddi.html">UDDI</a>
</div>
<div>
<a href="expwsmodules.html">Exposing Persistent Stored Modules as Web Services</a>
</div>
<div>
<a href="vsmx.html">Testing Web Published Web Services</a>
</div>
<div>
<a href="bpel.html">BPEL Reference</a>
</div>
<div>
<a href="xsql.html">XSQL</a>
</div>
<br />
</div>
<div id="text">
<a name="voauth" />
<h2>15.4. OAuth Support</h2>
<p>The OAuth protocol enables websites or applications (Consumers) to access Protected Resources from
Web services (Service Providers) via an API, without requiring Users to disclose their Service Provider
credentials to those Consumers. More generally, OAuth creates a freely-implementable and generic methodology
for API-oriented authentication.</p>
<p>For Consumer developers, OAuth is a method to publish and interact with protected data.</p>
<p>For Service Provider developers, OAuth gives users access to their data while protecting their
account credentials.</p>
<p>One use case would be allowing a printing service, printer.example.com (the Consumer), to access
private photos stored on photos.example.net (the Service Provider), without requiring Users to reveal their
photos.example.net credentials to printer.example.com.</p>
<p>OAuth allows the user to selectively grant access to their private resources housed on one site
(called the Service Provider), to another site (called the Consumer). In other words, OAuth enables you
to grant access to some of your information without sharing all of your identity.</p>
<p>OAuth does not require a specific user interface or interaction pattern, nor does it specify how
Service Providers authenticate Users, making the protocol ideally suited for cases where authentication
credentials are unavailable to the Consumer, such as with OpenID.</p>
<p>OAuth aims to unify the experience and implementation of delegated web service authentication with
a single, community-driven protocol. OAuth builds on existing protocols and best practices that have been
independently implemented by various websites. An open standard, supported by large and small providers
alike, promotes a consistent and trusted experience for both application developers and the users of those
applications.</p>
<p>What is publicly known as "OAuth" is really the "OAuth Core 1.0" specification. The "Core"
designation is used to stress that this is the skeleton upon which other extensions and protocols may be
built. OAuth Core 1.0 does NOT by itself provide many desired features such as automated discovery of
endpoints, language support, support for XML-RPC and SOAP, standard definition of resource access,
OpenID integration, a full range of signing algorithms, or any number of other great ideas posted to
the OAuth group.</p>
<p>This was intentional and is viewed by the authors as a benefit. As the name implies, Core
deals only with the most fundamental aspects of the protocol:</p>
<ul>
<li>Establish a mechanism for exchanging a username and password for a token with defined rights</li>
<li>Provide tools to protect these tokens</li>
</ul>
<p>More details can be found <a href="http://oauth.net/documentation/getting-started">here</a>.</p>
<a name="voauthtokens" />
<h3>15.4.1. OAuth Access Tokens</h3>
<p>Credentials bearing tokens enable a user to provide their credentials in tokenized form in cases
where HTTP redirection to a browser plus human interaction is unavailable or unsuitable. For example,
intermediary intelligent agents, mobile phones, or set-top devices.</p>
<a name="voauthtokensreqauth" />
<h4>15.4.1.1. Request Authentication</h4>
<p>To request an Access Token in this model, the Consumer makes an HTTP request to the Service
Provider's Access Token URL. The authentication request contains [nine] parameters contained in the HTTP
Authorization header or as URL parameters. Parameter names and values must be "percent-encoded" to handle
characters in different character sets. The request should be performed using TLS, and should use HTTP
POST.</p>
<br />
<a name="voauthtokensrecauth" />
<h4>15.4.1.2. Receive Authentication</h4>
<p>Before granting an access token, the Service Provider must ensure that the request signature
has been successfully verified as per OAuth, that a request with the supplied timestamp and nonce has
never been received before, and that the supplied username and password match a User's credentials. If
successful, the Service Provider generates an Access Token and Token Secret using a 200 Ok response and
returns them in the HTTP response body.</p>
<br />
<a name="voauthtokensacpr" />
<h4>15.4.1.3. Access Protected Resources</h4>
<p>After successfully receiving the Access Token and Token Secret, the Consumer is able to access
the Protected Resources on behalf of the User as per section 7 of the OAuth core specification. In other
words, the Access Token obtained here is no different in capability to the Access Token specified by OAuth.
Once authenticated using the above process, the Consumer will sign all subsequent requests for the User's
Protected Resources using the returned Token Secret.</p>
<br />
<br />
<a name="voauthserver" />
<h3>15.4.2. Virtuoso OAuth server</h3>
<p>Virtuoso implements the OAuth Core 1.0 specification, and exposes the following API endpoints:</p>
<a name="voauthserverreqtok" />
<h4>15.4.2.1. Request token</h4>
<p>Endpoint:</p>
<div>
<pre class="programlisting">
http://server-cname/OAuth/request_token
</pre>
</div>
<p>Parameters:</p>
<ul>
<li>
<strong>oauth_consumer_key</strong>: The Consumer Key.</li>
<li>
<strong>oauth_signature_method</strong>: The signature method the Consumer used to sign the request.</li>
<li>
<strong>oauth_signature</strong>. The signature as defined in Signing Requests (Signing Requests).</li>
<li>
<strong>oauth_timestamp</strong>: As defined in Nonce and Timestamp (Nonce and Timestamp).</li>
<li>
<strong>oauth_nonce</strong>: As defined in Nonce and Timestamp (Nonce and Timestamp).</li>
<li>
<strong>oauth_version</strong>: OPTIONAL. If present, value MUST be 1.0 .</li>
</ul>
<a name="voauthserverreqtokexample" />
<h5>15.4.2.1.1. Example</h5>
<p>Request:</p>
<div>
<pre class="programlisting">
http://localhost:8890/OAuth/request_token?oauth_version=1.0&oauth_nonce
=dad4cb071e2169cbcaa051d404ac61a3&oauth_timestamp=1201873644&oauth_cons
umer_key=f756023be5ff1f20881cf8fe398069f3976b2304&oauth_signature_metho
d=HMAC-SHA1&oauth_signature=z76k5fQ0msFsQzCmhO%2FJZ329ZUE%3D
</pre>
</div>
<p>Note: all long lines in example texts are split, i.e., the GET request is single line.</p>
<p>Response:</p>
<div>
<pre class="programlisting">
oauth_token=b4e22daa117b0bebf60ab6ba6e401edc7addd78c&oauth_token_secret
=4de6e3ab17553a0a385ebf6a3b4dd30f
</pre>
</div>
<br />
<br />
<a name="voauthserverauth" />
<h4>15.4.2.2. Authorization</h4>
<p>Endpoint:</p>
<div>
<pre class="programlisting">
http://server-cname/OAuth/authorize
</pre>
</div>
<p>Parameters:</p>
<ul>
<li>
<strong>oauth_token</strong>: The Request Token obtained in the previous step. The current
implementation of the Service Provider declare this parameter as REQUIRED.</li>
<li>
<strong>oauth_callback</strong>: OPTIONAL. The Consumer MAY specify a URL the Service
Provider will use to redirect the User back to the Consumer when Obtaining User Authorization
(Obtaining User Authorization) is complete.</li>
</ul>
<a name="voauthserverauthexample" />
<h5>15.4.2.2.1. Example</h5>
<p>Request:</p>
<div>
<pre class="programlisting">
http://localhost:8890/OAuth/authorize?oauth_token=b4e22daa117b0bebf60ab
6ba6e401edc7addd78c&oauth_callback=http%3A%2F%2Flocalhost%3A8890%2Foaut
h%2Fexample%2Fclient.php%3Fkey%3Df756023be5ff1f20881cf8fe398069f3976b23
04%26secret%3Dcc249bfb732039d8ecba9e4f94fdead7%26token%3Db4e22daa117b0b
ebf60ab6ba6e401edc7addd78c%26token_secret%3D4de6e3ab17553a0a385ebf6a3b4
dd30f%26endpoint%3Dhttp%253A%252F%252Flocalhost%253A8890%252FOAuth%252F
authorize
</pre>
</div>
<p>The User will be asked via web page to accept or decline the token.</p>
<br />
<br />
<a name="voauthserveract" />
<h4>15.4.2.3. Access token</h4>
<p>Endpoint:</p>
<div>
<pre class="programlisting">
http://server-cname/OAuth/access_token
</pre>
</div>
<p>Parameters:</p>
<ul>
<li>
<strong>oauth_consumer_key</strong>: The Consumer Key.</li>
<li>
<strong>oauth_token</strong>: The Request Token obtained previously.</li>
<li>
<strong>oauth_signature_method</strong>: The signature method the Consumer used to
sign the request.</li>
<li>
<strong>oauth_signature</strong>: The signature as defined in Signing Requests
(Signing Requests).</li>
<li>
<strong>oauth_timestamp</strong>: As defined in Nonce and Timestamp (Nonce and Timestamp).</li>
<li>
<strong>oauth_nonce</strong>: As defined in Nonce and Timestamp (Nonce and Timestamp).</li>
<li>
<strong>oauth_version</strong>: OPTIONAL. If present, value MUST be 1.0 .</li>
</ul>
<a name="voauthserveractexample" />
<h5>15.4.2.3.1. Example</h5>
<p>Request:</p>
<div>
<pre class="programlisting">
http://localhost:8890/OAuth/access_token?oauth_version=1.0&oauth_nonce=
8ad75091a66bdd741472be42149c828e&oauth_timestamp=1201873800&oauth_consu
mer_key=f756023be5ff1f20881cf8fe398069f3976b2304&oauth_token=b4e22daa11
7b0bebf60ab6ba6e401edc7addd78c&oauth_signature_method=HMAC-SHA1&oauth_s
ignature=tCxy0Lod4%2Bp%2FCBPV7Ph7RrsHXe4%3D
</pre>
</div>
<p>Response:</p>
<div>
<pre class="programlisting">
oauth_token=8c03b3da93480ca4728cc1194d6d03962f3bb5bb&oauth_token_secret
=854fd29c00adcedff4fbeaeb96584911
</pre>
</div>
<p>In addtion to the endpoints it define a API for PL applications to check authentication:</p>
<br />
<br />
<a name="voauthserverav" />
<h4>15.4.2.4. Authentication verification</h4>
<div>
<pre class="programlisting">
OAUTH.DBA.check_authentication (in params any, in lines any)
</pre>
</div>
<p>Parameters:</p>
<ul>
<li>
<strong>params</strong>: an array of strings representing the HTTP parameters</li>
<li>
<strong>lines </strong>: an array of HTTP request headers</li>
</ul>
<p>Result:</p>
<ul>
<li>on success it returns integer 1,</li>
<li>on failure it signal an SQL error.</li>
</ul>
<a name="voauthserveravsc" />
<h5>15.4.2.4.1. Sample code:</h5>
<p>A sample service (oauth.vsp):</p>
<div>
<pre class="programlisting">
<html>
<body>
<?vsp
OAUTH..check_authentication (params, lines);
?>
An OAuth testing page
</body>
</html>
</pre>
</div>
<br />
<a name="voauthserveravsr" />
<h5>15.4.2.4.2. Sample request:</h5>
<div>
<pre class="programlisting">
http://localhost:8890/admin/oauth.vsp?oauth_version=1.0&oauth_nonce=d57
640869b994b2d51bf9800229c4997&oauth_timestamp=1201873935&oauth_consumer
_key=f756023be5ff1f20881cf8fe398069f3976b2304&oauth_token=8c03b3da93480
ca4728cc1194d6d03962f3bb5bb&oauth_signature_method=HMAC-SHA1&oauth_sign
ature=X3K4lr9bJVz5YLnnyJDkykQZivY%3D
</pre>
</div>
<br />
<a name="voauthserveravsr" />
<h5>15.4.2.4.3. Sample request:</h5>
<div>
<pre class="programlisting">
http://localhost:8890/admin/oauth.vsp?oauth_version=1.0&oauth_nonce=d57
640869b994b2d51bf9800229c4997&oauth_timestamp=1201873935&oauth_consumer
_key=f756023be5ff1f20881cf8fe398069f3976b2304&oauth_token=8c03b3da93480
ca4728cc1194d6d03962f3bb5bb&oauth_signature_method=HMAC-SHA1&oauth_sign
ature=X3K4lr9bJVz5YLnnyJDkykQZivY%3D
</pre>
</div>
<br />
<a name="voauthserveravsr" />
<h5>15.4.2.4.4. Sample response:</h5>
<div>
<pre class="programlisting">
<html>
<body>
An OAuth testing page
</body>
</html>
</pre>
</div>
<br />
<br />
<br />
<a name="voauthimplods" />
<h3>15.4.3. OAuth Implementation in OpenLink Data Spaces</h3>
<p>OAuth tokens must be generated for each user account, for each ODS application, via ODS ->
Settings -> OAuth Keys. This UI provides a list of all applications to which the logged-in user has access,
i.e., of which the user is a member or owner. To enable access with OAuth, the user simply selects the
desired application instance from the list, and clicks the 'generate keys' button. The generated Consumer
Key and Secret will be associated with the given ODS user account & application instance.</p>
<p>Once a consumer token is available, the sequence below must be executed in order to establish an
authorized session:</p>
<ol>
<li>client uses request_token to get a token/secret pair for establishing session using consumer
token</li>
<li>client asks OAuth server to authorize the token from step 1. </li>
<li>using authorized token from step 1 client asks OAuth server for authentication token.</li>
<li>with authentication token from step 3, clients can access instance data associated with
the consumer token from step 1.</li>
</ol>
<a name="voauthimplodssoc" />
<h4>15.4.3.1. Sample OAuth Client</h4>
<p>To demonstrate the Virtuoso implementation of OAuth, we have written this sample client,
in Virtuoso/PL.</p>
<div>
<pre class="programlisting">
<html>
<?vsp
declare consumer_key, consumer_secret, oauth_token, oauth_secret, signature, timest, nonce varchar;
declare srv, res, signature_base, ret_url, url, tmp, sid varchar;
declare meth, pars any;
consumer_key := {?'key'};
srv := sprintf ('http://localhost:%s/OAuth/', server_http_port ());
sid := null;
res := '';
sid := {?'sid'};
if (sid = '')
sid := null;
else
{
-- if selected token is not same as one from the session we need to get new authentication token
if (consumer_key <> OAUTH..get_consumer_key (sid))
{
OAUTH..session_terminate (sid);
sid := null;
}
}
meth := get_keyword ('meth', params, 'weblog.post.new');;
pars := get_keyword ('pars', params, 'inst_id=15&title=testing&description=Some test post');;
if ({?'rt'} is not null and sid is null) -- request new token for the session
{
url := srv||'request_token';
url := OAUTH..sign_request ('GET', url, '', consumer_key, sid);
res := http_get (url);
sid := OAUTH..parse_response (sid, consumer_key, res);
OAUTH..set_session_data (sid, params);
ret_url := sprintf ('http://localhost:%s/oauth/oauth_client.vsp?ready=%U', server_http_port (), sid);
-- call authorize
url := sprintf ('%sauthorize?oauth_token=%U&oauth_callback=%U', srv, OAUTH..get_auth_token (sid), ret_url);
http_status_set (301);
http_header (sprintf ('Location: %s\r\n', url));
return;
}
else if ({?'ready'} is not null) -- get access token
{
-- we go here when token above is authorized
sid := {?'ready'};
url := srv||'access_token';
consumer_key := OAUTH..get_consumer_key (sid);
url := OAUTH..sign_request ('GET', url, '', consumer_key, sid);
res := http_get (url);
sid := OAUTH..parse_response (sid, consumer_key, res);
}
if (sid is not null) -- access token is ready, and we can call API
{
-- here we are ready to call service
if ({?'rt'} is null)
{
tmp := OAUTH..get_session_data (sid);
pars := get_keyword ('pars', tmp, pars);
meth := get_keyword ('meth', tmp, meth);
}
url := sprintf ('http://localhost:%s/ods/api/%s', server_http_port (), meth);
tmp := split_and_decode (pars);
params := '';
for (declare i,l int, l:=length (tmp); i < l; i := i + 2)
{
params := params || sprintf ('%U=%U&', tmp[i], tmp[i+1]);
}
--params := sprintf ('inst_id=%d&description=%U&title=%U', 15, 'Some test post', 'testing');
consumer_key := OAUTH..get_consumer_key (sid);
url := OAUTH..sign_request ('GET', url, params, consumer_key, sid);
res := http_get (url);
--dbg_obj_print (res);
}
?>
<head><title>OAuth Client</title></head>
<body>
<h1>OAuth client for ODS Controllers</h1>
<form method="POST" action="oauth_client.vsp">
<input type="hidden" name="sid" value="<?V sid ?>"/>
APPLICATION : <br /> <select name="key">
<?vsp for select a_name, a_key from OAUTH..APP_REG do { ?>
<option value="<?V a_key ?>" <?vsp if (consumer_key = a_key) http ('selected'); ?>><?V a_name ?></option>
<?vsp } ?>
</select>
<?vsp
if (sid is not null) http (sprintf (' TOKEN: %s', OAUTH..get_auth_token (sid)));
?>
<br />
ODS API: <br /><input type="text" name="meth" value="<?V meth ?>" size=50/> <br />
PARAMETERS: <br /> <textarea name="pars" rows="5" cols="50"><?V pars ?></textarea> <br />
<input type="submit" value="Execute" name="rt"/><br />
</form>
RESULT:
<hr/>
<pre><?V res ?></pre>
</body>
</html>
</pre>
</div>
<br />
<a name="voauthimplodssos" />
<h4>15.4.3.2. Sample OAuth Session</h4>
<p>The following shows a sample session, using the above Virtuoso/PL OAuth client.</p>
<div>
<pre class="programlisting">
GET /OAuth/request_token?oauth_consumer_key=50082d0fb861b0e6e67d5d986b8
333607edc5f36&oauth_nonce=b8f1089077cbce6e&oauth_signature_method=HMAC-
SHA1&oauth_timestamp=1211212829&oauth_version=1.0&oauth_signature=V1zmk
757LBHcmqVJ6obMhNX5hKA%3D HTTP/1.1
Host: localhost:6666
HTTP/1.1 200 Ok
Content-Length: NNN
<CR/LF>
oauth_token=86da75079d3aee0fab57a36fcffbf900768e4de3&oauth_token_secret
=M...
</pre>
</div>
<div>
<pre class="programlisting">
GET /OAuth/authorize?oauth_token=86da75079d3aee0fab57a36fcffbf900768e4d
e3&oauth_callback=http%3A//localhost%3A6666/oauth/oauth_client.vsp%3Fre
ady%3D00c874b2fab2f6424008b5064fe83e88 HTTP/1.1
Host: localhost:6666
HTTP/1.1 301 Moved
Location: /ods/oauth_authorize.vspx?....
</pre>
</div>
<div>
<pre class="programlisting">
GET /OAuth/access_token?oauth_consumer_key=50082d0fb861b0e6e67d5d986b83
33607edc5f36&oauth_nonce=242cc4875a0059f6&oauth_signature_method=HMAC-S
HA1&oauth_timestamp=1211212831&oauth_token=86da75079d3aee0fab57a36fcffb
f900768e4de3&oauth_version=1.0&oauth_signature=sqs/8nmNNnNJiZ/eBa688uNe
g9o%3D HTTP/1.1
Host: localhost:6666
HTTP/1.1 200 Ok
Content-Length: NNN
<CR/LF>
oauth_token=N..&oauth_token_secret=M...
</pre>
</div>
<div>
<pre class="programlisting">
GET /ods/api/weblog.post.new?description=Some%20test%20post&inst_id=15&
oauth_consumer_key=50082d0fb861b0e6e67d5d986b8333607edc5f36&oauth_nonce
=2f4765d20664e696&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1211
213321&oauth_token=db83a37d74faf53edc8ed56d418ded3a70fcc0bc&oauth_versi
on=1.0&title=testing&oauth_signature=oocIyr6kgoEQkC3WVwzvl6w62W4%3D HTT
P/1.1
Host: localhost:6666
HTTP/1.1 200 Ok
Content-Length: NNN
<CR/LF>
<result><code>1&lt/code></result>
</pre>
</div>
<br />
<br />
<a name="voauthcontrollers" />
<h3>15.4.4. OAuth Generate Keys for ODS Controllers (Web Services)</h3>
<p>The following steps describe how to Setup Application OAuth keys in ODS:</p>
<ol>
<li>Login as user at ODS Data Space.</li>
<li>Go to Settings -> OAuth keys
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Generate Keys" src="../images/ui/keys1.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.4.1. OAuth Generate Keys</td>
</tr>
</table>
</li>
<li>Select Application name from the drop-down list and click the "Generate Keys" button.</li>
<li>The generated Token and Secret values for the selected application will be shown as a result.
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Generate Keys" src="../images/ui/keys2.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.4.1. OAuth Generate Keys</td>
</tr>
</table>
</li>
</ol>
<br />
<a name="voauthubc" />
<h3>15.4.5. ODS Ubiquity Commands</h3>
<p>ODS provides Ubiquity commands to manipulate user accounts as well as instances and instance
specific data using the ODS Controllers API. This command set is available only for the Firefox browser
with the Ubiquity extension installed.</p>
<a name="voauthubinstall" />
<h4>15.4.5.1. Installation</h4>
<p>First, the Ubiquity Firefox extension must be installed. Then, ODS Ubiquity commands can be
installed by accessing http://host:port/ods/ods_ubiquity.html page. Ubiquity commands are accessed by the
ctrl-space key combination.</p>
<br />
<a name="voauthubcommands" />
<h4>15.4.5.2. Basic Session Setup Commands</h4>
<a name="voauthubcommandsei" />
<h5>15.4.5.2.1. ODS OAuth Endpoint Identification</h5>
<p>Assuming the OAuth endpoint: http://myopenlink.net/OAuth, in order to change it use the command:</p>
<div>
<pre class="programlisting">
Syntax: ods-oauth-host <host_url>
Example: ods-oauth-host http://demo.openlinksw.com/OAuth
</pre>
</div>
<br />
<a name="voauthubcommandscm" />
<h5>15.4.5.2.2. ODS Command Mode</h5>
<p>There are two command modes available to ubiquity commands when working against an ODS instance:
oauth or sid.</p>
<p>In OAuth mode, for every ODS application instance, an OAuth key must be obtained and then
initialized via the following steps: </p>
<ul>
<li>obtain an ODS based OAuth session-key via the ODS example endpoint: http://host:port/ods/oauth_sid.vsp
<div>
<pre class="programlisting">
http://myopenlink.net/ods/oauth_sid.vsp
</pre>
</div>
</li>
<li>bind session key to command session via the command: *ods-set-oauth <oauth-key>* or use
*ods-set-[class name]-oauth <oauth-key>* when oauth-key was generated for particular application
instance.</li>
</ul>
<p>If you choose the SID mode of interaction with ODS you have to perform the following steps:</p>
<ul>
<li>set mode via command: ods-set-mode sid or ods-set-mode oauth</li>
<li>set sid via command: ods-set-sid sid</li>
</ul>
<p>Note: The sid is a session ID applicable to all ODS commands for a given bound instance and
user combination. It's obtained from an ODS session.</p>
<br />
<a name="voauthubcommandsexample" />
<h5>15.4.5.2.3. Example</h5>
<p>The following example demonstrates oauth authentication getting the OAuth SID value for ex.
for existing Bookmark instance "mybookmarks" with owner user demo at the OpenLink Demo server.</p>
<p>In order to execute correctly the example, you need to have OAuth Generate Key for the Bookmark
"mybookmarks" instance at OpenLink Demo server. More information and simple scenario how to be done you can
find <a href="voauth.html#voauthcontrollers">here.</a>
</p>
<ol>
<li>Execute the command:
<div>
<pre class="programlisting">
ods-oauth-host <host_url>
-- for ex.:
ods-oauth-host http://demo.openlinksw.com/OAuth
</pre>
</div>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Authentication" src="../images/ui/keys3.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.5.2.3.1. OAuth Authentication</td>
</tr>
</table>
</li>
<li>Execute the command:
<div>
<pre class="programlisting">
ods-set-mode oauth
</pre>
</div>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Authentication" src="../images/ui/keys4.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.5.2.3.1. OAuth Authentication</td>
</tr>
</table>
</li>
<li>Obtain the OAuth Generated Key:
<ol>
<li>Go to http://cname:port/ods/oauth_sid.vsp . For ex. http://demo.openlinksw.com/ods/oauth_sid.vsp
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Authentication" src="../images/ui/keys5.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.5.2.3.1. OAuth Authentication</td>
</tr>
</table>
</li>
<li>In the shown form enter user demo and choose the application "mybookmarks". Click the "Execute" button.
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Authentication" src="../images/ui/keys6.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.5.2.3.1. OAuth Authentication</td>
</tr>
</table>
</li>
<li />
</ol>
</li>
<li>As result will be shown a form where you need to enter the user password.</li>
<li>Enter for user demo its password and click the "Login" button.
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Authentication" src="../images/ui/keys7.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.5.2.3.1. OAuth Authentication</td>
</tr>
</table>
</li>
<li>Click the "Authorize" button.
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Authentication" src="../images/ui/keys8.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.5.2.3.1. OAuth Authentication</td>
</tr>
</table>
</li>
<li>Copy the obtains OAuth SID value for ex.: 7ef4dcf23869488823b771b09b952cc9
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Authentication" src="../images/ui/keys9.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.5.2.3.1. OAuth Authentication</td>
</tr>
</table>
</li>
<li>Execute the following command:
<div>
<pre class="programlisting">
ods-set-sid 7ef4dcf23869488823b771b09b952cc9
or
ods-set-addressbook-oauth 7ef4dcf23869488823b771b09b952cc9
</pre>
</div>
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="OAuth Authentication" src="../images/ui/keys10.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.5.2.3.1. OAuth Authentication</td>
</tr>
</table>
</li>
</ol>
<li>You can also execute the command(s) depending on the application type:
<div>
<pre class="programlisting">
ods-set-briefcase-oauth <the obtained oauth session-key>
-- or
ods-set-bookmark-oauth <the obtained oauth session-key>
-- or
ods-set-feeds-oauth <the obtained oauth session-key>
-- or
ods-set-calendar-oauth <the obtained oauth session-key>
-- or
ods-set-addressbook-oauth <the obtained oauth session-key>
-- or
ods-set-poll-oauth <the obtained oauth session-key>
-- or
ods-set-weblog-oauth <the obtained oauth session-key>
-- or
ods-set-discussion-oauth <the obtained oauth session-key>
</pre>
</div>
</li>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>the <a href="rdfsparql.html#sparqloauthendpoint">Virtuoso SPARQL OAuth Tutorial</a> and the full
list of <a href="http://ods.openlinksw.com/wiki/ODS/VirtOAuthExamples">ODS Application Authentication
Examples using OAuth</a>
</p>
</div>
<br />
<br />
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>the full list of <a href="http://ods.openlinksw.com/dataspace/dav/wiki/ODS/VirtuosoOdsUbiquity">ODS Ubiquity Commands</a> and
the full list of <a href="http://ods.openlinksw.com/wiki/ODS/VirtuosoOdsUbiquityTutorialsOAuth">OpenLink
Data Spaces (ODS) Ubiquity Commands Tutorials</a>
</p>
</div>
<br />
<a name="voauthtool" />
<h3>15.4.6. OAuth Test Tool for ODS Controllers</h3>
<p>The ODS OAuth Test Tool creates examples to show users the correct format for constructing HTTP
requests signed according to OAuth specifications. The users use this format in their applications to make
successful requests to the ODS REST APIs.</p>
<p>The ODS users generate a Consumer Key and a Consumer Secret for their application instances by
ODS application UI (Setings -> OAuth Keys). You can find more information and sample scenario
<a href="voauth.html#voauthcontrollers">here.</a>
</p>
<p>To reach a specific ODS resource via the ODS REST API, a user must also specify a API method
and associated API parameters.</p>
<p>ODS OAuth standards validate the credentials of an external user by means of the digital signature.
If the user signs the request, and the ODS server validates the digital signature, the developer is granted
access to the requested resource.</p>
<p>To tool is accessible via http:/host:port/ods/oauth_test.vsp</p>
<a name="voauthtoolexample" />
<h4>15.4.6.1. Example</h4>
<p>The following example demonstrates creating and getting contact info by the ODS REST APIs
weblog.post.new and weblog.post.get using the OAuth Test Tool.</p>
<ol>
<li />
<li>Go to http://demo.openlinksw.com/ods</li>
<li>Log in as user demo with password demo</li>
<li>Go to Settings->OAuth Keys
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Weblog OAuth" src="../images/ui/keys11.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.6.1.1. Weblog OAuth</td>
</tr>
</table>
</li>
<li>Copy the Token value for an Weblog instance or create such in not existing. For ex.:
<div>
<pre class="programlisting">
150fd483a3219e09847676deebae6c725d5a0a03
</pre>
</div>
</li>
<li>Go to http://demo.openlinksw.com/ods/oauth_test.vsp</li>
<li>In the shown form enter for:
<ol>
<li>Server: http://demo.openlinksw.com/ods/api</li>
<li>Consumer Key: 150fd483a3219e09847676deebae6c725d5a0a03</li>
<li>API method: weblog.post.new</li>
<li>API parameters:
<div>
<pre class="programlisting">
inst_id=44&description=my test&title=my first post
</pre>
</div>
<ul>
<li>An easy way to get the instance id is using the ODS ubiquity commands sequence:
<div>
<pre class="programlisting">
ods-host http://demo.openlinksw.com/ods
ods-set-mode sid
ods-authenticate-user demo password demo
ods-get-instance-id demo's Weblog
</pre>
</div>
</li>
</ul>
</li>
<li>Select for Query options: "Generate URI and Submit".
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Weblog OAuth" src="../images/ui/keys12.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.6.1.1. Weblog OAuth</td>
</tr>
</table>
</li>
<li>Click the "Execute" button.</li>
<li>In the shown authorization form click the "Authorize" button.
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Weblog OAuth" src="../images/ui/keys13.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.6.1.1. Weblog OAuth</td>
</tr>
</table>
</li>
<li>As result will be shown the generated URI and the output message of executing the ODS
REST API. In our case, the id of the new created post will be: 37
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Weblog OAuth" src="../images/ui/keys14.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.6.1.1. Weblog OAuth</td>
</tr>
</table>
</li>
<li>Now let's get the data for the created post. In the form enter:
<ol>
<li>API method: weblog.get</li>
<li>API parameters: post_id=37</li>
<li>Select for Query options: "Generate URI and Submit".</li>
</ol>
</li>
<li>Click the "Execute" button.</li>
<li>As result in the "Response Body" text-area will be shown the
retrieved details for the posts with the given above id.
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Weblog OAuth" src="../images/ui/keys15.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.6.1.1. Weblog OAuth</td>
</tr>
</table>
</li>
</ol>
</li>
</ol>
<br />
<br />
<a name="voauthqa" />
<h3>15.4.7. OAuth QA</h3>
<a name="voauthqamyspace" />
<h4>15.4.7.1. MySpace Tools</h4>
<p>In order to use the <a href="http://developer.myspace.com/community/myspace/oauthintro.aspx">MySpace OAuth Testing Tool</a>:</p>
<ol>
<li>Need to have registered myspace account.</li>
<li>Need to apply to build apps on the MySpace Developer Platform.</li>
</ol>
<br />
<a name="voauthqagoogle" />
<h4>15.4.7.2. Google Tools</h4>
<p>
<a href="http://code.google.com/apis/gdata/articles/oauth.html#OAuthPlayground">Google's
OAuth playground tool</a> can be tried <a href="http://googlecodesamples.com/oauth_playground/">here</a>.</p>
<a name="voauthqagooglereg" />
<h5>15.4.7.2.1. Register your domain in Google</h5>
<p>In order to use the tool, you need to register the web application as domain:</p>
<ol>
<li>Login at your gmail account</li>
<li>Go to https://www.google.com/accounts/ManageDomains</li>
<li>Enter in the field for ex. the QA server ec2-67-202-42-146.compute-1.amazonaws.com and click the "Add Domain" button.
<p>Note: for now registered domains cannot be deleted (not supported from the Google UI)</p>
</li>
<li>As result the domain will be created and the manage domain page will be opened. Here you need to
verify you have admin privileges by choosing verification method </li>
<li>Choose "Upload an HTML file" and follow further the instructions.</li>
<li>Once the file is put in the correct server root, you should get the confirmation page:
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys16.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.1.1. Google OAuth</td>
</tr>
</table>
</li>
<li>Click the "Agree .." buttons.</li>
<li>As result will be additional setting page you need to change. Type in for "Target URL path
prefix:": http://ec2-67-202-42-146.compute-1.amazonaws.com/ods
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys17.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.1.1. Google OAuth</td>
</tr>
</table>
</li>
<li>Click the "Save" button.</li>
<li>As result will be shown the generated OAuth Consumer Secret for
the OAuth Consumer Key: ec2-67-202-42-146.compute-1.amazonaws.com:
<div>
<pre class="programlisting">
OAuth Consumer Key: ec2-67-202-42-146.compute-1.amazonaws.com
OAuth Consumer Secret: uEkfBvpMhTTT/VyFItEnEYt4
</pre>
</div>
</li>
<li>Also will be shown "test" link "Test your AuthSub registration here". Click it.</li>
<li>As result will be opened new window with OAuth request</li>
<li>Click the "Grant Access" button.
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys18.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.1.1. Google OAuth</td>
</tr>
</table>
</li>
<li>As result will be redirected to http://ec2-67-202-42-146.compute-1.amazonaws.com/ods/</li>
<li>Now lets return to our initial window and click there the button "Save".</li>
<li>Note that already is shown for the domain that is "Active":
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys19.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.1.1. Google OAuth</td>
</tr>
</table>
</li>
</ol>
<br />
<a name="voauthqagoogleplay" />
<h5>15.4.7.2.2. The Playground Tool qa steps</h5>
<p>Let's try the playground tool:</p>
<ol>
<li>Go to http://googlecodesamples.com/oauth_playground/</li>
<li>Select Scope, for ex. check the check-box for "Blogger".</li>
<li>Change oauth signature_method to HMAC-SHA1</li>
<li>Enter for "oauth consumer_key": ec2-67-202-42-146.compute-1.amazonaws.com</li>
<li>Enter for "consumer secret" the value generated from above.</li>
<li>Click the "Request token" button.</li>
<li>As result will get Response with Status Ok
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys20.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.2.1. Google OAuth</td>
</tr>
</table>
<ul>
<li>the Signature base string:
<div>
<pre class="programlisting">
GET&https%3A%2F%2Fwww.google.com%2Faccounts%2FOAuthGetRequestToken&oauth_consumer_key
%3Dec2-67-202-42-146.compute-.amazonaws.com%26oauth_nonce%3D60f50c8800b2f52807732ca1ae3855ef
%26oauth_signature_method%3DHMACSHA1%26oauth_timestamp%3D1224191856%26oauth_version%3D1.0
%26scope%3Dhttp%253A%252F%252Fwww.blogger.com%252Ffeeds%252F
</pre>
</div>
</li>
<li>the Authorization header:
<div>
<pre class="programlisting">
Authorization: OAuth oauth_version="1.0",
oauth_nonce="60f50c8800b2f52807732ca1ae3855ef",
oauth_timestamp="1224191856",
oauth_consumer_key="ec2-67-202-42-146.compute-1.amazonaws.com",
oauth_signature_method="HMAC-SHA1",
oauth_signature="nohPMCw%2BMrO8%2FwslS4oEm2wfuhg%3D"
</pre>
</div>
</li>
<li>the Response body:
<div>
<pre class="programlisting">
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Date: Thu, 16 Oct 2008 21:17:37 GMT
X-Content-Type-Options: nosniff
Expires: Thu, 16 Oct 2008 21:17:37 GMT
Cache-Control: private, max-age=0
Content-Length: 76
Server: GFE/1.3
oauth_token=COW3iN_7HxCXqfuzAQ&oauth_token_secret=ulsD7N5SuY16qC%2FvY2Sdk3AS
</pre>
</div>
</li>
</ul>
</li>
<li>And also in the "Get the Token" section now will be active the "Authorize" button. Click it.
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys21.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.2.1. Google OAuth</td>
</tr>
</table>
</li>
<li>As result will be shown the authentication page where you need to click the "Grant Access" button:
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys22.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.2.1. Google OAuth</td>
</tr>
</table>
</li>
<li>As result now in the "Get the Token" section will be active the "Access token" button. Click it.
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys23.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.2.1. Google OAuth</td>
</tr>
</table>
</li>
<li>As result the access_token will be obtained:
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys24.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.2.1. Google OAuth</td>
</tr>
</table>
</li>
<li>Click the "available feeds" button marked as 6.</li>
<li>As result in the "Response" body section will be shown:
<div>
<pre class="programlisting">
Blogger
http://www.blogger.com/feeds/default/blogs
http://www.blogger.com/feeds/<blogID>/posts/default
http://www.blogger.com/feeds/<blogID>/[<postID>]/comments/default
</pre>
</div>
</li>
<li>Copy the 1st URL and paste in the field after the method GET.</li>
<li>Click "execute".</li>
<li>As result will find your blogs, post, info at Blogger:
<table class="figure" border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<img alt="Google OAuth" src="../images/ui/keys25.png" />
</td>
</tr>
<tr>
<td>Figure: 15.4.7.2.2.1. Google OAuth</td>
</tr>
</table>
</li>
</ol>
<br />
<br />
<br />
<table border="0" width="90%" id="navbarbottom">
<tr>
<td align="left" width="33%">
<a href="vfoafssl.html" title="WebID Protocol Support">Previous</a>
<br />WebID Protocol Support</td>
<td align="center" width="34%">
<a href="webservices.html">Chapter Contents</a>
</td>
<td align="right" width="33%">
<a href="vwsssupport.html" title="WS-Security (WSS) Support in Virtuoso SOAP Server">Next</a>
<br />WS-Security (WSS) Support in Virtuoso SOAP Server</td>
</tr>
</table>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
981
