Entra ID (Azure AD) SAML (QUX)

Enabling QUX (Quadrant UX) SAML SSO with Entra ID (Azure AD) as the Identity Provider (IdP).

Please Note:

This article is ONLY for customers configuring SAML SSO for Quadrant UX (QUX) deployments using Entra ID (Azure AD) as the IdP.

If you are configuring Entra ID SAML for the Respond UX, please see Entra ID (Azure AD) SAML (RUX) instead of this article.

While similar, there are some differences in the implementation for customers using the Respond UX. If you are unsure which UX you are using, please see: Vectra Analyst User Experiences (Respond vs Quadrant) for more information.

The Quadrant UX requires different SAML claim names than the Respond UX when setting up SAML 2.0 based SSO but the claim creation process in the IdP is similar.

Introduction

• Customers can setup SSO federation to multiple SAML 2.0-based identity providers (IdP).

  • For most customers, only a single IdP is required.

• Once federated, already authenticated users will have one-click login in to the Vectra Quadrant UX.

• Unauthenticated users will get redirected to their IdP’s login portal.

• If multiple IdPs are configured, and the user is not already authenticated, the user will need to enter their email address so the domain name mapping can direct the user to the appropriate IdP.

• Features like password policies and multi-factor authentication will be enforced by the IdP.

• Once authenticated, users are assigned the Vectra role defined for their user or group in the IdP.

  • This will map to a role (and permissions) as defined in the Vectra Quadrant UX UI.

Multiple SAML Profile Support

Vectra now supports multiple SAML profiles in private preview. Not all customers will require this, and NO changes are required for existing single IdP SAML configurations. If you are interested in this feature prior to it's planned general availability in the v9.10 release, please ask your Vectra account team.

Please Note:

• Existing customers do NOT need to do anything if they will continue to only have a single SAML IdP configured.

• Any new profile that is added, for new or existing customers, will now need to have a Domains list configured as part of the Vectra SAML profile.

• If you add a 2nd profile to an existing deployment that did NOT have a Domains list configured previously, you MUST edit that existing profile to add the Domains mapping for that IdP.

• Nothing changes on the IdP side of the configuration.

• When multiple profiles are configured, users will be asked to enter their email address to be redirected to the appropriate IdP when they click Login with SSO on the Vectra login screen.

QUX SAML SSO - Notes of Interest

• Please ensure the users are only mapped to one Vectra Role in the IdP.

  • At this time, if a user is mapped to more than 1 role in the IdP, the user may not successfully log in with the desired role.

• IdP initiated flows are NOT supported.

  • While these flows may work, they are not recommended because they are highly susceptible to Man-in-the-Middle attack using stolen SAML assertions.

• The SessionNotOnOrAfter SAML parameter is supported to invalidate user sessions and require a user to re-authenticate.

• Single Log Out (SLO) and IdP initiated log out are NOT supported.

  • When a user logs out of the Quadrant UX, they are taken to a screen where they can log in locally or click a link to Log in via SSO.

• At this time, a user who successfully authenticates through their IdP to Vectra will have a session that is good for one day.

• Local login is still possible after SAML configuration:

  • Construct a login URL as shown below.

  • https//<ip_or_hostname>/accounts/login/?local=True

• API keys are not supported for SAML users.

  • For API use, Vectra recommends local accounts authenticated locally or against external authentication sources such as RADIUS, LDAP, or TACACS+.

• Token Encryption is currently NOT supported.

SAML Service Provider (SP) Initiated Flow

• This example flow diagram uses Azure as the IdP but SSO should work with any SAML 2.0 compliant IdP.

• Please note that all communication is brokered by the User Agent (user's browser). Vectra never needs to communicate with the IdP.

Release Demo for this Feature

Please Note:

At the time this feature became available, Azure AD App Roles needed to be configured in the App Manifest. Microsoft has since added functionality to create and manage App Roles in their GUI. The steps below have been updated but the video remains as originally published. The manifest is still a valid method to use if you desire but the App Roles GUI is simpler for most admins to deal with.

Configuration

• First we'll need to start creating the SAML Authentication Profile.

  • Additional profiles can be configured if multiple IdPs are required for your deployment.

• Open a new browser tab, log in as you normally do, and navigate to Configuration → ACCESS → External Authentication.

• Click on Create in the SAML Profiles section.

• A dialog will open and the SP ACS URL and SP Entity Provider will be displayed there for entry into the corresponding fields in the IdP. Make note of these values for later use with your IdP. The SP is the Service Provider (your Vectra QUX deployment in this case).

Please Note:

• Not every IdP uses the same terminology to refer to these fields.

• As an example, in Entra ID, Vectra's SP Entity Provider URI should be used for the Azure Identifier (Entity ID) and Vectra's SP ACS URL should be used for the Azure Reply URL (Assertion Consumer Service URL).

• Leave this tab in your browser open and proceed in another tab or window to your IdP configuration so that you can configure the IdP side and retrieve the required metadata XML file needed to complete the Vectra configuration.

Please Note:

If you want a hostname-based entry instead of IP-based entry for the SP ACS URL and SP Entity Provider, then you should:

• Configure in Vectra the Brain FQDN, in Configuration → COVERAGE → Data Sources → Network → Brain Setup → Brain → DNS Name.

• Check the DNS Name radio button for the For linking in alerts/notifications (except AWS SecurityHub) section.

• This will populate the SP entries using hostname instead of IP.

Please Also Note:

The DNS Name should be in lowercase in this area and any place you see it in your IdP.]

Configuration → COVERAGE → Data Sources → Network → Brain Setup → Brain

Configuring the Entra ID Application

• Select Enterprise applications from Entra ID.

• Click the + New application button.

• Click the + Create your own application button (this is not a Gallery application).

• Give it a name like Vectra QUX SSO or any name you desire.

• Use the Integrate any other application you don't find in the gallery option.

• Click Create at the bottom of the dialog.

• Select Single sign-on from the left or Set up single sign on from the Getting Started section.

• Select SAML from the single sign-on method list.

• Next we will configure the Enterprise application with the values we collected earlier.

• Edit the Basic SAML Configuration in the newly created Enterprise application.

• Mapping the values we collected earlier:

  • Vectra's SP Entity Provider URI should be used for the Microsoft Identifier (Entity ID).

  • Vectra's SP ACS URL should be used for the Microsoft Reply URL (Assertion Consumer Service URL).

• The rest of the Basic SAML Configuration can be left blank.

• Click the Save button at the top of the Basic SAML Configuration window.

• After this is saved, you can close the window. You will be asked if you want to test now. Select No, I'll test later. Additional configuration needs to be done before the new SAML app will work for login to Vectra.

• Next we will download the Federation Metadata XML file from the SAML app so that we can later complete the Vectra configuration.

• While still in your SAML app in Enterprise applications, scroll down to section 3 SAML Signing Certificate.

• Download the Federation Metatdata XML file to a location you can later access to upload the file to Vectra.

Configure the Role Claim and Vectra Roles in Entra ID

• We'll begin by creating the the user.assignedroles claim.

• In your SAML app, select Edit in section 2 User Attributes & Claims.

• Select Add a new claim.

• Enter https://schema.vectra.ai/role in the Name section.

• For Source attribute, select user.assignedroles.

• Save the claim.

• Azure AD defaults to including a user.userprincipalname claim (which is required) but if you do not have this or are using a different IDP, please ensure that you also create this claim similarly to how to you created the user.assignedroles claim.

  • This claim's name should be http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.

• Next we will configure App roles in your newly created App.

• In the Entra ID, select App Registrations.

• Select All Applications, search for your newly created app, and click on it.

• Select App roles from the sidebar.

• Back in your Vectra UI tab, navigate to Configuration → ACCESS → Roles.

• Click on each role that your SAML users will be using and make note of the specific Standardized Name for each role. You will need to enter these roles in Entra ID.

  • For example, the Security Analyst role has a Standardized Name of security_analyst.

  • Any custom roles that you create will also have a Standardized Name.

  

  • Default Standardized Names for roles in Vectra are:

    • admins

    • read_only

    • restricted_admins

    • security_analyst

    • setting_admins

    • super_admins

• Back in the App Registration → App roles tab, add a new entry for each role you will be using with your Vectra deployment.

• Default roles from Microsoft of User and msiam_access can be ignored or deleted if desired.

• Create new App roles using the + Create app role button for each role that you will have users or groups assigned to in Vectra.

• Be sure to use the Standardized Name that you collected previously for the Value field.

• The Display name and Description can be anything that you want to refer to inside the IdP for the Vectra roles you will be assigning to your users.

Role Configuration via Microsoft App Manifest

Please Note:

• Most users can skip this section. It is only included for advanced users who wish to use the app manifest to configure roles. Most users should instead use the instructions in this guide to configure roles for their SAML app.

• When SAML first came out for Vectra QUX deployments, the Microsoft App Manifest was required to be used to configure roles for the SAML app. The configuration can now be done much more simply and the steps in this article reflect the simpler method. If you wish to use the app manifest to configure roles, Vectra is providing the JSON formatted default app roles as an attachment below. Instructions are not provided for this method.

Assign Entra ID Users and Groups to the Roles

• In Entra ID, select Enterprise applications.

• Select All applications to view a list of all your applications.

• Search for and then click on your newly created SAML App for Vectra.

• Select the Users and groups from Manage in the sidebar or click onAssign users and groups from the panes.

• Select the + Add user/group button.

• Choose a user or group and then a Vectra role that you previously added and assign it.

• Repeat as required for other users and groups.

When you have finished mapping all your users and groups to Vectra roles in your SAML Enterprise app, you have finished the Microsoft side of the configuration and can move on to completing the configuration in Vectra.

• After IdP configuration and downloading the IdP Metadata XML file you can complete the configuration in the Vectra UI.

• Click Select a file next to Upload IDP Metadata XML File in the Create SAML Profile window.

• Fill in the Profile Name with a name.

• Fill in the Domains field with the domains that should map to the SAML IdP you are configuring.

  • For example, if you username is [e-mail], then you would enter company.com.

  • When multiple SAML profiles are configured, users will enter an email address after clicking Login with SSO.

  • Based on the user input and mapped domains, the user will be redirected to the appropriate IdP for authentication and then redirected back to Vectra with a SAML assertion.

• Click Create.

Testing

• Once configuration is complete on both the Service Provider (Vectra) and IdP side, you are ready to test SAML SSO to Vectra.

  • Keep in mind that only users and groups who are mapped to standardized Vectra role names in your IdP will succeed.

• Click the Login with SSO button on the login page for your Vectra QUX deployment.

• If you are already authenticated to your IdP, and have a mapping to a standardized role that exists in Vectra, you should be logged in without requiring any additional steps.

• If you are need to authenticate to your IdP, you will be asked for a email address when multiple profiles are configured and redirected to your IdP for authentication and then redirected back to Vectra and presented the UI with your mapped role permissions applied.

Please Note:

After SAML configuration, local login using username/password is still supported via a different URL constructed as follows:

• https//<ip_or_hostname>/accounts/login/?local=True

• For users not participating in SSO, please ensure they have this new URL to login to Vectra.

• After login, you can see your status under My Profile.

• If you have rights to the Configuration → ACCESS > Users screen, you can see all user logins.

  • SAML users are shown with a SAML: prefix.

  • SAML users are not locally defined in your Vectra deployment, they exist in the IdP and the configuration allows them to login to your Vectra deployment.