Problem

You want to integrate Blackboard with your PortalGuard Identity Provider to Provide SAML Single Sign-On.  

Solution

Create a new SAML Relying Party within the Identity Provider Configuration Editor and make the necessary changes within the Blackboard Management Website.

Quick Navigation

Configuration - Blackboard Management Website

Configuration - PortalGuard Server

Configuration - Blackboard Management Website

1. Navigate to the Blackboard Management Website and login to Blackboard using a full admin account. 

2. For On-Premises Blackboard Instances - Provision the built-in SAML authentication building block.

   • Follow the steps listed in the Activate the SAML Building Block -AND- Configure building block settings sections listed in Blackboard's SAML Authentication Provider Type help page.

• Important Note: This is NOT required for SaaS instances of Blackboard.

1. Navigate to the 'System Admin' menu and choose the 'Authentication' item in the Building Blocks menu.

2. On the 'Authentication' page, click the 'Create Provider' button and choose the SAML option.

3. Enter a 'Name' for the provider (i.e. 'PortalGuard SAML').

4. Set the 'Authentication Provider Availability' to 'Active'.

5. Set the 'User Lookup Method' to 'Username'.

6. Update the 'Link Text' field to utilize whatever text you wish the link to display on the Blackboard login page (i.e. SAML SSO).

7. Click the 'Save and Configure' button. 

8. Once in the 'Service Provider Settings' section, update the information as follows:

   • 'Entity ID'

     • Enter a value that describes this Blackboard Environment (i.e. 'BBProd' or 'BBTest') - you will need this for the PortalGuard configuration. 

   • 'Enable Automatic SSO'

     • Check this box.  This is required to allow IdP-Initiated SSO (by clicking the tile on the PortalGuard Single Sign-On Jump Page.

       • Note: Checking this box will automatically cause a slight update to the 'ACS URL' value displayed on this screen. 

   • 'Single Logout Service Type'

     • Ensure that only 'Redirect' is checked. 

   • 'Service Provider Metadata'

     • Click the 'Generate' button.  Save the resulting XML file to the PortalGuard server. 

   • 'Data Sources'

     • For this dropdown, choose the primary 'Data Source' that contains users in Blackboard (i.e. 'SYSTEM').

   • 'Compatible Data Sources'

     • Check ALL 'Data Sources' that contain user accounts in Blackboard.  To determine the actual values, do the following:

       • Open a new Browser tab and navigate to the Blackboard Admin page.  

       • Click 'Users' in the upper-left corner to navigate to the 'Users' page. 

       • Search for users to see different 'Data Source Key' values.  These are the values that should be checked in the 'Compatible Data Sources' list. 

9. Below the 'Service Provider Settings' section will be the 'Identity Provider Settings' section.  Update the information as follows:

   • 'Identity Provider Type'

     • Choose 'Point Identity Provider'

   • 'Metadata Type'

     • Choose 'Metadata File'

       • Access the following URL in a new tab/browser to download your PortalGuard metadata (replace 'YOUR.PG.SERVER' with the PortalGuard server hostname:

         • https://YOUR.PG.SERVER/sso/metadata.ashx

       • Save the file and rename it from 'metadata.ashx' to 'PG-metadata.xml'

     • Click on the 'Browse' button and select the 'PG-metadata.xml' file that you just saved and upload it. 

       • If metadata has already been uploaded, you will see a link that says 'Replace Metadata' instead.  Click that for the same effect. 

10. Within the 'Map SAML Attributes' section, update 'Remote User ID' by choosing the 'NameID' radio button.  Leave all other fields untouched. 

11. Click on the 'Submit' button at the bottom of the page to save the changes. 

12. In the Authentication Providers list, toggle the 'PortalGuard SAML' provider to 'Inactive' and then back to 'Active' to ensure the uploaded metadata takes effect. 

13. Important Note: Every time the PortalGuard IdP's metadata changes, you must follow steps 11-14 for the changes to take effect. 

Configuration - PortalGuard Server

1. Navigate to the PortalGuard server and open the Identity Provider Configuration Editor.

2. Click on the 'General IdP Settings' button and navigate to the SAML SLO tab.

3. Check the 'Enable SAML Single Log Out (SLO)' box is checked.

   1. Open

      

4. Save the changes.

5. Navigate to the SAML Websites tab and click on the 'Create' button to create a new Relying Party Configuration.

6. Give the new Relying Party a 'Name' and 'Description' that makes sense for this application (i.e. Blackboard SAML, etc.).

7. Next to 'Identifiers' click on the 'Add' button.

8. You will need to add an identifier here that matches what was set in step #10 of the Configuration - Blackboard Management Website section above:

   • i.e. BBProd

     • This will also be in the Blackboard Metadata file generated in step #10.  Opening this file will show the 'entityID' - the value of which should be entered as the 'Identifier' here.

9. For the 'Assertion Consumer URL', you will need to search through the metadata file generated in step#10 above.  Search for the first occurrence of 'AssertionConsumerService' and use the value in the subsequent 'Location' attribute. 

   • The typical format resembles: https://YOUR.BB.SERVER/auth-saml/saml/SSO/alias/_8_1

10. Your final result should resemble the following:

    1. Open

       

11. Navigate to the Identity Claims tab.

12. Ensure the correct 'Attribute Store' is selected. If you have multiple attribute stores, choose one as the Default and ensure 'Dynamically Determine Attribute Store' is checked.

    • This value will determine where user information is pulled from during SSO Authentication.

13. Click the 'Create' button to add a new Identity Claim to this Relying Party configuration using the following settings:

    • 'Name'

      • NameID

    • 'Send As NameID?'

      • Check the box

    • 'Schema Type'

      • urn:oasis:names:tc:SAML:2.0:nameid-format:email

        • this value can be chosen from the dropdown after clicking the 'Pre-defined Types...' button

    • 'Value Type'

      • String Field

    • 'Field Name'

      • sAMAccountName

    • 'Value Index'

      • 0

14. The final result for the first claim should resemble the following:

    1. Open

       

15. Click the 'Create' button to add a new Identity Claim to this Relying Party configuration using the following settings:

    • 'Name'

      • sAMAccountName

    • 'Send as NameID?'

      • Ensure this box is not checked

    • 'Schema Type'

      • sAMAccountName

    • 'Value Type'

      • String Field

    • 'Field Name'

      • sAMAccountName

    • 'Value Index'

      • 0

16. The final result for the second claim should resemble the following:

    • Open

      

17. When Completed, the Identity Claims tab should resemble the following:

    • Open

      

18. Navigate to the IdP-Initiated tab and configure the settings as follows:

    • 'Display Text'

      • Enter a label for the SSO Tile on the PortalGuard SSO Jump Page

      • i.e. Blackboard

    • 'Help Text'

      • The description end-users will see when mousing over the tile on the SSO Jump Page

      • i.e. Classes and Assignments

    • 'Display Image'

      • In the inetpub\PortalGuard\sso\img folder, browse to the 'blackboard.jpg' file if available, otherwise choose the 'default.jpg' file. 

      • You may also upload your own 100x100 image and place it in that folder for use. 

19. The final result should resemble the following:

    • Open

      

20. Navigate to the Single Log Out tab and configure it as follows:

    • 'Service Provider Supports the SAML SLO protocol'

      • Check this box.

    • 'Redirect Endpoint'

      • Search the Blackboard metadata file for the first occurrence of 'SingleLogoutService' and enter the value in the subsequent 'Location' attribute. 

        • This URL typically uses the following format: https://YOUR.BB.SERVER/auth-saml/saml/SingleLogout

    • 'Signing Cert File'

      • Search the Blackboard metadata file for the first occurrence of 'ds:X509Certificate'.  The preceding 'KeyDescriptor' element should show 'use="signing"'

      • Copy all text from inside the 'X509Certificate' element.  It typically starts with 'MII...' and ends with an '='

      • Paste the copied text into a new file in a text editor and save it to C:\Program Files\PistolStar\PortalGuard as 'BBSLO.cer'

        • Important Note: The contents of this file should all be on a single line and will be between 1000 and 2000 bytes in length. 

      • In the Identity Provider Configuration Editor, click on the 'Browse' button and choose the 'BBSLO.cer' file

21. The final result should resemble the following:

    • Open

      

22. Click the 'Save' button to save these changes. 

23. Click on the red 'Apply to Identity Provider' button and then click 'sync' to ensure these changes take effect. 

24. In an administrative text editor browse to inetpub\PortalGuard and edit the 'web.config' file.

25. Search the file for '' and add the Blackboard Server URL as a new line within this element:

    • Open

      

26. Save the changes to this file.