ADFS SAML (RUX)
Please note!!
This article is ONLY for customers using Vectra's Respond UX (RUX) to configure SAML SSO with ADFS.
If you are configuring ADFS SAML for the Quadrant UX, please see Setup SAML SSO with ADFS (Quadrant UX) instead of this article.
While similar, there are some differences in the implementation for customers using the Quadrant UX. The Respond UX requires different SAML claims than the Quadrant UX when setting up SAML . If you are unsure which UX you are using, please see: Vectra Analyst User Experiences (Respond vs Quadrant) for more information.
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 that should be mapped 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.
SAML 2.0-based Single Sign-On to the Respond UX
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.
SAML SSO Support for the Respond UX - 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.
An example looks like this: https**://[unique_customer_id].uw2.portal.vectra.**ai/signIn?local=True
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.
SAML Authentication Workflow with ADFS
Configuring ADFS for Vectra RUX
1. Get SAML Profile Information for ADFS
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 > 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 that 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
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 Cognito Detect 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
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, 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 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.
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 2^(nd) 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
Note: for each role assignment a rule needs to be created.
Note: Please 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
Attachments
Last updated
Was this helpful?