Home / Zoho - Reports - API - Home / SSO Integration

SSO Integration

Tags:  

SSO API is only available for White Label customers of Zoho Reports. If you want to know about SSO Integration, email support@zohoreports.com

Single Sign On Integration





Zoho Reports offer a full-fledged white label (private label) solution. As a part of it, it supports Single Sign on (SSO) with your website / application. Using the below mentioned procedure, it would be possible for you to implement a loosely coupled login mechanism for the white labeled Zoho Reports solution, that works with almost ANY authentication system that you currently are using. This would involve program changes in your website/application (code to be written at your end). This page outlines the various steps to setup, perform unit/integration testing and to go live with Zoho's third party SSO integration.

Setup Phase

  1. Provide the following information to the Zoho Reports 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 coming from Zoho Reports; needed for your test and production setups too)
    • Domain/sub-domain names (CNAME mapping) for test and production setups. CNAME map your test/production sub-domains to customer-reports.zoho.com
    • Fill the following Zoho Creator form to design your custom page - https://creator.zoho.com/zohodbhelp/domain-rebranding/#Form:DomainProperties
  2. After submitting the above information to the Zoho Reports team, we will send you an API key to be used you. (this is a different API key than the one provided at http://api.zoho.com/)

APIs


Sign Up API

URL Format

             Assuming your domain URL is reports.finepick.com.

form method="POST" action="https://reports.finepick.com/sso" target="_self"
input type= "hidden" name ="apikey" value="[your apikey]" 
input type ="hidden" name ="operation" value ="signup" 
input type ="hidden" name ="email" value ="[email id of the user to signup]" 
input type ="hidden" name ="full_name" value ="[Full Name of the user]" 
input type ="submit" name ="Sign Up" value ="submit" 
/form

Important: You need to send an HTTPS POST request to Zoho Reports for user Sign Up API.

Input Parameters for Sign Up API
Parameter
Description
operation
Value is "signup"
email
Email Id of the user to sign up
full_name  [optional]
Full Name of the user
apikey
Your API key

 
Response for Sign Up API:


Both Success & Failure responses are present in JSON format.
Return Value
Description
result
success/failure

If API call is success, then success value is present in the result attribute; else failure value.
zuid
ID generated by the Zoho system. Unique per user email address. 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.
ticket
this is used by the user to access the reports present in the Zoho Reports. This needs to be passed to Zoho as part of the URL.
cause
This attribute is present in the response, only in case of failure.


Sample Success Response

{ 
 "ticket":"666b88566441b69d1a137db824314b6a9be8959a75b1a1be8b951c6e18f352bb2e068f7f697fa4879e365e19967a5b537a08c8e85058625130e54e8467d85259", 
    "result":"success", 
    "zuid":5471 
}

Sample Failure Response

{ 
   "result":"failure", 
   "cause":"Invalid APIKey" 
}


Sign In API

Assuming your domain URL is reports.finepick.com.

URL Format

form method="POST" action="https://reports.finepick.com/sso" target="_self"
input type= "hidden" name ="apikey" value="[your apikey]" 
input type ="hidden" name ="operation" value ="signin" 
input type ="hidden" name ="email" value ="[email id of the user to signin]" 
input type ="submit" name ="Sign In" value ="submit" 
/form

Important: You need to send an HTTPS POST to Zoho Reports for user Sign In API.

Input Parameter for Sign In API
Parameter
Description
operation
Value is "signin"
apikey
Your API key
email
Email address of the user to sign in

Response for Sign in API:
Both success & failure responses are present in JSON format.
Return Value
Description
result
success/failure

If the API call is successful, then success value is present in the result attribute; else failure value.
zuid
ID generated by the Zoho system. Unique per user email address. This needs to be stored against the user for whom sign in API is being called. This will be useful for any communication / trouble shooting at a later stage.
ticket
This is used by the user to access the reports present in the Zoho Reports. This needs to be passed to Zoho as part of the URL.
cause
This attribute present in the response, only in case of failure


Sample Success Response

{ 
   "ticket":"666b88566441b69d1a137db824314b6a9be8959a75b1a1be8b951c6e18f352bb2e068f7f697fa4879e365e19967a5b537a08c8e85058625130e54e8467d85259", 
   "result":"success", 
   "zuid":5471 
}

Sample Failure Response

{
   "result":"failure", 
   "cause":"Invalid APIKey" 
} 


Sign Out API

URL Format:

https://reports.finepick.com/ZDBCustomDomainLogin.ma?ZDBACTION=signout

Important: You need to do a HTTP 301 Redirection to the above URL once the sign out process(clearing your application credential) completed in your server/application. Above URL will sign out from Zoho Reports and will redirect to your login page.

Workflow Test Scenarios

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


Pre-Requisites:
  • Make sure that the domain name is mapped to the corresponding Zoho Reports environment (customer-reports.zoho.com). For this particular documentation, we will assume that this domain mapping is https://reports.finepick.com Replace this with your own mapping URL.
  • Zoho Reports environment is located at customer-reports.zoho.com 

Test Login Flow
  1. Invoke the Sign Up or Sign In API above and get a ticket.
  2. Construct the URL as below and invoke the same,
    https://reports.finepick.com/oauthorize?zacode=[obtained_ticket]&state=https://reports.finepick.com/ZDBHome.cc
  3. The user identified by the ticket can operate till the ticket is logged off or all cookies are cleared (in which case step 2 should be followed again).

Test Logout Flow
  1. After logging in using the steps above, invoke the Sign out API from your server/application to Zoho Reports server.
  2. Try using the same ticket to visit your white label domain - you should be redirected to the registered login page of your website.

Test Login as Another user functionality
This step requires that you register 2 different email addressed using the Sign up API.
  1. Test the login flow as the first User
  2. Then use the ticket for User 2 and visit the site (using the same steps outlined in Test Login flow). - Domain will ignore the second ticket when one session is already active - so you will still see the session as user 1.
 

Integration Test Scenarios

Website driven Login flow

  1. User logs in to the main website.
  2. User clicks on a link that leads to the white-label site.
  3. White-label site requires login credentials of the user - which are not found in the current session
  4. So Zoho Reports 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 (e.g., https://finepick.com/login?serviceurl=https://reports.finepick.com)
  5. Since user is already logged in, finepick.com performs the sign in or sign up API call, depending on whether finepick.com already has the zuid for the user or not.
  6. With the newly generated ticket, finepick.com routes the user's browser to the service URL (in this example, https://reports.finepick.com/oauthorize?zacode=[obtained_ticket]&state=https://reports.finepick.com/ZDBHome.cc)
  7. Now white label site recognizes the user.

White label driven Login flow
  1. User visits the white label domain directly.
  2. If no login credentials for the user is found, then Zoho Reports 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. https://finepick.com/login?serviceurl=https://reports.finepick.com)
  3. The login page of finepick.com, collects and processes the user's login credentials based on the data stored in finepick.com
  4. After succesfully logging the user into finepick.com, if the service URL is a white label 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,https://reports.finepick.com/oauthorize?zacode=[obtained_ticket]&state=https://reports.finepick.com/ZDBHome.cc)
  6. Now the white label site (Zoho Reports) recognizes the user.

 Website Logout Flow:
  1. When the user clicks on the logout URL in the website, the website should call the Zoho Reports signout API and invalidate the ticket.
  2. The signout API call is a must!

White -label Logout Flow:
  1. When the user logs out from the reports 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.

Other Terms & Conditions:
  1. Before going live, it is mandatory for you to include Zoho's Terms and Conditions indicating that the community is hosted on Zoho and indicate Zoho's Terms & Conditions URL. The exact wordings will be given by your account manager.
  2. A full demo of the integration needs to be provided to the Zoho team.

    Post a comment

    Your Name or E-mail ID (mandatory)

    Note: Your comment will be published after approval of the owner.




     RSS of this page