Single Sign-On explanation

ChatBro allows you to configure authorization in a chat so that used the site's information about user, such as nickname, avatar, path to the profile. To do this, you need to pass additional parameters to ChatbroLoader.

ChatbroLoader({
encodedChatId: 'Your encodedChatId', // Or you can use other identificators such as chatPath or chatAlias
siteDomain: 'Your domain',
siteUserExternalId: 'Your site user id',
siteUserFullName: 'Some user name or nickname',
siteUserFullNameColor: 'Some color for username',
siteUserAvatarUrl: 'Some user avatar url',
siteUserProfileUrl: 'Path to user profile'
});

Example:

ChatbroLoader({
encodedChatId: '9czk',
siteDomain: 'sso.chatbro.com',
siteUserExternalId: '652',
siteUserFullName: 'Brad Pitt',
siteUserFullNameColor: '#d81818d9',
siteUserAvatarUrl: '//sso.chatbro.com/images/brad_pitt.jpg',
siteUserProfileUrl: '//sso.chatbro.com/profile/652'
});

The minimum set of options for user authentication consists of siteDomain, siteUserExternalId, siteUserFullName. Parameters siteUserAvatarUrl, siteUserProfileUrl and siteUserFullNameColor are optional.

Configure authorization

In the chat editor, you can combine different authorization methods or disable everything and leave only authorization via site. Try to write something to the chat below.

Also, you can disable the login type that uses the transfer of authorization parameters. It is recommended to do this if you do not use the login via site.  In example below, the parameters siteDomain, siteUserExternalId and siteUserFullName are passed to ChatbroLoader, but SSO is disabled. Try sending a message.

Spoofing protection

A spoofing attack is a situation in which a person or program successfully masquerades as another by falsifying data, to gain an illegitimate advantage. In other words, an attacker can substitute his authorization parameters and write to the chat using the data of another person. To avoid this, you need to enable spoofing protection.

After turning on the protection, in order to be able to send a message, you need to transfer an additional parameter called signature.

The signatures are calculated on the server side based on the transferred parameters. The order of the parameters in the calculation is very important.

signatureDataParts =
siteDomain
+ siteUserExternalId
+ siteUserFullName
+ siteUserAvatarUrl
+ siteUserProfileUrl
+ siteUserFullNameColor
+ permissions.join('')
+ secretKey;

md5(signatureDataParts);

You can find your secretKey in chat constructor just enable Spoofing protection. Parameters siteDomain and secretKey are always necessary. Other can be ignored if you do not use them in the ChabroLoader.

The user can be made a moderator. To do this, the user needs to add the parameter called permissions to ChatbroLoader. Permissions is an array of allowed moderation methods. Used only in conjunction with the signature parameter. Possible values are: ban (the ability to ban users), delete (the ability to delete messages). It is important to note that with this method of adding a moderator, the user will not be indicated as a moderator in the messages, although he will be able to moderate. The parameter "siteUserFullNameColor" will help to fix this situation.
For example: permissions: ['ban', 'delete']

If the signature parameter is not transmitted or transmitted, but is not correctly calculated, the message can not be sent. In the chat, in this case, a corresponding notification will be displayed.

If you do not want the chat to be installed to sites other than yours, turn off the "Show chat in case of a signature error" slider.

Examples of a correctly transmitted signature

The full set of parameters for user authorization is transferred

ChatbroLoader({
encodedChatId: '12UNE',
siteDomain: 'sso.chatbro.com',
siteUserExternalId: '653',
siteUserFullName: 'Johnny Depp',
siteUserFullNameColor: 'grey',
siteUserAvatarUrl: '//sso.chatbro.com/images/johnny_depp.jpg',
siteUserProfileUrl: '//sso.chatbro.com/profile/653',
// md5('sso.chatbro.com653Johnny Depp//sso.chatbro.com/images/johnny_depp.jpg//sso.chatbro.com/profile/653grey40657820-0ba1-4e1d-b2f6-b2a40fd09263');
signature: '634112fee5a8f406e516baa3ca849321'
});

The minimum set of parameters for user authorization is transferred

ChatbroLoader({
encodedChatId: '12UNE',
siteDomain: 'sso.chatbro.com',
siteUserExternalId: '654',
siteUserFullName: 'Leonardo DiCaprio',
// md5('sso.chatbro.com654Leonardo DiCaprio40657820-0ba1-4e1d-b2f6-b2a40fd09263');
signature: '24f9545f5665289fc87d5aa16e5d08ed'
});

Spoofing protection is enabled and possible to authorize via the social network or as a guest

ChatbroLoader({
encodedChatId: '52UNe',
siteDomain: 'sso.chatbro.com',
// md5('sso.chatbro.com67565da2-d138-4991-89bd-1f280b2234dc');
signature: '2f0ecd707c82de71bd1d3f62bb86253c'
});

The user is given the opportunity to delete messages in the chat

ChatbroLoader({
encodedChatId: '12UNE',
siteDomain: 'sso.chatbro.com',
siteUserExternalId: '654',
siteUserFullName: 'Leonardo DiCaprio',
permissions: ['delete'],
// md5('sso.chatbro.com654Leonardo DiCapriodelete40657820-0ba1-4e1d-b2f6-b2a40fd09263');
signature: '42d699d7130846632d43698471a11e4e'
});

An example of automating the transfer of authorization data to ChatbroLoader

The example is conditional in nature. Do not copy it.
Written on Node.JS. Use the Express web framework and Pug templating engine.

sso_example.js

const domain = 'sso.chatbro.com';
const secretKey = 'b442e18f-0134-42dc-a74a-9eac53dff3bd';

app.get('/page'function(req, res) {
let userName = req.query.userName; 
let resParams = {}; 
let signatureDataParts = ''

// don't do like this
let isLogged = !!userName;

resParams.isLogged = isLogged;
resParams.domain = domain;

if (isLogged) {
resParams.userId = Math.floor((Math.random() 100) 1);
resParams.userName = userName;
signatureDataParts += resParams.userId;
signatureDataParts += resParams.userName;
}

resParams.hash = crypto.createHash('md5').update(domain signatureDataParts secretKey).digest('hex');
res.render('page.pug', resParams);
});

page.pug

script
| var chatParams = {
| encodedChatId: '32UNn',
| siteDomain: '#{domain}',
| signature: '#{hash}'
| };

-if (isLogged) {
| chatParams.siteUserExternalId = '#{userId}';
| chatParams.siteUserFullName = '#{userName}';
-}

| ChatbroLoader(chatParams);