PAL SAML Login and POI Configuration

1 About SAML Login and Proof of Identity Configuration

The ATIPXpress PAL SAML Login and Proof of Identity Configuration manual was created to assist administrators when configuring the SAML Login and Proof of Identity Verification features. This document provides information on how to complete PAL SAML Configuration, as well as Proof of Identity Configuration, and using the PAL SAML Configuration to create a PFX Certificate.  

The Public Access Link (PAL) works with forms authentication by default, however if an agency needs to enable Security Assertion Markup Language (SAML) Authentication for requester login, the system can be configured with your identity provider details following the directions in this section. PAL can also be configured to provide Proof of Identity verification with identity providers such as Login.gov.  

NOTE: The Assertion Consumer URL for PAL Requester Login and Proof of Identity are different. Consult step 5 in the PAL SAML Configuration Tool section of this document for additional information.  

Ensure you have the Personal Exchange Format (PFX) file and its public key ready as well. You will need to provide the PFX file in PAL SAML Configuration, and the corresponding public key in the IDP app/account. Consult the Create PFX Certificate section for information on how to get the PFX Certificate file and its public key.

2 Enable PAL Requester Login Using SAML SSO

Follow the steps below to enable PAL requester login using SAML authentication:

NOTE: To configure the SAML SSO from PAL Configuration, the PAL configuration application must have permission to the PAL application folder with full control. If this is not applicable, use the PAL SAML Configuration Tool (Section 4.5).

1. Log in to PAL Configuration, and access Authentication in the left-hand menu.

2. Select the SAML SSO radio button:

3. First select the Purpose of SAML Configuration (Sign In or Proof of Identity).

4. Enter the Service Provider details as outlined below:

NOTE: This is case-sensitive. This PFX file should correspond to the public key you uploaded in your Identity Provider account. If you are using a different public key in your Identity Provider account, extract the public key form this PFX file and replace your public key in the Identity Provider account with this public key.

5. Next, enter the Identity Provider details:

NOTE: These will be different for test and production. Some IDPs do not support single logout, and it won’t be provided. If SLO is not supported, you should leave the SLO URL and SLO Binding fields blank. For some IDPs, SAML SSO URL and SAML SLO URL must be updated each year, approximately quarterly.

6. Once that is complete, fill in the Certificates field, as shown below and detailed in the following table:

NOTE: For some IDPs the x509 certificate text has to be updated each year and a reminder that the sandbox and production certificates may not be the same.  

7. The five checkboxes (Sign Authentication Request, Want SMAL Response Signed, Want Assertion Signed, Want Assertion Encrypted, Encrypt Logout Name ID) should remain unchecked, which is the default setting. If ID Provider provides single logout service, then the Single Logout Request and Single Logout Response checkboxes must be checked.

8. When all fields are complete, move on to the SAML Field Mapping section. Here, you can add or delete the fields based on what attributes/return value you have selected for your IDP entity app settings. The First Name, Last Name, Email, and Login fields are mandatory and cannot be removed. All three fields (Provider Field, PAL Field, and Description) are required while adding a new SAML Field in Mappings.

NOTE: The provider fields for both ‘Email’ and ‘Login’ PAL Fields are the same.  

NOTE: For Social Security number, the field will be masked only if the PAL Field is named ‘SSN’, ‘Social Security’, or ‘Social Security Number’.  

9. Once all the required fields are complete, click Save to save the settings.

3 Enable Proof of Identity Verification in PAL

Review the following identity provider prerequisites if you are enabling PAL to support proof of identity verification.  

• Configure your IDP entity account(s). You cannot use the same account for PAL login and for Proof of Identity Configuration.  

• Set up your sandbox environment (See your provider’s instructions; some providers allow you to set up the environment while other providers will perform the setup on your behalf

• When enabling Proof of Identity Verification in PAL, you can use either level 1 or level 2 for login, however level 2 is required for Proof of Identity Verification. Ensure that the assertion URL in your Identity Provider Entity settings matches with URL provided in step 5 of the PAL SAML Configuration Tool section.

Follow the steps below to enable proof of identity verification in PAL:

1. Log in to PAL Configuration and select Request Fields in the left-hand menu.

2. Locate the Proof of Identity Mode request field and select Digital Authentication or Upload Attachment/Digital Authentication from the drop-down list within the Default column.

3. Scroll down and click Save.

4 PAL SAML Configuration Tool

Follow the steps below to use the PAL SAML Configuration Tool:

1. Navigate to the PAL Application Server.

2. Search for SAML in the windows search box, then select the tool once located.  

a. Alternatively, navigate to the PAL Setup folder and locate the PAL.WebApp folder and in the bin folder you will find the application file

‘ATIPXpress.Utilities.SamlConfig’

3. Right click SAML Configuration Tool and select Run as administrator.  

4. The SAML Configuration interface appears as shown below. Select either Login or Proof of Identity from the SAML Using For drop-down list:

5. Next, configure the Service Provider information, as shown below and detailed in the following table:

NOTE: This PFX file should correspond to the public key you uploaded in your Identity Provider account. If you are using a different public key in your Identity Provider account, extract the public key form this PFX file and replace your public key in the Identity Provider account with this public key.

NOTE: This PFX file should correspond to the public key you uploaded in your Identity Provider account. If you are using a different public key in your Identity Provider account, extract the public key form this PFX file and replace your public key in the Identity Provider account with this public key.

6. Next, complete the required Identity Provider fields, as shown below and described in the following table:

NOTE: These will be different for test and production. Some IDPs do not support single logout, and it won’t be provided. If SLO is not supported, you should leave the SLO URL and SLO Binding fields blank. For some IDPs, SAML SSO URL and SAML SLO URL must be updated each year, approximately quarterly.

7. Once that is complete, fill in the Certificates field, as shown below and detailed in the following table:

NOTE: For some IDPs the x509 certificate text has to be updated each year and a reminder that the sandbox and production certificates may not be the same.

8. The five checkboxes (Sign Authentication Request, Want SMAL Response Signed, Want Assertion Signed, Want Assertion Encrypted, Encrypt Logout Name ID) should remain unchecked, which is the default setting. If ID Provider provides single logout service, then the Single Logout Request and Single Logout Response checkboxes must be checked.  

9. When all fields are complete, move on to the SAML Field Mapping section. Here, you can add or delete the fields based on what attributes/return value you have selected for your IDP entity app settings. The First Name, Last Name, Email, and Login fields are mandatory and cannot be removed. All three fields (Provider Field, PAL Field, and Description) are required while adding a new SAML Field in Mappings.

NOTE: The provider fields for both ‘Email’ and ‘Login’ PAL Fields are the same.  

NOTE: For Social Security number, the field will be masked only if the PAL Field is named ‘SSN’, ‘Social Security’, or ‘Social Security Number’.  

10. Once all the required fields are complete, click Save to save the settings.

NOTE: If using forms authentication, you’ll need to provide dummy data for the Proof of Identity settings options, even if these settings are not being used.

For login.gov, please visit https://developers.login.gov/ for all details about identity provider fields.  

5 Create PFX Certificate

For first-time setup, follow the steps below to create a PFX certificate file and extract a public key from the PFX file using OpenSSL.

1. Open IIS and click Server.  

2. In the Security section, double click the Server Certificates.

3. In the top right corner, click Create Self-Signed certificate:

4. A pop-up window appears where you can Specify a friendly name for the certificate in the field provided.  

5. Next, select Personal from the Select a certificate store dropdown:

6. Now that the certificate is created, and you can export the certificate into the PAL folder. Go to Manage Computer Certificate (located in the Control Panel or by using the Windows search feature)

7. In the Manage Computer window, click Personal and then click Certificate.

8. From the list of certificates, locate your certificate using the friendly name provided.

9. Right click the Certificate, select All Tasks, and then select Export.

10. In the new pop-up window, click Next to continue.

11. Under Export Private Key, select Yes, export the private key and click Next.

12. Under Export File Format:  

    1. Select Personal Information Exchange (PFX)

    2. Uncheck ‘Delete the private key if the export key if successful.

    3. Check all other options, then click Next.

13. Under Security, check Password, and type the password for your certificate.

NOTE: You will need this password in order to use the certificate i.e., in SAML configuration tool and to extract public key

14. For Encryption, select AES256-SHA256, then click Next.

15. Under File to Export, click Browse and choose your certificate location. We recommend putting the certificate in the PAL folder where your PAL web.config is located.

16. Type in your certificate name and click Next. Once the process is complete, Click Finish.

17. Now you have PFX certificate ready for SAML Service Provider Certificate. Next, we will derive public key from this PFX file. Remember the certificate containing public key, which we upload to login.gov, must be generated from the PFX certificate file that we use in SAML Configuration tool.

18. To create a certificate with public key, install OpenSSL on your computer and then open the command prompt by typing “cmd” in Windows search.

19. Go to you PFX file location (type cd full_path_of_pfx), and type the following command:

openssl pkcs12 -in your_file_name.pfx -clcerts -nokeys -out give_name_for_cert_public_key.crt\

20. When complete, press Enter. The certificate with a public key for login.gov is created.