# Any IdP SAML (RUX) {% hint style="warning" %} **Please Note:** This article is ONLY for customers setting up SAML SSO using Vectra's **Respond UX (RUX)**. 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. If you need SAML setup instructions for QUX deployments see the below. **Quadrant UX Specific SAML articles:** * [Any IdP SAML (QUX)](https://docs.vectra.ai/configuration/access/saml-sso-qux/any-idp-saml-qux) * [ADFS SAML (QUX)](https://docs.vectra.ai/configuration/access/saml-sso-qux/adfs-saml-qux) * [Entra ID (Azure AD) SAML (QUX)](https://docs.vectra.ai/configuration/access/saml-sso-qux/entra-id-azure-ad-saml-qux) * [Okta SAML (QUX)](https://docs.vectra.ai/configuration/access/saml-sso-qux/okta-saml-qux) * [Ping Identity SAML (QUX)](https://docs.vectra.ai/configuration/access/saml-sso-qux/ping-identity-saml-qux) {% endhint %} ## Respond UX IdP Specific Articles Customers with RUX deployments can use SSO with nearly any Identity Provider (IdP) vendor that is SAML 2.0 compliant. Vectra has tested Respond UX interoperability with Azure AD and Okta. Please see the following Respond UX specific articles for IdP specific SAML configuration guidance: * [Setup SAML SSO with Azure AD (Respond UX)](https://docs.vectra.ai/configuration/access/saml-sso-rux/entra-id-azure-ad-saml-rux) * [Setup SAML SSO with Okta (Respond UX)](https://docs.vectra.ai/configuration/access/saml-sso-rux/okta-saml-rux) * [Setup SAML SSO with Keycloak (Respond UX)](https://docs.vectra.ai/configuration/access/saml-sso-rux/keycloak-saml-rux) * [Setup SAML SSO with ADFS (Respond UX)](https://docs.vectra.ai/configuration/access/saml-sso-rux/adfs-saml-rux) ## 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 * 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 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. ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-ae2b8d1bb08be8cb845143dbd7a27c38de213bc8%2Fany-idp-saml-rux-1.png?alt=media) ## Configuration ### Start SAML Profile Creation in Vectra UI * First we'll need to create the SAML Authentication Profile. * 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. ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-43357412e28cf8704fae2292b03da1ee7ad5b647%2Fany-idp-saml-rux-2.jpg?alt=media) * 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) {% hint style="info" %} **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)**. {% endhint %} * 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. ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-1321331baa6672002dbfb022a84837eab6629a6d%2Fany-idp-saml-rux-3.jpg?alt=media) ### IdP Configuration The specific steps for configuration with your IdP differ from provider to provider. * Use the SP ACS URL and SP Entity Provider from the previous step to identify Vectra as a Service Provider in your IdP. {% hint style="info" %} **Please Note:** * The below claims should be named exactly as seen in between the quotes (not including the quotes). * Your IdP may have other required claims such as a UUID, etc. These are fine to include back to Vectra but the below are what Vectra requires. {% endhint %} #### Required Claims to Configure in Your IdP {% hint style="info" %} **IMPORTANT** It is important to correctly configure the claims returned from the IdP since during a mismatch, depending on the particular browser's behavior, it may or may not be clear what the cause of a failed login is. The below claims have to match precisely. {% endhint %} * `emailaddress` * This will need to be email address of the user that you will allow into Vectra SaaS. * `name` * The display name of the user you wish to map. * `role` * This will be the standardized name of the Vectra SaaS role for the user. * The *Configuration → ACCESS → Roles* interface will present two fields * **Role Name** - This is the name of the role in Vectra. * **Standardized Name** - This is the standardized name of the role and is required to be in the `role` claim coming from your IdP. ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-51bd49eaf9e37942de8db5c4f4cedb59d3a2f32b%2Ff08e42c616b0a9a7a14305283f5c9a49a3412de991052f5dc7c479ad4fa1df39.jpg?alt=media) {% hint style="warning" %} **Please Note:** * Claims with the role name only will cause a failed login, the standardized name must be used instead! * Only a single value is accepted for this value. If multiple roles are sent, the first one Vectra sees will be assumed to be the correct role to map the user to. {% endhint %} #### Metadata Retrieval * Vectra will require the IdP metadata URL to allow download of the federation metadata that includes the signing certificate. * The name of this URL will vary by IdP. For example, Azure AD refers to this as the **App Federation Metadata URL** **How to find the IdP metadata URL for various IdPs:**
IdPMetadata URL Instructions
Azure ADGo to Enterprise Applications in the Azure AD portal, find and select your app you have configured for SAML use, in the Manage section, select Single sign-on to open the Single sign-on pane, in the SAML Signing Certificate section, find the App Federation Metadata Url and copy it.
ADFSYou can download the SAML metadata document for your ADFS federation server from the following address: https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml
OktaGo to the Admin section of the Okta dashboard. Choose the application, select the Sign On section, and look under the Settings for SAML. The URL should look like: https://<app-domain>.oktapreview.com/app/<application-ID>/sso/saml/metadata
Auth0In the Auth0 dashboard, choose Clients, and then choose Settings. Scroll down, choose Show Advanced Settings, and then look for your SAML Metadata URL. It should look like: https://<your-domain-prefix>.auth0.com/samlp/metadata/<your-Auth0-client-ID>
Ping Identityhttps://documentation.pingidentity.com/pingfederate/pf81/index.shtml#pf_c_connectionfederationmetadata.html
#### User and Group Configuration * Users and Groups in your IdP will need to be mapped to Vectra standardized roles in your IdP. * Only map users and groups that you wish to have access to the Vectra Respond UX. * To see the standardized role names in the Respond UX, 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` ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-adcb9ffbc5018c0a4d724bf9be5ce4ddf4a0a171%2F72d07e1c6f7510a56f413f8e4cef25a8fe473974d58b0146904aeaeb321b14b1.jpg?alt=media) * Default Vectra standardized role names are as follows: * `admins` * `read_only` * `restricted_admins` * `security_analyst` * `setting_admins` * `super_admins` * At this time, the creation of custom roles is not supported in the Respond UX. #### **IdP Completion** {% hint style="success" %} Once you have completed setting up your Vectra tenant as a Service Provider in your IdP (having configured all the required claims), mapped your users and groups to Vectra standardized role names, and have your IdP Metadata URL copied you are ready to move on. {% endhint %} ### Completing Vectra Configuration * After IdP 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. ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-91025e357545dc50b293680fcc47e9697459bfe9%2Fany-idp-saml-rux-6.jpg?alt=media) * 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). ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-ecdc5ea33478f6f211b2e0e84238482387b35af1%2Fany-idp-saml-rux-7.jpg?alt=media) * 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. ## 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 tenant. ![](https://4227135129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHJ1ltuWFvsArFWtevnRn%2Fuploads%2Fgit-blob-9c58aa8dfa48605314bb068cc801b0ae239d6ea4%2Fany-idp-saml-rux-8.jpg?alt=media) * 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.