Analytics-Plus Help

SSO Integration

 

APIs

Workflow Test Scenarios

Integration Test Scenarios

Other Terms & Conditions

ManageEngine 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 ManageEngine 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 ManageEngine's third party SSO integration.

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 ManageEngine Reports for user Sign Up API.
Input Parameters for Sign Up API

ParameterDescription
operationValue is "signup"
emailEmail Id of the userto sign up
login_nameName of the user as displayed
full_nameSame as login name
apikeyYour API key

Note:

  • full_name and login_name should be the same
  • full_name and login_name should be a valid ManageEngine user name (2-30 characters long containing only numbers, alphabets, underscores and dot)

Response for Sign Up API:
Both Success & Failure responses are present in JSON format.

Return ValueDescription
resultsuccess/failure
If API call is success, then success value is present in the result attribute; else failure value.
zuidID generated by the ManageEngine 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.
ticketthis is used by the user to access the reports present in the ManageEngine Reports. This needs to be passed to ManageEngine as part of the URL.
causeThis attribute is present in the response, only in case of failure.

Sample Success Response

{
"ticket":"666b88566441b69d1a137db824314b6a9be8959a75b1a1be8b951c6e18f352bb2e068f 7f697fa4879e365e19967a5b537a08c8e85058625130e54e8467d85259",
"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 ManageEngine Reports for user Sign In API.
Input Parameter for Sign In API

ParameterDescription
operationValue is "signin"
apikeyYour API key
emailEmail address of the user to sign in

Response for Sign in API:
Both success & failure responses are present in JSON format.

Return ValueDescription
resultsuccess/failure

If the API call is successful, then success value is present in the result attribute; else failure value.

zuidID generated by the ManageEngine 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.
ticketThis is used by the user to access the reports present in the ManageEngine Reports. This needs to be passed to ManageEngine as part of the URL.
causeThis attribute present in the response, only in case of failure

Sample Success Response

{
"ticket":"666b88566441b69d1a137db824314b6a9be8959a75b1a1be8b951c6e18f352bb2e068f 7f697fa4879e365e19967a5b537a08c8e85058625130e54e8467d85259",
"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 ManageEngine Reports and will redirect to your logout 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 ManageEngine 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.
  • ManageEngine 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. Invoke the white label URL with the ticket as the only argument. Example: https://reports.finepick.com?ticket=[obtained ticket]
  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 ManageEngine 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 ManageEngine 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 along with the single parameter called "ticket" (the routed url is https://reports.finepick.com?ticket=[generated ticket])
  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 ManageEngine 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 ManageEngine ticket
  5. After successfully obtaining the ManageEngine 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])
  6. Now the white label site (ManageEngine Reports) recognizes the user.

Website Logout Flow:

  1. When the user clicks on the logout URL in the website, the website should call the ManageEngine 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. ManageEngine will automatically clear all cookies and session information about the user from ManageEngine's end.

Other Terms & Conditions:

  1. Before going live, it is mandatory for you to include ManageEngine's Terms and Conditions indicating that the community is hosted on ManageEngine and indicate ManageEngine'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 ManageEngine team.

Share this post : FacebookTwitter