OAuth 2.0

const createOAuth2Client = require('@arangodb/foxx/oauth2');

The OAuth2 module provides abstractions over OAuth 2.0 providers like Facebook, GitHub and Google.

Examples

  1. const crypto = require('@arangodb/crypto');
  2. const router = createRouter();
  3. const oauth2 = createOAuth2Client({
  4.   // We'll use Facebook for this example
  5.   authEndpoint: 'https://www.facebook.com/dialog/oauth',
  6.   tokenEndpoint: 'https://graph.facebook.com/oauth/access_token',
  7.   activeUserEndpoint: 'https://graph.facebook.com/v2.0/me',
  8.   clientId: 'keyboardcat',
  9.   clientSecret: 'keyboardcat'
  10. });
  12. module.context.use('/oauth2', router);
  14. // See the user management example for setting up the
  15. // sessions and users objects used in this example
  16. router.use(sessions);
  18. router.post('/auth', function (req, res) {
  19.   const csrfToken = crypto.genRandomAlphaNumbers(32);
  20.   const url = req.reverse('oauth2_callback', {csrfToken});
  21.   const redirect_uri = req.makeAbsolute(url);
  22.   // Set CSRF cookie for five minutes
  23.   res.cookie('oauth2_csrf_token', csrfToken, {ttl: 60 * 5});
  24.   // Redirect to the provider's authorization URL
  25.   res.redirect(303, oauth2.getAuthUrl(redirect_uri));
  26. });
  28. router.get('/auth', function (req, res) {
  29.   // Some providers pass errors as query parameter
  30.   if (req.queryParams.error) {
  31.     res.throw(500, `Provider error: ${req.queryParams.error}`)
  32.   }
  33.   // Make sure CSRF cookie matches the URL
  34.   const expectedToken = req.cookie('oauth2_csrf_token');
  35.   if (!expectedToken || req.queryParams.csrfToken !== expectedToken) {
  36.     res.throw(400, 'CSRF mismatch.');
  37.   }
  38.   // Make sure the URL contains a grant token
  39.   if (!req.queryParams.code) {
  40.     res.throw(400, 'Provider did not pass grant token.');
  41.   }
  42.   // Reconstruct the redirect_uri used for the grant token
  43.   const url = req.reverse('oauth2_callback');
  44.   const redirect_uri = req.makeAbsolute(url);
  45.   // Fetch an access token from the provider
  46.   const authData = oauth2.exchangeGrantToken(
  47.     req.queryParams.code,
  48.     redirect_uri
  49.   );
  50.   const facebookToken = authData.access_token;
  51.   // Fetch the active user's profile info
  52.   const profile = oauth2.fetchActiveUser(facebookToken);
  53.   const facebookId = profile.id;
  54.   // Try to find an existing user with the user ID
  55.   // (this requires the users collection)
  56.   let user = users.firstExample({facebookId});
  57.   if (user) {
  58.     // Update the facebookToken if it has changed
  59.     if (user.facebookToken !== facebookToken) {
  60.       users.update(user, {facebookToken});
  61.     }
  62.   } else {
  63.     // Create a new user document
  64.     user = {
  65.       username: `fb:${facebookId}`,
  66.       facebookId,
  67.       facebookToken
  68.     }
  69.     const meta = users.save(user);
  70.     Object.assign(user, meta);
  71.   }
  72.   // Log the user in (this requires the session middleware)
  73.   req.session.uid = user._key;
  74.   req.session.facebookToken = authData.facebookToken;
  75.   req.sessionStorage.save(req.session);
  76.   // Redirect to the default route
  77.   res.redirect(303, req.makeAbsolute('/'));
  78. }, 'oauth2_callback')
  79. .queryParam('error', joi.string().optional())
  80. .queryParam('csrfToken', joi.string().optional())
  81. .queryParam('code', joi.string().optional());

Creating an OAuth 2.0 client

createOAuth2Client(options): OAuth2Client

Creates an OAuth 2.0 client.

Arguments

  • options: Object

    An object with the following properties:

    • authEndpoint: string

      The fully-qualified URL of the provider’s authorization endpoint.

    • tokenEndpoint: string

      The fully-qualified URL of the provider’s token endpoint.

    • refreshEndpoint: string (optional)

      The fully-qualified URL of the provider’s refresh token endpoint.

    • activeUserEndpoint: string (optional)

      The fully-qualified URL of the provider’s endpoint for fetching details about the current user.

    • clientId: string

      The application’s Client ID (or App ID) for the provider.

    • clientSecret: string

      The application’s Client Secret (or App Secret) for the provider.

Returns an OAuth 2.0 client for the given provider.

Setting up OAuth 2.0 for Facebook

If you want to use Facebook as the OAuth 2.0 provider, use the following options:

  • authEndpoint: https://www.facebook.com/dialog/oauth
  • tokenEndpoint: https://graph.facebook.com/oauth/access_token
  • activeUserEndpoint: https://graph.facebook.com/v2.0/me

You also need to obtain a client ID and client secret from Facebook:

  1. Create a regular account at Facebook or use an existing account you own.
  2. Visit the Facebook Developers page.
  3. Click on Apps in the menu, then select Register as a Developer (the only option) and follow the instructions provided. You may need to verify your account by phone.
  4. Click on Apps in the menu, then select Create a New App and follow the instructions provided.
  5. Open the app dashboard, then note down the App ID and App Secret. The secret may be hidden by default.
  6. Click on Settings, then Advanced and enter one or more Valid OAuth redirect URIs. At least one of them must match your redirect_uri later. Don’t forget to save your changes.
  7. Set the option clientId to the App ID and the option clientSecret to the App Secret.

Setting up OAuth 2.0 for GitHub

If you want to use GitHub as the OAuth 2.0 provider, use the following options:

  • authEndpoint: https://github.com/login/oauth/authorize?scope=user
  • tokenEndpoint: https://github.com/login/oauth/access_token
  • activeUserEndpoint: https://api.github.com/user

You also need to obtain a client ID and client secret from GitHub:

  1. Create a regular account at GitHub or use an existing account you own.
  2. Go to Account Settings > Applications > Register new application.
  3. Provide an authorization callback URL. This must match your redirect_uri later.
  4. Fill in the other required details and follow the instructions provided.
  5. Open the application page, then note down the Client ID and Client Secret.
  6. Set the option clientId to the Client ID and the option clientSecret to the Client Secret.

Setting up OAuth 2.0 for Google

If you want to use Google as the OAuth 2.0 provider, use the following options:

  • authEndpoint: https://accounts.google.com/o/oauth2/auth?access_type=offline&scope=profile
  • tokenEndpoint: https://accounts.google.com/o/oauth2/token
  • activeUserEndpoint: https://www.googleapis.com/plus/v1/people/me

You also need to obtain a client ID and client secret from Google:

  1. Create a regular account at Google or use an existing account you own.
  2. Visit the Google Developers Console.
  3. Click on Create Project, then follow the instructions provided.
  4. When your project is ready, open the project dashboard, then click on Enable an API.
  5. Enable the Google+ API to allow your app to distinguish between different users.
  6. Open the Credentials page and click Create new Client ID, then follow the instructions provided. At least one Authorized Redirect URI must match your redirect_uri later. At least one Authorized JavaScript Origin must match your app’s fully-qualified domain.
  7. When the Client ID is ready, note down the Client ID and Client secret.
  8. Set the option clientId to the Client ID and the option clientSecret to the Client secret.

Get the authorization URL

oauth2.getAuthUrl(redirect_uri, args): string

Generates the authorization URL for the authorization endpoint.

Arguments

  • redirect_uri: string

    The fully-qualified URL of your application’s OAuth 2.0 callback.

  • args: (optional)

    An object with any of the following properties:

    • response_type: string (Default: "code")

    See RFC 6749.

Returns a fully-qualified URL for the authorization endpoint of the provider by appending the client ID and any additional arguments from args to the authEndpoint.

Exchange a grant code for an access token

oauth2.exchangeGrantToken(code, redirect_uri)

Exchanges a grant code for an access token.

Performs a POST response to the tokenEndpoint.

Throws an exception if the remote server responds with an empty response body.

Arguments

  • code: string

    A grant code returned by the provider’s authorization endpoint.

  • redirect_uri: string

    The original callback URL with which the code was requested.

  • args: Object (optional)

    An object with any of the following properties:

    • grant_type: string (Default: "authorization_code")

      See RFC 6749.

Returns the parsed response object.

Fetch the active user

oauth2.fetchActiveUser(access_token): 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

  • access_token: string

    An OAuth 2.0 access token as returned by exchangeGrantToken.

Returns the parsed response object.

Examples

  1. const authData = oauth2.exchangeGrantToken(code, redirect_uri);
  2. const userData = oauth2.fetchActiveUser(authData.access_token);