Using Gateway SSO for Web Applications with Dynamic Log In Forms

Gateway SSO Portlet is designed to pass along credentials to another web application for the purpose of Single Sign On. This is accomplished by submitting a sequence of pre-constructed forms to the other web application. This works for many web applications. It does not work for those that require some dynamic key or hidden input field that can not be pre-constructed by the Gateway portlet.

It is possible to create an SSO target that functions as a bridge between the Gateway SSO and the web application requiring the dynamic log in form. This KBA describes one such bridge.

This particular bridge will work for some dynamic form web applications served from the same domain* as the portal. To make use of this bridge, do the following:

1. Download bridgeA.html and place at {PORTAL_URL}/AcademusApps/rendering/html/sso/
2. Download bridgeB.html and place it somewhere under the sub-domain of the web application that is being SSO'ed into. We'll refer to that location (subfolder) as: {BRIDGE_B_LOCATION}. So that bridgeB.html is located at {BRIDGE_B_LOCATION}/bridgeB.html.
3. Download space.html and place it in the same sub-directory as bridgeB.html, or in other words at: {BRIDGE_B_LOCATION}/space.html.
4. Configure an SSO target (in the SSO Gateway configuration file) as normal (see Gateway SSO Configuration documentation) except:
   
   1. Put the form action that is normally the content of <url/>, in a form parameter of the name SSODynamicFormUrl:
      

            <parameter name="SSODynamicFormUrl"><value>{FORM_ACTION_URL}</value></parameter>
         

      where FORM_ACTION_URL is the form action

   2. Use
      

            <url>http://{PORTAL_URL}/AcademusApps/rendering/html/sso/bridgeA.html?
      SSODynamicFormId={UNIQUE_ID}&amp;url={ESCAPED_BRIDGE_B_LOCATION}/bridgeB.html</url>
         

      where <url/> is all on one line
      where PORTAL_URL is the URL to the where the /portal and /AcademusApps are served and
      where UNIQUE_ID is a unique Id unique for this SSO (to account for the case where you have multiple on the same page)
      where ESCAPED_BRIDGE_B_LOCATION is the BRIDGE_B_LOCATION URL escaped so that it can appear as a parameter on the URL. To obtain the correct value for it, click here and paste into the first prompt the value of BRIDGE_B_LOCATION, and hit OK, then copy the text that shows in the second prompt. This is the ESCAPED_BRIDGE_B_LOCATION.

Debugging SSO with the bridge

To DEBUG the SSO if it doesn't seem to be working:

1. Save the Log In page source for the other application as ssotest.html and place it at
   {PORTAL_URL}/AcademusApps/rendering/html/sso/.
2. Set
   

         
   <parameter name="SSODynamicFormUrl">
       <value>{PORTAL_URL}/AcademusApps/rendering/html/sso/ssotest.html</value>
   </parameter>
         
      

   temporarily.

3. Edit ssotest.html and change the form action to {PORTAL_URL}/AcademusApps/rendering/jsp/sso-test.jsp, save it and try again. The submission should show what parameters are being passed to the other application.

If you are unable to figure out what is failing, you might try to load {PORTAL_URL}/AcademusApps/rendering/html/sso/ssotest.html
(after reseting the original form action - i.e. reverse Debug Step 3) and manually fill in field and click submit.

Forms that require a Submit button be clicked

It may be that some web applications check that the button was pressed.

If so, add the following to your SSO target:

1.       <parameter name="SSODynamicFormButtonName"><value>{BUTTON_NAME}</value></parameter>
      

   where BUTTON_NAME is the name attribute of the button on the Log In form that is required to submit it

2.       <parameter name="SSODynamicFormButtonValue"><value>{BUTTON_VALUE}</value></parameter>
      

   where BUTTON_VALUE is the value attribute of that same button

NOTE: If #2 is left out, it will attempt to use the value of the first button on the Log In form with the same name.

Forms with onsubmit handlers

By default, this bridge will automatically call the form's onsubmit handler, if one is present on the dynamic form. In most cases this is probably the desired behavior as it will simulate what would happen if the user clicks submit through the User Interface. If for some reason this is not desired, it can be turned off by adding the following parameter to the SSO configuration:

      <parameter name="SSODynamicFormTriggerOnSubmit"><value>false</value></parameter>
   

Forms that are not directly accessible by a static URL

Some web applications create session specific URLs for users. As long as the web application will take a static URL and redirect to a session specific URL that ends at the Log In form nothing special needs to happen, for this bridge to function.

However, if the static URL goes to an intermediate page that requires a click on a link to then navigate to the actual Log In form, an additional configuration needs to be set:

      <parameter name="SSODynamicFormFollowLinkText"><value>{LINK_TEXT}</value></parameter>
   

where LINK_TEXT is the string of text that can be found within the link that needs to be accessed.

For example, if a link with the text of "Log In" must be clicked then the value of LINK_TEXT would be "Log In".

Please note, the bridge logic is such that it scans the list of links of the page and the first link whose text matches the value of the SSODynamicFormFollowLinkText parameter, will be accessed.

More information

Disclaimer

Web applications are developed it many different ways, which means that it is impossible to say for sure whether or not this bridge will work with a specific one without trying it out. Unicon is providing this bridge "as is", in hopes of helping our clients expand the sorts of applications they can provide a SSO into.

This SSO bridge was tested and found to work with Firefox 2, IE 7, Opera 9, and Safari 2. It may or may not work with other browsers.

For this bridge to work, the other application needs to be able to be displayed within a frameset. All web pages will display initially in a frameset, but some have code that runs and deliberately breaks out of framesets. This solution makes use of a frameset to control the SSO process (grabbing of data, and filling in the Log In form), so if the page breaks out of the frameset it will not function. This has nothing to do with whether or not the SSO window is an iframe or a popup with respect to the portal. It should function fine in both cases.

In theory, this SSO bridge should work for single sign on into Blackboard and Web Advisor. It has not been tested against those applications, but in principle it should be possible.

Your participation

Please add comments to this KBA, or otherwise let us know under what circumstances this bridge works. If you find a configuration, that works for a particular web application, please share that through a comment so that others will benefit.

* Browsers have a built-in security mechanism which prevents scripts from one domain from accessing web pages from another domain (they even limit access across sub-domains by default). This dynamic form bridge works by loading the bridgeA.html file in the sub-domain of the portal. Code in the file copies the form data from the SSO and saves it as a domain cookie. It then calls bridgeB.html which is in the sub-domain of the other application. Code in that file, retrieves the data stored in the domain cookie (as they both should be in the same domain), then deletes the cookie. It then copies those values into the actual log in form provided by the web application, and submits it. This then accomplishes the SSO for a web application that is in the same domain as the portal, regardless of the sub-domain. It will not function across domains. The SSO Gateway portlet itself will function cross-domain provided that the log in information can be pre-constructed (i.e. it is not dynamic).