External authentication

External authentication means that the authentication is handled by an external entity and once the authentication is done, the user is redirected back to the React application.

note

The external entity could be the backend of the React app or any other server.

Oneki.js expects a function to parse the parameters returned by the external entity

Architecture

The following scenario is the standard flow when a non logged-in user wants to display a page reserved only for the logged-in user. This means that this page is secured via the secure HOC
This flow can be customized via src/settings.ts

info

In the above scenario, the /login page uses the useLogin to redirect the user to the external entity.

Configuration

The useLogin, useLoginCallback, useLogout and useLogoutCallback hooks are configured via several parameters in src/settings.ts (see configuration)

the following parameters are available:

export default {
  idp: {
    default: {
      // MANDATORY parameters
      type: "external",
      externalLoginEndpoint: "/api/auth",

      // OPTIONAL parameters
      externalLogoutEndpoint: "/api/logout",
      userinfoEndpoint: "/api/whoami",
      postLoginRedirectKey: "redirectUri",
      postLogoutRedirectKey: "redirectUri",
      callback: (result, context) => [token, securityContext],
    },
  },
};

_Mandatory parameters are marked with a \*_

Key	Type	Description
type*	string	must be "form"
externalLoginEndpoint*	externalLoginEndpoint	The URL of an external webpage that allows the user to log in Can be A relative or absolute URL A function returning the URL
externalLogoutEndpoint	externalLogoutEndpoint	The URL of an external webpage that allows the user to log out Can be A relative or absolute URL A function returning the URL
userinfoEndpoint	userinfoEndpoint	The URL of an API called to retrieve the connected user's profile (via a HTTP GET request) Can be: A relative or absolute URL A function that returns an object representing the userInfo. For example a object like this: {email: 'foo@example.com', roles: ['ADMIN']}}
loginCallbackRoute	string	The URL to which the user is redirected after authentication Example: https://mysite.com/login-callback Defaults to: <current_url>/callback (so if current URL is https://mysite.com/login -> defaults to https://mysite.com/login/callback)
postLoginRedirectKey	string	Oneki.js adds a query param to the externalLoginEndpoint to indicate the callback URL to redirect to once the authentication is performed Example: if externalLoginEndpoint = "https://idp.com/auth" postLoginRedictKey = "redirectUri" loginCallbackRoute = https://mysite.com/login-callback then the external authentication URL is https://idp.com/auth?redirectUri=https://mysite.com/login-callback Defaults to: redirect_uri
logoutCallbackRoute	string	The URL to which the user is redirected after disconnection Example: https://mysite.com/logout-callback Defaults to: <current_url>/callback (so if current URL is https://mysite.com/logout -> defaults to https://mysite.com/logout/callback)
postLogoutRedirectKey	string	Oneki.js adds a query param to the externalLogoutEndpoint to indicate the callback URL to redirect to once the disconnection is performed Example: if externalLogoutEndpoint = "https://idp.com/logout" postLoginRedictKey = "redirectUri" loginCallbackRoute = https://mysite.com/logout-callback then the external authentication URL is https://idp.com/logoutredirectUri=https://mysite.com/logout-callback Defaults to: redirect_uri
callback	callback	a callback function to parse the query params received by the loginCallbackRoute. The fonction returns optionally a token and/or a securityContext if callback is null, Oneki.js assumes that the session is done via a cookie and the security context is retrieved via the userinfoEndpoint defined above) Defaults to: null
persist	string	How the token is persisted Possible values: memory: the token is stored only in the global state with the key auth.token localStorage: the token is stored in the global state with the key auth.token and in the browser's local storage with the key onekijs.token sessionStorage: the token is stored in the global state with the key auth.token and in the browser's session storage with the key onekijs.token cookie: the token is stored in the global state with the key auth.token and in the browser's cookies with the key onekijs.token Defaults to: memory

Example

The example below redirects the user to an external page (/login.html, not part of the React application) to handle the authentication. The redirect is done via useLogin in /login page

Once the authentication is done, he's redirected back to /login-callback?token=XXXX which is part the React application. Then:

• The token is extracted from the URL and put in the global state with the key auth.token.
• secure() HOC retrieves the user's profile of the user via an AJAX GET request to /userinfo with an HTTP Authorization header = Bearer <TOKEN_VALUE_IN_GLOBAL_STATE>

info

the page login.html could be hosted on another domain

Vite App

Open in CodeSandbox | View code on GitHub

Nextjs App

Open in CodeSandbox | View code on GitHub