# Okta SAML (QUX)
{% hint style="warning" %}
**Please Note:**
This article is **ONLY** for customers configuring SAML SSO for **Quadrant UX (QUX)** deployments using Okta **as the IdP**.
If you are configuring Okta SAML for the Respond UX, please see [Okta SAML (RUX)](https://docs.vectra.ai/configuration/access/saml-sso-rux/okta-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](https://docs.vectra.ai/deployment/getting-started/analyst-ux-options-rux-vs-qux).
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.
{% 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 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.
{% 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 %}
## 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///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.
## Configuration Steps
{% stepper %}
{% step %}
#### [Start SAML Profile Creation in Vectra UI](#id-1.-start-saml-profile-creation-in-vectra-ui)
This will allow you to retrieve the **SP ACS URL** and **SP Entity Identifier** for use in configuring the SAML app in Okta in the next step.
{% endstep %}
{% step %}
#### [Create SAML App in Okta](#id-2.-create-saml-app-in-okta)
Create the SAML App in Okta using the **SP ACS URL** and **SP Entity Identifier** you just retrieved in Step 1.
{% hint style="info" %}
**Please Note:**
* **Vectra SP ACS URL** = **Single sign-on URL** in Okta
* **Vectra SP Entity Identifier** = **Audience URI (SP Entity ID)** in Okta
{% endhint %}
{% endstep %}
{% step %}
#### [Add Required Attribute for the Vectra Role in Okta](#id-3.-add-required-attribute-for-the-vectra-role-in-okta)
In *Okta → Directory → Profile Editor*, choose your newly created app and add a required attribute for the Vectra Role to assign to your groups or users that you plan to allow logging in to the Vectra Quadrant UX.
* It is suggested to use **vectra\_role** for the variable name.
{% endstep %}
{% step %}
#### [Add Attribute Statements in Okta for Use in SAML Assertion](#id-4.-add-attribute-statements-in-okta-for-use-in-saml-assertion)
In *Okta → Applications → Your newly created app → General → Edit SAML Settings*, add **Attribute Statements** for these **REQUIRED** attributes that Vectra **MUST** see in SAML assertions:
* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
* Map to `user.email` in Okta.
* `https://schema.vectra.ai/role`
* Map to `appuser.vectra_role` in Okta.
* If you didn't use `vectra_role` as the variable name, use whatever variable name you created in step 3 but precede it by `appuser.` as in our example.
{% endstep %}
{% step %}
#### [Assign Users or Groups to Your Okta SAML App](#id-5.-assign-users-or-groups-to-your-okta-saml-app)
In *Okta → Applications → Assignments*, assign users or groups to your newly created app.
* For each user or group you add, enter the standardized Vectra role name that you want to map to the user or group. This standardized name can be found in *Configuration → ACCESS → Roles* when on the edit screen for a role.
* For example, the built in **Security Analyst** role has a standardized name of `security_analyst` :
{% endstep %}
{% step %}
#### [Download SAML Metadata From Okta](#id-6.-download-saml-metadata-from-okta)
To complete the SAML profile in Vectra in the next step, download the SAML metadata XML file from Okta.
{% endstep %}
{% step %}
#### [Complete Vectra Configuration](#id-7.-completing-vectra-configuration)
To complete the SAML profile in Vectra, upload the SAML metadata you just downloaded from Okta in the Vectra SAML profile creation screen.
{% hint style="info" %}
**Please Note:**
At this point the Vectra configuration is complete.
If you need to login with a local user account after SSO is configured you can edit the URL you use to login to Vectra.
* Local user login that bypasses the SAML flow is still available by adding `/login/?local=True` to the end of your Quadrant UX login URL.
* An example looks like this: `https://[ip_or_hostname]/accounts/login/?local=True`
* It is recommended to warn any existing users that you will be implementing SSO and that local login will be available using the modified URL should any issues arise.
{% endhint %}
{% endstep %}
{% endstepper %}
### 1. Start SAML Profile Creation in Vectra UI
* 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).
{% 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 configure the IdP side and retrieve the required metadata XML file needed to complete the Vectra configuration.
{% hint style="info" %}
**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.]
{% endhint %}
### 2. Create SAML app in Okta
* Navigate in Okta to *Applications → Applications* and click on **Create App Integration**.
* Choose **SAML 2.0** and click **Next**.
* On the **Create SAML Integration** General Settings tab, enter a name for the application such as **Vectra Quadrant UX**.
* We've configure the App Visibility settings to not show the app to Okta users to discourage IdP initiated login attempts as they are not supported per the Notes of Interest earlier in this article.
* Once done filling in this page, click **Next**.
* On the **Configure SAML** tab enter the **SP ACS URL** and **SP Entity Provider** you retrieved from Vectra earlier as follows:
* **SP ACS URL** = **Single sign-on URL** in Okta.
* **SP Entity Identifier** = **Audience URI (SP Entity ID)** in Okta.
* All other settings on this page can be left at their defaults.
* Click **Next** at the bottom of the page.
* On the final **Feedbac**k tab, enter what you wish to provide feedback to Okta and click **Finish**.
### 3. Add Required Attribute for the Vectra Role in Okta
Now we need to create a new Okta directory profile attribute for your SAML app you just created. This new attribute will hold the Vectra Role and is required.
* In Okta, navigate to *Directory → Profile Editor → Your new app* and click **+ New Attribute**.
* Data type: String (default).
* Display name: **Vectra Role** or whatever you want to call the attribute.
* Variable name: `vectra_role` or whatever you want to call the variable.
* Description: enter an optional description.
* Attribute required: Yes
* All other field can be left at their defaults.
* Click **Save**.
### 4. Add Attribute Statements in Okta for Use in SAML Assertion
Vectra requires specific attributes in the SAML assertion and Okta needs to be configured for these in your newly created SAML app.
* In *Okta → Applications → Your newly created app → General → Edit SAML Settings*, add **Attribute Statements** for these **REQUIRED** attributes that Vectra **MUST** see in SAML assertions:
* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
* Map to `user.email` in Okta.
* `https://schema.vectra.ai/role`
* Map to `appuser.vectra_role` in Okta.
* If you didn't use `vectra_role` as the variable name, use whatever variable name you created in step 3 but precede it by `appuser.` as in our example.
* These should be added to the **Attribute Statements (Optional)** area, **not** the **Group Attribute Statements (Optional)** area below that.
* Click **Next** and then **Finish** on the next screen.
### 5. Assign Users or Groups to Your Okta SAML App
Existing Okta users or groups can be assigned to the app. Since we now have a required attribute that doesn't normally exist in the Okta directory added to the app, when the user or group is assigned to the app, Okta will prompt you to enter the Vectra Role (only input the standardized role name (see below) from Vectra) that you want assigned to that user or group.
#### Vectra Standardized Role Names (Required)
* Later portions of this overall step will require the Vectra Standardized Role Name.
* To see the standardized role names in the Vectra Quadrant 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` .
* Default standardized role names are as follows:
* `admins`
* `read_only`
* `restricted_admins`
* `security_analyst`
* `setting_admins`
* `super_admins`
{% hint style="info" %}
**Please Note:**
Only a single value is accepted for the Role on the Vectra side when the SAML assertion is presented by the user agent.
* If multiple roles are sent, the 1st one Vectra sees will be assumed to be the correct role to map the user to.
{% endhint %}
#### Okta Users and Groups - Utilizing existing or creating new and assigning to the SAML app
* If you wish to use existing users and groups that already exist in Okta to determine which users will get access to Vectra, that is fine.
* To create new users or groups in Okta specifically for use with the Vectra Quadrant UX, simply create those users or groups as you usually do in Okta.
* Now we will move on to assigning the users or groups to the SAML app. This will cause Okta to ask for the Vectra Role (using the Standardized Role Name).
* The process to add a user to the application is essentially the same as adding a group but you operate on the user object instead of the group.
* In our example below we will use a group.
* In Okta, navigate to *Applications → Applications → Your SAML app* and click **Assign** and then **Assign to Groups**.
* In the pop up window that follows, select your group that you wish to assign to the SAML application.
* In our case, we have pre-created a **Super Admins** group that we wish to use for our Vectra Super Admins.
* Click **Assign** on the Okta group.
* Input the Vectra **Standardize Role** name you collected earlier in this overall step.
* You **MUST** put the **Standardized Role** name in exactly as you saw it in Vectra.
* In our example, we are inputting `super_admins`.
* Click **Save and Go Back**.
* Complete this same process for any remaining Groups or Users you wish to assign to the SAML application.
### 6. Download SAML Metadata From Okta
Vectra needs an XML SAML Metadata file from your Okta SAML app that includes the signing certificate to be able to complete the SAML profile in Vectra.
* In Okta, navigate to *Applications → Applications → Your SAML app* and click on the **Sign on** tab of you SAML app.
* Scroll down to the **SAML Signing Certificates** area and click on **Actions** on the right and then click on **View IdP metadata**.
* On the web page that opens in a new tab you will see the IdP metadata.
* Use your web browsers option that allows you to save the page, and save the contents to a filename of your choice.
* This data should download as a .xml file.
* After downloading the IdP Metadata you can complete the configuration back in the Quadrant UX.
### 7. Completing Vectra Configuration
* 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 `user@company.com`, 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.
{% hint style="info" %}
**Please Note:**
After SAML configuration, local login using username/password is still supported via a different URL constructed as follows:
* `https///accounts/login/?local=True`
* For users not participating in SSO, please ensure they have this new URL to login to Vectra.
{% endhint %}
* 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.
## Video Demo of Logging in to Okta via SAML SSO
{% embed url="" %}
