What are authentication artifacts used for in hapi.js authentication schemes?

Question

In the hapi.js API they specify that authentication schemes can also return artifacts as part of the credentials object.

What exactly are authentication artifacts and why are they useful? Is there a good example for why the hapi team included this as part of their API?

• result - an object containing:
  • credentials - the authenticated credentials.
  • artifacts - optional authentication artifacts.

http://hapijs.com/api#serverauthschemename-scheme

Answer 1

Short answer

On request.auth you have access to the following properties:

• credentials - Things that identify or represent the unique user
• artifacts - Optional authentication-related data that isn't credentials

Hapi auth schemes aren't stateful but they can store the important auth data in request.auth.artifacts so it can be accessed by other auth functions in the scheme at a later time.

What exactly are authentication artifacts?

First let's look at a general definition of an artifact (from Wikipedia):

[artifacts] refer to something that arises from the process in hand rather than the issue itself, i.e., a result of interest that stems from the means rather than the end.

An authentication scheme can optionally pass back to the consuming application some of the internal information (byproducts) about the authentication attempt once it's finished initially authenticating the request.

Obviously the data inside artifacts is different to each scheme. When using Hawk (with hapi-auth-hawk), the artifacts will be a object containing info specific to Hawk, such as the timestamp, nonce and MAC code from the request:

{ 
    method: 'GET',
    host: '127.0.0.1',
    port: '8000',
    resource: '/resource/1?b=1&a=2',
    ts: '1426940961',
    nonce: 'IRd0nH',
    hash: undefined,
    ext: 'and welcome!',
    app: undefined,
    dlg: undefined,
    mac: 'tKolc1UJ5w8zGcDT6+knQFDHAdJtf0/rDLOZHTzUCoU=',
    id: 'dh37fgj292je' 
} 

…why are they useful?

An example of why they're useful can be found in hapi-auth-hawk. Remember an auth scheme in hapi can have 3 different functions called for authentication:

• authenticate - Required function to authenticate the initial request
• payload - Optionally validates the payload
• response - Optionally validates the response

In hapi-auth-hawk, request.auth.artifacts is populated in the authenticate method from the initial request. This means that if payload or response are executed later, they can access that same shared state off the request object without having to parse the request again, so it's basically just a handy container for the pertinent auth data pulled from the request in this case.