Authentication Guide

The frontend authentication flow of the Web App works based on an auth code, generated by the frontend, which is then used to request an access token to be included in the headers of each request.

Frontend authentication flow

See the following step-by-step guide for embedding the XUND Web App and initializing authentication.

Referenced variables

The following variables are referenced in the examples. By replacing them with the proper values the example codes do the authentication.

Variable name	Environment	Value
`XUND_AUTH_BASE_URL`	BETA	`https://login.beta.xund.solutions/api`
`XUND_AUTH_BASE_URL`	CLASS2	`https://login.xund.solutions/api`
`XUND_APP_BASE_URL`	BETA	`https://frame.webapp.beta.xund.solutions` If you work with a branded Web App, the Web App config’s code must be part of the base URL For example: `https://frame.webapp.beta.xund.solutions/8c140473-49e8-48a8-a410-37bf697899b0`
`XUND_APP_BASE_URL`	CLASS2	`https://frame.webapp.class2.xund.solutions` If you work with a branded Web App, the Web App config’s code must be part of the base URL For example: `https://frame.webapp.class2.xund.solutions/8c140473-49e8-48a8-a410-37bf697899b0`
`YOUR_CLIENT_ID`		Unique Client ID generated for your API key in the Client Hub

Implementation steps

Create a .js file with the following content and host it near the page where you want to do the integration. In this example, we will name it as frontend-auth.js:

JS

import { CLIENT_ID, CH_ID_API_BASE_URL, WEBAPP_BASE_URL } from './config.js'

const initAuth = async () => {
  const appendSearchParamsIfSet = (url, searchParams) => {
    for (const [name, value] of Object.entries(searchParams)) {
      if (value) {
        url.searchParams.append(name, value)
      }
    }
  }

  const wrapperSearchParams = new URLSearchParams(window.location.search)

  const clientId = wrapperSearchParams.get('clientId') || CLIENT_ID
  const code = wrapperSearchParams.get('code') ?? ''

  const birth = wrapperSearchParams.get('birth')
  const gender = wrapperSearchParams.get('gender')
  const checkId = wrapperSearchParams.get('checkId')
  const state = wrapperSearchParams.get('state')
  const directCheck = wrapperSearchParams.get('directCheck')

  const authCode = crypto.randomUUID?.() ?? crypto.getRandomValues(new Uint32Array(40)).join('')

  const authorizeRequestUrl = new URL(`${CH_ID_API_BASE_URL}/authorize`)
  appendSearchParamsIfSet(authorizeRequestUrl, { clientId, authCode, state })

  await fetch(authorizeRequestUrl)

  const webappUrl = new URL(`${WEBAPP_BASE_URL}/${code}`)
  appendSearchParamsIfSet(webappUrl, { birth, gender, checkId, state, directCheck })

  const tokenRequestUrl = new URL(`${CH_ID_API_BASE_URL}/token`)
  appendSearchParamsIfSet(tokenRequestUrl, { clientId, authCode, redirectUri: webappUrl })

  document.getElementById('xund-iframe').src = tokenRequestUrl
}

initAuth()

window.addEventListener('message', async (e) => {
  if (e.origin !== WEBAPP_BASE_URL) {
    return
  }

  if (e.data.type === 'refresh') {
    initAuth()
  }
})

Create a config.js file to export the custom variables needed for the integration in the same directory with frontend-auth.js. Don’t forget to change the values of the variables (CLIENT_ID, CH_ID_API_BASE_URL, WEBAPP_BASE_URL):

JS

export const CLIENT_ID = YOUR_CLIENT_ID
export const CH_ID_API_BASE_URL = XUND_AUTH_BASE_URL
export const WEBAPP_BASE_URL = XUND_APP_BASE_URL

Load frontend-auth.js and create a container iframe too on the page where you want to do the integration (example):

HTML

<!DOCTYPE html>
<html lang="en" style="height: 100%">
  <head>
    <title>XUND Web App</title>
    <script src="frontend-auth.js" type="module"></script>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>

  <body style="height: calc(100% + 6px); margin: 0; overflow: hidden">
    <iframe
      allow="geolocation"
      id="xund-iframe"
      style="width: 100vw; height: 100vh; border: none"
      title="Web App Frame"
    />
  </body>
</html>

Definitions

frontend	A user-facing application embedding a XUND web app, where it’s a requirement to avoid storing a permanent `API key`. For setting up a frontend see Setting up a frontend for secure authentication
backend	An application inaccessible to end-users, viable for storing secrets. For setting up a backend-based authentication see Setting up a backend for secure authentication
auth code	A short-lived expiring token used for requesting an `access token`. Only one `auth code` is used for each `access token` request
access token	The XUND auth module sends this expiring token in the header of each request. When an `access token` is expired, the client needs to restart the session
API key	A pre-registered secret used for identifying a client
origin	A pre-registered hostname pointing to the `frontend`, used to check if requesting the `auth code` happens from the configured `frontend`