http://www.zorba-xquery.com/modules/oauth/client

Description

Before using any of the functions below please remember to import the module namespace:

import module namespace oauth = "http://www.zorba-xquery.com/modules/oauth/client";
This module provides the functions necessary to acquire access to the personal resources of a user through the open standard called OAuth. The application/mashup creator does not need to know the specifics of OAuth to use this module.

Module code

Here is the actual XQuery module code.

Imported Schemas

Please note that the schemas are not automatically imported in the modules that import this module.

In order to import and use the schemas, please add:

import schema namespace http =  "http://expath.org/ns/http-client";
import schema namespace sp =  "http://www.zorba-xquery.com/schemas/oauth/service-provider";
import schema namespace p =  "http://www.zorba-xquery.com/schemas/oauth/parameters";

Imported modules

See also

Authors

Stephanie Russell

Version Declaration

xquery version "3.0" encoding "utf-8";

Namespaces

anhttp://zorba.io/annotations
base64http://zorba.io/modules/base64
fhttp://zorba.io/features
hmachttp://zorba.io/modules/hmac
httphttp://expath.org/ns/http-client
http-clienthttp://expath.org/ns/http-client
oauthhttp://www.zorba-xquery.com/modules/oauth/client
oerrhttp://www.zorba-xquery.com/modules/oauth/error
ophttp://zorba.io/options/features
phttp://www.zorba-xquery.com/schemas/oauth/parameters
rahttp://zorba.io/modules/random
sphttp://www.zorba-xquery.com/schemas/oauth/service-provider
verhttp://zorba.io/options/versioning

Function Summary

service-provider($consumer-key as xs:string, $consumer-secret as xs:string, $signature-method as xs:string, $realm as xs:string, $authorize-url as xs:string, $request-token-method as xs:string, $request-token-url as xs:string, $request-token-callback-url as xs:string, $access-token-method as xs:string, $access-token-url as xs:string) as schema-element(sp:service-provider)

Utility function to build a service provider object.

parameters($name as xs:string, $value as xs:string) as element(p:parameters)

Create an OAuth Parameters instance.

add-parameter($parameters as schema-element(p:parameters)?, $name as xs:string, $value as xs:string) as schema-element(p:parameters)

Adds an OAuth parameter to an OAuth Parameters instance.

parameter($params as schema-element(p:parameters), $string as xs:string) as xs:string

This function returns the string value of the parameters whose key matches a $string input.

request-token($service-provider as schema-element(sp:service-provider)) as schema-element(p:parameters)

This function allows the client to obtain a set of temporary credentials from the service provider by making an authenticated HTTP request to the Temporary Credential Request endpoint.

request-token($service-provider as schema-element(sp:service-provider), $parameters as schema-element(p:parameters)?) as schema-element(p:parameters)

This function allows the client to obtain a set of temporary credentials from the service provider by making an authenticated HTTP request to the Temporary Credential Request endpoint.

access-token($service-provider as schema-element(sp:service-provider), $parameters as schema-element(p:parameters)) as schema-element(p:parameters)

This function allows the client to obtain a set of token credentials from the service provider by making an authenticated HTTP request to the Token Request endpoint.

protected-resource($protected-resource as schema-element(http:request), $service-provider as schema-element(sp:service-provider), $parameters as schema-element(p:parameters)) as item()*

This function allows the client access to the protected resources of the user.

timestamp() as xs:decimal

The timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT.

key($oauth-consumer-secret as xs:string, $oauth-token-secret as xs:string?) as xs:string

This function returns a string key which is the client and temporary credential concatenated with an ampersand.

nonce() as xs:string

This function should return a new UUID every time the function is invoked.

normalization($params as schema-element(p:parameters), $divide as xs:string, $option as xs:string?, $comma as xs:string) as xs:string

This function normalizes parameters into a single string.

authorization-header($params as element(p:parameters), $realm as xs:string, $signature as xs:string) as xs:string

This function formats the authorization header.

signature-base-string($http-method as xs:string, $base-uri as xs:string, $params as element(p:parameters)) as xs:string

This function constructs the Signature Base String; a consistent, reproducible concatenation of several of the HTTP request elements into a single string.

signature($base-string as xs:string, $oauth-signature-method as xs:string, $key as xs:string) as xs:string

This function generates a signature string which becomes the "oauth_signature" parameter.

parse-parameters($input as xs:string) as element(p:parameters)

This function takes an input string and parses the parameters into parameter elements.

http-request($consumer-secret as xs:string, $protected-resource as element(http:request), $oauth-token-secret as xs:string?, $params as element(p:parameters), $realm as xs:string?, $signature-method as xs:string) as item()*

This function makes the request, and sends it to the specified url using the specified http request method.

format-request($consumer-key as xs:string, $consumer-secret as xs:string, $protected-resource as element(http:request), $oauth-token as xs:string?, $oauth-token-secret as xs:string?, $realm as xs:string?, $signature-method as xs:string, $additional-parameters as element(p:parameters)?, $format-params as xs:boolean) as item()*

This function creates the parameters to be given to the http-request function.

format-request($consumer-key as xs:string, $consumer-secret as xs:string, $protected-resource as element(http:request), $oauth-token as xs:string?, $oauth-token-secret as xs:string?, $realm as xs:string?, $signature-method as xs:string, $additional-parameters as element(p:parameters)?) as item()*

additional-parameters($parameters as element(p:parameters)?) as element(p:parameters)?

This function finds the server-specific parameters.

request-token($consumer-key as xs:string, $consumer-secret as xs:string, $signature-method as xs:string, $method as xs:string, $realm as xs:string, $temporary-credential-request as xs:string, $callback-url as xs:string, $additional-parameters as element(p:parameters)?) as element(p:parameters)

This function allows the client to obtain a set of temporary credentials from the service provider by making an authenticated HTTP request to the Temporary Credential Request endpoint.

access-token($consumer-key as xs:string, $consumer-secret as xs:string, $signature-method as xs:string, $realm as xs:string, $oauth-token as xs:string, $oauth-token-secret as xs:string, $method as xs:string, $token-request-uri as xs:string, $additional-parameters as element(p:parameters)?) as element(p:parameters)

This function allows the client to obtain a set of token credentials from the service provider by making an authenticated HTTP request to the Token Request endpoint.

protected-resource($consumer-key as xs:string, $consumer-secret as xs:string, $signature-method as xs:string, $oauth-token as xs:string, $oauth-token-secret as xs:string, $realm as xs:string, $protected-resource as schema-element(http:request), $additional-parameters as element(p:parameters)?) as item()*

This function allows the client access to the protected resources of the user.

Functions

service-provider#10

declare function oauth:service-provider(
    $consumer-key as xs:string,
    $consumer-secret as xs:string,
    $signature-method as xs:string,
    $realm as xs:string,
    $authorize-url as xs:string,
    $request-token-method as xs:string,
    $request-token-url as xs:string,
    $request-token-callback-url as xs:string,
    $access-token-method as xs:string,
    $access-token-url as xs:string
) as schema-element(sp:service-provider)
Utility function to build a service provider object. This object contains the information required by the OAuth client to interact with an OAuth service provider. For instance the following expression: 
 let $consumer-key     := "#"
 let $consumer-secret  := "#"
 let $signature-method := "HMAC-SHA1"
 let $realm            := "twitter.com"
 let $authorize-url    := "http://api.twitter.com/oauth/authorize"
 let $request-token-method := "POST"
 let $request-token-url := "https://twitter.com/oauth/request_token"
 let $request-token-callback-url := "https://twitter.com/oauth/request_token"
 let $access-token-method := "POST"
 let $access-token-url := "https://api.twitter.com/oauth/access_token"
 return oauth:service-provider(
   $consumer-key, $consumer-secret, $signature-method,
   $realm, $authorize-url, $request-token-method,
   $request-token-url, $request-token-callback-url,
   $access-token-method, $access-token-url
 )
Will return the following XML schema instance:

Parameters

  • $consumer-key

    Client Identifier, also known as the consumer-key

  • $consumer-secret

    Client Shared-Secret, also known as the consumer-secret

  • $signature-method

    Method with which the signing key is signed (typically HMAC-SHA1)

  • $realm

    Realm that defines the protection space

  • $authorize-url

    authorize-url

  • $request-token-method

    request-token-method

  • $request-token-url

    request-token-url

  • $request-token-callback-url

    request-token-callback-url

  • $access-token-method

    access-token-method

  • $access-token-url

    access-token-url

Returns

  • schema-element(sp:service-provider)

    instance of the OAuth service provider XML schema.

parameters#2

declare function oauth:parameters(
    $name as xs:string,
    $value as xs:string
) as element(p:parameters)
Create an OAuth Parameters instance. Instances of OAuth parameters are used to contain value/pair data such as oauth_token and oauth_token_secret. For instance the following code snippet: 
  oauth:parameters("oauth_token", "#")
Returns the following XML schema instance:

Parameters

  • $name

    parameter name

  • $value

    parameter value

Returns

  • element(p:parameters)

    instance of the OAuth parameters XML schema.

add-parameter#3

declare function oauth:add-parameter(
    $parameters as schema-element(p:parameters)?,
    $name as xs:string,
    $value as xs:string
) as schema-element(p:parameters)
Adds an OAuth parameter to an OAuth Parameters instance. Instances of OAuth parameters are used to contain value/pair data such as oauth_token and oauth_token_secret. For instance the following code snippet: 
  let $params := oauth:parameters("oauth_token", "#")
  let $params := oauth:add-parameter($params, "oauth_token_secret", "#")
  return $params
Returns the following XML schema instance:

Parameters

  • $parameters

    parameters

  • $name

    parameter name

  • $value

    parameter value

Returns

  • schema-element(p:parameters)

    instance of the OAuth parameters XML schema.

parameter#2

declare function oauth:parameter(
    $params as schema-element(p:parameters),
    $string as xs:string
) as xs:string

This function returns the string value of the parameters whose key matches a $string input.

Parameters

  • $params

    element parameters

  • $string

    string as the "key" name

Returns

  • xs:string

    string value of the parameter with key $string let $params := oauth:parameters("oauth_token", "token") let $params := oauth:add-parameter($params, "oauth_token_secret", "secret") let $token-secret := oauth:parameter($params, "oauth_token_secret") return $token-secret

request-token#1

declare %an:sequential function oauth:request-token(
    $service-provider as schema-element(sp:service-provider)
) as schema-element(p:parameters)
This function allows the client to obtain a set of temporary credentials from the service provider by making an authenticated HTTP request to the Temporary Credential Request endpoint. This function is provided for convenience for request-token#2. Invoking this function is equivalent to: 
 oauth:request-token($service-provider, ())

Parameters

  • $service-provider

    Information about the service provider

Returns

  • schema-element(p:parameters)

    temporary credentials correctly parsed as parameter elements, or an error if http response status is not 200 OK

request-token#2

declare %an:sequential function oauth:request-token(
    $service-provider as schema-element(sp:service-provider),
    $parameters as schema-element(p:parameters)?
) as schema-element(p:parameters)

This function allows the client to obtain a set of temporary credentials from the service provider by making an authenticated HTTP request to the Temporary Credential Request endpoint. This function is provided for convenience.

Parameters

  • $service-provider

    Information about the service provider

  • $parameters

    Additionnal parameters to the request

Returns

  • schema-element(p:parameters)

    temporary credentials correctly parsed as parameter elements, or an error if http response status is not 200 OK let $twitter-config := oauth:service-provider(...) let $additional-parameter := oauth:parameters("foo", "bar") let $tokens := oauth:request-token($twitter-config, $additional-parameter) let $token := oauth:parameter($tokens, "oauth_token") let $token-secret := oauth:parameter($tokens, "oauth_token_secret") ...

access-token#2

declare %an:sequential function oauth:access-token(
    $service-provider as schema-element(sp:service-provider),
    $parameters as schema-element(p:parameters)
) as schema-element(p:parameters)

This function allows the client to obtain a set of token credentials from the service provider by making an authenticated HTTP request to the Token Request endpoint. This function is provided for convenience.

Parameters

  • $service-provider

    Contains service provider information

  • $parameters

    parameters

Returns

  • schema-element(p:parameters)

    token credentials correctly parsed as parameter elements, or an error if http response status is not 200 OK let $service-provider := oauth:service-provider(...) let $parameters := oauth:parameters("oauth_token", "#") let $parameters := oauth:add-parameter($parameters, "oauth_token_secret", "#") let $tokens := oauth:access-token($service-provider, $parameters) ...

protected-resource#3

declare %an:sequential function oauth:protected-resource(
    $protected-resource as schema-element(http:request),
    $service-provider as schema-element(sp:service-provider),
    $parameters as schema-element(p:parameters)
) as item()*

This function allows the client access to the protected resources of the user. This function is provided for convenience.

Parameters

  • $protected-resource

    (Not schema-validated) http:request element with http method and href.

  • $service-provider

    Information about the service provider

  • $parameters

    parameters

Returns

  • item()*

    protected resources parsed as parameter elements, or an error if http response status is not 200 OK let $tokens := oauth:parameters("oauth_token", "#") let $tokens := oauth:add-parameter($tokens, "oauth_token_secret", "#") let $service-provider := oauth:service-provider(...) let $request := validate { } return oauth:protected-resource($request, $service-provider, $tokens)

timestamp#0

declare %:private %an:nondeterministic function oauth:timestamp() as xs:decimal

The timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT.

Returns

  • xs:decimal

    integer time in seconds since Unix epoch

key#2

declare %:private function oauth:key(
    $oauth-consumer-secret as xs:string,
    $oauth-token-secret as xs:string?
) as xs:string

This function returns a string key which is the client and temporary credential concatenated with an ampersand.

Parameters

  • $oauth-consumer-secret

    Client credential referred to as the "consumer secret"

  • $oauth-token-secret

    Temporary credential referred to as the "oauth token secret"

Returns

  • xs:string

    String signing key

nonce#0

declare %:private %an:nondeterministic function oauth:nonce() as xs:string

This function should return a new UUID every time the function is invoked.

Returns

  • xs:string

    random string

normalization#4

declare %:private function oauth:normalization(
    $params as schema-element(p:parameters),
    $divide as xs:string,
    $option as xs:string?,
    $comma as xs:string
) as xs:string

This function normalizes parameters into a single string.

Parameters

  • $params

    Element containing OAuth specific parameters

  • $divide

    String, usually an equal sign(=)

  • $option

    Optional string, quotation mark '"' in the creation of the authorization header

  • $comma

    String, typically a comma (,) in the authorization header

Returns

  • xs:string

    string formatted specifically for the authorization header, or for parameterization

authorization-header#3

declare %:private function oauth:authorization-header(
    $params as element(p:parameters),
    $realm as xs:string,
    $signature as xs:string
) as xs:string

This function formats the authorization header.

Parameters

  • $params

    Element containing OAuth specific parameters

  • $realm

    Realm that defines the protection space

  • $signature

    string signed signature

Returns

  • xs:string

    string authorization header

signature-base-string#3

declare %:private function oauth:signature-base-string(
    $http-method as xs:string,
    $base-uri as xs:string,
    $params as element(p:parameters)
) as xs:string

This function constructs the Signature Base String; a consistent, reproducible concatenation of several of the HTTP request elements into a single string.

Parameters

  • $http-method

    string method for posting the request to the url

  • $base-uri

    string base-uri for request, access, or protected resources

  • $params

    Element containing OAuth specific parameters

Returns

  • xs:string

    signature base string formatted to create the signature

signature#3

declare %:private function oauth:signature(
    $base-string as xs:string,
    $oauth-signature-method as xs:string,
    $key as xs:string
) as xs:string

This function generates a signature string which becomes the "oauth_signature" parameter. The service provider verifies the signature as specified for each method.

Parameters

  • $base-string

    signature base string

  • $oauth-signature-method

    string signing method

  • $key

    string signing key

Returns

  • xs:string

    signature base string formatted to create the signature

parse-parameters#1

declare %:private function oauth:parse-parameters(
    $input as xs:string
) as element(p:parameters)

This function takes an input string and parses the parameters into parameter elements.

Parameters

  • $input

    string of parameters to be parsed into element parameters

Returns

  • element(p:parameters)

    element parameters

http-request#6

declare %:private %an:sequential function oauth:http-request(
    $consumer-secret as xs:string,
    $protected-resource as element(http:request),
    $oauth-token-secret as xs:string?,
    $params as element(p:parameters),
    $realm as xs:string?,
    $signature-method as xs:string
) as item()*

This function makes the request, and sends it to the specified url using the specified http request method.

Parameters

  • $consumer-secret

    Client Shared-Secret, also known as the consumer-secret

  • $method

    HTTP request method (e.g., "GET", "POST", etc.)

  • $oauth-token-secret

    the temporary credentials shared-secret

  • $params

    Element containing OAuth specific parameters

  • $realm

    Realm that defines the protection space

  • $signature-method

    Method with which the signing key is signed (typically HMAC-SHA1)

  • $url

    Target URL

Returns

  • item()*

    HTTP response.

format-request#9

declare %:private %an:sequential function oauth:format-request(
    $consumer-key as xs:string,
    $consumer-secret as xs:string,
    $protected-resource as element(http:request),
    $oauth-token as xs:string?,
    $oauth-token-secret as xs:string?,
    $realm as xs:string?,
    $signature-method as xs:string,
    $additional-parameters as element(p:parameters)?,
    $format-params as xs:boolean
) as item()*

This function creates the parameters to be given to the http-request function. It parses the response into parameter elements if the response status is 200 (OK).

Parameters

  • $consumer-key

    Client Identifier, also known as the consumer-key

  • $consumer-secret

    Client Shared-Secret, also known as the consumer-secret

  • $method

    HTTP request method (e.g., "GET", "POST", etc.)

  • $oauth-token

    The temporary credentials identifier

  • $oauth-token-secret

    The temporary credentials shared-secret

  • $realm

    Realm that defines the protection space

  • $signature-method

    Method with which the signing key is signed (typically HMAC-SHA1)

  • $url

    Target URL

  • $additional-parameters

    Parameters specific to a certain step (request-token, authorize, access-token, protected-resource) of the OAuth authorization

Returns

  • item()*

    correctly parsed parameters, or an error if http response status is not 200 OK

Errors

  • XQP0021(oerr:OC003)

    if we receive http 401 error from the server.

  • XQP0021(oerr:OC004)

    if we receive http 500 error from the server.

format-request#8

declare %:private %an:sequential function oauth:format-request(
    $consumer-key as xs:string,
    $consumer-secret as xs:string,
    $protected-resource as element(http:request),
    $oauth-token as xs:string?,
    $oauth-token-secret as xs:string?,
    $realm as xs:string?,
    $signature-method as xs:string,
    $additional-parameters as element(p:parameters)?
) as item()*

Returns

  • item()*

additional-parameters#1

declare %:private function oauth:additional-parameters(
    $parameters as element(p:parameters)?
) as element(p:parameters)?

This function finds the server-specific parameters. The specification states, "Servers MAY specify additional parameters..."

Parameters

  • $request

    element containing the client's request

Returns

  • element(p:parameters)?

    may return parsed parameters or empty sequence if there were no server specific parameters

request-token#8

declare %:private %an:sequential %an:nondeterministic function oauth:request-token(
    $consumer-key as xs:string,
    $consumer-secret as xs:string,
    $signature-method as xs:string,
    $method as xs:string,
    $realm as xs:string,
    $temporary-credential-request as xs:string,
    $callback-url as xs:string,
    $additional-parameters as element(p:parameters)?
) as element(p:parameters)

This function allows the client to obtain a set of temporary credentials from the service provider by making an authenticated HTTP request to the Temporary Credential Request endpoint.

Parameters

  • $consumer-key

    Client Identifier, also known as the consumer-key

  • $consumer-secret

    Client Shared-Secret, also known as the consumer-secret

  • $signature-method

    Method with which the signing key is signed (typically HMAC-SHA1)

  • $method

    HTTP request method (e.g., "GET", "POST", etc.) HTTP request method

  • $realm

    Realm that defines the protection space

  • $temporary-credential-request

    Target url for temporary credentials request

  • $callback-url

    Service provider redirects the user to this url after authorization. The parameter value MUST be set to "oob" (case sensitive), to indicate an out-of-band configuration.

  • $additional-parameters

    Parameters specific to a certain step (request-token) of the OAuth authorization

Returns

  • element(p:parameters)

    temporary credentials correctly parsed as parameter elements, or an error if http response status is not 200 OK

access-token#9

declare %:private %an:sequential %an:nondeterministic function oauth:access-token(
    $consumer-key as xs:string,
    $consumer-secret as xs:string,
    $signature-method as xs:string,
    $realm as xs:string,
    $oauth-token as xs:string,
    $oauth-token-secret as xs:string,
    $method as xs:string,
    $token-request-uri as xs:string,
    $additional-parameters as element(p:parameters)?
) as element(p:parameters)

This function allows the client to obtain a set of token credentials from the service provider by making an authenticated HTTP request to the Token Request endpoint.

Parameters

  • $consumer-key

    Client Identifier, also known as the consumer-key

  • $consumer-secret

    Client Shared-Secret, also known as the consumer-secret

  • $signature-method

    Method with which the signing key is signed (typically HMAC-SHA1)

  • $method

    HTTP request method (e.g., "GET", "POST", etc.)

  • $realm

    Realm that defines the protection space

  • $token-request-uri

    Target uri for token credentials request

  • $oauth-token

    The temporary credentials identifier

  • $oauth-token-secret

    the temporary credentials shared-secret

  • $additional-parameters

    Parameters specific to a certain step (access-token) of the OAuth authorization

Returns

  • element(p:parameters)

    token credentials correctly parsed as parameter elements, or an error if http response status is not 200 OK

protected-resource#8

declare %:private %an:sequential %an:nondeterministic function oauth:protected-resource(
    $consumer-key as xs:string,
    $consumer-secret as xs:string,
    $signature-method as xs:string,
    $oauth-token as xs:string,
    $oauth-token-secret as xs:string,
    $realm as xs:string,
    $protected-resource as schema-element(http:request),
    $additional-parameters as element(p:parameters)?
) as item()*

This function allows the client access to the protected resources of the user.

Parameters

  • $consumer-key

    Client Identifier, also known as the consumer-key

  • $consumer-secret

    Client Shared-Secret, also known as the consumer-secret

  • $signature-method

    Method with which the signing key is signed (typically HMAC-SHA1)

  • $method

    HTTP request method (e.g., "GET", "POST", etc.)

  • $realm

    Realm that defines the protection space

  • $url

    Target URL

  • $oauth-token

    The temporary credentials identifier

  • $oauth-token-secret

    the temporary credentials shared-secret

  • $additional-parameters

    Parameters specific to a certain step (protected-resource) of the OAuth authorization

Returns

  • item()*

    protected resources parsed as parameter elements, or an error if http response status is not 200 OK