Home / Administrator Guide / Zoho Discussions SSO Integration

Zoho Discussions SSO Integration

 
Zoho Discussions supports several techniques for Implementing Single Sign on with your website. Currently supported techniques include LDAP integration, SAML integration and REST based API integration. Of these, REST based API integration is most preferred for most customer support use cases. Using this technique it is possible for you to implement a loosely coupled login mechanism that works with almost ANY authentication system that you currently use. This approach also needs program changes at your website end - though in most cases, an intermediate level of programming skill in any programming language / web tool will do. 

This page outlines the various steps to setup, perform unit test, integration test and go live with 3rd party SSO integration for a community hosted on Zoho Discussions.

Note: 3rd party SSO integration is available only on selected plans. Please visit http://zoho.com/discussions/pricing.html to learn more.

Setup Phase

  1. Make sure your portal is in a suitable plan.
  2. Provide the following information to the Zoho Discussions team:
    • IP addresses of your test and production setups
    • The login and logout page URLs of your website (these will process login and logout requests emanating from Zoho Discussions) - again needed for your test and production setups.
    • Domain names (CName Map) for stage and live environments.
  3. Sign up once in the Zoho Discussions stage environment - http://stageiam.zoho.com
  4. Create a portal in Zoho Discussions stage environment - http://stagediscussions.zoho.com/home
  5. Obtain an API Key from Zoho for invoking REST based API calls. (this is DIFFERENT from the API key provided by api.zoho.com)

API Unit Tests

There are several unit tests to be conducted to familiarize and validate the API calls in your context:

Invoke the sign up API  : https://stageiam.zoho.com/internal/sso.zp?apikey=[your apikey]&operation=signup&email=[email id of the user to signup]&login_name=[name of the user as displayed in zoho discussions]&full_name=[same as login name]
  • Input values:
    1. full_name and login_name should be the same
    2. full_name and login_name should be a valid zoho user name (2-30 characters long containing only numbers, alphabets and underscores and dot)
    3. Email is unique in the system, so it is the full_name. If different, full_name is provided for the same email, the old full_name will still be hold.
  • Return Value:
    1. zuid - id generated by the zoho system. Unique per user email id. This needs to be stored against the user for whom sign up API is called. This will be useful for any communication / trouble shooting at a later stage
    2. ticket - this is used to establish a session with your community portal hosted on Zoho Discussions. This needs to be passed to Zoho as part of the URL.    
If the API failed, you will not get these 2 responses, and will get a JSON with a single attribute called "result" and value = "failure"

Invoke the sign in API - https://stageiam.zoho.com/internal/sso.zp?apikey=[your apikey]&operation=signin&email=[email id of the user to signup]
  • Input values:

    1. If provided, full_name and login_name should be the same
    2. If provided, full_name and login_name should be the same name provided in the sign up call
    3. Email if of a previously registered user.
  • Return Value:

    1. zuid - id generated by the zoho system. Unique per user email id. This needs to be stored against the user for whom sign up API is called. This will be useful for any communication / trouble shooting at a later stage
    2. ticket - this is used to establish a session with your community portal hosted on Zoho Discussions. This needs to be passed to Zoho as part of the URL.
If the API failed, you will not get these 2 responses, and will get a JSON with a single attribute called "result" and value = "failure"

Invoke the sign out API - https://stageiam.zoho.com/internal/sso.zp?apikey=[your apikey]&operation=signout&ticket=[previously generated ticket (generated via sign in or sing out api calls above)]
  • Input values:
    Ticket - should be a previously generated ticket. Tickets are generated using one of the sign in or sign up operations listed above. Sign out operation can be invoked multiple times, subsequent calls will have no effect.
  • Return Value:
    Result - "success."
If the API failed, you will not get these 2 responses, and will get a JSON with a single attribute called "result" and value = "failure"
 

Workflow Test Scenarios

This section outlines steps that are to be tried after the unit tests have been successfully completed.

Pre-Requisites:
  1. Make sure that the domain name is mapped to the corresponding zoho discussions environment. For this particular documentation we will assume that this domain mapping is http://community.foo.com. Replace this with your own mapping url.
  2. Zoho Discussions's stage environment is located at stagediscussions.zoho.com
Test Login Flow:
  1. Invoke the sign up or sign in API above, get a ticket
  2. Invoke the community URL  with the ticket as the only argument. Example: http://community.foo.com?ticket=[obtained ticket]
  3. This should show you log the member associated with the ticket and make him/her a member of the portal. This membership can be tested by the admin by visiting Settings -> Users panel.
  4. The member identified by the ticket can operate till the ticket logged off or all cookies are cleared (in which case step2 should be followed again).
Test Logout Flow:
  1. After logging in using the steps above, invoke the Sign out API from the server to discussions server.
  2. Try using the same ticket to visit the community site - you should be redirected to the registered login page of your website.
Test Login as Another user functionality:
  1. This step requires that you register 2 different email ids using the Sign up API.
  2. Test the login flow as the first User
  3. Then use the ticket for User 2 and visit the site (using the same steps outlined in Test Login flow). - Zoho Discussions will ignore the second ticket when one session is already active - so you will still see the session as user 1. 
This might sound like a security issue. But it is not. Since the only way 2 different user tickets can be used on Zoho Discussions is if
  1. The main website's login page is hacked and is made available without the user explicitly logging out (since each logout on the website should trigger the sign out API)
  2. Or the second user's ticket has been hijacked.
 

Integration Test Scenarios

Website Driven Login Flow:
  1. User logs in into the main website.
  2. User clicks on a link that leads to the community site.
  3. Community site requires login Credentials of the user - which are not found in the current session
  4. So community routes the request to the registered login URL with a parameter called serviceurl that will contain the full URL where the request should be routed after login (for eg. http://foo.com/login?serviceurl=http://community.foo.com)
  5. Since user is already logged in, foo.com performs the sign in or sign up API call) depending on whether foo.com already has the zuid for the user or not.
  6. With the newly generated ticket, foo.com routes the user's browser to the service url (in this example, http://community.foo.com) along with the single parameter called "ticket" (the routed url is http://community.foo.com?ticket=[generated ticket])
  7. Now Zoho Discussions recognizes the user and lets the user in (after adding him as a member if this is his first time visit)
Community Driven Login Flow:
  1. User visits the community directly
  2. If no login credentials for the user is found, then discussions will route the user the registered login url with a parameter called serviceurl. Serviceurl contains the full URL where the request should be routed to after login (for eg. http://foo.com/login?serviceurl=http://community.foo.com)
  3. The login page of foo.com, collects and processes the user's login credentials based on the data stored in foo.com
  4. After succesfully logging the user into foo.com, if the service URL is a Zoho Discussions url, the server should invoke the Sign in or Sign up API for the current logged in user, and obtain a zoho ticket
  5. After successfully obtaining the zoho ticket, the user's browser should be forwarded to the url denoted by service url (in this example, http://community.foo.com) along with the single parameter called "ticket" (the routed url is http://community.foo.com?ticket=[generated ticket])
  6. Now Zoho Discussions recognizes the user and lets the user in (after adding him as a member if this is his first time visit)
Website Logout Flow:
  1. When the user clicks on the logout url in the website the website should call the logout api and invalidate the ticket.
  2. The website can optionally route the user to the logout url of the community (always available at /logout.do)
  3. The website can also clear all cookies for the community cname (in out eg. community.foo.com).
  4. The signout API call is a must! And one of step 2 or step 3 above should be implemented.
Community Logout Flow:
  1. When the user logs out from the community site, he will be routed to the logout URL of the main site with the serviceurl parameter pointing to the community url.
  2. Zoho will automatically clear all cookies and session information about the user from Zoho's end.
Login Timeout: (This feature is not yet available in Zoho Discussions and will be implemented shortly)

  1. Different sites have different time out periods. Time out period can be defined as the shorted period for which a logged in user can remain inactive before the system automatically logs him out.
  2. It is proposed that Zoho Discussions will allow the user to configure a timeout interval. Once the timeout interval is hit, Zoho Discussions will log the user out on subsequent access to the community.

Other Terms & Conditions

Legal Terms
  • Before go live, it is mandatory to include TERMS and CONDITIONS indicating that the community is hosted on zoho and indicate Zoho's T&C URL. The exact wordings will be given by your account manager.
  • A full demo of the integration needs to be provided to the Zoho team along with a admin privilege to the Zoho Account manager.

     

 

 
 

 


    		 RSS of this page