SAML 2.0-based Single Sign-On to Vectra Detect UI
- Customers can now setup SSO federation to a SAML 2.0-based identity provider
- For release 6.2, Vectra has validated Azure AD, others are planned to follow
- Once federated, already authenticated users will get automatically logged in when they load the Detect URL
- Unauthenticated users will get redirected to their IdP’s login portal
- Features like password policies and multi-factor authentication will be enforced by the IdP
- Once authenticated, users are assigned the application role defined in the IdP
- This will map to a role (and permissions) defined on the Vectra Brain
- Local login is still supported via a different Detect URL constructed as follows
- https://<ip or hostname>/accounts/login/?local=True
SAML SSO Support for Detect - Notes of Interest
- Please ensure the users are only mapped to one Vectra Cognito Detect Role in the IdP
- If a user is mapped to more than 1 role, the user may not be assigned the preferred 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 Detect UI, they are taken to a screen where they can log in locally or click a link to "Log in via SSO"
- API keys are not supported for SAML users
- For API use, Vectra recommends local accounts or other external authentication sources where the role tied to a user is managed inside of Cognito
- GUIDs assigned to roles in the IdP Manifest need to be unique
- These can be easily generated using online tools such as http://guidgenerator.com
- The SessionNotOnOrAfter SAML parameter will be supported to invalidate user sessions and require a user to re-authenticate
- This is currently targeted for the 6.3 release
SAML Service Provider (SP) Initiated Flow
SAML SSO Sample Role JSON for IdP
Please see the attachment to this article (at the bottom of this page) for a full block of JSON representing all default roles as of V6.2 that can be pasted into the IdP Manifest.
"description": "Security Analyst",
"displayName": "Security Analyst",
Release Demo for this Feature
Steps to enable SAML SSO for Detect with Azure AD
Configuring the Azure AD Application and Cognito Detect
Select “Enterprise applications” from AzureAD
Click the "+ New application" button
Click the "+ Create your own application" button (this is not a Gallery application)
Give it a name like "Cognito Detect SSO" or any name you desire
Use the "Integrate any other application you don't find in the gallery option"
Click "Create" at the bottom of the dialog
Select “Single sign-on" from left or "Set up single sign on" from the Getting Started section
Select “SAML” from the single sign-on method list
- Next we'll need to create the Cognito Detect SAML Authentication Profile
Open a new browser tab and log in to Detect 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 Entity Identifier and SP and ACS URL will be displayed there for entry into the corresponding fields in the AzureAD SAML SSO setup flow
- Next we will configure the Azure application with these values
Go back to your AZure tab in your broswer and edit the Basic SAML configuration in the newly created Azure application
Vectra's "SP Entity Provider" URI should be used for the Azure "Identifier (Entity ID)"
Vectra's "SP ACS URL" should be used for the Azure "Reply URL (Assertion Consumer Service URL)"
The rest of the Basic SAML Configuration can be left blank
Click the "Save" button at the top of the Basic SAML Configuration window
After this is saved, you can close the window. You will be asked if you want to test now. Select "No, I'll test later"
- Next we will complete the External Authentication Profile in Detect
- While still in your Azure tab, scroll down to section 3 "SAML Signing Certificate"
- Download the "Federation Metatdata XML" file from Azure AD
- Go back to the Detect tab in your browser
Click "Select a file" next to "Upload IDP Metadata XML File" in the "Create SAML Profile" window
Fill in the "Profile Name" with "Azure AD" or any name you desire
Configure the Role Claim and Roles in Azure AD
- We'll begin by creating the the "user.assignedroles" claim
- In you Azure AD tab, select "Edit" in section 2 "User Attributes & Claims"
- Select "Add a new claim"
- Enter "https://schema.vectra.ai/role" in the "Name" section
For “Source attribute”, select “user.assignedroles”
Save the claim
- Azure AD defaults to including a "user.userprincipalname" claim (which is required) but if you do not have this or are using a different IDP, please ensure that you also create this claim similarly to how to you created the "user.assignedroles" claim
- This claim's name should be "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
- Next we will configure roles in the Manifest
- In the Azure AD Admin Center
- Select "Azure Active Directory"
- Select "App Registrations"
- Select "All Applications"
- Select your newly created application
- Select "Manifest" from the sidebar
- Make note of the location of the green arrow in the Manifest below, this is where we will begin to enter role definitions once you have collected the Standardized Names for your Detect Roles
- Back in your Cognito Detect tab, 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"
- Back in the Azure AD Manifest tab, add a new entry for each role in Cognito Detect
There will be 2 default roles from Microsoft of "User" and "msiam_access" which can be left alone
Create new roles under the "msiam_access" role by copying and pasting the role blocks and editing the content to match your actual roles and the descriptions/names you want to use for them
Be sure to use the Standardized Name for the "value" field that you collected previously
- The "description" and "displayName" can be anything that you want to refer to inside the IdP for the Detect roles you will be assigning to your users
- Also remember that the "id" needs to be globally unique inside of your Azure AD account
- The "id" can easily be generated using an online tool such as http://guidgenerator.com
- You can use the defaults as the site loads and just click "Generate some GUIDs!"
Assign Users and Groups to Roles in your Azure AD Application
In the Azure Active Directory pane, select Enterprise applications from the Azure Active Directory left-hand navigation menu
Select All applications to view a list of all your applications
- Select your newly create Detect Application
- Select the "Users and groups" from the sidebar or "Assign users and groups" from the panes
- Select the "+ Add user" button
- Add a user
- Choose a role that you just added to the Manifest
- The users and groups you have configured will show as below
Test your new SAML Single Sign-On Functionality
- The Detect URL you have been previously using now works with SAML SSO
- When a user access the URL and does not already have a valid authentication session open, they will be redirected to the IdP
- Once through the authentication flow, or if the user was already authenticated previously and still has a valid SAML session, they will land directly on the Detect Security Dashboard
- If the user logs out, or their session expires due to the inactivity timeout in Detect (defaults to 15 min but can be changed in Settings > General), they will be directed to the local login screen where they can login locally or "Log in via SSO"