README.react.md

React components for the Kloudless Authenticator

This is a thin React wrapper for the Kloudless Authenticator. We provide the following components to add the Authenticator to any React app:

• AuthButton: A button component that will launch the Authenticator when clicked.
• createAuthButton: A Higher-Order Component (HOC) that accepts your custom component and wraps it in a new one that launches the Authenticator.

Supports React v15, v16.

DEMO

Table of contents

• Installation
• How It Works
  • AuthButton
    • Example
  • createAuthButton
    • Example
• Props
• Event Handlers
• Set/Get Global Options
• Testing

Installation

npm install @kloudless/authenticator

How It Works

AuthButton

A button component that wraps the Authenticator view and will launch the Authenticator when clicked.

Example

import React from 'react';
import ReactDOM from 'react-dom';
import { AuthButton } from '@kloudless/authenticator/react';

ReactDOM.render(
  <AuthButton
    className="CSS_CLASS_NAME"
    title="AUTH_BUTTON_TITLE"
    disabled={false}
    options={{
      client_id: 'YOUR_KLOUDLESS_APP_ID',
      scope: 'any.all',
    }}
    onClick={() => { console.log('click') }}
    onSuccess={(result) => { console.log('success', result) }}
    onError={(error) => { console.log('error', error) }} />,
  document.getElementById('root'),
);

createAuthButton

A Higher-Order Component (HOC) that transforms your custom component into a new one that launches the Authenticator.

It will add a transparent component layer that will hack the onClick event handler. The hacked onClick event handler will be passed to the wrapped component and will launch the Authenticator when called.

All the properties and the event handlers passed to the new component will be passed to the wrapped component except for the options property.

Example

import React from 'react';
import ReactDOM from 'react-dom';
import { createAuthButton } from '@kloudless/authenticator/react';
import CustomButton from 'path/to/CustomButton';

// First, wrap you custom component.
// Your custom component should accept onClick and call it to launch the
// Authenticator.
const CustomAuthButton = createAuthButton(CustomButton);

ReactDOM.render(
  <CustomAuthButton
    options={{
      client_id: 'YOUR_KLOUDLESS_APP_ID',
      scope: 'any.all'
    }}
    onClick={() => { console.log('click') }}
    onSuccess={(result) => { console.log('success', result) }}
    onError={(error) => { console.log('error', error) }}
  />,
  document.getElementById('root'),
);

Props

• options (Required) OAuth config object.
• options.client_id (Required) The Kloudless application ID.
• options.scope (Optional) Used to determine which services the user can choose from to connect. Could either be an Array of different scopes, or a space-delimited string. ex: "any.calendar any.storage", ["any.calendar", "any.storage"]
• options.extra_data (Optional) A URL-encoded JSON object containing data used to pre-fill default values for fields in the Kloudless authentication forms. ex: the domain of a WebDAV server.
• options.oob_loading_delay (Optional) Indicates the number of milliseconds the loading spinner will last on the callback page before revealing the token. Defaults to 2000.
• title (Optional) The text shows on the AuthButton. Defaults to "Connect Account".
• className (Optional) CSS classes that apply to AuthButton. Defaults to an empty string.
• disabled (Optional) true to disable AuthButton. Defaults to false.

Event Handlers

• onSuccess (Required) Called when authentication success. The event parameter object contains the access token obtained via the OAuth flow, as well as the metadata of the connected account :

  {
      'access_token': 'TOKEN123ABC',
      'token_type': 'Bearer',
      'scope': 'box:normal.storage', // Currently, the requested scope is returned
      'state': 'randomstate123',
      'account': {
          'id': 123,
          'service': 'box',
          ...
      }
  }

• onError (Optional) Called when authentication fails. The event parameter object contains error information:

  {
    'error': "server_error"
    'error_description': "An error occurred. User did not authorize access to account"
    'state': "7691344675"
  }

• onClick (Optional) Called when the component is clicked.

Set/Get Global Options

See auth.setGlobalOptions() and auth.getGlobalOptions().

Testing

First, install dependencies as shown below. This only needs to be done once:

$ npm install --prefix storybook-react/

Then, start up the testing server:

$ npm run storybook:react

The testing server uses a default Kloudless App ID. To connect accounts to your own Kloudless app, you can change the ID either via the interactive storybook UI or via an environment variable as shown below:

# YOUR_APP_ID is the App ID
$ STORYBOOK_KLOUDLESS_APP_ID=YOUR_APP_ID npm run storybook:react