Problem

You want to integrate an application with your PG IDaaS Identity Provider using the SAML protocol.

Requirements

1. Access to the PG IDaaS Admin Panel

2. Metadata from the Service Provider (the application that you are integrating with)

3. Required Claims for the Service Provider

   • Either from SAML Configuration Documentation OR from the Service Provider Support Contact

Solution

The following steps outline how to configure a standard SAML Relying Party within the PG IDaaS Identity Provider. Some areas of the configuration are skipped in these steps as they have specific applications that do not typically apply. Please see Appendix B - Atypical SAML SSO Configurations for more details.

1. Within the PG IDaaS Admin Panel, navigate to the Single Sign On section using the left-hand navigation bar and click on the ‘New SAML’ button in the upper-left hand corner of the screen:
   
   

   Open

   

2. Each configuration is broken up into sections within the configuration, organized in a configuration specific navigation bar on the left hand. You’ll begin on the ‘General’ page.

3. On the 'General' page, update the configuration as follows:

   1. Name

      1. A Name for the configuration. This will only appear throughout the Admin Panel configurations and within the PG IDaaS Logging.

   2. Description

      1. A description to further explain the configuration. This is only visible within the PG IDaaS Admin Panel.

   3. Enabled

      1. Whether or not the SSO Configuration will be usable.

   4. Identifiers

      1. The unique ‘entityID’ for the Service Provider being configured. This will come from the Service Provider Metadata or otherwise from the SP SSO documentation.

         1. Within the metadata, the proper value is stored in the ‘entityID’ attribute. In the screenshot below, the 'entityID' is 'https://saml.istation.com'
            
            

            Open

            

             

         2. Multiple Identifiers can be provided as needed.

   5. Assertion Consumer URL

      1. This is the destination of the SAMLResponse generated by the Identity Provider. This will come from the Service Provider metadata or otherwise from the SP documentation.

         1. Within the metadata, the proper value is stored in the ‘location’ attribute of the AssertionConsumerService' element. If multiple elements are present, you should select the value of the ‘location’ attribute with a ‘binding’ set to: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
            
            

   6. Use ACS From SAMLRequest

      1. This should be left disabled by default unless you are not sure of the ACS.

      2. This setting will attempt to parse the ACS URL from the incoming SAMLRequest.

         1. This requires the SP-Initiated SSO flow AND the ACS to be present within the incoming request, which is not always the case.

4. Navigate to the 'Identity Claims' page and configure as follows:

   1. Attribute Store

      1. This should be set to ‘sql’ unless using Azure Active Directory.

   2. Dynamically Determine Attribute Store

      1. This should always be disabled as PG IDaaS utilizes a single Repository.

   3. IdP Signing Certificate

      1. Set to ‘--Default--’ unless a custom signing cert was generated for this integration.

   4. Identity Claims

      1. Configured based on the required claims for this particular Service Provider.

      2. While the specific claims will be defined by the Service Provider, the claims will be configured using the guidelines noted in Appendix A - Configuring SSO Claims within PG IDaaS.

5. Navigate to the 'IdP-Initiated' page and configure as follows:

   1. Display Text

      1. The label for the SSO Tile seen on the SSO Jump Page for your PG IDaaS website.

      2. Visible to your users.

   2. Help Text

      1. Visible to your users when hovering over the SSO Tile.

   3. Display Image

      1. The thumbnail icon used for the SSO Tile.

         1. This must be a relative path.

            1. e.g.: img\default.jpg

         2. The image itself must be uploaded by Technical Support.

            1. Please submit a Technical Support Ticket with the icon to ensure it is uploaded.

   4. Hide on SSO Jump Page

      1. This setting should be disabled unless you want to enforce SP-Initiated SSO.

   5. IdP-Initiated SSO not directly supported by RP

      1. If the Service Provider must initiate SSO, but you still wish to use the SSO Jump Page, this option should be enabled.

         1. This setting requires the configuration of the following ‘Default URL’.

   6. Default URL

      1. When IdP-Initated SSO is not supported by the Service Provider, this setting must be configured to redirect to the specific endpoint the Service Provider users to initiate SSO.

6. Navigate to the 'Authorization' page and configure as follows:

   1. Require Multi-Factor Authentication for site access

      1. Only enabled if you are looking to require MFA for access to specific apps.

   2. Authorized users

      1. By default, the Relying Party will be accessible to anyone who can authenticate via PortalGuard.  If you would like to restrict access, simply click the 'Add' button here and search for a User, Group, or OU.

      2. As soon as an entry is defined here, only users that match the entries on the 'Authorization' page will be allowed to access the Relying Party via SAML.

7. Save the Relying Party Configuration.

Appendix A - Configuring SSO Claims within PG IDaaS

PG IDaaS Identity Claims should be configured using the guidelines below unless otherwise instructed. The use of the pre-defined placeholders reduces the requirements of understanding how to properly format the SQL query for commonly used configurations.

1. Name: Internal name of the claim.

   1. This is not visible to the user or used in generating the SAMLResponse in any way.

2. Send as NameID?: Check only if this claim should be a NameID.

   1. Only one claim can be defined as a NameID. This will move the value to the ‘Subject’ of the SAMLResponse instead of the ‘Attributes’ section.

3. Schema Type: The resultant ‘name' value of the xml attribute.

   1. Pre-defined options are available, though most Service Providers will provided the expected ‘name’ for mapping.

4. Value Type: Formatted String

   1. This allows for the use of placeholders and ‘simplified’ claims.

5. Convert Case: (No Change)

   1. Update as needed if the Service Provider expects the attributes to come over in a specific case format.

6. Composite Value Format: Use a bracketed placeholder as defined in the following KB:

   1. https://bio-key.atlassian.net/servicedesk/customer/portal/1/topic/01bdf082-54bf-44af-bba0-5de7066e9008/article/355467265

      1. The placeholders can also be selected from a dropdown after clicking the ‘Add Placeholder’ button.

Appendix B - Atypical SAML SSO Configurations

Three sections within the SAML SSO Configuration are considered atypical due to how infrequent changes must be made. However, specific requirements may involve updating these tabs, as outlined below.