Subscribe to PortalGuard's Quarterly Newsletter for News & Updates on the Latest Release! Click to Subscribe

How to Configure and Manage The PortalGuard Announcements Feature


Problem

Your need the ability to dynamically display important information on the PortalGuard login screen, or when users access certain applications via SSO. 

Solution

Use the Announcements feature in PortalGuard to setup login or application-specific announcements. The Announcements feature also allows you to configure announcements for specific groups of users as needed. 

Quick Navigation:

Prerequisites:

  • PortalGuard SQL Back-End installed
    • This requires Microsoft SQL server 2008 or later - Express, Standard, and enterprise editions are all supported
  • PortalGuard version 5.6.0.0 or later
  • Administration (announcement creation, etc.) requires Microsoft Internet Explorer 11 or the latest version of Google Chrome/Mozilla Firefox.

Caveats & Considerations:

This feature of PortalGuard uses a .NET HTTP module to control access to the protected section of the website.  You must follow all steps in the Configuration  section below to ensure unauthorized users cannot access the protected 'admin' section of the Announcements feature. Please note the following limitations:

  • File or Directory Renaming
    • The announcements feature does NOT support moving or renaming any of the files in the /Exts/Announcements folder.
  • Use of Virtual Directories 
    • The Announcements feature does NOT support exposing it through a new Virtual Directory.
  • Use of URL Rewrite 
    • The Announcements feature does NOT support creating aliases to any of the files in the /Exts/Announcements folder.

Installation Instructions:

  1. Access the PortalGuard SQL Backend Database server Using Microsoft SQL Server Management Studio.  Once connected, create a new user named "announcements_user" and give them db_owner rights in the pstar database.
    • This is required for the user to run stored procedures. 
    • SQL - Announcements User Creation
  2. Navigate to the PortalGuard Server.
  3. Locate the PortalGuard Install Kit for your version of PortalGuard
    • This would be the folder containing the initial MSI used for the PortalGuard installation. 
  4. Navigate to the _Optional\Extensions\ folder and copy the "Announcements.zip" file into the root of the PortalGuard website.
    • i.e. C:\inetpub\PortalGuard\
  5. Done properly, this will create two new folders:
    • C:\inetpub\PortalGuard\bin
      • Contains a single file named "extAnnouncements.dll".
    • C:\inetpub\PortalGuard\Exts
      • Contains another folder named "Announcements", which contains numerous other files. 
  6. Open the C:\inetpub\PortalGuard\web.config file in an administrative text editor (i.e. Notepad++ or similar).
  7. Search for "AnnounceAuthz" and remove the HTML comments at the beginning and end of that line.
    • The final result should resemble the following:
      • Announcements - web config 1
  8. Search for "appSettings" and remove the HTML Comments at the beginning and end of the block.
    • The final result should resemble the following:
      • Announcements - web config 2
  9. Open the C:\inetpub\PortalGuard\Exts\Announcements\web.config file in an administrative text editor.
  10. Search for "AllowedUsers" and enter the usernames for any specific users who should always be allowed to manage announcements.
    • Announcements - AllowedUsers
  11. Search for "AllowedGroups" and enter values for any specific Groups or OUs that should always be allowed to manage announcements.  Groups must be listed via the fully distinguished name:
    • Announcements - AllowedGroups
      • Organization Units/containers must use the format: "*/theOU/acme/org"
  12. Search for "connectionString" and change the "Data Source" value to point to your SQL Server.
  13. Update the "Password" value to utilize the password that you set for the "announcements_user" in step #1 above.
    • Instructions for encrypting the password in this file can be found at the end of this article.  Click HERE to go there now.
  14. Save the changes to the web.config file. 
  15. In the same administrative text editor, open the C:\inetpub\PortalGuard\_layouts\PG\login.aspx file.
  16. Search for "bExtRedirected" and comment out/delete the line for "bool bExtRedirected = false;".
  17. Uncomment the line above by removing the "//" characters at the front of the line.  Your final result should resemble the following:
    • Announcements - Login Change 1
  18. Search for "announcements.css" and remove the HTML comments at the start of the line and the end of the subsequent line.  Your final result should resemble the following:
    • Announcements - CSS Uncomment
  19. Search for "getPreloginAnnouncements" and remove the "//" characters at the front of the line.  Your final result should resemble the following:
    • Announcements - Login Change 2
  20. Save the changes to login.aspx

 Managing Announcements:

The following URL structure can be used to create or edit Announcements:

https://<YOUR.PG.SERVER>/Exts/Announcements/admin/manage.aspx

Create a new announcement with the top-most link or click the title of an existing announcement to edit it.  You can sort the view by clicking on the column headers. 

  • NOTE: Announcements can only be deleted from this view.  If you wish to keep an announcement around, but not display it, simply edit the announcement and set the "End Date/Time" to a time in the past.

When editing a specific announcement, the Title, Start Time, End Time, and Body are all required fields.  The options for configuring each Announcement are detailed below:

  • For Specific SSO App
    • These announcements appear "inline" during a user's SSO attempt to a specific application.  
    • Enabling this setting displays a list of SSO targets defined on the PortalGuard server.  Only a single target app can be chosen and only "enabled" SAML, WS-Federation, and CAS configurations will be displayed in the list. 
  • Dismissible
    • Enabling this option allows users to dismiss announcements and will prevent the announcement from appearing again when they next login during the announcement's active timeframe.  Applications marked for a "Specific SSO App" cannot be dismissed. 
  • Display on Login Page
    • Enabling this option will cause the Announcement to appear directly on the PortalGuard Login page to be viewed without logging in.  Even if a user 'dismisses' the announcement on the stand alone announcements page, the announcement will still be displayed on the login form since the user is anonymous at that point. 
  • Hide on Announcements Page
    • This option is only available when the announcement is marked for "Display on Login Page".  This will prevent users from seeing the announcement on the login page AND the standalone announcements page. 

Encrypting Credentials in the SQL ConnectionString:

Once you have finished setting up the Announcements feature and tested for confirmation, you can optionally encrypt the "connectionString" portion of the Announcements web.config file to protect the SQL credentials that you entered during setup. 

NOTE:These steps need to be performed on each PortalGuard server where Announcements are running from.

  1. Launch Command Prompt as an Administrator.
  2. Change directory (using the "cd" command) to the .NET installation directory where "aspnet_regiis.exe" exists.  For .NET 4.0 or later, the following command is used:
    • cd "%WINDIR%\Microsoft.NET\Framework\v4.0.30319"

  3. Run the following command - it will encrypt the entire connection string (including server, username, and password) and you will not be able to edit it without completely overwriting that section with a new, clear-text copy:
    • aspnet_regiis -pef "connectionStrings" "C:\inetpub\PortalGuard\Exts\Announcements"

  4. Your final result should resemble the following:
    • SQL - ConnectionString Encryption
  5. Run iisreset and test the Announcements feature to ensure they still function as expected.

IF ANNOUNCEMENTS STOP WORKING AFTER ENCRYPTION:

Give the Application Pool identity under which your PortalGuard website runs access using the following command in an administrative Command Prompt:

  • aspnet_regiis -pa "NetFrameworkConfigurationKey" "IIS AppPool\DefaultAppPool"

    • Be sure to change "DefaultAppPool" in the command above to the name of the Application Pool under which your PortalGuard instance is running if it is different. 

As a final step, run iisreset once more and re-test the Announcements feature. 

REV. 09/2018 | PortalGuard

  • 65
  • 06-Mar-2019
  • 213 Views