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
- Setup Phase
- APIS
- Sign Up API
- Sign In API
- Sign Out API
- Workflow Test Scenarios
- Integration Test Scenarios
- Other Terms & Conditions
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
- 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
- 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
- Sign In
- Sign Out
Sign Up API
URL Format
<form method="POST" action="https://accounts.zoho.com/internal/sso.zp" 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="login_name" value="[name of the user as displayed]">
<input type="hidden" name="full_name" value="[Same as login name]"> <input type="submit" value="Sign Up" class="divbutton" name="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
Response for Sign Up API:
Both Success & Failure responses are present in JSON format.
Sample Success Response
{
"ticket":"666b88566441b69d1a137db824314b6a9be8959a75b1a1be8b951c6e18f352bb2e068f7f697fa4879e365e19967a5b537a08c8e85058625130e54e8467d85259",
"result":"success",
"zuid":5471
}
Sample Failure Response
{
"result":"failure",
"cause":"Invalid APIKey"
}
<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="login_name" value="[name of the user as displayed]">
<input type="hidden" name="full_name" value="[Same as login name]"> <input type="submit" value="Sign Up" class="divbutton" name="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 |
| login_name | Name of the user as displayed.
User name should contain only alphanumeric characters, (_) underscore and (.) dot. Space and other special characters are not allowed. |
| full_name | Same as login name |
| apikey | Your API key |
Note:
|
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
URL Format
<form method="POST" action="https://accounts.zoho.com/internal/sso.zp" 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" value="Sign In" class="divbutton" name="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"
}
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.
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
- Invoke the Sign Up or Sign In API above and get a ticket.
- Invoke the white label URL with the ticket as the only argument. Example: https://reports.finepick.com?ticket=[obtained ticket]
- 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
- After logging in using the steps above, invoke the Sign out API from your server/application to Zoho Reports server.
- 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.
- Test the login flow as the first User
- 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
- User logs in to the main website.
- User clicks on a link that leads to the white-label site.
- White-label site requires login credentials of the user - which are not found in the current session
- 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)
- 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.
- With the newly generated ticket, finepick.com routes the user's browser to the service URL (in this example, https://reports.finepick.com)/ along with the single parameter called "ticket" (the routed url is https://reports.finepick.com?ticket=[generated ticket])
- Now white label site recognizes the user.
White label driven Login flow
- User visits the white label domain directly.
- 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)
- The login page of finepick.com, collects and processes the user's login credentials based on the data stored in finepick.com
- 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
- 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)/ along with the single parameter called "ticket" (the routed url is https://reports.finepick.com?ticket=[generated ticket])
- Now the white label site (Zoho Reports) recognizes the user.
Website Logout Flow:
- When the user clicks on the logout URL in the website, the website should call the Zoho Reports signout API and invalidate the ticket.
- The signout API call is a must!
- 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
- Zoho will automatically clear all cookies and session information about the user from Zoho's end.
- 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.
- A full demo of the integration needs to be provided to the Zoho team.