React Ghost Auth

React Ghost Auth is an easy to use multi-provider authentication and authorisation library. The library uses the OpenID Connect Flow. You simply set your configurations options for all providers to be used, and use them. It's that simple.

Author

👤 Nicola Vurchio Github: @nicolavurchio-iad2

Installation

npm i @iad-os/react-ghost-auth

Playground

See how the library is used here Github: Ghost Auth Playground

Usage

1. Create an authConfig file and setup each provider's configuration options.

You can get the provider options from your chosen provider i.e Google, Keycloak, Microsoft etc. NOTE: AuthenticationConfig is solely for type checking

import { AuthenticationConfig } from '@iad-os/react-ghost-auth';

export const authConfig: AuthenticationConfig = {
  providers: {
    //Options example
    google: {
      name: 'google',
      authorization_endpoint: 'https://accounts.google.com/o/oauth2/auth',
      token_endpoint: 'https://oauth2.googleapis.com/token',
      client_id: 'xxxxxxxxxxxxxx.apps.googleusercontent.com',
      requested_scopes: 'profile email openid',
      redirect_uri: 'http://localhost:3000/redirect',
      end_session_endpoint: '',
      redirect_logout_uri: 'http://localhost:3000',
      access_type: 'offline',
      client_secret: 'xxxxxxxxxxxxxxxxxx',
    },

    keycloak: {
      //Put options here
    },

    microsoft: {
      //Put options here
    },
  },
};

2. Import the AuthenticationProvider and wrap your App Component

import AuthenticationProvider from '@iad-os/react-ghost-auth';

<AuthenticationProvider
  config={authConfig}
  axios={axios}
  onRoute={handleRoute}>

    </App> // Your app

</AuthenticationProvider>

3. Setup login on the UI by importing the useAuthentication hook

This exposes api's that can be found below i.e Public Api's

import { useAuthentication } from '@iad-os/react-ghost-auth';

const Login: React.FC = () => {
  const { login } = useAuthentication();

  function handleGoogle() {
    login("google");
  }

  function handleKeyCloak() {
    login("keycloak");
  }

  return (
      <Button onClick={handleGoogle}>
        Login with Google
      </Button>

      <Button onClick={handleKeyCloak}>
        Login with Keycloak
      </Button>
  );
};

Public APIs

The public api's below are returned from the useAuthentication hook | API | Purpose | | ------ | ------ | | login(providerName: string) | A function that initaites the login flow by redirecting the user to the chosen provider | | logout() | A function that clears the userInfo and tokenInfo and logs the user out of the app | | userInfo() | A function that returns the user information provided by the chosen provider | | tokenInfo() | A function that returns the access and refresh tokens| | isAuthenticated() | A method that returns true if user is authenticated and false otherwise | | status: EStatus | A variable that returns the login state which can be 'INIT', 'LOGIN', 'LOGGING' or 'LOGGED' | | changeStatus(status: EStatus) | A function that sets the login state i.e status| |providerInfo() | A function that returns the selected provider and default provider if one is provided|

Components

The components below can be used as wrappers to trigger preffered behaviour | Component | Purpose | | ------ | ------ | | RequireAuth | A wrapper component that requires user to be authenticated before it's content is exposed| | Logging | A wrapper component that exposes its content while the log in process is running| | Logged | A wrapper component that exposes its content after the log in process is successful| | AutoLogin | A wrapper or standalone component that initiates the login process automatically on page/site reload|