SSO integration

Last modified:

Advanced

What is SSO?

The system of cross authentication (Single sign-on) allows your users to enter UserEcho without additional registration, using your current username in your project.

How it works?

When the user navigates to your support forum. You must submit an additional parameter sso_token. The system automatically recognizes the parameter and authenticates the user. Based on information provided with token.

Simple link to UserEcho forum looks like that:

http://mycommunity.userecho.com/?sso_token=your_sso_token

For cross authentication with the widget you need to pass the same parameter:

var _ues = {
... ,
params:{sso_token:"your_sso_token"}
};

Available parameters

Parameter Value Required? Example Description
guid Varchar(255) yes "1000000" Unique user ID on the side of your site
expires Unix epoch timestamp yes 1462245336 Expiration date of token in Unix Epoch Timestamp.
Unix Epoch Timestamp We would recommend to add at least 1 hour to current timestamp.
display_name Varchar(30) yes "John Doe" Name of the user
email Varchar(255) recommended "john.doe@example.com" User's Email
verified_email Boolean no False Is email verified?
locale Varchar(5) no "en"
Available languages
Default language
avatar_url Varchar(255) no https://mysite.com/avatar.jpg Link to image of user avatar
force_update_avatar Boolean no False Force update of user's avatar, even if user already has it.
allowed_private_forums List [forum_id] no [29966,29965] List of forums IDs, user will have access to the provided forums.
groups List [forum_id] no [1,2,3] Assign user to specific groups.

Skip parameter if you do not use groups in your project.

If you pass the parameter all current user's groups will be unassigned first, then new groups will e assigned.
custom_fields Dict {field_id:value} no {"cf_1":"Test value", "cf_2":"on"} If your project has some custom fields in a user profile, you are able to pass them through sso.
Also now we accept custom fields for topics. If you pass
information in this way and user post some topic we check his last SSO
data and fill out fields with information provided via SSO.
enable_moderation Boolean no False Enable moderation for all public messages of the user. By default moderation is disabled.


Process of SSO_TOKEN generation

Feel free to use our examples on GitHub. We have prepared examples for: Python, Ruby, PHP, Node.js, C# and Go. If this is not enough for you here is description how to make it yourself.

1. Prepare JSON block with user's parameters

json_data = {
    "guid":"1454598",
    "expires":1462245336, 
    "display_name":"John Doe",
    "email":"john.doe@gmail.com",
    "locale":"en",
    "avatar_url":"http://test.com/avatar/1454598.png"
    }

2. Save as a string

json_string = json.dumps(json_data)

3. Expand the string

Note! Some encryption libraries can do this part automatically. So, if your library does it you can skip this step.
Attain the length of the block from the end to a multiple of block size AES (times 16) the character whose code is equal to the number of missing characters, for brevity:) Here's a clever algorithm. Ie block size 16. For example we have a string 44. The next multiple of 16 number 48. 48-44 = 4. then finish off a string four characters whose code is 4 (not four, and code 4).

    pad = AES.block_size - len(json_string) % AES.block_size
    data = json_string if pad == AES.block_size else json_string + (chr(pad) * pad)

4. Generating iv

iv - initialisation vector (http://en.wikipedia.org/wiki/Initialization_vector) - need to assign a string of 16 characters, preferably different every time, for safety. we do this randomized

iv  = randpool.RandomPool(AES.block_size).get_bytes(AES.block_size)

5. Encode data with sso_key and iv, then concatenate iv and encrypted data

  encrypted_bytes = iv + AES.new(sso_key, AES.MODE_CBC, iv).encrypt(data)

6. Screening of characters that not allowed in the links

  sso_token = urllib.quote(base64.b64encode(encrypted_bytes))


This article was helpful for 19 people. Is this article helpful for you?
Report an error
Still need help? New ticket