| Table of Contents |
|---|
...
Logon Handler is represented by the libLogonHandler.so library and provided as a part of the Supplementary Adapters and Handlers package (SupAdapters-FE-*).
| Info |
|---|
The mechanism of session validity by the Logon Handler may work along with other authentication logic. Logon Handler is designed for acceptor sessions only. |
Handler functions
Logon Handler allows forming a User Request (35=BE) message and then sends it to the authentication system.
...
| User Request (BE) | Value source |
|---|---|
| BeginString(8) | From configuration parameter Validator.MessageVersion |
SenderCompID(49) | From configuration parameter Validator.SenderCompID |
TargetCompID(56) | From configuration parameter Validator.TargetCompID |
| OnBehalfOfCompId(115) | From the incoming Logon(A) message SenderCompId(49) |
| Username(553) | From the incoming Logon(A) message Username(553) |
| Password(554) | From the incoming Logon(A) message Password(554) |
| RawDataLength(95) | From the incoming Logon(A) message RawDataLength(95) |
| RawData(96) | From the incoming Logon(A) message RawData(96) |
| UserRequestID(923) | The unique value is generated by the handler. |
| UserRequestType(924) | Set to "1": Log On User |
...
| User Request (BE) | Value source |
|---|---|
| BeginString(8) | From configuration parameter Validator.MessageVersion |
SenderCompID (49) | From configuration parameter Validator.SenderCompID |
TargetCompID (56) | From configuration parameter Validator.TargetCompID |
| OnBehalfOfCompId(115) | SenderCompId(49) of the disconnected session |
| UserRequestID(923) | The unique value starting with "lah" is generated by the handler. |
UserRequestType(924) | Set to "2": Log Out User |
...
Logon Handler processes the authentication system response with subsequent session acceptance or rejection. If a session should be authenticated in case of logon, the response from the authentication system is expected to be a User Response (BF) message with a result.
| User Response (BF) | Value source |
|---|---|
| UserStatus (926) | Mandatory tag in response. Supported values:
|
| DeliverToCompID (128) | The value of SenderCompId (49) for session passing authentication. The values from OnBehalfOfCompID (115) tag from the Request. |
| UserRequestID | Should be the same as UserRequestID in the origin User Request. |
| Username | The values from Username (553) tag from the Request. |
| UserStatusText (927) | Optional. A third-party system can add the error message with the reason for the rejection The human-readable status of the response. Should be defined by the authentication system to indicate the reason for the success or failure. The error message is not transferred to the client. The client session is disconnected without Logout (recommended by standard behavior) |
...
| Note |
|---|
Even if the authentication service resulted in accepting the session, the session can be rejected by other authentication and session acceptance checks. For example, the session can be rejected if the sequence number in the incoming logon is not expected. In this case, the session should be rejected due to FIX protocol recommendations. Recommendations about sequence number handling can be found here: Sequence number handling |
Logon and message samples
...
| Code Block | ||
|---|---|---|
| ||
20201216-06:24:04.722 : 8=FIX.4.4|9=112|35=BF|49=Validator|56=FIXEDGE|128=FIXCLIENT|34=4|52=20201216-06:24:04.722|923=lah.0|553=user|926=1|927=accepted|10=167| |
Requirements for a third-party system
The following requirements are determined for a third-party system:
...
Property name | Description | Required |
|---|---|---|
Common BL (Business Logic) handlers configuration parameters | ||
Name | Reference name used in the Business Logic Actions. Example: LogonHandler | Y |
Description | A description defined by a user Example: Logon Authentication Handler | Y |
DllName | Path to a library, starting from RootDir Example: ./libLogonHandler.so | Y |
VerifyHandlersVersion | If set to "true" FIXEdge prevents the use of an unexpected version of the module in order to avoid incompatible changes between two different FIXEdge versions. The recommended value is "true". If the version of the handler is different from the FIXEdge version, the module will not be loaded and the corresponding error will be logged. | N |
Specific Logon Handler configuration parameters | ||
Validator.SenderCompID | SenderCompID of the authentication service FIX session Corresponds to FixLayer.FixEngine.Session.Session_Name.SenderCompID from FIXEdge.properties. | Y |
Validator.TargetCompID | TargetCompID of the authentication service FIX session Corresponds to FixLayer.FixEngine.Session.Session_Name.TargetCompID from FIXEdge.properties. | Y |
Validator.MessageVersion | FIX protocol version of the authentication service session Corresponds to FixLayer.FixEngine.Session.Session_Name.Version from FIXEdge.properties. | Y |
Validator.TimeoutMs | Authentication service FIX session response timeout (in milliseconds) The request is sent synchronously. Until FIXEdge receives a response, the session will not be accepted or logged out, the messages will not be accepted and processed in this case. | Y |
...
Processing authentication service response
The response about the decision from the authentication service should be routed to the Logon Handler.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<Rule Description="Notify handler that connection is down">
<Source>
<FixSession SenderCompID="fake" TargetCompID="fake" />
</Source>
<Condition>
<EqualField Field="35" Value="C"/>
</Condition>
<Action>
<HandlerAction Name="LogonHandler" />
</Action>
</Rule> |
Recommendations
- It is recommended to establish the FIX Session to authentication service during system startup. The session should reconnect on each connection drop.
- It is recommended to reset sequences during maintenance windows, e.g. on the weekend.
- LogonHandler doesn't support Session Qualifier
Reject all sessions if LogonHandler is not loaded
If plugin failure must lead to rejection of all incoming connections it should be used within JavaScript.
Otherwise, if the LogonHandler is called as Business Logic Action <HandlerAction/> the initialization failure will lead to ignoring the action.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<CreateSessionEvent Description="Send authentication request for OrderEntry session and accept on success"> <Source> <FixSession SenderCompID=".*" TargetCompID="OrderEntry" /> </Source> <CreateSessionAction> <Script Language="JavaScript" FileName ="./FIXEdge1/conf/processLogonHandler.js"/> <AcceptSession/> </CreateSessionAction> </CreateSessionEvent> |
...
When FIXEdge doesn't receive a response in the time there would be WARN record in the FixEdge.log:
...
- Check the incoming FIX Session logs if there are no messages User Response (BF) then the issue on the Authentication Service side.