Overview

Logon Handler is a FIXEdge plugin that delegates FIX session authentication to third-party systems. Communication with the third-party systems is done via BE/BF messages over the FIX protocol.

Logon Handler is represented by the libLogonHandler.so library and provided as a part of the Supplementary Adapters and Handlers package (SupAdapters-FE-*).

Handler functions

Logon Handler allows forming a User Request (35=BE) message and then sends it to the authentication system.

Logon Handler performs the following functions:

1. Send an authentication request upon session logon

2. Notify the authentication system upon session disconnection
3. Process the authentication system response 

1. Send an authentication request upon session logon

Logon Handler sends a connection request, which is comprised of data and credentials received in the (35=A) Logon message.

The mapping between Logon Handler parameters and (35=A) Logon message parameters:

2. Notify the authentication system upon session disconnection

Logon Handler notifies the authentication system in the event of session disconnection.

3. Process the authentication system response 

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.

Session authentication failure reasons

FIXEdge rejects and drops the session for the following reasons:

• The authentication system is not available.
• There is no response from authentication after the time specified by the Validator.TimeoutMs property.
• The authentication system rejects the session. I.e. User Response (BF) is sent with UserStatus (926) = "2".
• UserStatus (926) parameter is absent in the response or it is not equal to "1" or "2", upon which the user request is rejected.

Logon and message samples

The authentication request is sent synchronously, so accepting the session would be delayed and processing of the next messages would wait for the response or timeout.

20201216-06:23:58.413 : 8=FIX.4.4|9=97|35=A|49=FIXCLIENT|56=FIXEDGE|34=1|52=20201216-06:23:58.367|98=0|108=30|141=Y|553=user|554=foobar|10=202|

BE message sample:

20201216-06:23:58.413: 8=FIX.4.4|9=119|35=BE|49=FIXEDGE|56=Validator|115=FIXCLIENT|34=3|52=20201216-06:23:58.413|923=lah.0|924=1|553=user|554=foobar|10=112|

BF message sample:

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:

• Should accept FIX sessions and be FIX Standard compliant
• Should be able to process messages with mapped parameters
• Should prepare BF messages and
  • use the same ID - UserRequestID(923)
  • send back and correspond to Username(553) and OnBehalfOfCompId(115)
  • convert tag 115 to 128
• Should send the user request status - UserStatus (926):
• Should specify the error or success reason UserStatusText (927) 
• Should send reply message within configured timeout Validator. TimeoutMs, see also LogonTimeFrame session parameter in client session

Configuration parameters

The handler is configured as part of the business logic in BL_Config.xml, along with other FIXEdge handlers.

The table below represents the Logon Handler config parameters.

The FIX session to the authentication system is configured in FIXEdge.properties.

Configuration Sample

Start LogonHandler

		<DllHandlers>
			<Handler
				Name="LogonHandler"
				Description="Logon Authentication Handler"
				DllName="./libLogonHandler.so"
				VerifyHandlersVersion="true"
				Validator.SenderCompID="FIXEDGE"
				Validator.TargetCompID="AuthService"
				Validator.MessageVersion="FIX50SP2"
				Validator.TimeoutMs="2000"
			/>
		</DllHandlers>

Configure authentication service FIXsession in FIXEdge.properties

FixLayer.FixEngine.Sessions = FIXEDGE-ABC_Authn, ...

FixLayer.FixEngine.Session.AuthService.SenderCompID = FIXEDGE
FixLayer.FixEngine.Session.AuthService.TargetCompID = AuthService
FixLayer.FixEngine.Session.AuthService.Version = FIXT11:FIX50SP2
FixLayer.FixEngine.Session.AuthService.Role = Initiator
FixLayer.FixEngine.Session.AuthService.Host = <ip address>
FixLayer.FixEngine.Session.AuthService.Port = <port>
FixLayer.FixEngine.Session.AuthService.HBI = 30
FixLayer.FixEngine.Session.AuthService.ForceReconnect = true
FixLayer.FixEngine.Session.AuthService.ReconnectMaxTries = -1
FixLayer.FixEngine.Session.AuthService.ReconnectInterval = 5000
FixLayer.FixEngine.Session.AuthService.ForceSeqNumReset = 0
FixLayer.FixEngine.Session.AuthService.IgnoreSeqNumTooLowAtLogon = true
FixLayer.FixEngine.Session.AuthService.IntradayLogoutTolerance = true
FixLayer.FixEngine.Session.AuthService.RecreateOnLogout = true
FixLayer.FixEngine.Session.AuthService.TerminateOnLogout = false
FixLayer.FixEngine.Session.AuthService.Schedule = AuthServiceSchedule
FixLayer.FixEngine.Session.AuthService.HiddenLogonCredentials = true 

# maintenance hours for the auth service: Sunday 22:00-23:00
Schedules.AuthServiceSchedule.StartTime = 0 0 23 * * 1
Schedules.AuthServiceSchedule.ConnectTime =  5 0 23 * * 1
Schedules.AuthServiceSchedule.DisconnectTime = 0 0 22 * * 1
Schedules.AuthServiceSchedule.TerminateTime = 5 0 22 * * 1

Notify the authentication service on the incoming connection and sending credentials

		<CreateSessionEvent Description="Send authentication request for OrderEntry session and accept on success">
			<Source>
				<FixSession SenderCompID=".*" TargetCompID="OrderEntry" />
			</Source>
			<CreateSessionAction>
				<HandlerAction Name="LogonHandler" />
				<AcceptSession/>
			</CreateSessionAction>
		</CreateSessionEvent>

Processing authentication service response

The response about the decision from the authentication service should be routed to the Logon Handler.

		<Rule Description="Notify handler of authentication result">
			<Source>
				<FixSession SenderCompID="AuthService" TargetCompID="FIXEDGE" />
			</Source>
            <Condition>
                <EqualField Field="35" Value="BF"/>
            </Condition>
			<Action>
				<HandlerAction Name="LogonHandler" />
			</Action>
		</Rule>

Notify the authentication service on session disconnection.

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

BL_Config.xml

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.

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

Where processLogonHandler.js should contain a line

handler("LogonHandler");

Troubleshooting

Authentication service doesn't send a response in time

When FIXEdge doesn't receive a response in time there would be WARN record in the FixEdge.log:

<timestamp>   WARN    [LogonHandler]  <thread>  Session <SenderCompId, TargetCompId> : process logon failed  - request is timed out

Solution:

• Check the incoming FIX Session logs if there are no messages User Response (BF) then the issue on the Authentication Service side.