ODS as an OAuth Provider

OAuth is an authentication and authorization protocol for application to application level interactions. It's driven by the combined use of distinct application and user tokens that provides a federated mechanism for identity authentication and resource access authorization driven by digital signatures.

ODS implements OAuth 1.0. Authentication through OAuth requries three steps on behalf of the client:

  • Obtain a request token from the ODS-based service
  • Let the user log into the service and accept the request token
  • Convert the request token into an access token

After completing these steps successfully the access token can be used in subsequent API calls as described in Accessing the ODS API with an OAuth Access Token.

Before being able to access the ODS API via this method clients need to register and retrieve a client consumer key and secret pair. This is done in the ODS admin interface's "Application Settings" menu. The menu point "OAuth keys" allow to create the required key/secret pairs. Alternatively http://server-cname/oauth/oauth_apps.vspx provides the same UI independant from the ODS admin interface. ODS only takes the domain part of the callback URL into account.

Aquiring a Request Token

The first step for the client is to get a request token. The corresponding URL endpoint is http://server-cname/OAuth/request_token. The client needs to use an OAuth signed HTTP GET request. This includes the following parameters:

  • oauth_consumer_key - The Consumer Key.
  • oauth_signature_method - The signature method the Consumer used to sign the request. ODS currently only supports HMAC-SHA1 as signature method.
  • oauth_signature - The signature as defined in Signing Requests. It is essentially a checksum of all paramters except for the signature itself.
  • oauth_timestamp - The timestamp of the request as defined in Nonce and Timestamp. The timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
  • oauth_nonce - As defined in Nonce and Timestamp. A nonce is a random string, uniquely generated for each request.
  • oauth_version - The optional OAuth version. If present, value must be 1.0.
  • oauth_client_ip - The optional IP address of the client responsible for the request. ODS makes sure that the client making each request is the same. Normally there is no need to specify the client IP since one client will make all the calls. However, if the client is only a proxy for other clients the IPs might differ which would require the real client's IP to be specified here and in the third step.

Example Request (query parameters have been wrapped for readability):

http://web.ods.openlinksw.com/OAuth/request_token
?oauth_nonce=dad4cb071e2169cbcaa051d404ac61a3
&oauth_timestamp=1201873644
&oauth_consumer_key=f756023be5ff1f20881cf8fe398069f3976b2304
&oauth_signature_method=HMAC-SHA1
&oauth_signature=z76k5fQ0msFsQzCmhO%2FJZ329ZUE%3D

If successful the service will return an URL-encoded string containing the request token and token secret which are required for the further steps.

Example response (body has been wrapped for readability):

oauth_token=b4e22daa117b0bebf60ab6ba6e401edc7addd78c
&oauth_token_secret=4de6e3ab17553a0a385ebf6a3b4dd30f

User Authentication

For the second step the client needs to direct the user to the ODS authentication page. It is here where the user will be asked to sign in and approve the client's request for access. The corresponding URL endpoint is http://server-cname/OAuth/authorize. The request needs to include the following parameters:

  • oauth_token - The request token as retrieved in the first step.
  • oauth_callback - The callback URL to which ODS will redirect the user once authentication has been completed.

Example URL (query parameters have been wrapped for readability):

http://web.ods.openlinksw.com/OAuth/authorize
?oauth_token=b4e22daa117b0bebf60ab6ba6e401edc7addd78c
&oauth_callback=http%3A%2F%2Flocalhost%3A8890%2Foauth%2Fexample%2Fclient.php

Once the user authenticated and approved or declined the request they are redirected to the given callback URL. The redirection URL contains the URL parameters specified by the client as well as the request token in the oauth_token paramter as specified in OAuth 1.0.

Converting the Request Token into an Access Token

The final step requires the client to convert the request token into an access token which can be used to authenticate calls to the ODS API. The corresponding URL endpoint is http://server-cname/OAuth/access_token. As with all OAuth-related calls this HTTP GET request needs to be signed and contains the following parameters:

  • oauth_consumer_key - The Consumer Key.
  • oauth_token - The request token as obtained in the first step.
  • oauth_signature_method - The signature method the Consumer used to sign the request. ODS currently only supports HMAC-SHA1 as signature method.
  • oauth_signature - The signature as defined in Signing Requests. It is essentially a checksum of all paramters except for the signature itself.
  • oauth_timestamp - The timestamp of the request as defined in Nonce and Timestamp. The timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
  • oauth_nonce - As defined in Nonce and Timestamp. A nonce is a random string, uniquely generated for each request.
  • oauth_version - The optional OAuth version. If present, value must be 1.0.
  • oauth_client_ip - The optional IP address of the client responsible for the request. ODS makes sure that the client making each request is the same. Normally there is no need to specify the client IP since one client will make all the calls. However, if the client is only a proxy for other clients the IPs might differ which would require the real client's IP to be specified here and in the first step.

Example Request (query parameters have been wrapped for readability):

http://web.ods.openlinksw.com/OAuth/access_token
oauth_version=1.0
&oauth_nonce=8ad75091a66bdd741472be42149c828e
&oauth_timestamp=1201873800
&oauth_consumer_key=f756023be5ff1f20881cf8fe398069f3976b2304
&oauth_token=b4e22daa117b0bebf60ab6ba6e401edc7addd78c
&oauth_signature_method=HMAC-SHA1
&oauth_signature=tCxy0Lod4%2Bp%2FCBPV7Ph7RrsHXe4%3D

If successful the service will return an URL-encoded string containing the accces token and token secret which can then be used to authenticate calls to the ODS API.

Example response (body has been wrapped for readability):

oauth_token=8c03b3da93480ca4728cc1194d6d03962f3bb5bb
&oauth_token_secret=854fd29c00adcedff4fbeaeb96584911

Accessing the ODS API with an OAuth Access Token

Once the client obtained an access token they can use it to perform subsequent calls to the ODS API. Like any OAuth calls these need to be signed. This means that in addition to the query parameters required for the ODS API call the following needs to be specified:

  • oauth_consumer_key - The Consumer Key.
  • oauth_token - The access token as obtained in the first step.
  • oauth_signature_method - The signature method the Consumer used to sign the request. ODS currently only supports HMAC-SHA1 as signature method.
  • oauth_signature - The signature as defined in Signing Requests. It is essentially a checksum of all paramters except for the signature itself.
  • oauth_timestamp - The timestamp of the request as defined in Nonce and Timestamp. The timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
  • oauth_nonce - As defined in Nonce and Timestamp. A nonce is a random string, uniquely generated for each request.
  • oauth_version - The optional OAuth version. If present, value must be 1.0.
  • oauth_client_ip - The optional IP address of the client responsible for the request. ODS makes sure that the client making each request is the same. Normally there is no need to specify the client IP since one client will make all the calls. However, if the client is only a proxy for other clients the IPs might differ which would require the real client's IP to be specified here and above.

Example Request to get user details via user.info() (query parameters have been wrapped for readability):

http://web.ods.openlinksw.com/ods/api/user.info
?oauth_version=1.0
&oauth_nonce=d57640869b994b2d51bf9800229c4997
&oauth_timestamp=1201873935
&oauth_consumer_key=f756023be5ff1f20881cf8fe398069f3976b2304
&oauth_token=8c03b3da93480ca4728cc1194d6d03962f3bb5bb
&oauth_signature_method=HMAC-SHA1
&oauth_signature=X3K4lr9bJVz5YLnnyJDkykQZivY%3D

Example Response (wrapped for readability):

<user>
<uid>127</uid>
<iri>http://demo.openlinksw.com/dataspace/person/demo#this</iri>
<name>demo</name>
<nickName>demo</nickName>
<fullName>Demo User</fullName>
</user>