Authentication Exits

This is preview documentation and is subject to change.

The LightWave Client™ Authentication Exits feature allows customers to add custom authentication tokens to REST requests as HTTP headers or queryParams. Using a simple YAML configuration file, the CLIENT process can be configured to fetch tokens from a customer-provided Pathway server and include them in each REST request.

The CLIENT process manages fetching and caching tokens, adding the tokens to each request, and fetching new tokens when the cached tokens expire.
Any token that can be supplied as an HTTP header or query param, such as OAuth bearer tokens and JSON Web Tokens (JWT) can be used.

How it Works

When the CLIENT process receives a request from an application, it checks its internal token cache to determine if a token is already available. If not, CLIENT queues the request and sends a request to the customer’s token server to get a new token. If an error occurs in fetching the token, the CLIENT process will retry the request up to the limit defined in the configuration file. If the token is fetched successfully, the token will be inserted into the request header or query param, based on the configuration. The token can be automatically base64 encoded, and reformatted before being added to the request. For example, if the token server returns the token as 32 bytes of binary data, the token can be base64 encoded and reformatted into a bearer token header value such as “Bearer dGhpcyBpcyB0aGUgdG9rZW4=”.

Creating a Custom Token Server

The CLIENT process communicates with the token provider serverclass using a standard request and response IPM. The DDL for the message exchange is provided in the LWAEDDL file included with the LightWave Client distribution. This DDL can be compiled and used to produce IPM structures in the programming language used for the token server.

The Token Request

The CLIENT process sends the following IPM request to the token server, where:

The RQ-CODE field will contain the value LW-AE-RQ-GET-TOKEN-V1.
The RQ-TS-UNIQE field will contain a unique value retrieved from the TS_UNIQUE_CREATE_ system procedure call.
All other fields will be filled with binary 0s.

TEXT

Definition LW-AE-GET-TOKEN-V1-RQ.

  Num  LV Element Name                        Offset(Bit) Data Type & Size                          Source Definition

  001  01 LW-AE-GET-TOKEN-V1-RQ               0           Group 32
  002   02 HEADER                             0           Group 32                                  LW-AE-RQ-HEADER
  003    03 RQ-CODE                           0           Enumeration
    004     89 LW-AE-RQ-GET-TOKEN-V1                      Enumeration clause
  005    03 RESERVED-1                        2           Binary(16) signed
  006    03 RQ-TS-UNIQUE                      4           Binary(64) signed, Occurs [2:2]
  007    03 RESERVED                          20          Character 12

          Definition size is 32 bytes.

The Token Response

Upon receiving this request, the token server should retrieve a token from the underlying token server and return it using the following IPM structure, where:

The RP-CODE indicates the outcome of the request:
- LW-AE-RP-SUCCESS indicates a token was returned.
- LW-AE-RP-RETRY indicates that the CLIENT process should retry the request.
- LW-AE-RP-ERROR indicates that an error occurred.
If RP-CODE is LW-AE-RP-SUCCESS:
- The TOKEN-TTL field contains the number of seconds that the token is valid. When this interval is near expiration or has expired, the CLIENT process will attempt to fetch a new token.
- The TOKEN-LEN field indicates that length of the token contained in the TOKEN field.
- The TOKEN field contains the token data.
If RP-CODE is LW-AE-RP-RETRY:
- RETRY-INTERVAL contains the number of seconds to wait before retrying the request.

TEXT

Definition LW-AE-GET-TOKEN-V1-RP.

  Num  LV Element Name                        Offset(Bit) Data Type & Size                          Source Definition

  001  01 LW-AE-GET-TOKEN-V1-RP               0           Group 1064
  002   02 HEADER                             0           Group 32                                  LW-AE-RP-HEADER
  003    03 RP-CODE                           0           Enumeration
    004     89 LW-AE-RP-SUCCESS                           Enumeration clause
    005     89 LW-AE-RP-RETRY                             Enumeration clause
    006     89 LW-AE-RP-ERROR                             Enumeration clause
  007    03 RETRY-INTERVAL                    2           Binary(16) signed
  008    03 RESERVED                          4           Character 28
  009   02 TOKEN-TTL                          32          Binary(32) signed
  010   02 TOKEN-LEN                          36          Binary(32) signed
  011   02 TOKEN                              40          Character 1024

Error Handling

When the CLIENT process encounters an error, either when communicating with the token server, or an error is returned by the token server itself, it will retry the request using the retry interval and max count supplied in the configuration file. If the error condition persists, the error will be reported back to the client application using the standard LightWave Client error handling mechanism. For a detailed description of LightWave Client error handling, see Error Handling.

The result of the token server request is made available in the LIGHTWAVE-ERROR-RP message. In the event of an error communicating with the token server serverclass, a LIGHTWAVE-ERROR-RP IPM will be returned to the client application, where:

The RP-CODE field will contain LW-RP-ERROR.
The ERROR-SOURCE field will contain LW_ERROR_SOURCE_LIGHTWAVE_AUTH_EXIT.
The ERROR-CODE field will contain the Pathway error code, as returned from SERVERCLASS_SEND_INFO_.
The ERROR-SUBCODE field will contain the filesystem error associated with the Pathway error code.
The ERROR-MESSAGE field will contain a text message describing the error, as a NULL terminated string.

If the token server encounters an error while obtaining a token, it can return a reply indicating the error, or requesting a retry after a supplied interval.

To indicate a retry, return the LW-AE-GET-TOKEN-V1-RP structure, where:

The RP-CODE field is LW-AE-RP-RETRY.
The RETRY-INTERVAL field is the number of seconds to wait before sending another request.
All other fields are ignored.

To indicate an error, return the LW-AE-GET-TOKEN-ERROR-RP, where:

The RP-CODE field is LW-AE-RP-ERROR
The ERROR-CODE, ERROR-SUBCODE, ERROR-MESSAGE-LEN, and ERROR-MESSAGE fields contain information the client application can use to report the error condition in the token server.

CODE

Definition LW-AE-GET-TOKEN-ERROR-RP.

  Num  LV Element Name                        Offset(Bit) Data Type & Size                          Source Definition

  001  01 LW-AE-GET-TOKEN-ERROR-RP            0           Group 4140
  002   02 HEADER                             0           Group 32                                  LW-AE-RP-HEADER
  003    03 RP-CODE                           0           Enumeration
    004     89 LW-AE-RP-SUCCESS                           Enumeration clause
    005     89 LW-AE-RP-RETRY                             Enumeration clause
    006     89 LW-AE-RP-ERROR                             Enumeration clause
  007    03 RETRY-INTERVAL                    2           Binary(16) signed
  008    03 RESERVED                          4           Character 28
  009   02 ERROR-CODE                         32          Binary(32) signed
  010   02 ERROR-SUBCODE                      36          Binary(32) signed
  011   02 ERROR-MESSAGE-LEN                  40          Binary(32) signed
  012   02 ERROR-MESSAGE                      44          Character 4096

When this response is received, and all retries are exhausted, this error will be returned to the client application in the LIGHTWAVE-ERROR-RP structure, where:

The RP-CODE field will contain LW-RP-ERROR.
The ERROR-SOURCE field will contain LW_ERROR_SOURCE_LIGHTWAVE_AUTH_EXIT.
The ERROR-CODE field will contain the ERROR-CODE value returned by the token server.
The ERROR-SUBCODE field will contain the ERROR-SUBCODE value returned by the token server.
The ERROR-MESSAGE field will contain the ERROR-MESSAGE returned by the token server, as a NULL terminated string.

Configuring Authentication Exits

The Authentication Exit is configured using a process configuration file. The configuration is activated by specifying the configuration options in an EDIT file and providing the file location with the --auth-exit startup option. Change monitoring for the configuration file may be configured using the --monitor option, for example:

TEXT

tacl> run CLIENT --auth-exit +$vol.subvol.aeconf [ --monitor auth-exit ]

The configuration is specified using YAML 1.1 format. The file contains information defining the token serverclass that supplies the token, and instructions for injecting the token into the request, for example:

YAML

---
AuthExitConfig:
  tokenProvider:
    providerType: serverclass
    pathmon: =token^pathmon
    serverclass: tokenserver
    ioRetryInterval: 3
    ioRetryMax: 3
  tokenOptions:
    tokenType: "header"
    tokenName: "Authorization"
    tokenFormat: "Bearer %s"
    tokenBase64Encode: false
    tokenTTL: 3600
...

Checking Configuration File Syntax

During the process of creating or updating a configuration file, the configuration may be validated using the LWCCOM VALIDATE command.

CODE

tacl> run lwccom
LightWave Client COM 1.4.0 - \NODE.$X123
Copyright (c) 2024 NuWave Technologies, Inc. All rights reserved.
LWCCOM 1-> validate config lwaeconf
Checking CONFIG file LWAECONF.
The file contains a valid 'auth-exit' configuration.
The CONFIG file is valid.
LWCCOM 2->

Configuration Reference

tokenProvider Elements

Element	Description
providerType	Indicates the type of provider, which must be “serverclass”. If omitted, the default value is “serverclass”
pathmon	The process name of the serverclass PATHMON process, which may be specified as a DEFINE. Required if type is "serverclass".
serverclass	The serverclass name. Required if type is "serverclass".
ioRetryInterval	The number of seconds to wait before attempting another request to the token server, after an error has occurred. If omitted, the default value is 3.
ioRetryMax	The number of retries to attempt before returning an error to the client application. If omitted, the default value is 3.

tokenOptions Elements

Element	Description
tokenType	Indicates where the token should be injected into the request. The value must be “header” or “queryparam”. If omitted, the default value is “header”.
tokenName	The name to use for the token header or query param. This element is required.
tokenFormat	A format string to use to further format the token value. The string may contain a single placeholder in value ‘%s’ and any additional text to use to format the token. For example, the format string “Bearer %s” will format the token in the form “Bearer the-token”. If omitted, no formatting occurs.
tokenBase64Encode	Indicates whether the token returned from the token server should be base64 encoded. Supply true to enable base64 encoding. If omitted, the default value is false.
tokenTTL	The default value for the token time to live, in seconds. If the token server returns 0 in the token reply TOKEN-TTL field, this value will be used. If omitted, the default value is 3600 (1 hour).