Problem

You want to integrate PortalGuard with the CCCTech Center SSO Proxy as required by the California Community Colleges Chancellor's Office.

Solution

Download and modify the PortalGuard Relying Party Template for the CCCTech Center SSO Proxy.  This template will act as a starting point for the pilot integration, as recommended by the CCCTech Center. 

Quick Navigation

• Pre-Requisites and Caveats

• Download and Install the Relying Party Template

• Adding Links for Proxy-Integrated Applications

• Sending Different Values for the 'eduPersonAffiliation' Claim When No Such Value Exists in AD

Pre-Requisites and Caveats

Before you can integrate with the CCCTech Center SSO Proxy, you must complete the following Pre-Requisites:

1. Configure PortalGuard for Single Sign-On

   • If you have not already done so, please follow the steps in this KB Article to configure your PortalGuard Server for SSO

2. PortalGuard MUST be externally accessible over HTTPS

3. Your User Repository (Typically Active Directory) MUST have an attribute that contains the 'cccid' value.

   • This value needs to be passed to the SSO Proxy as a SAML Claim and you will not be able to proceed without it being available in your environment. 

4. Provide your PortalGuard Metadata File to the CCCTech Center

   • If you are part of the InCommon Federation, the CCCTech Center will be able to download your Metadata from the Federation. 

   • If you are NOT part of the InCommon Federation, you must provide the CCCTech Center contact with a link to download your PortalGuard Metadata file:

     • The link to download your PortalGuard Metadata file will follow this format: https://[YOUR.PORTALGUARD.URL]/sso/metadata.ashx

5. Schedule a Proxy Integration Kick-Off Meeting with the CCCTech Center Support Team

   • We typically work with Matt Schroeder (mschroeder@ccctechcenter.org)

   • This meeting will inform the CCCTech Center that you are looking to finalize the integration with PortalGuard - this will also allow the Tech Center to prep the Pilot environment so that you can test your integration before going live.  

Download and Install the Relying Party Template

1. Download the 'ProxyPilot.saml.rp.zip' file attached to this article. 

2. Extract the 'ProxyPilot.saml.rp.xml' file to your PortalGuard Server. 

3. On the PortalGuard Server, copy/move the 'ProxyPilot.saml.rp.xml' file to the Program Files\PistolStar\PortalGuard\Policies folder.

4. If the Identity Provider Configuration Editor is open, close it completely and reopen to view the new Configuration entry under the SAML Websites tab.

   • Open

     

5. Edit the 'ProxyPilot' entry by highlighting it and clicking the 'Edit' button.

6. On the General tab, edit the value of the 'Assertion Consumer URL':

   • The URL should end with MIS followed by a 3 digit number specific to your institution. Update this URL to reflect your specific MIS number.

     • You can receive this from the CCCTech Center if you do not already know it. 

7. Navigate to the Identity Claims tab

8. Verify the claims are referencing the correct fields in your User Repository

   • This template assumes the use of Active Directory or a similar LDAP User Repository

   • The value after 'String:' references the LDAP field that will be used to populate this claim:

     • Open

       

   • To change the field, simple highlight the claim and click 'Edit'.  Update the 'Field Name' value as needed:

     • Open

       

9. Take special care to update the 'CCCID' claim to reference the appropriate field in your AD Environment. This is the last claim in the list.

   • As noted in the Pre-Requisites and Caveats section above, this field must contain the CCCID value for all users in your environment. 

10. Take special care to update the 'eduPersonAffiliation' claim to reference the appropriate field in your AD environment.  This claim should return either 'staff' or 'student'.  If you do not have a field in AD that returns one of these two values, please refer to the Sending Different Values for the 'eduPersonAffiliation' Claim When No Such Value Exists in AD section below.

11. Save the Changes to this Configuration. 

12. Click the 'Apply to Identity Provider' button and click 'Sync' to ensure these changes take effect immediately. 

Adding Links for Proxy-Integrated Applications

If you want to create links to Proxy-Integrated applications on your PortalGuard SSO Jump Page, you will need to create new configurations specific to those applications.  For each tile that you wish to create, follow the steps below.

1. On the PortalGuard server, Open the Identity Provider Configuration Editor.

2. On the SAML Websites tab, click the 'Create' button

3. Fill in the following fields accordingly:

   • Name

     • A display name for your application - this will only be seen in the SAML Websites tab to identify the configuration.

   • Description

     • Helpful text for providing more context to whoever may be editing this configuration. 

   • Identifiers

     • Click on the 'Add' button and put it a random - but unique - string. 

     • This MUST NOT be used as an identifier anywhere else, but does NOT need to relate to the application. 

   • Assertion Consumer URL

     • The URL to the Application via the Proxy

     • You can retrieve the appropriate URL from the CCCTech Center team.

4. Navigate to the Identity Claims tab.

5. Click the 'Create' button to create a new claim using bogus information:

   • Open

     

   • This claim is purely to allow PortalGuard to save the configuration.  The information entered here will NOT be sent out. 

6. Navigate to the IdP-Initiated tab.

7. Enter a 'Name' and 'Help Text' for the Tile.

   • The 'Name' value will be the label on the tile as it appears on the SSO Jump page.

   • The 'Help Text' value will be seen if the user hovers over the tile but does not click on it. 

8. Check the box next to 'IdP-Initiated SSO not directly supported by RP'

9. Enter the Proxy-enabled URL for the application.

   • This can be copied/obtained from step #3 above.

10. Save the configuration. 

11. Click the 'Apply to Identity Provider' button and click 'Sync' to ensure these changes take effect immediately. 

12. Login to PortalGuard and navigate to the SSO jump page.  Click on the new tile to test the SSO to the application directly. 

Sending Different Values for the 'eduPersonAffiliation' Claim When No Such Value Exists in AD

1. On the PortalGuard server, open the Identity Provider Configuration Editor.

2. Click on the 'General IdP Settings' button.

3. Navigate to the Response tab.

4. Check the box labeled 'Allow Duplicate SAML/WS-Fed/CAS Identifiers?'

   • Open

     

5. Save these settings. 

6. Edit the 'ProxyPilot' configuration under the SAMLWebsites tab and change the name to 'ProxyPilot-Staff' or something similar.

   • This configuration will return 'staff' as a static value for the 'eduPersonAffiliation' claim.

7. Navigate to the Identity Claims tab.

8. Edit the 'eduPersonAffiliation' claim:

   • Open

     

9. Update the 'Value Type' dropdown to 'Formatted String'.

10. Under the Formatted sub-tab, set the value of the 'Composite Value Format' field to 'staff' (without the quotation marks).

    • Open

      

11. Save these changes to the claim. 

12. Navigate to the Authorization tab.

13. Click on the 'Add' button.

14. Search for a Group, OU, or User that should always have the 'staff' affiliation when authenticating against the CCCTech Center SSO Proxy.

    • You can only add one entry per search, but you can have multiple entries - with any mix of OU, Group, or individual user.

    • IMPORTANT NOTE: There can be no overlap with users that should always have the 'student' affiliation when authenticating against the CCCTech Center SSO Proxy.  The Authorization on both relying parties MUST be distinctly limiting. If a user attempts to authenticate who matches both policies, they will not be able to be able to successfully authenticate to the Proxy. 

      • If you have users that need both 'staff' and 'student' affiliations, a multivalued claim in AD will need to be created and referenced within the relying party. 

15. Navigate to the General tab and double-click the only value present in 'Identifiers'.  Copy the value to your clipboard.

16. Save the Configuration.

17. Under the SAMLWebsites tab of the Identity Provider Configuration Editor, highlight the 'ProxyPilot-Staff' entry and click on the 'Copy' button.

18. Give the new relying party a name of 'ProxyPilot-Students'. 

19. Next to 'Identifiers' click the 'Add' button and paste in the value copied from step #15 above.

20. Navigate to the Identity Claims tab and edit the 'eduPersonAffiliation' claim. 

21. Change the value of the 'Composite Value Format' field to 'student' (without the quotation marks).

22. Navigate to the Authorization tab and add the Groups, OUs, or individual users that should always have the 'student' affiliation when authenticating against the CCCTech Center SSO Proxy. 

    • Pay special attention to the IMPORTANT NOTE above, as the same conditions apply here. 

23. Save the configuration. 

    • If you see a popup with a title of 'Duplicate Entry' when attempting to save, that means you have not configured your Authorization tab properly.  Please review and save. 

24. Click on the 'Apply to Identity Provider' button and then 'Sync' on the next screen to ensure these changes take effect immediately.