Authentication Integration Document

Informal document for the authentication interface showing you an example of how you can integrate the portal.chat software with 3rd party online systems such as portal websites.

Authentication interface – example 

We prefer to achieve the authentication by sending TLS secured HTTP Post request to the portal website.
At present we need only three requests:
————————————————————
Authenticate POST parameters:
requestId – [string]
accessKey – [string]
username – [string]
password – [string]
The username parameter can be as provided by the user.
For the password parameter we can send it again as provided by the user, or if your system uses some hashing we can implement that client side. For example in our system we don’t end and store password, but hashes computed by the browser.

The response to this request should be JSON object with the following fields:
errorCode – [integer] Numerical error code
error (optional) – [string] Plain text explanation of the error if such is available form your system
remediationOptions (optional) – [array] If there is an error a list of options for the user. This array consists of objects. Each object has the following fields:
name – [string] Name of the option (like: register an account, recover forgotten password)
url – [string] Url to the page where the user can pursue the option.
(The rest applies only if errorCode = OK).
account – [object] An object that describes the account of the authenticated user. Has the following fields:
identifier – [string] The identifier of the account that is used to determine which advertisement is owned by this account. (Only if errorCode = OK)
email – (optional) – [string] The email address of the account administrator user. To be used to send various notifications like chat transcripts.
operator – [object] An object that describes the authenticated operator. Has the following fields:
image – (optional) – [string] Url to the profile image of the user. To be used to initialize the user’s profile picture.
email – (optional) – [string] The email address of the operator. To be used to send various notifications like chat transcripts.
isMaster – [boolean] Determines whether the operator is the owner of the account. If he is he has access to more features like: statistics, ability to see everybody’s chats etc.
authenticationToken (optional) – [string] This field is explained below. (Only if errorCode = OK)

Possible error codes:
0 – OK – Successfully authenticated.
1 – Wrong Credentials
2 – Suspended or Deleted account – This is in case the credentials are correct by the account no longer exists.
253 – Access denied
254 – Already processed request
255 – Internal server error – Something that happened in your system that prevents the request to be processed at all.
————————————————————
AuthenticateWithToken
POST parameters:
requestId – [string]
accessKey – [string]
authenticationToken – [string]
isUrlAuthentication – possible values are “0” and “1”. It is “1” only if the authenticationToken comes from a URL parameter to the operator panel login page. Otherwise it will be “0”.

The response should be identical to the response of Authenticate. Error 1(Wrong Credentials) here means wrong authentication token.
————————————————————
LogOut
POST parameters:
requestId – [string]
accessKey – [string]
authenticationToken – [string]

Should invalidate the authentication token.
The response to this request should be JSON object with the following fields:
errorCode – [integer] Numerical error code
error (optional) – [string] Plain text explanation of the error if such is available form your system

Possible error codes:
0 – OK – Successfully authenticated.
1 – Invalid authentication token
253 – Access denied
254 – Already processed request
255 – Internal server error – Something that happened in your system that prevents the request to be processed at all.
————————————————————

About authenticationToken (optional implementation):

Our system allows people to authenticate automatically if they choose. To be able to do that when integrating with you we need to either:
– Store credentials client side which we normally try to avoid and is currently supported only by the mobile apps (and not by the web interface).
– Or store an authentication token that can be used to identify the user later on.

If possible we prefer the second option.
The authentication token should work like this:
When the user authenticates initially your system generates such token and gives it to us (The “Authenticate” request).
During subsequent authentication our system sends just the authentication token and your system validates it (The “AuthenticateWithToken” request).
Your system should invalidate the authentication token at least in two cases:
– When the user logs out via our system (our system calls the “LogOut” request)
– When the user changes his credentials (somewhere in your system).

In the response to the request “AuthenticateWithToken” your system should do one of the following:
– Do not include “authenticationToken” field in the response. In this case and if the error code is 0(OK) we will assume the authentication token is still valid for subsequent request.
– Include “authenticationToken” field in the response and populate with the same value that was sent. In this case and if the error code is 0(OK) we will assume the authentication token is still valid for subsequent request.
– Include “authenticationToken” field in the response and populate with a value different form the one that was sent. In this case and if the error code is 0(OK) we will assume the authentication token that was sent is no longer valid, but the same use can subsequently authenticate with the newly returned token.
– Include “authenticationToken” field in the response and populate with an empty string. In this case and if the error code is 0(OK) we will assume the authentication token that was sent is no longer valid for subsequent request (but the authentication was still successful).

The authenticationToken can be used to navigate to the operator panel page and automatically authenticate the user. This is done the following way:
– Your system generates authenticationToken on its own.
– In the url to the operator panel page you include: “?authenticationToken=[The generate authentication token]”.
– Our system detects it and instead of the normal authentication procedure it immediately sends “AuthenticateWithToken” request to your server using the token found in the URL. In this request the “isUrlAuthentication” field will have value “1”.
– Your server validates the token the normal way. We recommend that in case of success your server should invalidate the received authenticationToken and populated the “authenticationToken” response field either with newly generated token (allowing automatic re-authentication) or with empty string (forbidding automatic re-authentication). This is recommended because the initial authentication token has been passed through the URL and is more prone to hijacking. By immediately invalidating it after being used for the first time we increase security.

If you choose not to implement this option:
You should:
– Not include “authenticationToken” fields in the responses to “Authenticate” and “AuthenticateWithToken”
– Respond to “AuthenticateWithToken” with error code 1(Wrong Credentials)
– Respond to “LogOut” with error code 0(OK)

Out system will:
– Normally not call “AuthenticateWithToken” ever as long as it never receives authentication tokens.
– When calling “LogOut” the “authenticationToken” field will be an empty string
– Currently we support automatic authentication without authenticationToken only in the mobile apps. So the “Remember me” option in the web interface will not work for the account of your agents and will be removed from your customized login screen.
————————————————————
About requestId (optional implementation):
Each request we send will have an Id that is unique. Sometimes due to timeouts or other communication issues one request can be send twice.
In this case it is better if your system ignore the request when it is identified a request with the same Id was already handled.
When you ignore such request you should respond with error code 254(Already processed request).
For this purpose you will need to maintain a list of already processed request Ids.
The old Ids can be removed from the list after 120 seconds. Out system will not attempt to send the same request more then 60seconds after it sent it the first time.

The implementation of this feature is optional. This system will operate ok without it.
If you choose to not implement this feature it is enough to ignore the requestId POST field altogether and never respond with error code 254(Already processed request).

If you server is stateless and the implementation requires storing the requestId list in a database or files we recommend that you do NOT implement this feature.
————————————————————
About accessKey (optional implementation):
For the purpose of securing the communication with your server you can provide as with one string called accessKey.
In this case every request will have a field called “accessKey” which will contain the string provided by you.
Your server should validate that the sent accessKey matches the accessKey you gave us.
If that is not the case you should respond with error code 253(Access denied).

The implementation of this feature is optional.
If you choose to not implement this feature it is enough to ignore the accessKey POST field altogether and never respond with error code 253(Access denied).
————————————————————
About reporting issues:
As part of the setup process you will be asked to provide administrator email.
In case our system detects some issue when communicating with your system an email will be automatically sent to this administrator email with notification.
Such issues are:
– Your system is unreachable.
– You SSL certificate can not be validated.
– You server responds incorrectly to requests.

Leave a Reply

July 18, 2016

Posted In: API

Tags:

Leave a Comment