Authentication services

Oneki.js provides 4 services you can use to implement the authentication process
The use of these services is the same regardless of the type of authentication

Service	Description
login service	Service processing the connection request. e.g: an AJAX POST, a redirect to an OIDC IDP, ...
login callback service	When authentication is performed by an external party (e.g an OIDC Identity Provider), this service handles the callback after a connection
logout service	Service processing the disconnection request
logout callback service	When the disconnection is performed by an external party (e.g an OIDC Identity Provider), this service handles the callback after a disconnection

Login service

Based on the configuration found in src/settings.ts, the login service:

• redirects the user to an external identity provider (External authentication, Open ID Connect, Oauth2)
• provides a submit function to send the credentials to the server (Form based authentication)

It's instantied via the hook useLogin.

const [error, loading, submit] = useLogin(idpName, options);

Parameters

Mandatory parameters are marked with a *

Inputs

Parameter	Type	Description
idpName	string	idpName is used to retrieve the configuration with the key idp/:idpName in src/settings.ts. See the page Configuration for more details Defaults to: "default"
options	LoginOptions	Object with non mandatory attributes Defaults: {}
options. onSuccess	AppSuccessCallback	Called if the login request was successful. Mainly used for Form based authentication Defaults to: a function that redirects the user to the original requested page or the homepage
options. onError	AppErrorCallback	Called if the login request failed. Mainly used for Form based authentication Defaults to: a function that sends a notification on the topic login-error

Outputs

Parameter	Type	Description
error	BasicError	Set if an error occurs during the login phase. The error object contains three properties: code message: the error message payload: any additionnal data specific to the error
loading	boolean	Flag to indicate that an AJAX request is in progress
submit	(data) => void	A function to submit the credentials to the server Mainly used for Form based authentication

Example

Form based authentication

Vite App

Open in CodeSandbox | View code on GitHub

Nextjs App

Open in CodeSandbox | View code on GitHub

OIDC authentication

import React from "react";
import { useLogin } from "onekijs";

export default React.memo(() => {
  const idpName = 'google';
  const [error] = useLogin(idpName); // redirects the user to Google's signin page
  if (error) {
    return <div>{error.payload.message}</div>
  }
  return null;
}

Login callback service

The login callback service manages a redirection following a connection. This service is useful when the authentication is done by an external entity (external login, open id connect, ...)

Based on the configuration found in src/settings.ts, the login callback service can (non exhaustive list):

• Extracts the token from the query parameters and potentialy store it
• Extracts an authorization code from the query parameters and exchange it for a token

It's instantied via the useLoginCallback hook.

const [error, loading] = useLoginCallback(idpName, options);

Parameters

Mandatory parameters are marked with a *

Inputs

Parameter	Type	Description
idpName	string	idpName is used to retrieve the configuration with the key idp/:idpName in src/settings.ts. See the page Configuration for more details Defaults to: "default"
options	LoginOptions	Object with non mandatory attributes Defaults: {}
options. onSuccess	AppSuccessCallback	Called if the login request was successful. Defaults to: a function that redirects the user to the original requested page or the homepage
options. onError	AppErrorCallback	Called if the login request failed. Defaults to: a function that sends a notification on the topic login-error

Outputs

Parameter	Type	Description
error	BasicError	Set if an error occurs during the login phase. The error object contains three properties: code message: the error message payload: any additionnal data specific to the error
loading	boolean	Flag to indicate that an AJAX request is in progress

Example

OIDC authentication
The user is redirected to this page by the external entity

import React from "react";
import { useLoginCallback} from "onekijs";

export default React.memo(() => {
  const idpName = 'google';
  const [error] = useLoginCallback(idpName);
  if (error) {
    return <div>{error.payload.message} <span onClick={() => error.remove()}>X</span></div>
  }
  return null;
}

Logout service

Based on the configuration found in src/settings.ts, the logout service:

• redirects the user to an external identity provider (External authentication, Open ID Connect, Oauth2)
• sends a AJAX request to the backend (Form based authentication)

It's instantied via the useLogout hook.

const [error, loading] = useLogout(options);

note

idpName is not needed as it's stored in the localStorage during the login process.

Parameters

Mandatory parameters are marked with a *

Inputs

Parameter	Type	Description
options	LogoutOptions	Object with non mandatory attributes Defaults: {}
options. onSuccess	AppSuccessCallback	Called if the logout was successful. Defaults: a function that redirects the user to the original requested page or the homepage
options. onError	AppErrorCallback	Called if the logout returned an error. Defaults: a function sending a notification on the topic logout-error

Outputs

Parameter	Type	Description
error	BasicError	Set if an error occurs during the logout phase. The error object contains three properties: code message: the error message payload: any additionnal data specific to the error
loading	boolean	Flag to indicate that an AJAX request is in progress

Example

Vite App

Open in CodeSandbox | View code on GitHub

Nextjs App

Open in CodeSandbox | View code on GitHub

Logout callback service

The logout callback service manages a redirect following a logout. This service is useful when the authentication is done by an external entity (external login, open id connect, ...)

It's instantied via the hook useLogoutCallback.

const [error, loading] = useLogoutCallback(options);

Parameters

Inputs

Mandatory parameters are in bold

Parameter	Type	Description
options	LogoutOptions	Object with non mandatory attributes Defaults: {}
options. onSuccess	AppSuccessCallback	Called if the logout callback was successful. Defaults: a function that redirects the user to the original requested page or the homepage
options. onError	AppErrorCallback	Called if the logout callback returned an error. Defaults: a function sending a notification on the topic logout-error

Outputs

Parameter	Type	Description
error	BasicError	Set if the callback request contains an error. The error object contains three properties: code message: the error message payload: any additionnal data specific to the error
loading	boolean	Flag to indicate that an AJAX request is in progress

Example

OIDC authentication
The user is redirected to this page by the external entity following a logout

import React from "react";
import { useLoginCallbackService } from "onekijs";

export default React.memo(() => {
  const [error] = useLogoutCallbackService();
  if (error) {
    return <div>{error.payload.message} <span onClick={() => error.remove()}>X</span></div>
  }
  return null;
}