Overview
The SAML SSO Configuration page provides system administrators with the means to integrate eCase with an external Identity Provider (IdP) that supports the Security Assertion Markup Language (SAML) 2.0 protocol.
When this integration is active, eCase delegates all 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.
eCase has two independent Service Providers (SPs), each of which requires its own dedicated configuration on this page:
Service Provider | Purpose |
|---|---|
User Application | The primary eCase case management web application, used by the end users. The Assertion Consumer Service (ACS) endpoint for this SP is /Saml.aspx on the User Application host. |
Admin Application | The eCase Administration console, used exclusively by system administrators to manage platform configuration. The ACS endpoint for this SP is /Saml.aspx on the Admin Application host. |
NOTE: When the Enable SAML SSO toggle is turned on, both the User Application and the Admin Application sections require fully populated required fields. Leaving either section incomplete will prevent the configuration from being saved.
NOTE: Enabling or disabling SAML SSO terminates all active sessions immediately. The moment the configuration is saved with a change to the Enable SAML SSO toggle state, all authenticated sessions, including the session belonging to the administrator who performed the save are invalidated. Plan this operation during a scheduled maintenance window or outside peak business hours to minimize disruption.
Prerequisites
The following prerequisites shall be satisfied prior to initiating the SAML SSO configuration in eCase.
Before accessing the SAML SSO Configuration page, the administrator shall obtain the following values from the Identity Provider (IdP) administrator. The table below maps each required value to the corresponding eCase configuration field it populates.
Required Value | Alternate Identifier | eCase Field |
|---|---|---|
SP Entity ID / Issuer | Audience URI; Relying Party Identifier; SP Issuer | Service Provider (User Application and Admin Application sections) |
IdP Entity ID / Issuer URL | Federation Service Identifier; Azure AD Identifier; Issuer | Partner Identity Provider |
SSO Service URL | SAML Single Sign-On Endpoint; IdP-Initiated SSO URL; Login URL | Partner Service URL |
IdP Signing Certificate | Token-signing certificate; Federation certificate (public key) | Partner Certificate File (.cer / .crt / .pem) |
SLO / Logout URL | Single Logout Service URL; SAML Logout endpoint | Logout URL |
Name ID Format (optional) | NameIDFormat URN — e.g., urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress | Name ID Format (leave blank to use IdP default) |
NOTE: Two SP registrations are typically required in the IdP; one for the User Application and one for the Admin Application, each with a distinct Entity ID (Issuer). The IdP SSO URL, signing certificate, and logout URL are usually shared across both registrations.
Configuration Checklist
It is important to confirm that each of the following items has been completed before proceeding to the configuration steps:
SP Entity ID for the User Application has been determined and registered in the IdP (e.g., https://ecase.agency.gov).
SP Entity ID for the Admin Application has been determined and registered in the IdP (e.g., https://ecaseadmin.agency.gov). This value must differ from the User Application Entity ID.
IdP Entity ID / Issuer URL has been copied exactly as it appears in the IdP configuration.
IdP SSO Service URL has been copied and confirmed reachable from the eCase server network.
IdP Signing Certificate has been exported as a .cer, .crt, or .pem file. File size must not exceed 5 MB.
IdP Logout (SLO) URL has been copied.
Both SP entries (User Application and Admin Application) have been registered in the IdP with their respective ACS URLs pointing to the correct /Saml.aspx endpoint on each application host.
If request signing is required by the IdP: an SP signing certificate has been exported as a .pfx file with a known password.
A maintenance window has been scheduled. Toggling the Enable SAML SSO switch, in either direction, will immediately terminate all active user sessions.
Accessing SAML SSO Configuration
The SAML SSO Configuration page is available in the Admin Web Application.
To access the configuration page, log in to the eCase Admin application and navigate to System Configuration. Select SAML SSO Configuration to manage the SAML SSO Settings. Only users with appropriate administrative permissions can access and manage this page.
Enable SAML SSO
At the top of the SAML SSO Configuration page, an Enable SAML SSO toggle is available. By default, the toggle is disabled and field validation is not enforced.
Field | Description |
|---|---|
Enable SAML SSO | Activates or deactivates SAML SSO for the entire eCase platform. When ON, all user authentication is delegated to the configured Identity Provider and eCase's built-in credential-based login is suspended. When OFF, eCase reverts to its standard username-and-password login mechanism. Changing the state of this toggle triggers immediate termination of all active user sessions on save. |
When the toggle is ON, SAML SSO is enabled, and all the configuration fields become mandatory.
Proceed with filling out the details in the User Application and Admin Application section.
The User Application and the Admin Application section allows for separate SAML configuration for administrative access.
The following fields are required when SAML SSO is enabled:
Field | Description |
|---|---|
Service Provider | Enter the Entity ID (Issuer) that uniquely identifies the eCase User Application as a service provider within your IdP. This is the value that was registered in the IdP during setup. Example: https://ecase.agency.gov. This value is case-sensitive and must match the Audience URI / Relying Party Identifier configured in your IdP exactly, character for character. |
Partner Identity Provider | Enter your IdP's Entity ID or Issuer URL — the globally unique identifier that the IdP uses to identify itself in SAML messages. ADFS Example: http://adfs.agency.gov/adfs/services/trust. Entra ID Example: https://sts.windows.net/<tenant-id>/. This value must match the Issuer element that appears in the SAML responses your IdP sends. Any mismatch will cause eCase to reject the assertion. |
Partner Service URL | Enter your IdP's SAML Single Sign-On Service URL — the endpoint to which eCase will redirect users' browsers when initiating an authentication request. This URL must begin with https:// or http://. Use the Test button located adjacent to this field to verify that the eCase server can reach the IdP endpoint over the network before saving. A successful test confirms HTTP reachability only; the full SAML exchange is validated at first login. |
Partner Certificate File | Provide the IdP's token-signing certificate (public key component only). eCase employs this certificate to verify the digital signatures applied to SAML assertions and responses received from the IdP. Accepted File Formats: .cer, .crt, .pem. Maximum File Size: 5 MB. The filename of the currently uploaded certificate is displayed in the read-only text field adjacent to the upload control. Select the X icon to remove and replace an existing certificate file. |
Signature Certificate | Provide eCase's SP signing certificate in .pfx format if the IdP requires eCase to apply digital signatures to outbound SAML AuthnRequests or Single Logout (SLO) requests. This file must contain both the private key and the certificate chain. Accepted File Format: .pfx only. If this field remains unpopulated, eCase will not apply digital signatures to outbound SAML requests, and the Signature Certificate Password field will not be required. |
Signature Certificate Password | Enter the password that secures the .pfx file provided in the Signature Certificate field. This field is required if and only if a Signature Certificate has been provided. The password is validated against the .pfx file at the time the configuration is saved. |
Name ID Format | Enter the SAML NameIDFormat value to request from the IdP. If this field remains unpopulated, eCase will not specify a format preference, and the IdP will apply its default. Enter the full URN if the IdP requires a specific format. Common Values: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress — for email address-based identity; urn:oasis:names:tc:SAML:2.0:nameid-format:persistent — for persistent, opaque identifiers; urn:oasis:names:tc:SAML:2.0:nameid-format:transient — for transient, session-scoped identifiers. |
Logout URL | Enter your IdP's Single Logout (SLO) service URL; the endpoint to which eCase will redirect users after they sign out, so that the IdP session is also terminated. This ensures users are fully logged out from both eCase and the IdP. This URL must begin with https:// or http://. |
PRO TIP: Select the Test button adjacent to the Partner Service URL field to confirm network connectivity between the eCase server and the IdP prior to saving. If the test returns an error, review firewall rules, proxy configurations, and DNS resolution for the IdP hostname. The configuration shall not be saved until the connectivity test completes successfully.
Configure the Admin Application Service Provider
The Admin Application section configures SAML SSO for the eCase administration console. The fields in this section are identical in name, purpose, and validation behavior to those described above for the User Application.
Key Differences from User Application Configuration
Although the field set is identical, the following distinctions apply when configuring Admin Application:
The Service Provider (Entity ID) must be different from the User Application Entity ID. The IdP treats each SP Entity ID as a distinct registered application. Assigning the same Entity ID to both the User Application and the Admin Application will prevent the IdP from distinguishing between them, resulting in incorrect attribute mappings and potential authentication failures.
Example: User Application Entity ID: https://ecase.agency.gov | Admin Application Entity ID: https://ecaseadmin.agency.gov.
The IdP SSO URL, signing certificate, and logout URL are typically the same as those used for the User Application, as both applications authenticate against the same IdP instance.
The Admin Application ACS URL (Assertion Consumer Service URL) must be registered separately in your IdP, pointing to the /Saml.aspx endpoint on the Admin Application host. This is the URL your IdP will redirect users to after a successful admin authentication.
NOTE: Please ensure that the Admin Application is registered as a separate SP in your IdP. If the Admin Application SP registration is omitted from the IdP, administrators will be locked out of the eCase Admin Application when SAML SSO is enabled. Verify that both the User Application and Admin Application SP entries are fully registered and functioning in your IdP before activating SSO.
Configure No-PIV / Two-Factor Authentication
This section governs the configuration of a secondary authentication factor for users who are unable to authenticate using a PIV (Personal Identity Verification) card or CAC (Common Access Card). This configuration operates independently of the SAML SSO toggle; the secondary authentication factor may be enabled regardless of whether SAML SSO is active.
When SAML SSO is enabled, this section is labeled as No-PIV Configuration. When SAML SSO is disabled, this section is labeled Two-Factor Authentication Configuration. The fields and behavior are identical in both states.
Field | Description |
|---|---|
Enable Two-Factor Authentication | Master toggle for the secondary authentication factor. When this toggle is disabled (unchecked), two-factor authentication is turned off for all users, and all subordinate fields in this section are hidden. When enabled, users will be required to complete a secondary verification step after their primary authentication credential has been accepted. |
Verification Mode
When two-factor authentication is enabled, the administrator must select one of the following verification modes. Each mode exposes an additional field specific to its configuration requirements.
Client Certificate (PIV / CAC)
When this mode is selected, users are required to present a valid smart card - PIV or CAC — certificate as their second authentication factor.
Field | Description |
|---|---|
Client Certificate Subject Fields | This field is required when Client Certificate mode is selected. Enter the X.509 certificate subject field names that eCase will use to match the presented client certificate to a registered eCase user account. Enter each field name as it appears in the certificate's Subject Distinguished Name. Common values include CN (Common Name) and E (Email Address). Separate multiple field names with a comma. Example: CN, E. |
OTP via Email
When this mode is selected, a one-time password (OTP) is transmitted to the user's registered email address in eCase as the secondary verification credential. This mode is appropriate when PIV/CAC cards are unavailable or have not been issued to the user population.
Field | Description |
|---|---|
Allowed Verification Failures | This field is required when OTP via Email mode is selected. Enter the maximum number of consecutive failed OTP verification attempts permitted before the user's account is locked. Accepted range: 1 to 10. Default value: 3. After the account is locked, an administrator must unlock it through user management before the user can attempt authentication again. Set this value conservatively to mitigate brute-force attacks against OTP codes. |
NOTE: For OTP via Email to function correctly, the eCase SMTP connector must be fully configured and the target user's email address must be populated in their eCase user profile. If either prerequisite is not satisfied, the OTP email will not be delivered. Verify the SMTP settings on the Connector Configuration page prior to enabling this mode.
Save and Activate SAML SSO
Complete the following procedure in the order specified to safely enable SAML SSO.
Each step is designed to validate the configuration before committing the change that will affect all active users.
1. Complete all required fields: Ensure that all fields marked as Required in both the User Application and Admin Application sections are populated with valid values. Review each field against the descriptions in Sections 4 and 5 before proceeding.
2. Test IdP connectivity: Select the Test button adjacent to the Partner Service URL field in each SP section. Confirm that both tests return a successful result, indicating that the eCase server can reach the IdP SSO endpoint over the network. Do not proceed if either test fails.
3. Enable the SAML SSO toggle: Set the Enable SAML SSO toggle at the top of the page to the ON (enabled) position. Required field indicators (*) will be displayed on all mandatory fields. Confirm that all required fields are populated before continuing.
4. Select Save: Select the Save button (keyboard shortcut: Alt+V). A confirmation dialog will appear, warning that all active sessions will be terminated upon proceeding.
5. Confirm the change: Select OK in the confirmation dialog to save the configuration. eCase will save the settings and immediately invalidate all active sessions, including the current administrative session.
6. Verify the SAML authentication flow: Navigate to the eCase User Application login page. Confirm that the browser is automatically redirected to the configured IdP for authentication. Authenticate with valid IdP credentials and verify that the browser is redirected to the eCase home page upon successful authentication.
7. Verify Admin Application access: Repeat step 6 for the eCase Admin Application. Authenticate with IdP credentials that are mapped to a System Administrator account in eCase and confirm that the administration console is fully accessible.
NOTE: Before enabling SSO, ensure that at least one local eCase System Administrator account with a known password exists and is documented securely. If the SAML integration fails after activation; for example, due to a certificate mismatch or misconfigured ACS URL — this break-glass account is the only mechanism by which an administrator can sign in using the standard eCase login to disable SSO and restore access for other users.
The following table describes the system behavior for each possible state change that can occur when the SAML SSO Configuration page is saved.
Scenario | System Behavior |
|---|---|
SAML SSO toggled ON (was previously OFF) | All active sessions are immediately terminated upon saving. All users, including the administrator who saved the configuration details are redirected to the IdP login page upon their next request to the eCase application. The SAML SSO configuration takes effect immediately. |
SAML SSO toggled OFF (was previously ON) | All active sessions are immediately terminated upon saving. Users are redirected to the eCase standard credential-based login page upon their next request. The IdP integration is suspended, and eCase reverts to built-in authentication. |
SAML SSO remains ON | All active sessions are immediately terminated upon saving. The updated IdP configuration takes effect for all subsequent login attempts. Users must re-authenticate through the IdP with the new configuration upon their next request. |
SAML SSO remains OFF | The configuration is persisted for future use. No session termination occurs. The administrator remains on the configuration page and receives a success message. The saved values will be applied when SAML SSO is subsequently enabled. |
FAQs
Q. Why does the Test button return “Service URL is not Valid”?
A. This indicates that the eCase server cannot reach the IdP SSO URL over the network. The test only performs an HTTP reachability check and does not validate the SAML protocol exchange.
Verify that the IdP SSO URL is correct. Check firewall rules, proxy configurations, and DNS resolution for the IdP hostname from the eCase server. Ensure the correct URL scheme (https://) and port are accessible.
Q. Why can users authenticate at the IdP but still cannot access eCase?
A. eCase cannot map the IdP identity to a user account due to mismatched Username or Email values.
Ensure the user’s Username/Email in eCase exactly matches the identity sent by the IdP.