SAML SSO user management¶

Configuring single sign-on (SSO) in Corelight Investigator allows users to log in with their existing company credentials instead of managing separate passwords. This integration uses the 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 Identity Provider (IdP).

Preparatory steps¶

1. Log in with an SSO-domain administrator¶

The SSO configuration process is automatically tied to the domain of the currently logged-in administrator. Before you begin, you must be logged into Investigator with a local administrator account whose email address belongs to the domain you intend to configure for SSO (for example, admin@yourcompany.com).

2. Create a local administrator for backup access¶

It is strongly recommended that you create a separate local administrator account before enabling SSO. This account serves as your backup for emergency access if your IdP is unavailable.

There are two approaches for the account’s email address, with the first being the safest and most recommended:

Recommended Method (Non-SSO Domain Email): Use an email address from a domain that is not part of your SSO configuration (for example, using an address from a separate, dedicated administrative domain). This is the simplest and safest method, as it creates an account that can never be affected by SSO operations.
Alternative Method (SSO-Domain Email): This is for advanced users and carries significant risk. If an account with an SSO-domain email is ever logged into via SSO, it becomes permanently linked to SSO and will be deleted if SSO is disabled for the tenant.

Steps to create the local administrator account:

In Investigator, navigate to System Settings | Users & Access.
On the Users tab, click + Add User.
In the Create User panel, provide the following:
- Alias: Enter a descriptive name for the account, such as Emergency Admin.
- Email: Enter the email address from your non-SSO domain (for example, admin@yourcompany-management.net).
- Role: Select Admin from the dropdown menu.
Click Create and complete the registration process.

3. Secure the local administrator account¶

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

The best practice for managing the required MFA on a shared local administrator account is to use an enterprise password manager that can store the password and also generate the required time-based one-time passwords (TOTP).

4. 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:

Existing accounts can be linked to SSO: If a local user account already exists with an email from the SSO domain (for example, jane.doe@yourcompany.com), it remains a local-only account until a user logs in using SSO. At that point, the account becomes enabled for both local password and SSO login, but it can no longer be managed (edited or deleted) from the Users page. User preferences are kept.
New User Restrictions: Once SSO is active, you cannot create new local users from the UI if their email address belongs to the SSO-federated domain. Attempts to create users for other non-SSO domains may also fail if the domain is not recognized by the system.

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 your IdP requires from Investigator.

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

Important

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.
In the SAML Single Sign-on section, click Enable.
In the Enable SAML Single Sign-on wizard, on the Configure IdP tab, copy the 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.
Keep the wizard open in your browser tab and proceed to the next step.

Step 2: Provide Investigator details to configure your IdP¶

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

In your IdP’s application settings, paste the Assertion Consumer Service URL and Remote Manager Audience URL into the corresponding fields.
Ensure your IdP’s SAML assertion is configured to send the following attributes, which Investigator requires:
- email_address
- roles
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: Provide IdP details to configure Investigator¶

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

Return to the Investigator SAML wizard you left open. On the Configure IdP screen (where you copied the URLs from), click Next.
On the Configure Investigator tab, click Upload the configuration file.
Select the SAML metadata file you downloaded from your IdP and click Open.
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
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.

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), you can leave the mapping fields blank.
- To use custom role names from your IdP, enter the name of the 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.
Review the user settings configuration and click Save.
On the final review screen, click Save and Enable to activate the SSO connection.
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¶

A successful connection confirms that your SSO configuration is active and complete. You do not need to create users manually in Investigator.

Users who are assigned the application in your IdP can now navigate to the Investigator login page and use the Sign In with SSO button. When they log in for the first time, their Investigator account will be created automatically.

For more details on how user accounts are managed after enabling SSO, see Managing users after enabling SSO.

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 Single Sign On Service URL is incorrect in the Investigator configuration. Copy the correct URL from your IdP.

Managing users after enabling SSO¶

Once SSO is active, your IdP becomes the primary method for authenticating SSO-based users, but existing local accounts continue to function according to specific rules.

Administrator local login: Administrator accounts always retain the ability to log in directly with their local credentials (username and password), bypassing SSO. This is the primary method for emergency access if your IdP is temporarily unavailable and does not require you to disable SSO for the entire tenant.
User provisioning: All new users from your SSO domain must be added and managed through your IdP. The Users tab in Investigator is effectively read-only for SSO users.
Login process: SAML users must use the Sign In with SSO button on the login page. They might need to provide their email domain to be redirected to the correct IdP for authentication.
User linking for matching domains: If a local user account exists with an email address that matches the SSO domain (for example, a user created before SSO was enabled), the first time that user authenticates using SSO, the account becomes linked to SSO and enabled for both local password and SSO login. While user preferences are kept, the account can no longer be managed (edited or deleted) from the Users page after being linked to SSO.
Modifying the configuration: To update your SAML settings after the initial setup, you can re-open the configuration wizard at any time from the Access tab.

If your IdP is unavailable, use the local administrator account you created for backup access to bypass SSO and log in directly to Investigator.

Steps to log in locally¶

Navigate to your standard Investigator login page.
Do not click the Sign In with SSO button. Instead, enter the Email and Password for your backup local administrator account.
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 users from the Investigator UI. This includes any accounts, even administrator accounts, that were originally local but have since been enabled for SSO login. This action should only be performed during a planned maintenance window, and only after reviewing the list of SSO-enabled users in the Investigator instance to ensure that no critical user accounts will be removed.

Steps to disable SSO¶

Navigate to System Settings | Users & Access and select the Access tab.
On the SAML Single Sign-on screen, click the red Disable SSO link.
In the confirmation dialog, type confirm to verify the action.
Click the Disable button to complete the action.

Consequences of disabling SSO¶

Effect: All SSO-enabled user accounts are permanently removed from the Investigator instance. They are not simply disabled.
Re-enabling: If you enable SSO again later, users will need to be re-provisioned through your IdP. User profile settings are typically restored if the email address matches a previous user.

Changing identity providers¶

You can typically change from one IdP to another without disrupting user access by editing your existing SSO configuration.

Steps to change identity providers¶

Obtain the SAML configuration metadata file from your new IdP.
In Investigator, navigate to System Settings | Users & Access and select the Access tab.
In the SAML Single Sign-on section, click the Edit button. This re-opens the configuration wizard.
Click Next to proceed past the Configure IdP tab.
On the Configure Investigator tab, click Upload the configuration file and select the new metadata XML file you just downloaded. This will overwrite the previous IdP’s settings.
Click Next to proceed to the Configure Roles tab.
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.
Review the settings on the Configure Roles tab and click Save.
On the final review screen, click Save and Enable to activate the new configuration.
Click Check Connection to verify the integration with the new IdP.
Have a test user log in with the new IdP to confirm the migration was successful.