Okta SAML (QUX)
**Please note!! - This article is ONLY for customers using Vectra's Quadrant UX. 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 . If you are configuring SAML for the Respond UX, please see the following articles (instead of this article):
Okta SAML SSO Support for the Quadrant 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 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 using username/password after SAML configuration is still supported via a different URL constructed as follows:
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.
SAML Service Provider (SP) Initiated Flow
This example flow diagram uses Azure as the IdP but Okta works the same way as any other 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.
Overview of Required Steps to Setup SSO with Okta
Start creating a SAML Profile in Vectra Quadrant UX and retrieve the SP ACS URL and SP Entity Identifier.
Create a SAML App in Okta for Vectra using the SP ACS URL and SP Entity Identifier you just retrieved.
SP ACS URL = "Single sign-on URL" in Okta
SP Entity Identifier = "Audience URI (SP Entity ID)" 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.
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"
"https://schema.vectra.ai/role" - Map to "appuser.vectra_role"
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
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.
Download the SAML Metadata from the Okta SAML app and complete the SAML config on the Vectra side.
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 your Vectra URL:
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.
1. Start creating SAML profile in Vectra Quadrant UX
First we'll need to create the SAML Authentication Profile in the Vectra Quadrant UX.
Only one SAML profile can be active at any given time.
Open a new browser tab and log in as you normally do and navigate to Manage > 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 Okta. Make note of these values for later use with Okta.
The SP is the Service Provider (Vectra)
Leave this tab in your browser open and proceed in another tab or window to Okta configuration so that you can complete the required Okta configuration and download the SAML metadata and complete the Vectra SAML profile for Okta.
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 "Feedback" tab, enter what you wish to provide feedback to Okta and click "Finish"
3. Add Vectra role attribute to your Okta SAML app you just created
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 Vectra required attribute statements to your Okta SAML app.
Vectra requires specific attributes in the SAML assertion and Okta needs to be configured for these in your newly created SAML app.
In Okta, navigate to Applications > Applications > your newly created SAML app > General Tab and click "Edit" on "SAML Settings" and 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"
"https://schema.vectra.ai/role" - Map to "appuser.vectra_role"
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 Okta users or groups to your 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 Manage > 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
Please note that 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.
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 and Complete SAML Configuration in Vectra
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.
Switch back to the browser tab or window with your Quadrant UX.
Upload the IdP Metadata XML file into the "Create SAML Profile" dialog box.
Fill in the "Profile Name" with a name of your choice.
Click "Create" and you have completed all the required steps to enable SAML 2.0 based SSO to the Vectra Quadrant UX using Okta as the IdP.
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 in via SSO" button on the login page for your Vectra 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 redirected to your IdP for authentication and then redirected back to Vectra.
Local login using username/password after SAML configuration is still supported via a different URL constructed as follows:
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.
Below you will find a video demonstrating the Okta SAML SSO login flow
Last updated
Was this helpful?