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

    Parameter Description
    operation Value is "signup"
    email Email Id of the userto sign up
    login_name Name of the user as displayed
    full_name Same as login name
    apikey Your 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 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 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.
    ticket this 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.
    cause This 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

    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 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.
    ticket This 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.
    cause This 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.
     

    Copyright © 2016, ZOHO Corp. All Rights Reserved.