Page tree
Skip to end of metadata
Go to start of metadata

Experimental version added on FIXEdge 6.10.0

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

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.

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:

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

2. Notify the authentication system upon session disconnection

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

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

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.

User Response (BF) Value source
UserStatus (926)

Mandatory tag in response.

Supported values:

  • 1 - Log On User. Accept the session
  • 2 - Log Out User. Reject the session
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.

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

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.

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

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.

Incoming Logon Message
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:

BE Message
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:

BF Message
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
  • 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.

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

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

LogonHandler doesn't support session qualifier

Configuration Sample

Start LogonHandler

BL_Config.xml
		<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

BL_Config.xml
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

BL_Config.xml
		<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.

BL_Config.xml
		<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.

BL_Config.xml
        <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.

BL_Config.xml
		<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

processLogonHandler.js
handler("LogonHandler");

Troubleshooting

Authentication service doesn't send a response in time

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

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.
  • No labels