authbox

authbox-node

authbox-node is the official Node.js interface to Authbox.

Installation

npm install authbox

Quick Start

Import Authbox

var authbox = require('authbox');

Barebones Authbox Configuration

At the bare minimum, Authbox takes in an apiKey and a secretKey. You set this once by calling the configure method:

authbox.configure({
  apiKey: 'YOUR_API_KEY',
  secretKey: 'YOUR_SECRET_KEY'
});

Configure Authbox Using getRequestData

To put it simply, the more data you provide Authbox, the better it works. Two additional pieces of data that greatly increase the efficacy of Authbox are the current user and current session. You can set these by providing an additional field in the one time call to configure. This additional setting is called getRequestData and should be a function that takes a request and a callback that fires when you have fetched the additional data from your database or the request itself: getRequestDataFunction(req, cb). A sample configure call that sets these additional pieces of information would look like this:

authbox.configure({
  apiKey: 'YOUR_API_KEY',
  secretKey: 'YOUR_SECRET_KEY',
  getRequestData: function(req, cb) {
    cb(null, {
      // The functions below are created by the client and make the necessary
      // calls in order to get the relevant information.
      $user: getUserFromRequestOrDB(req),
      $session: getSessionFromRequestOrDB(req)
    });
  }
});

Users in Authbox

Ideally, you would provide us with the actual signed in user. A sample Authbox user looks like the following:

 $user : {
   $userIDs: [
     {$type:'$email', $key: '[e-mail]'},
     {$type:'$phone', $key: '12121112222'},
     ...
   ],
   $creationTime: 1369114061000
 };

As you might have guessed from the above snippet, Authbox User objects consist of two special components: $userIDs and $creationTime. You can provide any additional information you want on the user, but $userIDs and $creationTime are the most important. $userIDs is an array of user identifiers that consist of a $type and a $key. The key is the actual value while the type can be one of the following:

• $email
• $phone
• $username
• $facebook
• $twitter
• $google
• $github
• $stripe
• $opaqueID

In summary, an Authbox User consists of an array of userIDs (type and key) and an optional creationTime key.

• $key: the user ID (either an email address, phone number, username, or opaque identifier)
• $type: either $email, $phone, $username, $facebook, $twitter, $google, $github, $stripe, OR $opaqueID
• $creationTime: optional: unix timestamp of when the account was created

Sessions in Authbox

Sessions in Authbox are pretty straightforward as they just consist of a $sessionID and an optional $creationTime. A sample session looks like this:

$session : {
  $sessionID: 'session id',
  $creationTime : 1369114061000
};

Finishing Up The Quickstart And Putting On Your Big Boy Pants / Big Girl Dress

If that's all you feel like doing then that's it! You have now enabled Authbox and are tapping in to our abuse prevention services. You rock. But the real fun is just getting started ... Keep reading to learn about how to track custom actions, rate limit any endpoint, and much much more.

Advanced Use

Logging Actions using check

As mentioned above, the more information you can give Authbox about what the user is doing, the better we can make predictions about whether the user is a good or bad actor. Help us help you.

How can you do that you ask? Well, the first step is by explicitly sending actions. To do this, simply add a check call to any endpoint or user action that you are interested in and pass along the relevant data - again - send as little or as much data as you feel comfortable with.

var action = {
  $actionName: '$setting_changed',
  $settingName: 'secondary_email',
  $settingOldValue: '[e-mail]',
  $settingNewValue: '[e-mail]'
};

// Fires authbox check.
Authbox.check(request, action, cb).then(function(verdict) {
  // Do something based on the verdict. See below for more information
});

Reserved Keywords and Type Tags

At this point you maybe asking yourself what is going on with all of these '$'. Authbox uses '$' to indicate special keywords that have semantic meaning and get processed specially in our system. This is not some kind of subliminal attempt to get you to pay us, though you are welcome to do so if you feel so inspired.

Not all fields require the '$' prefix. In fact, the majority of data customers send us is custom data and is NOT prefixed with '$'. In order for us to be able to parse this data and run it through the appropriate classifiers and models, we need you to annotate these with Type Tags.

Using Type Tags

Type Tags allow you to provide custom data and help us determine how to process it.

Let's say your site wants to add a check for a user creating a custom alert that has a title and text body field. You could do this by creating a custom action and data on that action like so:

var action = {
  $actionName: 'create_custom_alert',
  alert_title__text: 'Title of the Alert',
  alert_body__text: 'Body of the Custom Alert'
};

// Fires authbox check.
Authbox.check(request, action, cb).then(function(verdict) {
  // Do something based on the verdict.
});

Note that both the alert_title__text and alert_body__text are not prefixed with a '$' and both have the '__text' suffix on the key. The presence of '__text' indicates to Authbox that user generated content is being provided and it will be parsed properly. For a list of valid type tags see below:

• TODO: VALID TYPE TAGS

Verdicts

After making a check call, Authbox will return a verdict. You don't have to take action for all of them -- they're just suggestions from Authbox for what to do. Here's the list of possible verdicts:

• ALLOW: do nothing and allow the request
• BLOCK: block the request.
• RATE_LIMIT: block the request and show a rate limiting message
• CONFIRMATION_CHECKPOINT_REQUIRED: block the request, show a message confirming that the user actually wants to do this
• IDENTITY_CHECKPOINT_REQUIRED: block the request and ask the user for an identity challenge (2 factor auth, security question, etc. NOT password!)
• BOT_CHECKPOINT_REQUIRED: block the request and ask the user to prove they're human (i.e. a CAPTCHA)

When the user completes an identity or bot challenge successfully, you'll need to send Authbox an IDENTITY_CHALLENGE_SUCCESS, IDENTITY_CHALLENGE_FAIL, BOT_CHALLENGE_SUCCESS or BOT_CHALLENGE_FAIL message (see above).

In the future we'll be releasing a client-side SDK that will automate all of this if you don't want to build it yourself.

todo ...

• Tags / schema
• Out of the box actions
• Reserved Keywords
• Customization Options
• Linking Actions and Content
• Read Endpoints
• Middleware Docs