SSO integration

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