LOGIN

Clients initializing access to the market center

Once client establishes the web socket connection, the client has 30 seconds to complete the login process. Otherwise, the socket will be closed by FI.

CHALLENGE

First client needs to send a challenge request to the system.

SAMPLE REQUEST CHALLENGE

{“type”:”challenge”}

In response, FI backend will send the customer a challenge response.

SAMPLE REQUEST RESPONSE TO CHALLANGE

{“result”:”OK”,”type”:”challenge”,”key”:”MIGfMA0GCSqGSIb3DQEBAQUAA4GNA
DCBiQKBgQCvBXTe278Lwg2MoI7iGKolSYuF+sNFKrsZplxCN9x0kItU3KIf8+1q60ILLwLewCEf7foxzp
Wp32j9YYU9vNBghuJ7BHcDYTffTRcv+QdNno491j701Hq7DIw13AGCQQTRcnfclvblnytIEWoQsiUv
PJcdiWgqJIX3IQGA47a+uwIDAQAB”}

KEY FIELD

The response contains a “key” field, which contains a public key string the client must use to encrypt the password field. The “key” field is a 64 base ASCII print out of the binary byte array for the corresponding public key of asymmetric public/ private key pair. FI backend will hold the private key while sending clients the public key. Client will first convert the ASCII back to binary byte array. Then use that binary byte array to create a “RSA” public key instance. Afterwards, client will use that RSA public key instance to encrypt info required in this order entry API, e.g. password encryption.

JAVA SAMPLE

The sample code below is a java-based example of how to recreate a public key using key value from the challenge response and using that public key to encrypt a password (“test123”). The output binary array is then be translated into ASCII string output, which can be used in “pass” field for the login message.

byte[] array = javax.xml.bind.DatatypeConverter.parseBase64Binary(key);
KeyFactorykf = KeyFactory.getInstance(“RSA”);
publicKey = kf.generatePublic(new X509EncodedKeySpec(array));
Cipher = Cipher.getInstance(“RSA”);
cipher.init(Cipher.ENCRYPT_MODE, publicKey);
byte[] result = cipher.doFinal (“test123”.getBytes(“UTF-8”));
String output = javax.xml.bind.DatatypeConverter.printBase64Binary(result);

After encryption of password, the next step is to send in the login request. The string in the “pass” field is from the output result in sample above.

{“type”:”login”,”userid”:”USER”,”pass”:”s7UW26iGE/iVfk2ihPYIcyzRqZRi/Ztb23UNMomf3xrBzGK
UHKzfNwZe5PIR/0zvfevYvkJnKLQVhR4U9/kObD/Ir0z6mBfLLgFwEcRm08jYI/nk7lDU+W32PqduT
OCThlkXYueQslK54vR9rKvMs=”}

In response, FI backend will validate the user/password. Below is a sample of failure and success response. If login fails, the FI backend will terminate the socket.

SAMPLE LOGIN SUCCESS

{“result”:”invalid user/password”,”type”:”login”}

SAMPLE LOGIN FAILURE

{“result”:”OK”,”type”:”login”}

LOGOUT

Sample request examples:

{“type”:”logout”}

This is for clean logout. Once backend receives this message, it will immediately terminate the web socket connection.

ILLUSTRATION

User authentication through the backend for every web layer

EXAMPLES

2 TYPES OF MESSAGES ARE AVAILABLE FOR AUTHENTICATION

USER LOGIN

For users to set up a direct connection to the FI backend for trading - use the login message.

login - used by all users to establish a websocket connection and gain access to FI backend
{
type:login,
userid://userid of WS user
pass://user password signed with key from challenge
}

SUPER ADMIN LOGIN

To authenticate users for access to web portals - users can send an http request to the web backend with username and password - the web backend can then use the "verifylogin" message to check if it is correct on behalf of the user.

verifylogin - used only by superuser (admin) as a one time message to authenticate a user and retrieve
user data
{
type:verifylogin,
userid://userid of customer being authenticated
pass://password of customer being authenticated signed with key from challenge
}

REQUEST VERIFY LOGIN

type:verifylogin
userid: ‘julian@fundamentalinteractions.c’
pass://julian’s password encrypted with challenge key
}

RESPONSE VERIFY LOGIN IF PASSWORD IS CORRECT

type: verifylogin
result: OK
active: “Y”
userid: julian@fundamentalinteractions.c
verify_level:0
}

RESPONSE IF PASSWORD IS NOT CORRECT

{
type:verifylogin,
result: invalid user/password
userid: julian@fundamentalinteractions.c
}

Any user can optionally also have a property stored called "attr" which will be returned with the "verifylogin" message.

2FA LOGIN OPTION

“login” can have two steps, but not “verifylogin”.

“verifylogin” will generate token afterwards, if no 2fa token is present, it cannot generate token.

You need to pass the error back to screen to display that “2fa token” is missing.

“verifylogin”, you will have to provide password and 2fa token value in one request, otherwise FI can only verify the password. For “gentoken” option, if we don’t check 2fa value, that beats the purpose of 2fa verification.

1. Enable the 2fa. We can enable it via config for the whole site or via each account. There is an additional parameter "use2fa", set it to 'Y'/'N' for enable/disable.

2. If "use2fa" is set to 'Y' in "adduser" message, system will generate a new 2fa seed, this seed value is sent back in response message "2faseed" field. Use this value to generate corresponding QR code. The field "2faseed" is sent only once for security reason, we don't want to keep on sending this field value back each time user login. If user does not initialize his authenticator with "2faseed", then he has to call "adduser" one more time to generate a new value, which will return only once too.

3. For "verifylogin" and "login", you should send in "2fatoken" with value from the google authenticator for verification. "login" does not have to set it, but if user does not set it, user cannot do anything else until he use "send2fatoken" to set the correct token.

If "token" value is incorrect, you will get a "invalid token" value as opposed to "invalid user/password" for invalid password.

PASSWORD RESET

There are two methods for password reset.

It is through “adduser” command, where you will need to set field “updateprof”:true

First, we divide the user group into administrator and ordinary user.

For an ordinary user, in order to change their password, only way that they can do it is to provide an existing password and new password using “newpass” and “pass” where the value of the field should be encrypted with the challenge key.

For administrator, it can do same thing above and he need to set “userid” field to specify the corresponding account.

I think there is a need to reset the password without providing the existing password. This is reserved for the administrator (super User) login.

If the user can provide additional proof (such as 2FA, or email validation), then web layer (using admin log) can send an override flag to FI backend to reset the password.

It is suggested adding “resetpass”:true field. Only admin login can set the flag, when doing so, admin will sending in “newpass” field (without “pass” field)

Once FI receives such a message, FI will override the user’s existing password with a new password.

SAMPLE REQUEST

->  {"type":"adduser","userid":"[e-mail]","roles":"XXSSS","updateprof":true,"firm":"FINT","resetpass":true,
"pass":"","newpass":"qE+5flZqEYYWyq5YneTeokxknzzCtfcADcuoOYzlyjPzMvvBarUg7kBtoPmFIgXHzPjtdDG2ICVNnCJUQsx5uOzttalFYBlJAjZ+g5UGlYt25xVdjsSgmo+h8MXzVIBtdzCNXDrB9gWWQsaL/NWgBW12sh5BrMz6kKTfUF0bH60=",
"attr":{"email":"[e-mail]","first_name":"Denis","last_name":"Oborniev"}}

SAMPLE RESPONSE

<-
{"result":"OK","firm":"FINT","roles":"XXSSS","broker_comm_rate":"0","updateprof":true,"type":"adduser","attr":{"last_name":"Oborniev",
"first_name":"Denis","email":"[e-mail]"},"userid":"[e-mail]","resetpass":true}