authentication-client

A thin Authentication API consumer (43KB) powered by Browserify

---

Development

Please see the CONTRIBUTING instructions before contributing to this repository

---

Getting Started

Install the required dependencies

make yarn
make npm

To build the library for Production use

npm run build

To run a live-reload build task for Development run

npm start

---

Tests

To run the tests use

npm test

To produce a test coverage report use

npm run cov

You can access the report by running open coverage/lcov-report/index.html.

▶️ Code coverage results for the latest build

---

API Reference

To generate the JSDoc API Reference run

npm run docs

You can access the generated docs by running open docs/index.html

▶️ API Reference for the latest build

---

Usage

• Installation
• Setup
• Environments
• Session operations
• AdblockerDetector operations
• Redirector operations
• User operations
• Password operations

Installation

Add the following line in your package.json file and replace the <TAG> with your target version, ie v2.5.0

"dependencies": {
  "authentication-client": "[email protected]:Avocarrot/authentication-client.git#v2.5.0"
}

Cross-domain Storage setup

To setup the Hub for cross domain storage use:

AuthenticationClient.initStorage([
  {origin: /.*subdomain.domain.com\d$/, allow: ['get', 'set', 'del']}
]);

The corresponding Client is generated automatically. For more information see https://github.com/zendesk/cross-storage

Setup

The library can be instantiated with the following arguments

Argument	Description	Default
clientId	The app's registered client id	N/A
clientSecret	The app's registered client secret	N/A
loginHost	The login app host	"http://login.avocarrot.com"
apiHost	The authentication-api host	"http://auth.avocarrot.com"
domain	The Store domain prefix	"avocarrot"
environment	The environment to use	AuthenticationClient.Environment.Production

Environments

You can setup the library to run in two Environments:

• Production
• Sandbox

Production

All API calls are forwarded to the production Authentication API using the configuration file at config/default.js.

import AuthenticationClient from 'authentication-client';

var authenticationClient = AuthenticationClient.getInstanceFor({
  clientId: '1234',
  clientSecret: '5678'
})

Sandbox

All calls to Authentication API are mocked and a temporary session is provided.

import AuthenticationClient from 'authentication-client';

var authClient = AuthenticationClient.getInstanceFor({
  clientId: '1234',
  clientSecret: '5678',
  loginHost: 'http://localhost:9000',
  environment: AuthenticationClient.Environment.Sandbox
})

Session operations

/**
 * Initializes session for user (if defined) in Store
 * Note: This should be the FIRST call before attempting any other session operations
 *
 * @return {Promise}
 *
 */
authClient.session.initialize()
  .then((res)  => {/* ... */})
  .catch((err) => {/* ... */});

/**
 * Determines if session is valid (user is authenticated)
 *
 * @return {Boolean}
 *
 */
authClient.session.isValid;

/**
 * Validates session
 * - redirects to `loginHost`
 *
 * @return {Void}
 *
 */
authClient.session.validate();

/**
 * Invalidates session
 * - redirects to `loginHost`
 *
 * @return {Void}
 *
 */
authClient.session.invalidate();

AdblockerDetector operations

When an adblocker is enabled you should invalidate the authentication session

/**
 * Redirects to url
 *
 * @param {String} url - The target url
 * @return {Void}
 *
 */
authClient.adblockerDetector.detect((isEnabled) => {
  if (isEnabled) {
    authClient.session.invalidate();
  }
});

Redirector operations

To enable authenticated redirections between clients (fallback support for Safari / cross-storage) use:

/**
 * Redirects to url
 *
 * @param {String} url - The target url
 * @return {Void}
 *
 */
authClient.redirector.authenticatedRedirect(url);

User operations

While in Sandbox mode you can authenticate using the default Sandbox User found in /fixtures/users.json

Default Sandbox User

Property	Value
email	[email protected]
password	qwerty123

/**
 * Authenticate a User (login)
 *
 * @param {String} email - The user's email
 * @param {String} password - The user's password
 * @return {Promise} - res.message, res.data, err.message
 *
 */
authClient.user.authenticate(email, password)
  .then((res)  => {/* ... */})
  .catch((err) => {/* ... */});

/**
 * Create a User (register)
 *
 * @param {String} email - The user's email
 * @param {String} password - The user's password
 * @param {String} firstName - The user's first name
 * @param {String} lastName - The user's last name
 * @return {Promise} - res.message, res.data, err.message,
 *
 */
authClient.user.create(email, password, firstName, lastName)
  .then((res)  => {/* ... */})
  .catch((err) => {/* ... */});

/**
 * Get User details
 *
 * @return {Object} - User
 *
 */
 // Read-Write
 authClient.user.firstName;
 authClient.user.lastName;

 // Read-only
 authClient.user.email;
 authClient.user.bearer;
 authClient.user.publisherId;
 authClient.user.roles;

/**
 * Update User
 *
 * @return {Promise} - res.message, err.message
 *
 */
authClient.user.firstName = "John";
authClient.user.lastName = "Doe";
authClient.user.save()
  .then((res)  => {/* ... */})
  .catch((err) => {/* ... */});

/**
 * Authenticate user using a login token
 *
 * @param {String} accessToken - The access token to use (required)
 * @param {String} refreshToken - The refresh token to use (optional)
 * @return {Promise} - res.message, err.message
 *
 */
authClient.user.authenticateWithToken(accessToken, refreshToken)
  .then((res)  => {/* ... */})
  .catch((err) => {/* ... */});

/**
 * Flushes stored tokens for User (logout)
 *
 * @return {Promise} - res.message, err.message
 *
 */
authClient.user.flush()
 .then((res)  => {/* ... */})
 .catch((err) => {/* ... */});

Password operations

The following rules apply for password acceptance

• Password must be at least 8 characters long
• Password must contain both numbers and characters
• Password cannot contain spaces

/**
 * Request a password reset for an email
 *
 * @param {String} email - The email where the reset link will be sent
 * @return {Promise} - res.message, err.message
 *
 */
authClient.authenticator.requestPasswordReset(email)
  .then((res)  => {/* ... */})
  .catch((err) => {/* ... */});

/**
 * Reset password
 *
 * @param {String} token - The password reset token (provided via the reset link)
 * @param {String} password - The password to set
 * @return {Promise} - res.message, err.message
 *
 */
authClient.authenticator.resetPassword(token, password)
  .then((res)  => {/* ... */})
  .catch((err) => {/* ... */});

---

Confirmation Operations

/**
 * Get information about a confirmation token
 * @param {String} token - Confirmation token UUID
 * @return {Promise} - res.{uuid, expires, user_id, id}, err
 *
 */
authClient.confirmation.get(token)
  .then((res) => {/* ... */})
  .catch((err) => {/* ... */})

/**
 * Create a new confirmation token for a user (Resend Confirmation Email)
 * @param {String} email - The email where the confirmation link will be sent
 * @return {Promise} - res.{uuid, expires, user_id, id}, err
 *
 */
authClient.confirmation.resend(email)
  .then((res) => {/* ... */})
  .catch((err) => {/* ... */});

/**
 * Confirm user email using a confirmation token
 * @param {String} token - The token
 * @return {Promise} - Status 204, err
 *
 */
authClient.confirmation.confirm(token)
  .then(() => {})
  .catch((err) => {/* ... */});

---

Built With

• Gulp
• Browserify
• JSDoc

---

Versioning

For the versions available, see the releases for this repository.