Help > Chat Room > General > Single Sign On Integration

Single Sign On Integration

You can use the Single Sign On (SSO) API to automatically log your visitors into your chat room. This can be helpful if you have a separate log in area on your website and you don't want to make your visitors log in twice.

The SSO API allows you to send an HTTP request from within your application to log a user into or out of your chat room. A token is returned by the API, which is then used in a small IMG tag on the next page to store the necessary browser cookies.

If you are using PHP, we highly recommend using our SSO Library. It contains one file with all of the library code you'll need and other files with example usage.

If you are using WordPress for your website, we have a WordPress plugin that automatically integrates your log in and registration process.

Please follow the directions below to integrate the SSO API into your website.

Get Your API Key

The API Key is passed as a parameter in your API calls to verify that you are an authorized user of the chat room API. Your API Key is like a password to your account and should be kept private and secure.

You can get your Website Toolbox chat room API Key by following the instructions below:

  1. Log in to your Website Toolbox account.
  2. Click the Settings link.
  3. Copy the API Key mentioned next to the API Key option.

Make The Request To Generate Access Token

In the log in script for your website, make an HTTP Request to the SSO API log in URL:

http://CLIENT.discussionchatroom.com/sso/token/generate?apikey=APIKEY&username=USERNAME&email=EMAIL&avatarUrl=AVATARURL&password=PASSWORD

Replace APIKEY with the Secret API Key.

Replace USERNAME with the username of the to be logged-in user.

Replace EMAIL with the email ID of the to be logged-in user.

Replace AVATARURL with the url of user’s profile picture. This is optional. Otherwise, the user can always set their avatar in the chat room itself.

Replace PASSWORD with the unecrypted password of the to be logged-in user.

The username and password are optional parameters that will only be used if the account needs to be created because it doesn't already exist. If the account is created without a password, the user would not be able to log in directly to the chat room unless they first reset their password on the log in page. SSO log in would work smoothly even without the user's account having a password.

Parse the Response to Retrieve Access Token

Parse the JSON response of the request sent to generate access token to retrieve the authentication token i.e. “access_token”. The JSON response will look similar to this:

{
  "success" : true,
  "message" : "This is success or failure message.",
  "access_token" : "88SngRlfrqL"
}

success - It corresponds to the status of the request. It is true, if the authentication token is generated successfully. It is false otherwise.

message - It is message shared back in the response. It is more useful for error response.

access_token - It is the access token generated for the user after successful authentication. This token will get expired in 60 minutes to ensure the security.

Login Request to the Chat Room

On your website, add the following HTML IMG tag to your "log in successful" landing page:

<img border="0" width="1" height="1" alt="" src= "//CLIENT.discussionchatroom.com/sso/token/login?access_token=ACCESS_TOKEN&rememberMe=REMEMBERME" >

Replace ACCESS_TOKEN with the access_token, retrieved in step Parse The Response To Retrieve Access Token>..

Replace REMEMBERME with the value 0 or 1. To have the browser remember the user's log in information even after the browser is closed, replace REMEMBERME with 1, otherwise replace it with 0 to clear the log in information once the browser is closed.

The browser window that loads the IMG tag will be logged into the chat room as the user with the username provided while making the request to generate access token.

The Safari browser ships with a conservative cookie policy which limits cookie writes to only the pages chosen ("navigated to") by the user. This prevents the forum's log in cookie from being set on the "log in successful" landing page. Therefore, the only way to make Single Sign On work on the Safari browser is to also pass the authentication token in your chat room's link on your website. For example:

<a href="http://CLIENT.discussionchatroom.com/?access_token=ACCESS_TOKEN&rememberMe=REMEMBERME">Chat Room</a>

Log out from the Chat Room

In case the user wants to log out from the chat room or when the user logs out from the website, add the following HTML IMG tag to your "log out successful" landing page:

<img border="0" width="1" height="1" alt="" src="//CLIENT.discussionchatroom.com/sso/token/logout?access_token=ACCESS_TOKEN" >

Replace ACCESS_TOKEN with the access_token, retrieved in step Parse the Response to Retrieve Access Token.

If you do not have the authentication token that was returned during login, it can be retrieved or regenerated (if expired) by making the request to generate access token API.

URL Settings

You can set your website URLs by following the instructions below:

  1. Log in to your Website Toolbox account.
  2. Click the Settings link.
  3. Under “Single Sign On section, specify your website URLs for following pages:
    • Log In Page: Specify the address of your website's Login page to ensure that all chat room logins occur using your website's log in form.
    • Log Out Page: Specify the address of your website's Log out page to ensure that users are shown your website's log out page once they have been logged out of the chat room.
    • Registration Page: Specify the address of your website's Registration page to ensure that users are shown your website's registration page on clicking on the "Create Account" link on the chat room log in page.

Register A User in the Chat Room

To register a user in the chat room, make an HTTP Request to the SSO API user registration URL:

http://CLIENT.discussionchatroom.com/sso/user/register?apikey=APIKEY&username=USERNAME&email=EMAIL&password=PASSWORD&avatarUrl=AVATARURL

Replace APIKEY with the Secret API Key.

Replace USERNAME with the username of the to be registered user.

Replace EMAIL with the email ID of the to be registered user.

Replace PASSWORD with the unecrypted password of the to be registered user. This is an optional parameter. In cases where an account is created without a password, the user would not be able to log in directly to the chat room unless they first reset their password on the log in page. SSO log in would work smoothly even without the user's account having a password.

Replace AVATARURL with to be registered user?s profile picture URL. This is optional.

Sending a registration request is optional since accounts will be created automatically if they don't already exist during a single sign on log in request.

The JSON response will also return an access token that can be used to log the user in. Follow the steps in Parse the Response to Retrieve Access Token and Login Request to the Chat Room to log in the newly registered user.

Delete A User

To delete users from the chat room, make an HTTP Request to the SSO API user deletion URL:

http://CLIENT.discussionchatroom.com/sso/user/delete?apikey=APIKEY&emails=EMAILS

Replace APIKEY with the Secret API Key.

Replace EMAILS with the email addresses of the to be deleted users. It can hold either a single email address or multiple comma separated email addresses.

Edit User Details

To edit details of the chat room user, make an HTTP Request to the SSO API edit user URL:

http://CLIENT.discussionchatroom.com/sso/user/edit?apikey=APIKEY&user=USER&username=NEWUSERNAME&email=NEWEMAIL&password=NEWPASSWORD&avatarUrl=NEWAVATARURL

Replace APIKEY with the Secret API Key.

Replace USER with the current email address of the user.

Replace NEWUSERNAME with the new username which needs to be set.

Replace NEWEMAIL with the new email which needs to be set.

Replace NEWPASSWORD with the new password which needs to be set.

Replace NEWAVATARURL with the new avatar URL which needs to be set.

The parameters apikey and user are mandatory fields. The other fields are optional. You should not add parameters in the URL whose value should not be updated for the user. The value for “username” and “email” will not be updated if it is blank.

Important Notes

  • Need Help? Our developers can setup Single Sign On integration on your website for just $149.Contact Us
  • To access the chat room, there should be a chat room link on your page like:

    <a href=”http://CLIENT.discussionchatroom.com/”>Launch chat room</a>

  • CLIENT should be replaced by your Website Toolbox chat room username.
  • Responses can be parsed for debugging purpose. The JSON response will look similar to this.
  • The query string must be URL-encoded.


If you still need help, please contact us.


Product Pages: Chat Room, Chat Room Pricing, Chat Room Features, Chat Room Examples