BreadButter Node.js

The official BreadButter Node.js Server library.

Download

Npm

npm install breadbutter-nodejs --save

BreadButter API

• Prior to coding, some configuration is required at https://app.breadbutter.io/app/#/app-settings.

• For the full Developer Documentation please visit: https://app.breadbutter.io/api/

Instantiating a new client

• Your APP_ID can be found in App Settings
• APP_SECRETS are configured here
• The BREADBUTTER_API_ENDPOINT should be set to https://api.breadbutter.io

Create a new instance from LogonClient.

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRETS', 'BREADBUTTER_API_ENDPOINT');

SSO Login QuickStart

The StartLogin function in the JS library begins the BreadButter managed SSO process.

Further documentation on starting the login process via our JavaScript client can be found at our GitHub page here

The following example demonstrates what to do once the callback_url has been used by our system to redirect the user back to your page; with the token as the query string parameter.

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRETS', 'BREADBUTTER_API_ENDPOINT');
 
const callback_url = 'https://your_callback_url/?token=some_validation_token';
 
let token = client.parseToken(callback_url);
 
client.validateLogin(token).then((response) => {
    
    if(response.isEventSuccess()) {
        //authentication and validation succeeded. proceed with post-auth workflows for your system
    }
}).catch((err) => {
    console.log(err);
});

Node.js Only Workflow

The following workflow is required if you're using a Node.js that handles both the front and back ends. If this does not apply to you, please refer to the SSO Login QuickStart section.

Step 1 - startLogin

This call begins the breadbutter managed SSO process. The client_data property is optional and is used to pass any data that is required after validating the request. The tags property is an ArrayList of type Tag which is a simple object representing a key/value pair. The force_reauthentication property is an optional method to attempt or force an Identity Provider to reauthenticate with the user.

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRETS', 'BREADBUTTER_API_ENDPOINT');

//optional parameters
let  client_data = "{\"ClientData\":\"Value\"}";
//

client.startLogin({
    identity_provider: client.IdentityProviders.GOOGLE,
    email_address: '[email protected]',
    client_data: client_data,
    callback_url: callback_url,
    destination_url: destination_url,
    force_reauthentication: client.ForceAuthentication.ForceAuthenticationTypes.OFF
}).then((response) => {
    console.log(response.url);
}).catch((err) => {
  console.log(err);
});

The response.url property returned should be redirected to by the application. Upon submitting their credentials, users will be redirected to the callback_url set within the application settings at https://app.breadbutter.io/app/#/app-settings.

Step 2 - validateLogin

This method is used to validate the results of the login attempt. token corresponds to the query parameter with the name token appended to the callback url specified for your app.

The response contains all details of the login and the user has now completed the SSO workflow.

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRETS', 'BREADBUTTER_API_ENDPOINT');
 
const callback_url = 'https://your_callback_url/?token=some_validation_token';
 
client.validateLogin(token).then((response) => {
    if (response.isEventSuccess()) {
        //authentication and validation succeeded. proceed with post-auth workflows for your system
    } else {
        if (response.isFail('validation_details', 'domain_validation')) {
            //email didn't match the one provided to startLogin
        }
        if (response.isFail('validation_details', 'ip_validation') ||
            response.isFail('validation_details', 'geo_validation') ||
            response.isFail('validation_details', 'time_validation')) {
            //validation failed via restriction settings for the app
        }
    }
}).catch((err) => {
    console.log(err);
});

Events

The createEvent method allows one to create events that are outside of our SSO workflows.

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRETS', 'BREADBUTTER_API_ENDPOINT');

client.createEvent({
    type: client.Event.Type.LOGIN,
    validate: true,
    local_validation: client.Event.Validation.PASS,
    email_address: '[email protected]',
    first_name: 'Firstname',
    last_name: 'Lastname',
    ip_address: '0.0.0.0',
    user_agent: 'Client/UserAgent'
}).then((response) => {
    console.log(response);
}).catch((err) => {
    console.log(err);
});

OAuth Tokens

Optionally, Identity Providers can be configured to return OAuth Tokens. These tokens can be used to make API requests on behalf of the user by the OAuth protocol. In order to enable this feature Return Authorization Data must be enabled for your Provider. For more information visit the Refresh Tokens Documentation.

RefreshToken

RefreshToken renews the Access Token via the Refresh Token.

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRETS', 'BREADBUTTER_API_ENDPOINT');

var identityProviderId = "identity_provider_id"; //can be retrieved by calling GetProviders
var token = "refresh_token"; //returned by authorization_data_tokens.refresh_token in the ValidateLogin Response

client.refreshToken({
    identity_provider_id: identityProviderId,
    token: token
}).then((response) => {
    console.log(response.authorization_data_tokens);
}).catch((err) => {
  console.log(err);
});

RevokeToken

RevokeToken invalidates the Token passed

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRETS', 'BREADBUTTER_API_ENDPOINT');

var identityProviderId = "identity_provider_id"; //can be retrieved by calling GetProviders
var token = "refresh_or_access_token"; //returned by refresh_token or access_token from authorization_data_tokens in the ValidateLogin Response

client.revokeToken({
    identity_provider_id: identityProviderId,
    token: token
}).catch((err) => {
  console.log(err);
});

Helper Methods

GetProviders

This method is used to retrieve a list of all providers enabled for the application. If an email address is passed to the method, it will return the list of providers available for that email domain.

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRETS', 'BREADBUTTER_API_ENDPOINT');
 
client.getProviders('[email protected]').then((response) => {
    for(let i = 0; i < response.social_identity_providers.length; i++) {
        let provider = response.social_identity_providers[i];
        if (provider.type == client.IdentityProviders.GOOGLE) {
            //make google available in UI or handle other custom rules
        }
    }
    for(let i = 0; i < response.enterprise_identity_providers.length; i++) {
        let provider = response.enterprise_identity_providers[i];
        if (provider.type == client.IdentityProviders.GOOGLE) {
            //make google available in UI or handle other custom rules
        }
    }
}).catch((err) => {
  console.log(err);
});

ParseToken

This method parses out the value of the token query parameter returned with your callback url.

const client = require('breadbutter-nodejs')('APP_ID', 'APP_SECRETS', 'BREADBUTTER_API_ENDPOINT');
const callback_url = 'http://your_callback_url/?token=some_validation_token';

let token = client.parseToken(callback_url);
console.log(token);

//output
//some_validation_token