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 a “token set” from a customer-provided Pathway server and include the tokens in each REST request.

The CLIENT process is configured to retrieve a single named or unnamed token set. A named token set is one or more tokens to be used with each RESET request referred to by a customer provided name.
The CLIENT process manages fetching and caching the token set, adding the tokens to each request, and fetching a new token set when the cached token set expires.
Any token that can be supplied as an HTTP header or query param, such as OAuth bearer tokens and JSON Web Tokens (JWT), may be in a token set.

How it Works

When the CLIENT process receives a request from an application, it checks its internal token set cache to determine if a token set is already available. If not, CLIENT queues the request and sends a request to the customer’s token server to get a new token set. If an error occurs in fetching the token set, the CLIENT process will retry the request up to the limit defined in the configuration file. If the token set is fetched successfully, the tokens in the set will be inserted into the request header or query param, based on the information returned from the token server. Tokens in a set can be automatically base64 encoded and reformatted before being added to the request. For example, if the token server returns a 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 Set 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-FETCH-TKN-SET-V1.
The RQ-TS-UNIQE field will contain a unique value retrieved from the TS_UNIQUE_CREATE_ system procedure call.
The TKN-SET-NAME and TKN-SET-NAME-LEN are filled in from the values in the YAML configuration file, if the tokenSetName option is present. If the option is not present, the fields will be binary 0s.
All other fields will be filled with binary 0s.

TEXT

Definition LW-AE-FETCH-TKN-SET-V1-RQ.

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

  001  01 LW-AE-FETCH-TKN-SET-V1-RQ           0           Group 292
  002   02 HEADER                             0           Group 32                                  LW-AE-RQ-HEADER
  003    03 RQ-CODE                           0           Enumeration
    004     89 LW-AE-RQ-FETCH-TKN-SET-V1                  Enumeration clause
    005     89 LW-AE-RQ-INFO-TKN-SET-V1                   Enumeration clause
    006     89 LW-AE-RQ-VERIFY-TKN-SET-V1                 Enumeration clause
  007    03 RESERVED-1                        2           Binary(16) signed
  008    03 RQ-TS-UNIQUE                      4           Binary(64) signed, Occurs [2:2]
  009    03 RESERVED                          20          Character 12
  010   02 TKN-SET-NAME-LEN                   32          Binary(32) signed
  011   02 TKN-SET-NAME                       36          Character 256                             LW-AE-TKN-SET-NAME

          Definition size is 292 bytes.

The Token Response

Upon receiving this request, the token server should retrieve the tokens in the token set from one or more underlying token servers and return the tokens in the set 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 TKN-SET-NAME and TKN-SET-NAME-LEN fields are echoed from the request.
- The TKN-SET-TTL field contains the number of seconds that the token set is valid. When this interval is near expiration or has expired, the CLIENT process will attempt to fetch a new token set. If the token server returns 0, the default value is 3600 (1 hour).
- TKN-SET-COUNT indicates the number of tokens in the TKN-SET array. Up to 16 tokens can be returned in a token set.
- TKN-SET is an array, with each occurrence containing the following set of fields:
  - TKN-TYPE indicates whether the token is to be sent as a header field (LW-AE-TKN-TYPE-HEADER) or a query param (LW-AE-TKN-TYPE-PARAM).
  - BASE64-ENCODE indicates whether the token returned from the token server should be base64 encoded. The token server should return 1 to enable base64 encoding, or zero to indicate no encoded should be performed by the CLIENT process for this token.
  - TKN-FORMAT should contain 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. TKN-FORMAT-LEN is the length of the format string.
  - TKN-NAME is the name to use for the token header or query param. TKN-NAME-LEN is the length of the token name.
  - The TKN-VALUE-LEN field indicates that length of the token contained in the TKN-VALUE field.
  - The TKN-VALUE 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-FETCH-TKN-SET-V1-RP.

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

  001  01 LW-AE-FETCH-TKN-SET-V1-RP           0           Group 41548
  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 TKN-SET-NAME-LEN                   32          Binary(32) signed
  010   02 TKN-SET-NAME                       36          Character 256                             LW-AE-TKN-SET-NAME
  011   02 TKN-SET-TTL                        292         Binary(32) unsigned
  012   02 TKN-COUNT                          296         Binary(32) signed
  013   02 TKN-SET                            300         Group 2578, Occurs [1:16]                 LW-AE-FETCH-ITEM-V1
              Occurs depends on TKN-COUNT.
  014    03 TKN-TYPE                          300         Enumeration
    015     89 LW-AE-TKN-TYPE-HEADER                      Enumeration clause
    016     89 LW-AE-TKN-TYPE-PARAM                       Enumeration clause
  017    03 BASE64-ENCODE                     302         Binary(32) signed
  018    03 TKN-FORMAT-LEN                    306         Binary(32) signed
  019    03 TKN-FORMAT                        310         Character 256
  020    03 TKN-NAME-LEN                      566         Binary(32) signed
  021    03 TKN-NAME                          570         Character 256
  022    03 TKN-VALUE-LEN                     826         Binary(32) signed
  023    03 TKN-VALUE                         830         Character 2048

          Definition size is 41548 bytes.

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-TOKEN-ERROR-RP.

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

  001  01 LW-AE-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

          Definition size is 4140 bytes.

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:
    tokenSetName: "Customer-defined-name"
...

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
tokenSetName	The token set name to use for the token server requests. If omitted, then no token set name will be contained in the token server request.