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

import module namespace oauth = "http://www.zorba-xquery.com/modules/oauth/client";

OAuth Client Module 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.

Stephanie Russell

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

• the XQuery module can be found here.

Imported modules:

• http://www.zorba-xquery.com/modules/random
• http://www.zorba-xquery.com/modules/cryptography/hmac
• http://expath.org/ns/http-client
• http://www.zorba-xquery.com/modules/datetime
• http://www.zorba-xquery.com/modules/oauth/error

Imported schemas:

• http://expath.org/ns/http-client

For more details please also see:

• OAuth

	access-token ( $request as element(request)+ ) as element(*)+ 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.
	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, $oauth-verifier as xs:string?, $method as xs:string, $token-request-uri as xs:string, $additional-parameters as xs:string? ) as element(*)+ 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.
	additional-parameters ( $request as element(*)+ ) as element(*)? This function finds the server-specific parameters.
	authorization-header ( $params as element(*)+, $realm as xs:string, $signature as xs:string ) as xs:string This function formats the authorization header.
	http-request ( $consumer-secret as xs:string, $method as xs:string, $oauth-token-secret as xs:string?, $params as element(*)+, $realm as xs:string?, $signature-method as xs:string, $url as xs:string) ) This function makes the request, and sends it to the specified url using the specified http request method.
	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 element(*)+, $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 as element(*)+, $string as xs:string ) as xs:string This function returns the string value of the parameters whose key matches a $string input.
	parse-parameters ( $input as xs:string ) as element(*)+ This function takes an input string and parses the parameters into parameter elements.
	protected-resource ( $protected-resource as element(http:request), $request as element(request)+ ) as element(*)+ This function allows the client access to the protected resources of the user.
	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, $method as xs:string, $url as xs:string, $additional-parameters as xs:string?) ) This function allows the client access to the protected resources of the user.
	request-token ( $request as element(request)+ ) as element(*)+ 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 ( $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 xs:string? ) as element(*)+ 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.
	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.
	signature-base-string ( $http-method as xs:string, $base-uri as xs:string, $params as element(*)+ ) 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.
	timestamp ( ) as xs:decimal The timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT.

access-token

declare %ann:sequential %ann:nondeterministic function oauth:access-token (
            $request as element(request)+ 
 ) as element(*)+

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.

• $request request element containing the client's request

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

• http://tools.ietf.org/html/rfc5849#section-2.3

access-token

declare %ann:sequential %ann: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, 
            $oauth-verifier as xs:string?, 
            $method as xs:string, 
            $token-request-uri as xs:string, 
            $additional-parameters as xs:string? 
 ) as element(*)+

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.

• $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
• $oauth-verifier The verification code
• $additional-parameters Parameters specific to a certain step (access-token) of the OAuth authorization

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

• http://tools.ietf.org/html/rfc5849#section-2.3

additional-parameters

declare function oauth:additional-parameters (
            $request as element(*)+ 
 ) as element(*)?

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

• $request element containing the client's request

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

• http://tools.ietf.org/html/rfc5849#section-2.1

authorization-header

declare function oauth:authorization-header (
            $params as element(*)+, 
            $realm as xs:string, 
            $signature as xs:string 
 ) as xs:string

This function formats the authorization header.

• $params Element containing OAuth specific parameters
• $realm Realm that defines the protection space
• $signature string signed signature

• string authorization header

• http://tools.ietf.org/html/rfc5849#section-3.5.1

http-request

declare %ann:sequential function oauth:http-request (
            $consumer-secret as xs:string, 
            $method as xs:string, 
            $oauth-token-secret as xs:string?, 
            $params as element(*)+, 
            $realm as xs:string?, 
            $signature-method as xs:string, 
            $url as xs:string) 
 )

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

• $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

• -

• http://tools.ietf.org/html/rfc5849#section-3.1

key

declare 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.

• $oauth-consumer-secret Client credential referred to as the "consumer secret"
• $oauth-token-secret Temporary credential referred to as the "oauth token secret"

• String signing key

• http://tools.ietf.org/html/rfc5849#section-3.4.2

nonce

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

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

• random string

• http://tools.ietf.org/html/rfc5849#section-3.3

normalization

declare function oauth:normalization (
            $params as element(*)+, 
            $divide as xs:string, 
            $option as xs:string?, 
            $comma as xs:string 
 ) as xs:string

This function normalizes parameters into a single string.

• $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

• string formatted specifically for the authorization header, or for parameterization

• http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2

parameters

declare function oauth:parameters (
            $params as element(*)+, 
            $string as xs:string 
 ) as xs:string

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

• $params element parameters
• $string string as the "key" name

• string value of the parameter with key $string

parse-parameters

declare function oauth:parse-parameters (
            $input as xs:string 
 ) as element(*)+

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

• $input string of parameters to be parsed into element parameters

• element parameters

protected-resource

declare %ann:sequential %ann:nondeterministic function oauth:protected-resource (
            $protected-resource as element(http:request), 
            $request as element(request)+ 
 ) as element(*)+

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

• $protected-resource (Not schema-validated) http:request element with http method and href.
• $request request element containing the client's request

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

• http://tools.ietf.org/html/rfc5849#section-3

protected-resource

declare %ann:sequential %ann: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, 
            $method as xs:string, 
            $url as xs:string, 
            $additional-parameters as xs:string?) 
 )

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

• $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

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

• http://tools.ietf.org/html/rfc5849#section-3

request-token

declare %ann:sequential %ann:nondeterministic function oauth:request-token (
            $request as element(request)+ 
 ) as element(*)+

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.

• $request request element containing the client's request

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

• http://tools.ietf.org/html/rfc5849#section-2.1

request-token

declare %ann:sequential %ann: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 xs:string? 
 ) as element(*)+

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.

• $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

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

• http://tools.ietf.org/html/rfc5849#section-2.1

signature

declare 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.

• $base-string signature base string
• $oauth-signature-method string signing method
• $key string signing key

• signature base string formatted to create the signature

• http://tools.ietf.org/html/rfc5849#section-3.4

signature-base-string

declare function oauth:signature-base-string (
            $http-method as xs:string, 
            $base-uri as xs:string, 
            $params as element(*)+ 
 ) 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.

• $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

• signature base string formatted to create the signature

• http://tools.ietf.org/html/rfc5849#section-3.4.1

timestamp

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

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

• integer time in seconds since Unix epoch

• http://tools.ietf.org/html/rfc5849#section-3.3