FOIAXpress SAML SSO Configuration

Overview

The Sign On Mode dialog in FOIAXpress allows system administrators to integrate FOIAXpress with an external Identity Provider (IdP) that supports the Security Assertion Markup Language (SAML) 2.0 protocol.

When SAML SSO is active, FOIAXpress delegates user authentication to the configured IdP — such as Active Directory Federation Services (ADFS), Microsoft Entra ID (formerly Azure Active Directory), Okta, PingFederate, or any other SAML 2.0-compliant provider — instead of using local FOIAXpress credentials.

Regardless of the Identity Provider, the steps to configure Sign On Mode on FOIAXpress remain the same.

NOTE: When SAML SSO is selected as the Sign On Mode, all required fields in the Service Provider, Identity Provider, and IDP Certificate steps must be populated. An incomplete configuration cannot be saved. Additionally, changing the Sign On Mode terminates active sessions. It is recommended to plan this operation during a scheduled maintenance window or outside peak business hours to minimize disruption.

Prerequisites

1. Before you access the Sign On Mode dialog, the FOIAXpress administrator must obtain the following values from the IdP administrator. The table below maps each required value to the FOIAXpress field it populates.

2. Ensure that you using version 11.7.2 or above. If not, you must Update Assertion URL.

3. Obtain the metadata XML file from your IdP administrator where one is available; FOIAXpress populates every Identity Provider and IDP Certificate field whose value is present in the file

PRO TIP: Enable Customer Enabled Support Admin before proceeding with the SSO configuration, so you have Casepoint assistance readily available.

Configuration Checklist

Confirm that each of the following items is complete before proceeding to the configuration steps.

1. Issuer for FOIAXpress has been determined and registered in the IdP (for example, https://myDns/FOIAXpress, or a unique name such as casepointFOIAXpressProd).

2. Assertion Service URL (https://<<DNS>>/FOIAXpress/AssertionConsumerService.aspx) has been registered in the IdP.

3. IdP Entity ID / Issuer URL has been copied exactly as it appears in the IdP configuration.

4. IdP SAML SSO URL has been copied and confirmed reachable from the FOIAXpress server network.

5. Identity Provider Certificate has been exported as a Base64-encoded .cer file. (See Retrieve a .cer File via the Certificate Management Console.)

6. IdP Logout (SLO) URL has been copied (if single logout will be used).

7. If the IdP requires signed authentication requests: an SP signing certificate (.pfx) and its password have been prepared.

8. If the IdP requires encrypted assertions: an SP encryption certificate (.pfx) and its password have been prepared.

9. A maintenance window has been scheduled. Changing the Sign On Mode terminates active sessions.

10. At least one local FOIAXpress administrator account with a known password exists and is documented securely as a break-glass account.

11. A decision has been made on whether your IdP team will import the Service Provider metadata XML file, which you can download from the Service Provider step, or configure the values manually.

Accessing the Sign On Mode

The Sign On Mode dialog is available in the FOIAXpress application.

To access the dialog:

1. Sign in to FOIAXpress with an Admin role.

2. Navigate to Administration.

3. Select Security and select Sign On Mode.

The Sign On Mode page allows you to configure how you authenticate into FOIAXpress. When enabled, SAML-based Single Sign-On (SSO) lets you sign in using your organization’s identity provider instead of a separate FOIAXpress account. This configuration typically requires coordination with your IT or identity management team.

The Sign On Mode drop-down menu offers two options — Forms and SAML SSO — which display different fields, described in the sections below.

Forms Authentication

• Select Forms to have users sign in with a FOIAXpress user name and password instead of an identity provider. Forms mode displays a single additional field:

There are no other fields to complete. Click Save to apply the change.

SAML SSO Configuration

Selecting SAML as the Sign On Mode

• Select SAML SSO from the Sign On Mode drop-down menu.

Selecting SAML SSO displays the SAML SSO Configuration wizard. A step indicator guides you through three steps: Service Provider, Identity Provider, and Review & Save.

   • Click Next to move forward and Back to return to the previous step.

   • Click a numbered step in the indicator to jump straight to that step.

   • Required fields are marked with a red asterisk.

   • Each panel has its own collapsible Advanced Settings section. Click the heading to expand or collapse it.

Update Assertion URL

Follow the steps in this section to update Assertion URL in FX. This is required when upgrading to from any version below 11.7.2.

NOTE: If the application is already on 11.7.2 or up, an assertion URL update is not required

1. The customer must first obtain and provide their Identity Provider Metadata from their identity provider. This will be provided as either an XML file or URL.

2. Next, we’ll confirm or update the Identity Provider Certificate in SAML Configuration. This must be confirmed otherwise, SAML authentication will fail. Open the provided metadata file and locate for the signing cert in x.509 format, as highlighted below:

3. You’ll use this value to create a certificate. Follow these steps:

1. Copy the full text following <X509Certificate> (highlighted in yellow below):

2. Open Notepad, then paste the copied Certificate text into a new Notepad document.

3. Paste the following at the beginning then hit Enter to add a line break:

-----BEGIN CERTIFICATE-----

4. Add another line break at the end, then paste the following on the new line:

-----END CERTIFICATE-----

5. It should look like the example below. Save the file with a .cer file extension

4. Save the .cer file in a location that is accessible by the FX application.

5. Open the FOIAXpress Database Configuration tool, select the Sign-On Mode tab, then paste the file name (if placed within the application folder) or full path in the Partner Certificate File field:

6. Update the Assertion Service URL. If you are upgrading from version 11.5.4 or under, you need to update the assertion URL after upgrade. See Section 1.2.1 in the v11.7.0 Release Notes for details.

7. You must request that the customer’s SAML ID provider update the assertion URL on their end. The ID provider team can update the assertion URL on their end during or after an upgrade.

NOTE: If you see the following error message, it is likely due to an incorrect identity provider’s certificate.

Service Provider Metadata File

Generate Service Provider Metadata File

Follow the steps below to generate the FX Service Provider Metadata file:

1. First, have the pfx file ready (as used in the previous section).

2. Get the public key (.cer file) from pfx in base64 format (you can use OpenSSL, or do it from Certificate Management Console using the steps in the next section)

3. If you are preparing metadata for an existing configuration, then you will need to collect the following details from your current configuration:

   1. Assertion URL (if you upgrading from v11.5.4 or earlier, then the assertion URL has changed)

   2. Service Provider Name (first text field)

   3. Want Authentication Request Signed (checkbox)

   4. Want Assertion Signed (checkbox)

4. Go to the SAML Service Provider (SP) Metadata XML Builder and provide your information to generate an XML file.

5. Provide the generated XML file to your Identity Provider.

Retrieve .cer via Certificate Management Console

Follow these steps to retrieve a .cer file from pfx through the Certificate Management Console:

NOTE: This requires that the pfx is installed in the system.

1. Go to Certificate Management Console

2. Select the cert (pfx) then right click and select All Tasks > Export.

3. Select Public key only (no private key).

4. Select Base 64 format.