/
Enable PortalGuard Sidecar

Enable PortalGuard Sidecar

Owned by Stephen Call (Deactivated)
Nov 11, 2021
4 min read

Problem

You need to add links to PortalGuard's Self-Service Password Reset and Account Unlock Features on another website's login page, which is NOT federated with PortalGuard for Single Sign-On.

Solution

Use PortalGuard's Sidecar Mode to enable the Self-Service functionality directly from the target website's login page.

Requirements for Sidecar Mode

  1. The target website MUST be using Forms-based Authentication.

  2. Users MUST use a FQDN hostname to access the target website.

  3. Both the target website and the PortalGuard website MUST exist as part of the same web domain.

  4. Backup all existing resources/files on the target website before making any of the changes below.

Configuration Steps

  1. On the PortalGuard Server - navigate to C:\inetpub\PortalGuard\_Layouts\PG and duplicate login.aspx. Rename the new file to sidecar-login.aspx and edit this file in an administrative text editor.

    • We recommend using Notepad++ or similar.

  2. Search the file for 'bSidecar'. Uncomment this line and set the value to 'true'.

  3. Remove the comments from the 'document.domain' line and set the value to the suffix of your domain.

    • i.e. if your PortalGuard website is located at 'password.pgtest.int.com' the value for 'document.domain' would be 'pgtest.int'.

  4. Save the changes to this file.

  5. Navigate to C:\inetpub\PortalGuard and edit the root 'web.config' file in an administrative text editor.

  6. Search for 'X-Frame-Options' and comment out the <add name="X-Frame-Options" value="DENY"> line.

  7. Uncomment the fifth line after the <add name="X-Frame-Options" value="DENY"> line and update the value to your Target Website URL.

  8. Your final result should resemble the following:

  9. Save the changes to this file.

  10. Open the PortalGuard Install Kit used to install PortalGuard in your environment.

  11. Navigate to the _Optional/Sidecar folder.

  12. Copy the 'Generic' folder and bring this to the target website server.  Paste it wherever it will be easy to access the files.

  13. Within the 'Generic' folder, locate the pg_sidecar.js file and edit said file in an administrative text editor.

  14. On line 2 of the file, set 'DEBUG' to 'true' for testing.

  15. View the source HTML for the target website's login page.

  16. Search for the 'id=' value of both the Username and Password fields.

    • The label and 'id=' value for thee input fields will likely be different for each website, but can easily be determined by clicking into the field and then right-clicking the field and choosing 'inspect element'. 

      • The highlighted element in this view will contain the 'id=' value needed to continue with the Sidecar configuration.

  17. Input each value into the pg_sidecar.js file appropriately.

  18. Search for the 'id=' value of the Login button.

    • This button may be called 'Submit' or some other name in the actual login form.  The button that we need is whatever submits the login form to the website for authentication.

    • Again, right-clicking the button and choosing 'inspect element' will often bring up the source view with the appropriate section highlighted.

  19. Input the value into the pg_sidecar.js file appropriately.

  20. Your results should resemble the following:

  21. Within the pg_sidecar.js file, make the following changes:

    • Update 'document.domain'

      • This value should match the value defined in step #3 above

    • Update the root URL for 'var strAutoLoginURL'

    • Update the root URL for 'var strSelfServURL'

    • Update the 'function doSubmit()' to appear as shown here

  22. Save the changes to pg_sidecar.js.

  23. Copy this file and paste it into the same folder of the target website as the main login page.

  24. For the Target Website - Edit the target website's login page in an Administrative Text Editor.

  25. In the <head> section of the target website's login page, add the following line to enable the website to load pg_sidecar.js:

    <script src="pg_sidecar.js" type="text/javascript"></script>

  26. Add links to the PortalGuard functionality you want integrated with this application.

    • For this example, we will add a link to initiate PortalGuard's Self-Service Password Reset functionality using the following html:

      <a href="javascript:AccountSelfService()">Forgot your Password?</a><br />

    • The location of the link will vary based on the application and personal preference.

  27. Locate the </body> tag towards the bottom of the page.  Add the following lines of code just above the </body> tag:

    <script type="text/javascript">setHandler(document.forms[0]);document.getElementById(THIS_USER_FLD).focus();</script> <iframe id="ifrmDestFrame" name="ifrmDestFrame" src="about:blank" style="display:none;position:absolute;left:0px;top:0px;width:800px;height:600px;border:3px solid #008800" frameborder="0"></iframe>

  28. The final result should resemble the following:

  29. Save the changes to this file.

  30. Test the integration by attempting to authenticate with a user who has not enrolled within PortalGuard

    • This should cause an iframe to open with PortalGuard prompting the user for enrollment

  31. Test the SSPR integration by clicking the link that was created in step #26 above.  If a username was provided on the login form, and iframe should open with the username pre-populated, otherwise the user will be required to enter his or her username.