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