OAuth 1.0a
const createOAuth1Client = require('@arangodb/foxx/oauth1');
The OAuth1 module provides abstractions over OAuth 1.0a providers likeTwitter, XING and Tumblr.
Examples
const router = createRouter();
const oauth1 = createOAuth1Client({
// We'll use Twitter for this example
requestTokenEndpoint: 'https://api.twitter.com/oauth/request_token',
authEndpoint: 'https://api.twitter.com/oauth/authorize',
accessTokenEndpoint: 'https://api.twitter.com/oauth/access_token',
activeUserEndpoint: 'https://api.twitter.com/1.1/account/verify_credentials.json',
clientId: 'keyboardcat',
clientSecret: 'keyboardcat'
});
module.context.use('/oauth1', router);
// See the user management example for setting up the
// sessions and users objects used in this example
router.use(sessions);
router.post('/auth', function (req, res) {
const url = req.reverse('oauth1_callback');
const oauth_callback = req.makeAbsolute(url);
const requestToken = oauth1.fetchRequestToken(oauth_callback);
if (requestToken.oauth_callback_confirmed !== 'true') {
res.throw(500, 'Could not fetch OAuth request token');
}
// Set request token cookie for five minutes
res.cookie('oauth1_request_token', requestToken.oauth_token, {ttl: 60 * 5});
// Redirect to the provider's authorization URL
res.redirect(303, oauth1.getAuthUrl(requestToken.oauth_token));
});
router.get('/auth', function (req, res) {
// Make sure CSRF cookie matches the URL
const expectedToken = req.cookie('oauth1_request_token');
if (!expectedToken || req.queryParams.oauth_token !== expectedToken) {
res.throw(400, 'CSRF mismatch.');
}
const authData = oauth1.exchangeRequestToken(
req.queryParams.oauth_token,
req.queryParams.oauth_verifier
);
const twitterToken = authData.oauth_token;
const twitterSecret = authData.oauth_token_secret;
// Fetch the active user's profile info
const profile = oauth1.fetchActiveUser(twitterToken, twitterSecret);
const twitterId = profile.screen_name;
// Try to find an existing user with the user ID
// (this requires the users collection)
let user = users.firstExample({twitterId});
if (user) {
// Update the twitterToken if it has changed
if (
user.twitterToken !== twitterToken ||
user.twitterSecret !== twitterSecret
) {
users.update(user, {twitterToken, twitterSecret});
}
} else {
// Create a new user document
user = {
username: `twitter:${twitterId}`,
twitterId,
twitterToken
}
const meta = users.save(user);
Object.assign(user, meta);
}
// Log the user in (this requires the session middleware)
req.session.uid = user._key;
req.session.twitterToken = authData.twitterToken;
req.session.twitterSecret = authData.twitterSecret;
req.sessionStorage.save(req.session);
// Redirect to the default route
res.redirect(303, req.makeAbsolute('/'));
}, 'oauth1_callback')
.queryParam('oauth_token', joi.string().optional())
.queryParam('oauth_verifier', joi.string().optional());
Creating an OAuth1.0a client
createOAuth1Client(options): OAuth1Client
Creates an OAuth1.0a client.
Arguments
- options:
Object
An object with the following properties:
- requestTokenEndpoint:
string
The fully-qualified URL of the provider’sTemporary Credentials Request endpoint.This URL is used to fetch the unauthenticated temporary credentials thatwill be used to generate the authorization redirect for the user.
- authEndpoint:
string
The fully-qualified URL of the provider’sResource Owner Authorization endpoint.This is the URL the user will be redirected to in order to authorize theOAuth consumer (i.e. your service).
- accessTokenEndpoint:
string
The fully-qualified URL of the provider’sToken Request endpoint.This URL is used to exchange the authenticated temporary credentialsreceived from the authorization redirect for the actual token credentialsthat can be used to make requests to the API server.
- activeUserEndpoint:
string
(optional)
The fully-qualified URL of the provider’s endpoint for fetching detailsabout the current user.
- clientId:
string
The application’s Client ID (or Consumer Key) for the provider.
- clientSecret:
string
The application’s Client Secret (or Consumer Secret) for the provider.
- signatureMethod:
string
(Default:"HMAC-SHA1"
)
The cryptographic method that will be used to sign OAuth 1.0a requests.Only "HMAC-SHA1-"
and "PLAINTEXT"
are supported at this time.
Note that many providers may not implement "PLAINTEXT"
as it exposes theClient Secret and oauth_token_secret
instead of generating a signature.
Returns an OAuth 1.0a client for the given provider.
Setting up OAuth 1.0a for Twitter
If you want to use Twitter as the OAuth 1.0a provider, use the following options:
- requestTokenEndpoint:
https://api.twitter.com/oauth/request_token
- authEndpoint:
https://api.twitter.com/oauth/authorize
- accessTokenEndpoint:
https://api.twitter.com/oauth/access_token
- activeUserEndpoint:
https://api.twitter.com/1.1/account/verify_credentials.json
You also need to obtain a client ID and client secret from Twitter:
- Create a regular account at Twitter or use anexisting account you own.
- Visit the Twitter Application Managementdashboard and sign in with your Twitter account.
- Click on Create New App and follow the instructions provided.The Callback URL should match your oauth_callback later. You may beprompted to add a mobile phone number to your account and verify it.
- Open the Keys and Access Tones tab, then note down the Consumer Key_and _Consumer Secret.
- Set the option clientId to the Consumer Key and the optionclientSecret to the Consumer Secret.Note that if you only need read-only access to public information, you can alsouse the clientId and clientSecret directlywithout OAuth 1.0a.
See Twitter REST API Reference Documentation.
Setting up OAuth 1.0a for XING
If you want to use XING as the OAuth 1.0a provider, use the following options:
- requestTokenEndpoint:
https://api.xing.com/v1/request_token
- authEndpoint:
https://api.xing.com/v1/authorize
- accessTokenEndpoint:
https://api.xing.com/v1/access_token
- activeUserEndpoint:
https://api.xing.com/v1/users/me
You also need to obtain a client ID and client secret from XING:
- Create a regular account at XING or use an existingaccount you own.
- Visit the XING Developer page and sign in withyour XING account.
- Click on Create app and note down the Consumer key and Consumer secret.
- Set the option clientId to the Consumer key and the optionclientSecret to the Consumer secret.See XING Developer Documentation.
Setting up OAuth 1.0a for Tumblr
If you want to use Tumblr as the OAuth 1.0a provider, use the following options:
- requestTokenEndpoint:
https://www.tumblr.com/oauth/request_token
- authEndpoint:
https://www.tumblr.com/oauth/authorize
- accessTokenEndpoint:
https://www.tumblr.com/oauth/access_token
- activeUserEndpoint:
https://api.tumblr.com/v2/user/info
You also need to obtain a client ID and client secret from Tumblr:
- Create a regular account at Tumblr or use anexisting account you own.
- Visit the Tumblr Applications dashboard.
- Click on Register application, then follow the instructions provided.The Default callback URL should match your oauth_callback later.
- Note down the OAuth Consumer Key and Secret Key. The secret may behidden by default.
- Set the option clientId to the OAuth Consumer Key and the optionclientSecret to the Secret Key.See Tumblr API Documentation.
Fetch an unauthenticated request token
oauth1.fetchRequestToken(oauth_callback, opts)
Fetches an oauth_token
that can be used to create an authorization URL thatredirects to the given oauth_callback
on confirmation.
Performs a POST response to the requestTokenEndpoint.
Throws an exception if the remote server responds with an empty response body.
Arguments
- oauth_callback:
string
The fully-qualified URL of your application’s OAuth 1.0a callback.
- opts:
Object
(optional)
An object with additional query parameters to include in the request.
See RFC 5849.
Returns the parsed response object.
Get the authorization URL
oauth1.getAuthUrl(oauth_token, opts): string
Generates the authorization URL for the authorization endpoint.
Arguments
- oauth_token:
string
The oauth_token
previously returned by fetchRequestToken
.
- opts: (optional)
An object with additional query parameters to add to the URL.
See RFC 5849.
Returns a fully-qualified URL for the authorization endpoint of the providerby appending the oauthtoken
and any additional arguments from _opts tothe authEndpoint.
Examples
const requestToken = oauth1.fetchRequestToken(oauth_callback);
if (requestToken.oauth_callback_confirmed !== 'true') {
throw new Error('Provider could not confirm OAuth 1.0 callback');
}
const authUrl = oauth1.getAuthUrl(requestToken.oauth_token);
Exchange an authenticated request token for an access token
oauth1.exchangeRequestToken(oauth_token, oauth_verifier, opts)
Takes a pair of authenticated temporary credentials passed to the callback URLby the provider and exchanges it for an oauth_token
and oauth_token_secret
than can be used to perform authenticated requests to the OAuth 1.0a provider.
Performs a POST response to the accessTokenEndpoint.
Throws an exception if the remote server responds with an empty response body.
Arguments
- oauth_token:
string
The oauth_token
passed to the callback URL by the provider.
- oauth_verifier:
string
The oauth_verifier
passed to the callback URL by the provider.
- opts:
Object
(optional)
An object with additional query parameters to include in the request.
See RFC 5849.
Returns the parsed response object.
Fetch the active user
oauth1.fetchActiveUser(oauth_token, oauth_token_secret, opts): Object
Fetches details of the active user.
Performs a GET response to the activeUserEndpoint.
Throws an exception if the remote server responds with an empty response body.
Returns null
if the activeUserEndpoint is not configured.
Arguments
- oauth_token:
string
An OAuth 1.0a access token as returned by exchangeRequestToken.
- oauth_token_secret:
string
An OAuth 1.0a access token secret as returned by exchangeRequestToken.
- opts:
Object
(optional)
An object with additional query parameters to include in the request.
See RFC 5849.
Returns the parsed response object.
Examples
const authData = oauth1.exchangeRequestToken(oauth_token, oauth_verifier);
const userData = oauth1.fetchActiveUser(authData.oauth_token, authData.oauth_token_secret);
Create an authenticated request object
oauth1.createSignedRequest(method, url, parameters, oauth_token, oauth_token_secret)
Creates a request object that can be used to perform a request to the OAuth 1.0aprovider with the provided token credentials.
Arguments
- method:
string
HTTP method the request will use, e.g. "POST"
.
- url:
string
The fully-qualified URL of the provider the request will be performed against.
The URL may optionally contain any number of query parameters.
- parameters:
string | Object | null
An additional object or query string containing query parameters or bodyparameters that will be part of the signed request.
- oauth_token:
string
An OAuth 1.0a access token as returned by exchangeRequestToken.
- oauth_token_secret:
string
An OAuth 1.0a access token secret as returned by exchangeRequestToken.
Returns an object with three properties:
url: The normalized URL without any query parameters.
qs: A normalized query string containing all parameters and query parameters.
headers: An object containing the following properties:
accept: The string
"application/json"
.authorization: An OAuth authorization header containing all OAuthparameters and the request signature.
Examples
Fetch a list of tweets mentioning @arangodb
:
const request = require('@arangodb/request');
const req = oauth1.createSignedRequest(
'GET',
'https://api.twitter.com/1.1/search/tweets.json',
{q: '@arangodb'},
authData.oauth_token,
authData.oauth_token_secret
);
const res = request(req);
console.log(res.json.statuses);
Signing a more complex request:
const url = 'https://api.example.com/v1/timeline?visible=public';
const params = {hello: 'world', longcat: 'is long'};
const req = oauth1.createSignedRequest(
'POST',
url, // URL includes a query parameter that will be signed
params, // Request body needs to be signed too
authData.oauth_token,
authData.oauth_token_secret
);
const res = request.post(url, {
form: params,
headers: {
accept: 'application/x-www-form-urlencoded',
// Authorization header includes the signature
authorization: req.headers.authorization
}
});
console.log(res.json);