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.
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.
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.
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:
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:
---
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.
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. |