Configuring SAML SSO

Configuring single sign-on (SSO) in Investigator allows users to log in with their existing company credentials instead of managing separate passwords. This integration uses the Security Assertion Markup Language (SAML) 2.0 standard to delegate authentication to an external Identity Provider (IdP), such as Okta or Auth0.

Prerequisites

To ensure a successful SSO configuration and maintain backup administrative access, complete the following requirements and preparatory steps.

Required permissions

  • Administrator access to your Corelight Investigator instance.

  • Administrator access to your organization’s SAML 2.0 IdP.

Supported login flow

Corelight Investigator supports SP-initiated (Service Provider-initiated) SSO only. Users must begin the login process from the Investigator login page.

Note

IdP-initiated login (logging in by clicking an application tile in the IdP’s portal) is not supported at this time.

Preparatory steps

1. Log in with the primary SSO-domain administrator

The configuration process automatically ties the SSO connection to the email domain of the currently logged-in administrator. This domain will become the first approved SSO domain.

Before proceeding, ensure you are logged into Investigator with a local administrator account whose email address belongs to the primary domain you intend to configure for SSO (for example, admin@yourcompany.com).

2. Audit and remove unwanted local users

Once SSO is enabled for a domain, the Investigator interface locks user management for that domain. You will not be able to manually delete local users with emails matching your SSO domain (for example, former.employee@yourcompany.com) using the Investigator UI once the integration is active.

A best practice before enabling SSO, is to audit your current list of local users. Delete any accounts that should not have access.

3. Set up a dedicated local administrator

It is strongly recommended that you create a separate, independent local administrator before enabling SSO. This account serves as your dedicated system recovery mechanism if your IdP is unavailable or if the SSO configuration is temporarily broken.

Important

Do not enable SSO while logged in as the dedicated local administrator. When enabling SSO, ensure you are not logged in using the local administrator account. If you enable SSO while logged in as this user (for example, admin@gmail.com), the system ties the configuration to this email domain. If you later disable SSO, the system automatically deletes all users associated with the configuration’s domains. This would permanently delete your backup administrator, potentially locking you out of the system.

There are two approaches for the account’s email address, with the non-SSO domain being the recommended method.

  • Recommended method: Non-SSO domain email Use an email address from a domain that is not part of your SSO configuration (for example, admin@gmail.com). This is the safest method because the account acts independently of your SSO provider and can never be linked to SSO operations, ensuring reliable emergency access.

  • Alternative method: SSO-domain email This is for advanced users as it is high risk. It involves using an email address that matches your SSO domain (for example, admin@yourcompany.com). If this account is ever used to log in using SSO, it becomes permanently linked to SSO and will be deleted if SSO is disabled.

Steps to create the local administrator account:

  1. In Investigator, navigate to System Settings | Users & Access.

  2. On the Users tab, click + Add User.

  3. In the Create User panel, provide the following:

    • Alias: Enter a descriptive name for the account, such as Backup Admin.

    • Email: Enter the email address from your non-SSO domain (for example, admin@yourcompany-management.net).

    • Role: Select Admin from the dropdown menu.

  4. Click Create and complete the registration process.

4. Secure the local administrator account

Multi-factor authentication (MFA) is required for all local accounts created directly in Investigator. For users who authenticate using SSO, MFA is managed by your IdP, not by Investigator.

  • Managing shared access: If you choose to use a shared local administrator account, you may want to use an enterprise password manager to store the password and generate the required Time-based One-Time Password (TOTP). This ensures all authorized administrators can access the OTP code without relying on a single individual’s mobile device.

5. Understand how SSO affects local accounts with matching domains

Once SSO is enabled for a domain, Investigator handles local accounts with email addresses from that domain in the following ways:

  • New user restrictions: You cannot manually create new local users from the UI if their email address belongs to an approved SSO domain. These users must be provisioned using the IdP.

  • Existing accounts are migrated (Identity Merge): If a local user account already exists with an email from the SSO domain, the system performs an identity merge the first time that user logs in via SSO.

    • Credential handling: Upon the first successful SSO login, the account is converted to an SSO-only account. The previous local password is rendered invalid for that user.

    • UI Management: The account can no longer be managed (edited or deleted) from the Users page.

    • Stale local accounts: If a local user with a matching domain never attempts an SSO login (and is not removed), they theoretically retain local access. However, all local accounts in Investigator enforce mandatory Multi-Factor Authentication (MFA), mitigating the risk of unauthorized access via stagnant local credentials.

  • User preferences are retained: User preferences are retained during the merge.

Configuring SSO

This process establishes a trusted connection between Investigator and your IdP by exchanging configuration information.

Step 1: Get connection details from Investigator

Collect the connection details that your IdP requires from Investigator.

  1. In Investigator, navigate to System Settings | Users & Access and click the Access tab.

  2. Before proceeding, verify you are logged in as an administrator whose email address belongs to the domain you intend to configure for SSO (for example, admin@yourcompany.com). The configuration process is automatically tied to the domain of the currently logged-in user.

  3. In the SAML Single Sign-on section, click Enable.

  4. In the Enable SAML Single Sign-on wizard, on the Configure IdP tab, copy Assertion Consumer Service URL and Remote Manager Audience URL. You will need these URLs for your IdP configuration, as they are specific to your account.

  5. Keep the wizard open in your browser tab and proceed to the next step.

Step 2: Configure your IdP with Investigator details

Use the connection details you copied from Investigator to create and configure the SAML application in your IdP.

  1. Log in to your IdP (for example, Okta, Azure AD) and create a new SAML application.

  2. In your IdP’s application settings, paste the Assertion Consumer Service URL and Remote Manager Audience URL into the corresponding fields.

  3. Ensure your IdP’s SAML assertion is configured to send the following claims (which do not contain any namespaces in front of them), which Investigator requires for user provisioning and authorization:

    • email_address

    • roles

  4. From your IdP, download the SAML configuration metadata file. This is typically an XML file and is the most reliable way to transfer the IdP’s details to Investigator.

Step 3: Configure Investigator with IdP details

Upload the metadata file from your IdP to establish the trusted connection in Investigator.

  1. Return to the Investigator SAML wizard you left open. On the Configure IdP screen (where you copied the URLs from), click Next.

  2. On the Configure Investigator tab, click Upload the configuration file.

  3. Select the SAML metadata file you downloaded from your IdP in Step 2, and click Open.

  4. The wizard displays the details it extracted from your uploaded file. Verify the following information is correct:

    • The name of your uploaded file

    • Single sign-on URL

    • Entity ID

    • Certificate

  5. Click Next.

Step 4: Configure roles and activate SSO

Complete the setup by mapping user roles from your IdP to Investigator and activating the SSO connection.

  1. On the Configure Roles tab, map your IdP roles to the Investigator roles (Admin, Analyst, Viewer). You have two options:

    • To use the default role names (corelight_admin, corelight_analyst, corelight_viewer), leave the corresponding fields blank.

    • To use custom role names from your IdP (for example, CK_Admins_Global), enter the name of the custom role your IdP sends for each Investigator role into the corresponding field. For example, if your IdP sends a role named CK_Admins_Global, you would enter that name into the Admin field.

  2. Review the user settings configuration and click Save.

  3. On the final review screen, click Save and Enable to activate the SSO connection.

  4. After the confirmation message appears, click Check Connection to verify that the integration is working. If the check fails, see the Troubleshooting common errors section.

Next steps after activating SSO

A successful connection confirms that your SAML Single Sign-On configuration is now active and ready for use by your primary domain.

User provisioning and login

Once the connection is active, you do not need to create users manually in Investigator.

  • How users log in: Users permitted by your IdP can navigate to the Investigator login page and use the Sign In with SSO button.

  • Automatic account creation: When users log in for the first time, their Investigator account will be created automatically based on the attributes sent by the IdP.

Expanding SSO access to multiple domains

This initial procedure completes the SSO setup for your primary domain. If you need to include users from other email domains (such as subsidiaries or partners), you can configure Investigator for multi-domain support.

To enable access for additional domains (multi-domain setup), proceed immediately to the Managing approved email domains section.

  • Related Information: For more details on the new rules governing user accounts and how they are managed after enabling SSO, see the Managing users after enabling SSO section.

Managing approved email domains

Once Single Sign-On (SSO) is active, your IdP becomes the primary source of truth for authenticating users. The Approved Email Domains panel gives you granular control over which email domains are permitted to use SSO to log into your Investigator instance.

The email domain of the administrator who initially enabled SSO is automatically added as the first approved domain. You can then add or remove other domains belonging to your organization, such as subsidiary or partner domains.

Key rules and limitations

  • Minimum requirement: You must maintain a minimum of one approved domain. The delete option is disabled for the last remaining domain.

  • Maximum limit: You can add a maximum of 30 approved domains.

Important

The system validates the user account using the value in the email_address attribute in the SAML assertion. For a user to successfully authenticate, their login email address must match an approved domain.

How to add an approved domain

To expand SSO access to users from other email domains, follow these steps:

  1. Navigate to System Settings | Users & Access and select the Access tab.

  2. In the SAML Single Sign-on section, find the Approved Email Domains panel.

  3. Click the + Add Domain button.

  4. In the Add domain modal, enter the domain (for example, partner-company.com). The modal provides real-time validation.

  5. Click Add Domain. On success, the modal will close and the new domain will appear in the list.

How to remove an approved domain

Removing a domain is a highly disruptive action and must be performed with caution.

Warning

Removing an approved domain will cause all users from that domain to immediately lose access to Investigator. User accounts from that domain are deleted; users will not be able to log back in unless the domain is re-added and they are re-provisioned through your IdP. For details on how user accounts are managed after this action, see the Managing users after enabling SSO section.

  1. In the Approved Email Domains panel, locate the domain card you want to remove.

  2. Click the trash can icon next to the domain name.

  3. A confirmation modal Remove {domain.name}? will appear. Review the warning carefully:

    • Any users using this domain will lose access to Investigator immediately.

    • This action cannot be undone; users will not be able to log back in unless the domain is re-added and they are re-provisioned through your IdP.

  4. To confirm, click the red Remove Domain button.

Managing users after enabling SSO

Once SSO is active, your IdP becomes the primary authority for authenticating users. This means the IdP is the system that determines if a user is active, what their current email is, and what permissions (roles) they have. Investigator simply reads this confirmed information from the IdP, and is no longer the system managing it.

User management for approved domains must now be performed within your IdP.

New user creation and UI restrictions

All new users are provisioned automatically via your IdP when they first log in, ensuring secure and centralized access.

  • New user creation: Accounts are created automatically when the user logs in for the first time using the IdP.

  • User provisioning: All new users from any approved SSO domain must be added and managed through your IdP.

  • UI management: The Users tab in Investigator is effectively read-only for all SSO-provisioned users (you cannot invite, edit, or delete them locally).

  • Login process: SAML users must use the Sign In with SSO button on the Investigator login page (the supported SP-initiated flow). Users may be prompted to enter their email domain to be redirected to the correct IdP.

Why can’t I delete users?

When SSO is enabled for a domain, Investigator delegates all lifecycle management (creation, updates, and termination) to your IdP. Consequently, the Delete (trash can) icon is disabled in the Investigator UI for all users belonging to an approved SSO domain.

To revoke a user’s access:

  1. Remove the user from your IdP: Unassign the application or disable the user in your IdP (for example, Okta, Azure).

  2. Effect on Investigator: The user will immediately be unable to log in via SSO. The user record will remain visible in Investigator for historical data association, but they cannot access the system.

Disabling SSO: Avoid service interruption

Disabling SSO is a highly disruptive action that must not be used as a workaround for user creation. This action compromises centralized user management and requires re-provisioning of all SSO-enabled users

  • Disabling SSO: This action permanently removes all current SSO-enabled users from the Investigator UI, including administrator accounts that were linked to SSO. User accounts are permanently deleted; they are not simply disabled or deactivated.

  • Re-enabling SSO: If SSO is enabled again later, all users will need to be re-provisioned through your IdP.

Account linking and emergency access

This section explains how existing local accounts are affected by SSO and how the dedicated local administrator access is maintained for system recovery.

  • Existing account linking: If a local user account already exists with a matching approved SSO domain email, the first SSO login links the account permanently to SSO. This account can no longer be managed (edited or deleted) from the Users page.

  • Local administrator access: The local administrator account always retains the ability to log in directly using its local credentials (Email and Password fields). This is the primary method for emergency access without having to disable SSO for the entire tenant.

  • Configuration updates: To update SAML settings (such as certificate changes, role mapping), you can re-open the configuration wizard at any time from the Access tab.

Using the local administrator account

If your IdP is unavailable, use the local administrator account you created in the preparatory steps to log in directly to Investigator using the associated username and password rather than following the SSO flow.

Steps to log in locally

  1. Navigate to your standard Investigator login page.

  2. Do not click the Sign In with SSO button. Instead, enter the Email and Password for your local administrator account into the standard login fields.

  3. Click Sign In and complete the MFA prompt to finish logging in.

After completing these steps, you will be logged in to Investigator with local administrator privileges.

Disabling SSO

If you need to revert your tenant entirely to local authentication, you can disable the SAML SSO connection.

Warning

Disabling SSO is a disruptive action with immediate consequences. It will permanently remove all current SSO-enabled users from the Investigator UI. This includes any accounts, even administrator accounts, that were originally local but have since been enabled for SSO login.

Prerequisite considerations

This action should only be performed during a planned maintenance window.

Before proceeding, review the list of SSO-enabled users across all approved domains in the Investigator instance to ensure that no critical user accounts will be removed.

Steps to disable SSO

  1. Navigate to System Settings | Users & Access and select the Access tab.

  2. On the SAML Single Sign-on screen, click the red Disable SSO link.

  3. In the confirmation dialog, type confirm to verify the action.

  4. Click the Disable button to complete the action.

Consequences of disabling SSO

  • Permanent deletion: All SSO-enabled user accounts, from all approved domains, are permanently deleted from the Investigator instance. They are not simply disabled or deactivated.

  • Re-provisioning required: If you enable SSO again later, all users will need to be re-provisioned through your IdP. User profile settings are typically restored if the email address matches a previous user.

  • Domain reset: When SSO is re-enabled, the system will only re-establish the primary domain of the enabling administrator. Any other approved domains will need to be added back manually using the Approved Email Domains panel.

Changing identity providers

You can typically switch from one IdP to another (for example, Okta to Azure AD) without disrupting existing user access by simply editing your current SSO configuration.

Steps to change identity providers

  1. Obtain the SAML configuration metadata file from your new IdP.

  2. In Investigator, navigate to System Settings | Users & Access and select the Access tab.

  3. In the SAML Single Sign-on section, click the Edit button. This re-opens the configuration wizard.

  4. Click Next to proceed past the Configure IdP tab.

  5. On the Configure Investigator tab, click Upload the configuration file and select the new metadata XML file you just downloaded. This action will overwrite the previous IdP’s settings.

  6. Click Next to proceed to the Configure Roles tab.

  7. Re-map your user roles (for example, Analyst users, Viewer users) if the role names from your new IdP are different from the previous ones.

  8. Review the settings on the Configure Roles tab and click Save.

  9. On the final review screen, click Save and Enable to activate the new configuration.

  10. Click Check Connection to verify the integration with the new IdP.

  11. Have a test user log in with the new IdP to confirm the migration was successful.

Alternative method: Disabling SSO and re-running configuration

If the Edit function is unavailable for updating your configuration, you must follow the Disabling SSO procedure and immediately re-run the full Configuring SSO procedure.

Important

This alternative method is highly disruptive and should be avoided unless necessary.

  • Risk of user loss: It will permanently remove all currently linked SSO-enabled users from the Investigator instance (as detailed in Disabling SSO).

  • Temporary downtime: Users authenticating using SSO will be temporarily locked out until the new configuration is fully completed and verified.

Troubleshooting common errors

If the connection check fails, check for these common issues:

Error message / Symptom

Common cause / Solution

Invalid signature

The X.509 Certificate in Investigator is incorrect or has been rotated in your IdP. Copy the latest certificate from your IdP and paste it into the SAML configuration.

Audience is invalid

The Remote Manager Audience URL in your IdP does not exactly match the one provided by Investigator. Check for typos or extra spaces.

User is not assigned to role

The IdP is not sending the roles attribute in the SAML assertion, or the role name does not match what is configured in Investigator. Verify the attribute name and value in your IdP.

Redirects to an error page (404)

The SSO URL is incorrect in the Investigator configuration. Copy the correct URL from your IdP.