Form based authentication

Form based authentication means that the login page presents a form, so that the user can specifiy a username and password.

Oneki.js allows you to build the form as you wish, but provide a function to:

• submit the username / password to the backend server
• manage the response returned by the backend server

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 hook to generate a submit function. This function executes the AJAX POST request that sends the credentials to the backend system.

Example

Basic form login

Login

examples/cra-examples/src/auth/login/form/IndexPage.tsx

loading...

See full example on GitHub

Settings

examples/cra-examples/src/settings.ts

loading...

See full example on GitHub

👁 Preview

Configuration

the useLogin and useLogout hooks are configured via several parameters in src/settings.ts (see configuration)

the following parameters are available:

export default {
  idp: {
    default: {
      // MANDATORY parameters
      type: "form",
      loginEndpoint: "/api/login",

      // OPTIONAL parameters
      logoutEndpoint: "/api/logout",
      userinfoEndpoint: "/api/whoami",
      loginMethod: "POST",
      loginContentType: "application/json",
      usernameKey: "username",
      passwordKey: "password",
      rememberMeKey: "rememberMe",
      logoutMethod: "GET",
      callback: (result, context) => [null, result],
    },
  },
};

_Mandatory parameters are marked with a \*_

Key	Type	Description
type*	string	must be "form"
loginEndpoint*	loginEndpoint	The URL of the API that authenticate the user Can be A relative or absolute URL A function returning the URL
logoutEndpoint	logoutEndpoint	The URL of the API that disconnect the user 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']}}
loginMethod	string	if loginEndpoint is a URL, the HTTP method used to send the username and password to the server Defaults to: POST
loginContentType	string	the HTTP Content-Type header value can be application/x-www-form-urlencoded application/json Defaults to: application/json
usernameKey	string	the name of the parameter in the request sent to the server that contains the username Defaults to: username
passwordKey	string	the name of the parameter in the request sent to the server that contains the password Defaults to: password
rememberMeKey	string	the name of the parameter in the request sent to the server that contains the rememberMe Defaults to: rememberMe
logoutMethod	string	if logoutEndpoint is a URL, the HTTP method used to call the logout URL Defaults to: GET
callback	callback	a callback function to parse the AJAX POST response. 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

tip

Oneki.js provides out of the box two callback functions ready to be used. These functions can be referenced via their alias

Alias	Description
idp.<idpId>.callback = 'token'	Use this value if the response contains the token. This function: persists the token based on the value idp.<idpId>.persist validates the JWT token if idp.<idpId>.validate = true refreshes the token if the response contains a refresh_token
idp.<idpId>.callback = 'securityContext'	Use this value if the response contains a JSON that represents the user profile. Instead of calling the userinfoEndpoint to retrieve the profile, this function persists directly the response in the global state