Poco::Net

class OAuth10Credentials

File Information

Library: Net
Package: OAuth
Header: Poco/Net/OAuth10Credentials.h

Description

This class implements OAuth 1.0A authentication for HTTP requests, according to RFC 5849.

Only PLAINTEXT and HMAC-SHA1 signature methods are supported. The RSA-SHA1 signature method is not supported.

The OAuth10Credentials can be used to sign a client request, as well as to verify the signature of a request on the server.

To sign a client request, using a known consumer (client) key, consumer (client) secret, OAuth token and token secret:

  1. Create an OAuth10Credentials object using all four credentials, either using the four argument constructor, or by using the default constructor and setting the credentials using the setter methods.
  2. Create a URI containing the full request URI.
  3. Create an appropriate HTTPRequest object.
  4. Optionally, create a HTMLForm object containing additional parameters to sign.
  5. Sign the request by calling authenticate(). This will add an OAuth Authorization header to the request.
  6. Send the request using a HTTPClientSession.

To request the OAuth request token from a server, using only the consumer (client) key and consumer (client) secret:

  1. Create an OAuth10Credentials object using the two consumer credentials, either using the two argument constructor, or by using the default constructor and setting the credentials using the setter methods.
  2. Specify the callback URI using setCallback().
  3. Create a URI containing the full request URI to obtain the token.
  4. Create an appropriate HTTPRequest object.
  5. Sign the request by calling authenticate(). This will add an OAuth Authorization header to the request.
  6. Send the request using a HTTPClientSession.
  7. The response will contain the request token and request token secret. These can be extracted from the response body using a HTMLForm object.

Requesting the access token and secret (temporary credentials) from the server is analogous to signing a client request using consumer key, consumer secret, request token and request token secret. The server response will contain the access token and access token secret, which can again be extracted from the response body using a HTMLForm object.

To verify a request on the server:

  1. Create an OAuth10Credentials object using the constructor taking a HTTPRequest object. This will extract the consumer key and token (if provided).
  2. Provide the consumer secret and token secret (if required) matching the consumer key and token to the OAuth10Credentials object using the setter methods.
  3. Create an URI object containing the full request URI.
  4. Call verify() to verify the signature.
  5. If verification was successful, and the request was a request for a request (temporary) token, call getCallback() to obtain the callback URI provided by the client.

Member Summary

Member Functions: authenticate, createNonce, createSignature, getCallback, getConsumerKey, getConsumerSecret, getRealm, getToken, getTokenSecret, nonceAndTimestampForTesting, percentEncode, setCallback, setConsumerKey, setConsumerSecret, setRealm, setToken, setTokenSecret, signHMACSHA1, signPlaintext, verify

Enumerations

SignatureMethod

OAuth 1.0A Signature Method.

SIGN_PLAINTEXT

OAuth 1.0A PLAINTEXT signature method

SIGN_HMAC_SHA1

OAuth 1.0A HMAC-SHA1 signature method

Constructors

OAuth10Credentials

OAuth10Credentials();

Creates an empty OAuth10Credentials object.

OAuth10Credentials

explicit OAuth10Credentials(
    const HTTPRequest & request
);

Creates an OAuth10Credentials object from a HTTPRequest object.

Extracts consumer key and token (if available) from the Authorization header.

Throws a NotAuthenticatedException if the request does not contain OAuth 1.0 credentials.

OAuth10Credentials

OAuth10Credentials(
    const std::string & consumerKey,
    const std::string & consumerSecret
);

Creates an OAuth10Credentials object with the given consumer key and consumer secret.

The token and tokenSecret will be left empty.

OAuth10Credentials

OAuth10Credentials(
    const std::string & consumerKey,
    const std::string & consumerSecret,
    const std::string & token,
    const std::string & tokenSecret
);

Creates an OAuth10Credentials object with the given consumer key and consumer secret, as well as token and token secret.

Destructor

~OAuth10Credentials

~OAuth10Credentials();

Destroys the OAuth10Credentials.

Member Functions

authenticate

void authenticate(
    HTTPRequest & request,
    const Poco::URI & uri,
    SignatureMethod method = SIGN_HMAC_SHA1
);

Adds an OAuth 1.0A Authentication header to the given request, using the given signature method.

authenticate

void authenticate(
    HTTPRequest & request,
    const Poco::URI & uri,
    const Poco::Net::HTMLForm & params,
    SignatureMethod method = SIGN_HMAC_SHA1
);

Adds an OAuth 1.0A Authentication header to the given request, using the given signature method.

getCallback inline

const std::string & getCallback() const;

Returns the callback URI.

getConsumerKey inline

const std::string & getConsumerKey() const;

Returns the consumer key.

getConsumerSecret inline

const std::string & getConsumerSecret() const;

Returns the consumer secret.

getRealm inline

const std::string & getRealm() const;

Returns the optional realm to be included in the Authorization header.

getToken inline

const std::string & getToken() const;

Returns the token.

getTokenSecret inline

const std::string & getTokenSecret() const;

Returns the token secret.

nonceAndTimestampForTesting

void nonceAndTimestampForTesting(
    const std::string & nonce,
    const std::string & timestamp
);

Sets the nonce and timestamp to a wellknown value.

For use by testsuite only, to test the signature algorithm with wellknown inputs.

In normal operation, the nonce is a random value computed by createNonce() and the timestamp is taken from the system time.

setCallback

void setCallback(
    const std::string & uri
);

Sets the callback URI.

setConsumerKey

void setConsumerKey(
    const std::string & consumerKey
);

Sets the consumer key.

setConsumerSecret

void setConsumerSecret(
    const std::string & consumerSecret
);

Sets the consumer secret.

setRealm

void setRealm(
    const std::string & realm
);

Sets the optional realm to be included in the Authorization header.

setToken

void setToken(
    const std::string & token
);

Sets the token.

setTokenSecret

void setTokenSecret(
    const std::string & tokenSecret
);

Sets the token.

verify

bool verify(
    const HTTPRequest & request,
    const Poco::URI & uri
);

Verifies the signature of the given request.

The consumer key, consumer secret, token and token secret must have been set.

Returns true if the signature is valid, otherwise false.

Throws a NotAuthenticatedException if the request does not contain OAuth credentials, or in case of an unsupported OAuth version or signature method.

verify

bool verify(
    const HTTPRequest & request,
    const Poco::URI & uri,
    const Poco::Net::HTMLForm & params
);

Verifies the signature of the given request.

The consumer key, consumer secret, token and token secret must have been set.

Returns true if the signature is valid, otherwise false.

Throws a NotAuthenticatedException if the request does not contain OAuth credentials, or in case of an unsupported OAuth version or signature method.

createNonce protected

std::string createNonce() const;

Creates a nonce, which is basically a Base64-encoded 32 character random string, with non-alphanumeric characters removed.

createSignature protected

std::string createSignature(
    const Poco::Net::HTTPRequest & request,
    const std::string & uri,
    const Poco::Net::HTMLForm & params,
    const std::string & nonce,
    const std::string & timestamp
) const;

Creates a OAuth signature for the given request and its parameters, according to <https://dev.twitter.com/docs/auth/creating-signature>.

percentEncode protected static

static std::string percentEncode(
    const std::string & str
);

Percent-encodes the given string according to Twitter API's rules, given in <https://dev.twitter.com/docs/auth/percent-encoding-parameters>.

signHMACSHA1 protected

void signHMACSHA1(
    Poco::Net::HTTPRequest & request,
    const std::string & uri,
    const Poco::Net::HTMLForm & params
) const;

Signs the given HTTP request according to OAuth 1.0A HMAC-SHA1 signature method.

signPlaintext protected

void signPlaintext(
    Poco::Net::HTTPRequest & request
) const;

Signs the given HTTP request according to OAuth 1.0A PLAINTEXT signature method.

Variables

SCHEME static

static const std::string SCHEME;

Securely control IoT edge devices from anywhere   Connect a Device