Authentication

To authenticate users the NeoDay client library makes requests to an endpoint of your choice that must return a signed token for the bearing user. The token is a JWT signed with your client secret using the HS256 algorithm.

The authentication endpoint can be passed into the NeoDay constructor. It is possible to configure additional parameters and headers. The parameters will be sent as GET parameters.

let neo = new neoday.NeoDay({
    base_url: 'https://gateway.test.client-designated-gateway.neo.day',
    locale: 'nl_NL',
    auth: {
        endpoint: '/api/auth',
        x_site_token: '',
        client_id: '',
        headers: {},
        params: {}
    }
});

Once a component is mounted that requires authentication the following flow is initiated:

Implementing the authentication endpoint

The client library will make a GET request to configured endpoint and will expect a JSON response containing a JWT signed with your client secret.

The following claims must be set on the token:

claim	name	description
`sub`	subject	The user's ID
`iss`	issuer	Your client ID
`iat`	issued at	Must be less then or equal to 10 minutes from now
`exp`	expiration	Must be less then or equal to 10 minutes in the future
`nbf`	not before	Must be less then or equal to 10 minutes in the past

The following claims are optional:

claim	description	default
`create_user`	Set this to `false` to prevent creating new users	`true`

The token must be signed with your client secret using the HS256 algorithm.

After the token is generated it must be returned within the "token" property of a JSON object. Below is an example using the javascript jose library.

const [clientID, clientSecret] = getClient();
const user = getLoggedInUser();

const jwt = await new jose.SignJWT({})
  .setProtectedHeader({ alg: 'HS256' })
  .setIssuedAt()
  .setNotBefore('0s')
  .setExpirationTime('60s')
  .setIssuer(clientID)
  .setSubject(user.id)
  .sign(new TextEncoder().encode(clientSecret))

JSON.stringify({ token: jwt })
// {"token":"eyJhbGciOiJIUzI1NiJ9........"}

Personal data

Additional data such as a user's name or email can be added to the token. This data will then be available to components of NeoDay, allowing for example the user's name to be shown on their customer card. The possible fields that can be submitted depend on what is configured on the gateway. For example if there is a first_name and email field configured they can be added to the token using a person property:

const person = {
  first_name: "John",
  email: "[email protected]"
};
const jwt = await new jose.SignJWT({person})
  .setProtectedHeader({ alg: 'HS256' })
  .setIssuedAt()
  .setNotBefore('0s')
  .setExpirationTime('60s')
  .setIssuer(clientID)
  .setSubject(user.id)
  .sign(new TextEncoder().encode(clientSecret))

/** Decoded payload:
 * {
 *  "person": {
 *    "first_name": "John",
 *    "email": "john.doe@example.com"
 *  },
 *  "iat": 1669208031,
 *  "iss": "my-client-id",
 *  "sub": 1,
 *  "exp": 1669211631
 * }
 */