Creating a Custom Token Server
This is preview documentation and is subject to change.
The SERVER/SWORKER 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 Server distribution. This DDL can be compiled and used to produce IPM structures in the programming language used for the token server.
The Token Set Information Request
The SERVER/SWORKER process sends the following IPM request to the token server to retrieve token information, where:
The RQ-CODE field will contain the value LW-AE-RQ-INFO-TKN-SET-V1.
The RQ-TS-UNIQUE 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 AuthExit rule, if the tokenSetName property is defined in the rule. If the property is not defined, the string field will be filled with the configured string padding character, and the binary value set to zero.
All other fields will be filled with binary 0s.
Definition LW-AE-INFO-TKN-SET-V1-RQ.
Num LV Element Name Offset(Bit) Data Type & Size Source Definition
001 01 LW-AE-INFO-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 Set Verification Response
Upon receiving this request, the token server should verify that the values sent in the request are valid. The outcome is indicated in the IPM reply where:
The RP-CODE indicates the outcome of the request:
LW-AE-RP-SUCCESS indicates that all the token values from the verification request are valid.
LW-AE-RP-RETRY indicates that the SERVER/SWORKER process should retry the request.
LW-AE-RP-ERROR indicates that an error occurred with the Token Server, or that one or more of the token values are invalid. The result means the same for the token verification of the REST request.
If RP-CODE is LW-AE-RP-SUCCESS:
The set of token values in the request are valid.
TKN-SET-TTL is the number of seconds for which the values may be retained in the token cache. Future REST requests are verified against the token cache until the TTL has expired. Once expired, the next REST request will result in a new verification request sent to the Token Server.
If RP-CODE is LW-AE-RP-ERROR:
LWS attempts to retry the token verification request until RP-CODE is LWS-AE-RP-SUCCESS or LWS exhausts its configured retry attempts.
If retry attempts are exhausted, the current (and any pending) REST request awaiting a token verification are denied with HTTP status 403.
TKN-SET-NAME and TKN-SET-NAME-LEN must echo the values from the verification request.
Definition LW-AE-INFO-TKN-SET-V1-RP.
Num LV Element Name Offset(Bit) Data Type & Size Source Definition
001 01 LW-AE-INFO-TKN-SET-V1-RP 0 Group 8716
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 526, Occurs [1:16] LW-AE-INFO-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-DECODE 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
Definition size is 8716 bytes.The Token Set Verification Request
The SERVER/SWORKER process sends the following IPM request to the token server to verify token values, where:
The RQ-CODE field will contain the value LW-AE-RQ-VERIFY-TKN-SET-V1.
The RQ-TS-UNIQUE 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 AuthExit rule, if the tokenSetName property is defined in the rule. If the property is not defined, the string field will be filled with the configured string padding character, and the binary value set to zero.
TKN-COUNT is the number of token values in the request.
From 1 to 16 token values may be present in TKN-SET:
TKN-TYPE is one of LW-AE-TKN-TYPE-HEADER or LW-AE-TKN-TYPE-PARAM.
The TKN-NAME and TKN-NAME-LEN fields contain the token name and the token name length, respectively. The values are copied from the token info set returned by the Token Server.
The TKN-VALUE and TKN-VALUE-LEN fields contain the value and value length, respectively, of the token extracted from the named header or query param in the REST request.
Note that the verification request message length will vary depending on the number of tokens sent.
Definition LW-AE-VERIFY-TKN-SET-V1-RQ.
Num LV Element Name Offset(Bit) Data Type & Size Source Definition
001 01 LW-AE-VERIFY-TKN-SET-V1-RQ 0 Group 37128
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 64 LW-AE-TKN-SET-NAME
012 02 TKN-COUNT 100 Binary(32) signed
013 02 TKN-SET 104 Group 2314, Occurs [1:16] LW-AE-VERIFY-ITEM-V1
Occurs depends on TKN-COUNT.
014 03 TKN-TYPE 104 Enumeration
015 89 LW-AE-TKN-TYPE-HEADER Enumeration clause
016 89 LW-AE-TKN-TYPE-PARAM Enumeration clause
017 03 TKN-NAME-LEN 106 Binary(32) signed
018 03 TKN-NAME 110 Character 256
019 03 TKN-VALUE-LEN 366 Binary(32) signed
020 03 TKN-VALUE 370 Character 2048
Definition size is 37128 bytes.The Token Set Verification Response
Upon receiving this request, the token server should verify that the values sent in the request are valid. The outcome is indicated in the IPM reply where:
The RP-CODE indicates the outcome of the request:
LW-AE-RP-SUCCESS indicates that all the token values from the verification request are valid.
LW-AE-RP-RETRY indicates that the SERVER/SWORKER process should retry the request.
LW-AE-RP-ERROR indicates that an error occurred with the Token Server, or that one or more of the token values are invalid. The result means the same for the token verification of the REST request.
If RP-CODE is LW-AE-RP-SUCCESS:
The set of token values in the request are valid.
TKN-SET-TTL is the number of seconds for which the values may be retained in the token cache. Future REST requests are verified against the token cache until the TTL has expired. Once expired, the next REST request will result in a new verification request sent to the Token Server.
If RP-CODE is LW-AE-RP-ERROR:
LWS attempts to retry the token verification request until RP-CODE is LWS-AE-RP-SUCCESS or LWS exhausts its configured retry attempts.
If retry attempts are exhausted, the current (and any pending) REST request awaiting a token verification are denied with HTTP status 403.
TKN-SET-NAME and TKN-SET-NAME-LEN must echo the values from the verification request.
Definition LW-AE-VERIFY-TKN-SET-V1-RP.
Num LV Element Name Offset(Bit) Data Type & Size Source Definition
001 01 LW-AE-VERIFY-TKN-SET-V1-RP 0 Group 104
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 64 LW-AE-TKN-SET-NAME
011 02 TKN-SET-TTL 100 Binary(32) unsigned
Definition size is 104 bytes.