# ADFS SAML (RUX)
{% hint style="warning" %}
**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)](https://docs.vectra.ai/configuration/access/saml-sso-qux/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](https://docs.vectra.ai/deployment/getting-started/analyst-ux-options-rux-vs-qux).
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.
{% endhint %}
## 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.
{% hint style="info" %}
**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.
{% endhint %}
## 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://.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.
{% hint style="info" %}
**Please Note:**
The **DNS Name** should be in lowercase in this area and any place you see it in ADFS.
{% endhint %}
* 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](#id-1.-get-saml-profile-information-for-adfs), 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](#id-1.-get-saml-profile-information-for-adfs). 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.**
{% hint style="info" %}
**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.
{% endhint %}
#### 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**.
{% hint style="info" %}
**Please Note:**
For each role assignment a rule needs to be created.
{% endhint %}
{% hint style="info" %}
**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.
{% endhint %}
### 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://
