Identity Provider/SSO

The PortalGuard Identity Provider (IdP) is used to provide SSO to other external web servers.It plays a central role in the identity federation model of integrating PortalGuard with other web servers.It currently supports a subset of the SAML v1.1, SAML v2.0 and WS-Federation specifications.

Using IdP_Config.exe

Use the IdP_Config.exe utility to edit all PortalGuard Identity Provider-related settings and create relying party configurations.This utility can be found in the root "PortalGuard" folder under the install path (C:\Program Files\Pistolstar\PortalGuard by default).

Signing Certificate Creation

A self-signed certificate must be used by the PortalGuardIdP to sign outgoing SAML assertions.This can be created quickly using openssl.exe which is included in the PortalGuard Trial zip file in the “PortalGuard Trial\For IIS\_Optional” folder.Open a DOS prompt and change directory to this folder, then run the following command and follow the prompts that appear:

opensslreq -x509 -days 3650 -newkey rsa:2048 -keyoutPGIdP.pem -out PGIdP.pem -config ./openssl.cnf

Remember the password you provide as it will need to be entered in the IdP_Config.exe as well.

Lastly, you can easily create a file containing the public certificate using the following command:

openssl x509 -outform PEM -in PGIdP.pem -out PGIdP.cer

Microsoft SharePoint 2010 Configuration

This section details how to configure both the PortalGuardIdP and SharePoint 2010 to receive claims-based SSO to SharePoint.

Requirements

Procedure

The following steps include the creation of a new/demo SharePoint website which utilizes claims-based authentication.The name of the SharePoint server is highlighted in the steps below as “mustang.pg.local”.Replace this with the name of your own SharePoint server or alias.

On PortalGuard server

  1. Launch Identity Provider Configuration Editor (IdP_Config.exe)
  2. On the top-level Attribute Stores tab, create a new Attribute Store configuration
  3. Point it to your Active Directory.Since the PG IdP makes no changes to attribute stores, the “Generic User” account on the LDAP Basic tab only needs read access.This field value must be the full distinguished name of the user in AD.

  1. Create a new Relying Party configuration with the following settings:
  2. General tab:
    1. Name: SharePoint 2010
    2. Add Identifier: urn:sharepoint:sso
    3. Assertion Consumer URL: https://mustang.pg.local/_trust/

  1. WS-Fed tab:
    1. Click “SharePoint 2010” button in “Templates” group
    2. OK “token lifetime” notification popup that appears
  2. Identity Claims tab:
    1. Choose the newly created Attribute Store if not already selected
    2. Create first new claim:

Name: Email Address

../admin-guide-images/ ii. Schema Type (from drop-down): http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Value Type: Direct Field

Field Name: mail

../admin-guide-images/ v. Value Index: 0

    1. Create second new claim:

Name: AD Groups

../admin-guide-images/ ii. Schema Type (from drop-down): http://schemas.microsoft.com/ws/2008/06/identity/claims/role

Value Type: Groups (Unqualified)

  1. IdP-Initiated tab:
    1. Display Text: SharePoint 2010
    2. Help Text: Team room
    3. Check “IdP-initiated SSO not directly supported by RP
    4. Default URL: https://mustang.pg.local

  1. Click the Save button to commit the changes to the Relying Party configuration

On SharePoint server

  1. Copy the PortalGuardIdP signing certificate to SharePoint server, e.g. C:\PGIdP.cer
  2. Copy create_PG_TrustedTokenIssuer.ps1 and create_DemoSSO_webapp.ps1 to the SharePoint server
  3. Open create_PG_TrustedTokenIssuer.ps1 in a text editor and:
    1. Change the $certpath variable to the path to the PortalGuardIdP signing certificate on the SharePoint server
    2. Change the server portion of the $SSOURL variable to your PortalGuard server.This value must use HTTPS and still end in “/sso/go.ashx”.
    3. Save the changes
  4. Open create_DemoSSO_webapp.ps1 in a text editor and:
    1. Change the $waurl variable to the SharePoint server name or alias, e.g. https://mustang.pg.local.
    2. Change the $apppool variable to the DOMAIN\account identity under which the website should run
    3. Change the $useremail variable to your test user’s exact email address – they will explicitly be given Full Control permissions to this test site.
  5. Launch SharePoint 2010 Management Shell
  6. Change directory using the “cd” command to the folder containing the .ps1 files
  7. Execute the create_PG_TrustedTokenIssuer.ps1 script by typing the name and hitting enter.It may take some time to complete.
  8. Execute the create_DemoSSO_webapp.ps1 script by typing the name and hitting enter.It may also take some time to complete.

You should now be able to launch a browser and access the new SharePoint website (e.g. https://mustang.pg.local).You should be redirected to the PortalGuardIdP to login, then redirected back to SharePoint upon successful login.

You can also use SharePoint Central Administration to use PortalGuard for SSO under Application Management -> Manage web applications then clicking the website and clicking the “Authentication Providers” button in the ribbon.After choosing the zone to edit, PortalGuard should appear as an option under the “Trusted Identity provider” section:

Microsoft Exchange 2013 (OWA Only)

This section shows you how to configure Microsoft Outlook Web App (OWA) 2013 SP1 or later to allow Single Sign-On or enforce Two-Factor Authentication through PortalGuard.The follow steps have been tested up through Exchange 2013 Cumulative Update 8 (CU8).If you have a newer version of Exchange 2013, please contact Technical Support to assure no newer version of this documentation exists.

 

Requirements – PortalGuard Server

All end-users must be able to reach the PortalGuard website (e.g. port 443 for HTTPS) over the network.End-users will be redirected to the PortalGuard server(s) to authenticate when accessing OWA.

PG_IdP.dll is version 4.3.1.5 or higher. This file can be found in the <PGROOT>\bin folder.

NOTE: Please contact PortalGuard support if you do not have at least this version to determine the best upgrade method.

Requirements – Exchange Server

Must be running Exchange 2013, SP1 (aka CU4) or higher

NOTE: You can determine the Exchange version using the following Exchange Management Shell command:

get-exchangeserver |ftname,admindisplay*

The result’s “Build” value for Exchange 2013 can be looked up here.The Build Number for CU4 is “847.32”.

On the PortalGuard Server

Create/Edit SAML Configurations

1) Follow the steps in the Identity Provider / SSO section of Chapter 5. This will help you:

a. Create the IdP Signing Certificate,

b. Set up the “General IdP Settings” and

c. Edit the default Attribute Store so the PortalGuardIdP can pull user data from your directory

If you already have SAML SSO to other websites through PortalGuard, then you have already completed these steps.

2) Launch the Identity Provider Configuration Utility (IdP_Config.exe).

3) In the “SAML Websites” list, click the “Create” button.

4) Open the “WS-Fed” tab and in the Templates section, click the “OWA 2013” button.

NOTE: If you do not see this button, then you are not running the proper version of PortalGuard and will need to contact Technical Support to upgrade your server.

5) On the popup dialog that appears, enter the OWA CAS server URL “base” that users enter to access OWA.This must include the protocol, but must not include any additional URL path.

Correct:

https://owa.acme.com

Incorrect:

https://owa.acme.com/owa

owa.acme.com

6) OK the “successfully applied template” popup and save the configuration.

7) Back in the “SAML Websites” tab, click the “Create” button again.

8) Open the “WS-Fed” tab and in the Templates section, click the “OWA 2013 (ECP)” button.

9) On the popup dialog that appears, enter the same OWA CAS server URL “base” you entered in the previous step.

10) OK the “successfully applied template” popup and save the configuration.

11) Click the “Apply To Identity Provider” button in the main IdP_Config dialog and perform the “Sync” on the dialog that follows to make the changes available to end-users.

Determine Signing Certificate Thumbprint

Exchange requires the hex-encoded Thumbprint value from yourPortalGuardIdP’s signing certificate.This can be accessed by double-clicking the public PGIdP.cer file created in step 1a above and scrolling down to the “Thumbprint” field on the Details tab:

For Exchange, the thumbprint value must be all CAPITAL LETTERS and only contain character values 0-9 and A-F inclusive.If copied from the certificate details above, then all spaces must be removed and all letters must be capitalized (Tip: The “Ctrl-Shift-U” hotkey in Notepad++ will capitalize the highlighted text).

NOTE: There is a known issue within the Microsoft certificate display snap-in that includes “invisible” Unicode characters at the beginning and end of the “Thumbprint” value (see this link for further details).It is suggested that you paste the copied value in a text editor, then re-type the entire value manually on the line below and use this manually edited line in the steps below.

On the OWA Client Access Server(s)

NOTE: The steps below must be performed on each Exchange front-end/Client Access Servers (CAS).

Trust PortalGuardIdP Signing Certificate

NOTE: The following Exchange shell commands reference ADFS but PortalGuard’s federation with OWA 2013 does NOT require ADFS to be running in your environment.PortalGuard simply leverages the same configuration steps and back-end .NET modules.Do NOT setup a new ADFS server as it is not needed.

1) Copy the PGIdP.cer file from the PortalGuard server to the Windows Desktop on CAS instance.

2) Launch an Exchange Management Shell as an administrator

3) Run “mmc” from the shell

4) In the Microsoft Management Console, choose the File -> Add/Remove Snap-in… menu item:

5) In the left-hand list, choose Certificates, click the Add > button, then choose Computer account, Local computer then click the Finish button.

6) Click OK to view the local machine’s certificate store.In the left-hand tree, find the Trusted People container, right-click it, then choose the All Tasks -> Import… menu item.

7) Browse to the PGIdP.cer file, accept all other defaults, then use the Finish button to add the PortalGuard’sIdP signing certificate to this machine.

Configure OWA Authentication Types

8) Paste the following two lines into a text editor:

$uris = @(" https://YOUR.OWA.SERVER/owa","https://YOUR.OWA.SERVER/ecp")

Set-OrganizationConfig -AdfsIssuer "https://YOUR.PORTALGUARD.SERVER/sso/go.ashx" -AdfsAudienceUris $uris -AdfsSignCertificateThumbprint "YOUR-PGIDP-SIGNINGCERT-THUMBPRINT"

9) Edit the text by replacing both instances of YOUR.OWA.SERVER with the server name by which users access OWA, e.g. owa.acme.com.

10) On the 2nd line, replace YOUR.PORTALGUARD.SERVER with the server name by which users can access PortalGuard, e.g. portalguard.acme.com.

11) Also on the 2nd line, replace YOUR-PGIDP-SIGNINGCERT-THUMBPRINT with the thumbprint created in the last step of the previous section.For SHA-1, this thumbprint is 40 characters long.

A correctly edited version of these two lines should look like this:

$uris = @(" https://owa.acme.com/owa","https://owa.acme.com/ecp")

Set-OrganizationConfig -AdfsIssuer "https://portalguard.acme.com/sso/go.ashx" -AdfsAudienceUris $uris -AdfsSignCertificateThumbprint "1234567890ABCDEF1234567890ABCDEF12345678"

12) Copy the two edited lines from the text editor and paste them into the Exchange Management Shell.Press Enter to execute them.You will receive a warning that iisreset must be run before the changes take effect.

13) Get the name of the ECP virtual directory for the CAS you want to federate.You can get the full list for your environment by running the following Powershell command:

Get-EcpVirtualDirectory

14) Paste the following line into a text editor:

Get-EcpVirtualDirectory -Identity "THESERVER\YOUR-ECP-VDIR-NAME" | Set-EcpVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false

15) Edit the text by replacing THESERVER with the CAS server host name (e.g. OWA1) and YOUR-ECP-VDIR-NAME with the ECP virtual directory name you got from the previous PowerShell command, e.g. ecp (Default Web Site).

A correctly edited version should look like this (note the backslash between the hostname and the ECP virtual directory name):

Get-EcpVirtualDirectory -Identity "OWA1\ecp (Default Web Site)" | Set-EcpVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false

16) Copy the edited line from the text editor and paste it into the Exchange Management Shell and press Enter to execute it.You will receive two warnings about having to run iisreset and needing to make the same change for the OWA virtual directory.You can ignore those for now.

17) Get the name of the OWA virtual directory for the CAS you want to federate.You can get the full list for your environment by running the following Powershell command:

Get-OwaVirtualDirectory

18) Paste the following line into a text editor:

Get-OwaVirtualDirectory -Identity "THESERVER\YOUR-OWA-VDIR-NAME" | Set-OwaVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false

19) Edit the text by replacing THESERVER with the CAS server host name (e.g. OWA1) and YOUR-OWA-VDIR-NAME with the OWA virtual directory name you got from the previous PowerShell command, e.g. owa (Default Web Site).

A correctly edited version should look like this (again, note the backslash between the hostname and the ECP virtual directory name):

Get-OwaVirtualDirectory -Identity "OWA1\owa (Default Web Site)" | Set-OwaVirtualDirectory -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false

20) Copy the edited line from the text editor and paste it into the Exchange Management Shell and press Enter to execute it.You will receive a warning about having to run iisreset.

21) Restart IIS from the Powershell command line by running “iisreset”.Here is a screenshot of the 3 commands being run for a CAS server named antigua:

Test Configuration Changes

You should now be automatically redirected to the PortalGuard login screen when attempting to access OWA.After successful authentication, the user will be automatically redirected back to OWA.

Microsoft Office 365

This section details how to configure both the PortalGuardIdP and Office 365 to achieve SSO to Office 365 and also allow various email clients access to Office 365 when it is federated with PortalGuard.

Pre-Requisites

  • Directory synchronization from your local AD domain to Azure AD in the cloud must be correctly configured.Please see the Microsoft TechNet article, Prepare for directory synchronization, for more information.

NOTE: The “password synchronization” DirSync option is not required for SSO to work correctly. Password synchronization is now supported by Microsoft for federated accounts so you can enable it if you wish (see the May 5, 2014 update at this link).

  • The Office 365 domain marked as the “default” (e.g. company.onmicrosoft.com) cannot be federated for SSO purposes.You must have created a new domain and associated user accounts with it.Please see the article Add your domain to Office 365 or use the Add Domain wizard within the Office 365 Administrator portal for more information. If the new, custom domain you want to federate is currently set as the default, you must set a different domain as the default. Please see this Office 365 forum post for details on how to do this.

If your organization accesses Office 365 using Outlook clients or the native email app on mobile devices like iOS, Android, then the following pre-requisites also apply to support these “active” clients:

  • You must be using PortalGuard version 5.2.0.0 or later (released in August 2015).
  • The server name used to reach the PortalGuard server (e.g. “logon.acme.com”) must be resolvable in public and private DNS and be reachable by both internet and LAN-based users.
  • The PortalGuard IIS website must use a SSL certificate issued by a trusted Certificate Authority (e.g. Digicert, Verisign).
  • The HTTPS/SSL port on the PortalGuard IIS website must be the “default” SSL site. The HTTPS binding cannot use a specific hostname. Windows Server 2012 and later allows Server Name Indication (SNI) to host multiple HTTPS sites on the same port. However, some mobile devices are not SNI-capable so they are not be able to connect to the PortalGuard server. On Win2012 and up, the Require Server Name Indication setting also must not be enabled.The screenshot below shows the two settings that cannot be used if you wish to support all client devices:

If IIS on your Windows 2012 server or later has a potential configuration HTTPS issue, you may also see this warning in IIS Manager:

NOTE: As of August 2015, Microsoft’s own “Outlook for iOS“ and “Outlook for Android” apps do not support logging into a federated Office 365 domain, regardless of whether the STS is ADFS or a 3rd party product. Users wanting Office 365 email on their mobile devices must continue using the built-in/native email app on the device.

Procedure

The name of the new Office 365 domain is highlighted in the steps below as “portalguard.us”.Replace this with the name of your own domain.

On PortalGuard server

  1. Launch Identity Provider Configuration Editor (IdP_Config.exe)
  2. On the top-level Attribute Stores tab, create an Attribute Store for your local Active Directory domain/forest.This will match nearly all the settings from the User Repository configuration in PG_Config.exe.
  3. On the “SAML Websites” tab, create a new Relying Party configuration.
  4. Go to the WS-Fed tab and click the Office 365 button.This will set nearly all of the fields for you.The settings you must manually change are:
    1. On the Identity Claims tab, choose the “Attribute Store” configuration that points to your Active Directory
    2. On the IdP-Initiated tab, choose an appropriate Display Image if users will be using the PortalGuard SSO jump page.
    3. Also on the IdP-Initiated tab, the “Default URL” should be changed to a “smart link” to improve the user experience. You should be able to use the following format:

https://www.outlook.com/owa/YOUR.DOMAIN

This works in later revisions of Office 365. If it does not, follow the instructions from Using smart links or IdP initiated authentication with Office 365 to determine amp; build the appropriate URL.

  1. Click the Save button to commit the changes to the Relying Party configuration
  2. Apply the changes to the IdP using the button with red text
  3. Launch a text editor such as Notepad++ (link) as an administrator
  4. Open the root PortalGuardweb.config file (found in C:\InetPub\PortalGuard)
  5. Search for the “httpErrors” element. It should look like this initially:

  1. In the image above, remove the XML comments at the beginning (“<!--") and end (“-->”) of line 115. This is the line that contains the word PassThrough. These two subtractions are shown in pink highlight in the image above and are marked with the numbers 1 and 2.
  2. Using the line numbers in the previous image, add a new XML comment (“<!--") at the beginning of line 116. Lastly, add a XML “closing” comment (“-->”) at the very end of line 128.The resulting file section should now look like below with the two additions shown in green highlight and marked with the numbers 1 and 2:

  1. Save and close the file
  2. Launch an administrative command prompt and run the command: iisreset

On the “DirSync” Active Directory Domain Controller

  1. Copy the PortalGuardIdP signing certificate to the server, e.g. C:\PGIdP.cer
  2. Copy the _Optional\Office365 folder from the PortalGuard kit to the DC. This folder contains PowerShell scripts such as federate-office365.ps1 and backup-ADFS-Fed-Settings.ps1.
  3. Launch Windows Azure Active Directory Module for Windows PowerShell.This shortcut to PowerShell should have been installed while configuring Directory Synchronization.
  4. Change directory using the “cd” command to the _Optional\Office365 folder copied over in the previous step.
  5. Connect to Microsoft Online using the command below. Enter an Office 365 administrator username and password when prompted:

Connect-MsolService

  1. If the target Office 365 domain currently set to “Managed” authentication, then skip the remainder of this step.If the domain is already federated with your local ADFS, then run following PowerShell command to save the current ADFS settings to a local XML file if you need to revert back to them:

.\backup-ADFS-Fed-Settings.ps1

The settings will be saved in adfs-fed-settings.xml in the current directory.

NOTE: If you receive an error about script execution, run the following command to fix it for this prompt:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

You must also revert the domain back to a “Managed” domain temporarily. Use the following PowerShell command:

Set-MsolDomainAuthentication -Authentication Managed

Enter your domain name when prompted (as shown below):

  1. You are now ready to attempt federation with PortalGuard. Type the command below and hit Enter:

.\federate-office365.ps1

NOTE: If you receive an error about script execution, run the following command to fix it for this prompt:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

  1. The PowerShell script will prompt for the following:
    1. The full Office 365 domain name to federate, e.g.:

portalguard.us

    1. The full base URL of yourPortalGuard server (without a path), e.g.:

https://malt.pistolstar.com

    1. The full URL where users are redirected after signing out of Office 365 in a browser:

http://your.main.portal

NOTE: If this URL is a server other than PortalGuard, a new <SignoutWhiteList> value must be added in C:\InetPub\PortalGuard\web.config using the “<add&>” element:

    1. The Issuer value from the Response tab in the General IdP Settings.The screenshot below shows where to find this:

NOTE: This Issuer value must contain any domain name specific to your environment, e.g. “your.domain/idp”. Office 365 requires all Issuer values to be globally unique across the world so you cannot use a generic value like “PortalGuard” or “IdP”.If you must change this value in PortalGuard’sGeneral IdP Settings, be sure to notify any other Service Providers you may have already federated with -OR- change the corresponding SP-side configurations if you have access. Please also see the note on the next page if you intend to federate multiple Office 365 domains with the same PortalGuard instance.

    1. The full file path to the signing certificate used by the PortalGuardIdP.This was copied to the current server in step #1 above:

C:\PGIdP.cer

The image below shows an example run of the federate-office365.ps1 script.When this script is finished, it runs the Get-MsolDomain and Get-MsolDomainFederationSettings commands for the provided domain for confirmation. It should show “Federated” in the Authentication column if the conversion was successful.

NOTE: If you have already federated an Office 365 domain with PortalGuard, then running the federation script a second time with the same settings will result in an “Unable to convert the domain. The settings you selected are already in use.” error as shown below:

This occurs because Office365 requires ALL “Issuer” values in the world to be unique. So when you run the federate-office365.ps1 PowerShell script for the additional domain, be sure to use all the same settings except use a slightly altered “IdP Issuer” value. You can simply add a single trailing “/” character to the end of original Issuer value – this alone is enough to make it different and allow the federation to complete successfully.

Example:

Initial IdP Issuer value

https://idp.acme.com

Second IdP Issuer value

https://idp.acme.com/

Verification

After these steps, if a user goes directly to Office 365 using http://portal.microsoftonline.com or https://outlook.office365.com, they will be redirected to your PortalGuard server login page after entering their email address/username. They will typically see a transient message about this redirection as shown below.

NOTE: You can skip this redirection altogether by directing users to use the following URL (swap in your own Office 365 domain where shown):

https://www.outlook.com/owa/YOUR.DOMAIN

This will take the users directly to your PortalGuard server’s logon screen.

If you use “active” clients like Microsoft Outlook or native mobile email apps, they can be added as per Microsoft’s documentation.

Troubleshooting

If the steps above succeeded but users are not able to access their Office 365 email, please run Microsoft’s Connectivity Analyzer:

https://testconnectivity.microsoft.com/

Choose the Office 365 tab and the Office 365 Single Sign-On Test radio button then click Next.

Enter the email address of a test account in your domain and its password. Leave the “Windows Azure Active Directory (default)” radio button checked.Check the “I understand…” checkbox, answer the CAPTCHA below it and click the Perform Test button:

The test will either succeed or fail. If it fails, you can expand the top-level “Test Steps” element to see which step failed:

If you need help interpreting the results, use the Copy To Clipboard icon in the upper right corner to copy all the results and email them to us at techsupport@portalguard.com.

Reverting to Prior ADFS Federation

If your Office 365 domain had been federated with ADFS before attempting to federate it with PortalGuard, then you should be able to easily revert back to using ADFS if you backed up the ADFS federation settings as described in the steps above. The ADFS settings are stored in adfs-fed-settings.xml in the _Optional\Office365 folder you copied to the DirSync domain controller.

Launch a Windows Powershell on the AD domain controller with DirSync installed and run the following commands:

1) Change directory using the “cd” command to the _Optional\Office365 folder in the PortalGuard kit.

2) Connect to Microsoft Online using the command below. Enter an Office 365 administrator username and password when prompted:

Connect-MsolService

3) Enter the command below and enter the Office 365 domain name when prompted:

.\ restore-ADFS-Fed-Settings.ps1

NOTE: The script will fail if the “adfs-fed-settings.xml” file is not found in the current directory.

Central Authentication Service (CAS)

As of version 4.3.1, PortalGuard can act as a Central Authentication Service (CAS) server to provide web-based SSO. CAS is typically supported by higher education applications. PortalGuard supports a primary subset of CAS version 3.0 functionality.

Requirements

  • Microsoft SQL server 2005 or later
    • Both Express and Enterprise editions are supported
  • URL Rewrite module for IIS (see below for installation steps)
  • Target server that supports CAS 3.0 (the “CAS Client”)

Note: PortalGuard’s implementation of CAS does not currently support CAS proxy functionality, /samlValidate or the gateway or renew parameters.

Installation – PortalGuard Server

1) Download the IIS URL Rewrite extension from the URL below and install it: http://www.iis.net/downloads/microsoft/url-rewrite

NOTE: You do not need to install any additional products from the “Web Platform Installer” application.It is safe to “Exit” the program after the URL Rewrite extension has been installed.

2) Run “iisreset” from an administrative command prompt

Installation – SQL Server

3) For new installs of PortalGuard, please follow the steps in the PortalGuard SQL Backend section earlier in this chapter.If you are upgrading an existing PortalGuard instance and have already installed PortalGuard’s SQL backend, then you only need to run the following script from the PortalGuard install kit:

PortalGuard\_Optional\SQL scripts\upgrade-For-CAS.sql

Configuration – PortalGuard Server

4) As an administrator, open C:\InetPub\PortalGuard\web.config in a text editor.Remove the HTML comments shown in the image below.They are:

a. The “<!--“ text that precedes the <rewrite> element and

b. The “-->” text that follows the </rewrite> element

Save and close the web.config file.

5) Launch the Identity Provider Configuration Editor (IdP_Config.exe) and click the General IdP Settings button.

6) The PortalGuardIdP requires a valid signing certificate. Follow the steps in Signing Certificate Creation if you have not already done so.

7) On the CAS SSO tab, check the CAS Support Enabled checkbox and save the change.

CAS Configuration Example - Blackboard

8) In IdP_Config, click the CAS Websites tab, click the Blackboard entry and click the Edit button.

9) On the General tab, double-click the entry in the Service Ids / URLs list to edit it.Set it to the root URL of your Blackboard server.

10) On the SSO Jump Page tab, set the Default Access URL to the root URL of the Blackboard server as well, then save the CAS configuration.

11) On the Attribute Stores tab, configure the default entry to point to your user directory (whether it is Active Directory, LDAP or SQL).

12) Apply the changes to the PortalGuard server using the red button that should have appeared on the main screen of the configuration editor.

Configuration – CAS Client (Blackboard example)

13)Log into the Blackboard server and click the System Admin tab

14)In the Building Blocks section, click the Authentication item

15)From the Create Provider button, choose CAS:

16) In the Create CAS screen, set the following fields then click the Save and Configure button:

a. Name: PortalGuard CAS

b. Authentication Provider Availability: Active

c. User Lookup Method: Username

d. Restrict by hostname: Use this provider for any hostnames

e.Provider Settings – Link Text: CAS SSO

17)In the CAS Settings screen, set the following fields then click the Submit button:

a. CAS Server URL Prefix: http://YOUR.PG.SERVER/cas

b. Global Logout: Yes

c.Logout URL Suffix: /logout

d. Require Credentials: No

NOTE: If you wish to have Blackboard contact the PortalGuard server over SSL, then one of the following must be true:

4) The PortalGuard server must use a commercially-signed SSL certificate (from Verisign or Thawte), OR

5) If PortalGuard is using a self-signed certificate, you must add it to the certificate store of the Blackboard server’s JDK using keytool. Please see the Blackboard Troubleshooting section below.

18)Ensure the Blackboard server resolves the PortalGuard server name to the expected IP address and can reach it via HTTP.CAS requires that both the end user and “target” server can reach the CAS server.

Confirming Configuration

Accessing Blackboard should display the standard Blackboard login screen.However, there should be a CAS SSO link at bottom of the screen.

Click it to initiate CAS-based Single Sign-On; the user should be redirected to PortalGuard login screen.Providing the correct username and password should result in the user being automatically authenticated into PortalGuard and Blackboard.

Blackboard Troubleshooting

CAS SSO to Blackboard may not work if you deviate from the steps above.Please reference this section if you encounter errors receiving CAS SSO to Blackboard.

Network Connectivity

During CAS authentication, your Blackboard server directly connects to PortalGuard to retrieve user information.As such, the following must be true:

1) The Blackboard server must be able to resolve the PortalGuard server name to an IP address.Use “nslookup” on the Blackboard server to ensure the PortalGuard server name resolves to the expected IP address.

2) HTTP/HTTPS traffic must not be blocked between the PortalGuard and Blackboard servers.Check the firewalls between the servers to ensure the traffic is not being blocked.

If network connectivity is a problem for Blackboard, you will most likely see an error message like below but where yourPortalGuard server name is shown instead of cas.pistolstar.com:

Self-Signed SSL Certificate on PortalGuard

If you specified a HTTPS URL for the CAS Server URL Prefix setting in step #17 above, your Blackboard server will attempt to establish a SSL connection to the PortalGuard web server.This should work without issue if the PortalGuard server is using a certificate issued by a trusted 3rd certificate authority (e.g. Verisign, DigiCert).If PortalGuard is using a self-signed SSL certificate, Blackboard will show an unable to find valid certification path to requested target error:

The workarounds for this issue are either:

1) Change the CAS Server URL Prefix setting in the Blackboard CAS configuration to use standard HTTP.No passwords are sent over this server-to-server connection so this may be an acceptable approach for you.

2) Update the Blackboard server’s JDK keystore file to include the self-signed certificate and any/all intermediate certificates.The keystore path is typically in the bbconfig.appserver.keystore.filename variable in bb-config.properties. If you update the keystore yourself, you must run PushConfigUpdates for them to take effect (link).Please see Blackboard: CAS Authentication Provider Type and Web Services for SSL for more details or contact Blackboard or your Blackboard hosting provider for help.

Change Blackboard Default Authentication Provider

It is generally a best practice to have CAS SSO start when users access Blackboard initially.This reduces logon steps for the large majority of users and eliminates confusion and potential help desk calls.It is also a best practice to establish a URL for administrative/manual login to Blackboard to ensure administrators can login to Blackboard regardless of the CAS server’s availability. NOTE: This step should only be done after you have sufficiently verified CAS SSO through PortalGuard is working.

To change the default authentication type in Blackboard, perform the following steps:

1) Log into the Blackboard server and click the System Admin tab

2) In the Building Blocks section, click the Authentication item

3) Determine your primary authentication provider. It could be named “Default” if you’re using Blackboard’s built-in user repository or “LDAP” if you configured Blackboard to authenticate against an external LDAP directory like Active Directory.

4) Click the arrow that appears next to the authentication provider and choose “Edit” from the pop-up menu

5) For the Restrict by hostname tab, choose the “Restrict this provider to only the specified hostname”. In the Restricted Hostnames field, enter the host name administrators will begin using to perform manual logins to Blackboard.This hostname/alias must be in DNS for it to resolve to the Blackboard server.

6) Click Submit to save the change.

7) IMPORTANT: Leave the administrator logged into Blackboard through the current browser session and try accessing Blackboard through the “standard” and “admin-only” server names to ensure they work as expected.If they do not, then simply edit the default authentication provider, set it back to Use this provider for any hostnames, save the change and contact either Blackboard or PortalGuard support for assistance.