GAINS SSO Configuration Guide

Introduction

This guide provides instructions for configuring Single Sign-On (SSO) settings in GAINS. As an authorized user, you can now self-configure SSO settings through a new dedicated page.

Prerequisite: GAINSX 24.07

Accessing the SSO Settings Page

1. Log in to GAINS with your authorized credentials.
2. Navigate to the new SSO settings page under System Management.

Navigating to Single Sign On

Configuring SSO Settings

Fill out the following fields to configure your SSO settings:

1. Single Sign-On via SAML
   • Description: Controls the use of SSO on this instance of GAINS.
   • Type: Toggle (On/Off)
   • Default: Off
   • Note: When off, GAINS will use local user authentication and management.
2. IDP Metadata
   • Description: Upload the metadata file from your Identity Provider (IDP).
   • Type: File Upload
   • Note: This file contains configuration details and will auto-populate some fields such as (if defined in the metadata):
     • Identity Provider Sign in URL
     • Sign Out Redirect URL
3. Identity Provider Sign In URL
   • Description: The URL where GAINS should send SAML authentication requests.
   • Type: Text (potentially auto-populated via metadata upload)
   • Note: This URL is essential for initiating the SSO process.
4. Sign Out Redirect URL
   • Description: The URL users are redirected to upon signing out from GAINS.
   • Type: Text (potentially auto-populated via metadata upload)
   • Default: GAINS login page URL
5. Group Prefix
   • Description: A prefix added to group names mapped from IDP to GAINS.
   • Type: Text
   • Default: "GAINS_"
   • Note: Below this field, you'll see a list of currently active groups from the Roles table.
6. Validate Signed Response
   • Description: Enables validation of the SAML response signature.
   • Type: Toggle (On/Off)
   • Default: Off
7. Validate Signed Assertions
   • Description: Enables validation of signed assertions within the SAML response.
   • Type: Toggle (On/Off)
   • Default: Off

Read-Only Fields

These fields will be displayed for your reference and to allow GAINS to be configured as a Service Provider in your Identity Management platform.

1. GAINS Sign In URL
   • Description: The URL used for GAINS sign-in, to be configured on your IDP.
2. GAINS Metadata
   • Description: The GAINS SAML metadata file URL.
   • Note: A "Download" option will be available to obtain the metadata file.

Testing SSO Configuration

Modal shown before beginning SSO test

Before saving,

Before saving, you can test your SSO configuration:

1. Click the "Test SSO" button.
2. A modal will appear with the title "Begin SSO Test" and instructions.
3. Click "Begin Test" to start the test - this opens a new tab which will be blank.
4. You must close the newly opened test tab which will then return you to the original tab to show the test results.
5. View the test results in the new modal:
   • If successful, you'll see a "Test Successful" message.
   • If failed, you'll see a list of reasons for the failure.

Saving SSO Configuration

After filling out the required fields:

1. Click the "Save Configuration" button.
2. This action will:
   • Clear existing sessions by invalidating the GAINS session cache
   • Require active users to log in again

Important Notes

• All changes to settings are logged for tracking purposes.
• When SSO is active, the GAINS login page will be modified to include:
  • A "Sign In with <SSO Provider>" option at the top.
  • The existing GAINS local login option below

GAINS log in page with SSO option

Troubleshooting

If you encounter issues during configuration or testing, please contact your system administrator or GAINS support team for assistance.