ADFS SAML (RUX)

Enabling RUX (Respond UX) SAML SSO with ADFS as the Identity Provider (IdP).

Please Note:

This article is ONLY for customers configuring SAML SSO for Respond UX (RUX) deployments using ADFS as the IdP.

If you are configuring ADFS SAML for the Quadrant UX, please see ADFS SAML (QUX) instead of this article.

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

The Respond UX requires different SAML claim names than the Quadrant 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 Respond UX.

  • 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 UI.

Multiple SAML Profile Support

Vectra now supports multiple SAML profiles. Not all customers will require this, and NO changes are required for existing single IdP SAML configurations.

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.

RUX 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.

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

  • When a user logs out of the Respond 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 user login that bypasses the SAML flow is still available by adding /signIn?local=True to the end of your Respond UX login URL.

  • Example: https://[unique_customer_id].uw2.portal.vectra.ai/signIn?local=True

  • If you are publishing the URLs of applications used in your environment on a dedicated app/page, you can publish the URL associated with the Login with SSO link to ensure users always use this path

• Token Encryption is currently NOT supported.

SAML Service Provider (SP) Initiated Flow

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

  • Vectra does communicate with the IdP to retrieve the required federation metadata during configuration and refreshes that metadata periodically to ensure new certificates are ingested from the IdP when expiration is near.

Prerequisites

• Vectra tested using Microsoft ADFS server version 10.

  • Note: SSO may also work on lower versions of Microsoft ADFS supporting SAML 2.0 (i.e. from version ADFS 2.0), but this was not tested by Vectra and is not supported.

• Verify the version of your Microsoft ADFS server. The CurrentFarmBehavior value must be 3 or 4.

  • To do so, you can run PowerShell command to get ADFS version: Get-AdfsFarmInformation

  
• SSL - Vectra Respond UX requires that the SSL Certificate of the ADFS server be publicly signed to allow for certificate validation.

Configuring ADFS for Vectra RUX

1. Create Vectra SAML Profile

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

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

• Open a new browser tab and 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 (Vectra SaaS)

• Leave this tab in your browser open and proceed in another tab or window to your IdP configuration so that you can retrieve the IdP Metadata URL needed to complete the Vectra SaaS configuration.

• The SP ACS URL is the Assertion Consumer Service URL. It represents the endpoint on the service provider (Vectra side) where ADFS will redirect to with its authentication response. This URL will be of the following format: https://<Brain URL and AWS Region>.amazoncognito.com/saml2/idpresponse.

• The SP Entity Provider represents the entity of the Vectra Service Provider.

• Click Next. Take note of these information as they will be needed in the next steps to configure the corresponding fields in the ADFS SAML SSO setup flow.

• 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 Note:

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

• Next, we will configure ADFS with these values.

2. Add a Relying Party Trust in ADFS

Relying party trust is a term used in ADFS to identify service providers (in our case Vectra) that can communicate with an ADFS endpoint.

• Go to AD FS Management, select in the left navigation pane Relying Party Trust, then on the right navigation pane click Add Relying Party Trust.

• On the Wizard Welcome page, select the option Claims Aware, then click Start.

• Select Enter data about the relying party manually, then click Next.

• Enter a display name (like Vectra Respond UX and any optional notes, then click Next

• Click Next to accept the defaults for the Configure Certificate step.

• Select Enable support for the SAML 2.0 WebSSO Protocol.

• Enter the SP ACS URL retrieved from Vecgra SAML Profile configuration page in Step 1, then click Next.

• In the Relying party trust identifier, enter the SP Entity Provider retrieved from the Vectra SAML profile configuration page in Step 1. Click Add, then Click Next.

• Select Permit Everyone (or other access control policy of your choice), then click Next.

• No changes are needed for the Ready to Add Trust section. Click Next.

• At the Finish screen, uncheck Configure claims issuance policy for this application, then click Close.

• Next, we will configure custom attributes to use as a claims.

3. Add a Claim Description in ADFS

Claim descriptions will allow us to create a custom attribute that will be sent by ADFS in its SAML response. In our case, we need to create attributes corresponding to standardized name of a Vectra role, email address, and name, so that Vectra can then give the right permissions associated to the role indicated in the SAML response. Thus, once authenticated, users are assigned by Vectra the application role defined in the ADFS.

• Go to AD FS Management, select Service from the left navigation pane then Claim Descriptions.

• Click Add Claim Description... on the right navigation pane and add new claims for role, emailaddress, and name.

• Enter a Display name like Vectra Role.

• Enter the Short Name user.assignedrole.

• Enter the Claim Type role.

• Finally leave the two Publish… boxes unchecked and finish by clicking Ok.

• Enter a Display name like Vectra Email.

• Enter the Short Name user.email.

• Enter the Claim Type emailaddress.

• Finally leave the two Publish… boxes unchecked and finish by clicking Ok.

• Enter a Display name like Vectra Name.

• Enter the Short Name user.name.

• Enter the Claim Type name.

• Finally leave the two Publish… box unchecked and finish by clicking Ok.

4. Add Rules Claim in ADFS

In ADFS, the Claims Issuance Policy defines what pieces of information about a user go where in a claim.

• To define it, go to AD FS Management, select Relying Party Trusts from the left navigation pane then Edit Claim Issuance Policy… from right navigation pane.

4a. Add the SSO rule Claim

• Select Send LDAP Attributes as a Claim, then click Next.

• Enter a Claim rule name like Vectra Respond UX.

• Then select Active Directory for Attribute Store.

• Then select User-Principal-Name as LDAP Attribute and map it to Name ID as Outgoing Claim Type.

• Then select User-Principal-Name as LDAP Attribute and map it to Vectra Email as Outgoing Claim Type.

• Then select Display-Name as LDAP Attribute and map it to Vectra Name as Outgoing Claim Type.

Please Note:

The User-Principal-Name contains the value of the email address of the user.

• The Name ID outgoing claim should always be present to ensure correct session handling and can be seen as the login field in SAML.

4b. Add Role rule Claim

• Now, go to Edit Claim Issuance Policy window to create a second claim rule, which will map the AD group to the standardized Vectra role name. This will map to a role (and permissions) defined in Vectra.

• Add a new rule Claim Add Rule…

• Select Send Group Membership as a Claim, then click Next.

• Enter a Claim rule name.

• Browse the Active Directory and select the group to map

• Select the Outgoing claim type newly created Vectra Role in our example.

• Then, we need to indicate the Outgoing claim value which will be the standardized name of your role to be assigned.

  • To find this value, go back in your Vectra tab, navigate to the Configuration → ACCESS → Roles screen.

• Click on each role that your SAML users will be using and make note of the specific Standardized Name for each role.

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

• Enter the specific Standardized Vectra Role Name to map then click Finish.

Please Note:

For each role assignment a rule needs to be created.

Please Note:

Ensure the users are only mapped to one Vectra Role in the IdP. If a user is mapped to more than 1 role, the user may not be assigned the preferred role.

5. Finish SAML Profile in Vectra

• After ADFS configuration and copying the IdP Metadata URL you can complete the configuration back in the Respond UX.

• Switch back to the browser tab or window with your Respond UX.

• Paste the IdP Metadata URL into the Create SAML Profile dialog box.

• Fill in the Profile Name with a name of your choice.

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

  • 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.

• Your SAML profile is now complete and will show in the Respond UX. Clicking on it will show the details similar to the below (this will vary by vendor and details provided).

• As you can see above, the Profile Name and Domains list can be edited for profiles that have already been configured.

  • You can click the View link on a profile in the SAML Profiles list in your UI to get back to this screen.

6. Test your new SAML Single Sign-On Functionality

• 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 SaaS tenant.

• 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 mapped role permissions applied.

• ADFS login page:

• Note: local authentication can be performed using URL https://<Vectra_Respond_UX_URL/signIn?local=True