/**
   * Get user details from SSO connection and set them in the user session.
   *
   * @return boolean: Flag whether a user was actually logged in or not.
   */
  @Override
  public boolean ssoCheckUserDetails(JsonSessionState session) {
    // After the SSO roun-trip, restore any old query parameters we lost
    List<String> currentParams = request.getParameterNames();
    // Cast a copy of keySet() to array to avoid errors as we modify
    String[] oldParams = session.keySet().toArray(new String[0]);
    // Loop through session data...
    for (String key : oldParams) {
      // ... looking for SSO stored params
      if (key.startsWith(SSO_STORAGE_PREFIX)) {
        // Remove our prefix...
        String oldParam = key.replace(SSO_STORAGE_PREFIX, "");
        // ... and check if it survived the trip
        if (!currentParams.contains(oldParam)) {
          // No it didn't, add it to form data... the parameters are
          //   already accessible from there in Jython
          String data = (String) session.get(key);
          formData.set(oldParam, data);
          // Don't forget to clear it from the session
          session.remove(key);
        }
      }
    }

    // Check our SSO providers for valid logins
    for (String ssoId : sso.keySet()) {
      sso.get(ssoId).ssoCheckUserDetails(session);
      GenericUser user = (GenericUser) sso.get(ssoId).getUserObject(session);
      if (user != null) {
        session.set("username", user.getUsername());
        session.set("source", ssoId);
        return true;
      }
    }
    return false;
  }
  /**
   * Initialize the SSO Service, prepare a login if required
   *
   * @param session The server session data
   * @throws Exception if any errors occur
   */
  @Override
  public String ssoInit(JsonSessionState session) throws Exception {
    // Keep track of the user switching portals for
    // link building in other methods
    String portalId = (String) session.get("portalId", defaultPortal);
    ssoLoginUrl = serverUrlBase + portalId + SSO_LOGIN_PAGE;

    // Find out what page we are on
    String path = request.getAttribute("RequestURI").toString();
    String currentAddress = serverUrlBase + path;

    // Store the portal URL, might be required by implementers to build
    //  an interface (images etc).
    session.set("ssoPortalUrl", serverUrlBase + portalId);

    // Makes sure all SSO plugins get initialised
    for (String ssoId : sso.keySet()) {
      sso.get(ssoId).ssoInit(session, rg.getHTTPServletRequest());
    }

    // Are we logging in right now?
    String ssoId = request.getParameter("ssoId");

    // If this isn't the login page...
    if (!currentAddress.contains(SSO_LOGIN_PAGE)) {
      // Store the current address for use later
      session.set("returnAddress", currentAddress);
      // We might still be logging in from a deep link
      if (ssoId == null) {
        // No we're not, finished now
        return null;
      } else {
        // Yes it's a deep link, store any extra query params
        // since they probably won't survive the round-trip
        // through SSO.
        for (String param : request.getParameterNames()) {
          if (!param.equals("ssoId")) {
            // Store all the other parameters
            session.set(SSO_STORAGE_PREFIX + param, request.getParameter(param));
          }
        }
      }
    }

    // Get the last address to return the user to
    String returnAddress = (String) session.get("returnAddress");
    if (returnAddress == null) {
      // Or use the home page
      returnAddress = serverUrlBase + portalId + "/home";
    }

    // Which SSO provider did the user request?
    if (ssoId == null) {
      log.error("==== SSO: SSO ID not found!");
      return null;
    }
    if (!sso.containsKey(ssoId)) {
      log.error("==== SSO: SSO ID invalid: '{}'!", ssoId);
      return null;
    }

    // The main event... finally
    sso.get(ssoId).ssoPrepareLogin(session, returnAddress, serverUrlBase);
    return ssoId;
  }