Keycloak SAML (RUX)
Please note!!
This article is ONLY for customers using Vectra's Respond UX (RUX) to configure SAML SSO with Keycloak as the IdP.
While similar, there are some differences in the implementation for customers using the Quadrant UX. The Respond UX requires different SAML claims than the Quadrant UX when setting up SAML. If you are unsure which UX you are using, please see: Vectra Analyst User Experiences (Respond vs Quadrant) for more information.
Quadrant UX IdP Specific Articles
If you are configuring SAML for the Quadrant UX, please see the following articles (instead of this article):
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.
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 that should be mapped 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.
SAML 2.0-based Single Sign-On to the Respond UX
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.
SAML SSO Support for the Respond 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 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.
An example looks like this: https://[unique_customer_id].uw2.portal.vectra.ai/signIn?local=True
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.
Requirements if you already know Keycloak and SAML well:
For customers who are familiar with Keycloak and SAML setup, this section will give the basic requirements for configuration. There are many ways that Keycloak can be configured, but ultimately, all that matters is that any signed valid SAML assertion sent by a client that contains the claims Vectra requires will work. Feel free to deviate from the method used in the more detailed steps that follow this section, if your organization manages Keycloak differently.
Create SAML profile in Vectra UI (same steps as in the more detailed explanations below).
This is done in Configuration > Access > External Authentication in the Vectra UI.
You will need the SP ACS URL and SP Entity Provider from the Vectra SAML setup dialog to create the Keycloak client.
To complete this profile, in Realm settings > General > Metadata in Keycloak, you'll need to copy the "SAML 2.0 Identity Provider Metadata" URL and enter it in the Vectra UI.
Any domains that will map to this IdP will also need to be part of the Keycloak profile in Vectra.
Configure a Keycloak SAML client using the SP ACS URL and the SP Entity Provider from the Vectra SAML configuration dialog.
The "Client ID" in Keycloak will need to be the "SP Entity Provider" from Vectra.
For the "Home URL", enter the URL of your Vectra RUX tenant.
The "Valid redirect URI" in Keycloak will need to be the "SP ACS URL" from Vectra.
Configure Keycloak to send the following claims as part of the SAML assertion that will be sent from the Client (user's browser) to Vectra.
"emailaddress"
This will need to be email address of the user that you will allow into your Vectra deployment.
"name"
The display name of the user you wish to map.
"role"
Please note that only a single value is accepted for this value. If multiple roles are sent, the 1st one Vectra sees will be assumed to be the correct role to map the user to.
These roles must precisely match the "Standardized Name" of a Vectra role.
For example a Super Admin is "super_admins" for the Standardized Name of the Vectra role.
Once the Vectra SAML configuration is saved and Keycloak is configured, you can test SAML SSO to your Vectra tenant.
Steps to Integrate Keycloak (IdP) with Vectra (SP)
First we'll need to start the creation of the SAML authentication profile in your Vectra UI.
Next we'll copy the standardized role names from Vectra that you will later assign to users/groups in Keycloak.
On the Keycloak side, you'll need a realm that you can use.
The specifics of realm configuration in Keycloak are not covered in this guide.
Please refer to Keycloak documentation if you need to configure a new realm for use with Vectra.
In Realm settings > General > Metadata in Keycloak, you'll need to copy the "SAML 2.0 Identity Provider Metadata" URL and save this to complete the Vectra SAML authentication profile later.
Next a client will need to be setup in your Keycloak Realm to support Vectra as a Service Provider (SP).
Roles will need to be created in Keycloak that use the "Standardized Name" of a role in Vectra.
Groups can be used in Keycloak to map users to these roles.
After saving the metadata URL and domains list for the profile in Vectra, the profile is complete and you can now use SAML SSO to log in to your Vectra UI.
Creating SAML Profile in the 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.
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.
Gathering Standardized Role Names from Vectra UI
Navigate in your Vectra UI to Configuration > Access > Roles and edit an entry:
In the above case we are examining the "Security Analyst" role (the "Role Name") and you can see the "Standardized Name" is "security_analyst".
PLEASE NOTE:
Role claims that are assigned in Keycloak that will be sent as part of a SAML assertion MUST use the standardized name from Vectra and not the role name.
If the role name is used instead, the login will fail.
Please note that only a single value is accepted for this value.
If multiple roles are sent, the 1st one Vectra sees will be assumed to be the correct role for the user.
At this time, the creation of custom roles is not supported in the Respond UX.
Default standardized names for Vectra roles:
Admin
admins
Auditor
auditor
Global Analyst
global_analyst
Read-Only
read_only
Restricted Admin
restricted_admins
Security Analyst
security_analyst
Setting Admin
setting_admins
Super Admin
super_admins
Make note of the standardized names for Vectra roles for later configuration as claims within Keycloak.
Keycloak (IdP) Configuration Guidance
Client Creation
In your Keycloak admin GUI, navigate to Manage > Clients and click "Create client".
Choose the "SAML" option for "Client type".
Paste in the "SP Entity Provider" you gathered earlier from the Vectra UI for the "Client ID".
Give this client a name and optional description and then click "Next" at the bottom.
In the "Login settings" screen for your client, enter the following:
For the "Home URL", enter the URL of your Vectra RUX tenant.
Paste in the "SP ACS URL" you gathered earlier from the Vectra UI for the "Valid redirect URIs" entry.
Click "Save" at the bottom of your screen.
Update Client Settings
You should be in the now more detailed settings for your client, if not, find your client in the list of clients and click on it to check and configure other options.
The default "Settings" should be fine but in case they are ever changed, please ensure the "SAML capabilties" and "Signature and Encryption" settings are configured as in the below screenshot.
In the "Keys" tab, the default has this configured but please ensure that "Client signature required" is unchecked as you see in the below screenshot:
Add Roles to Client
Repeat as necessary for all Vectra roles you intend to use in your deployment:
On the "Roles" tab, click "Create role" and enter the Vectra "Standardized Name" of a role you will map users or groups to and an optional description, and then click "Save"
You can leave the "Attributes" and "Users in role" blank for now.
When done adding all the roles you will be using, you can see the list on the "Roles" tab of your client details.
In our example below, we have 3 roles that we will be using:
Modify Client Scope
Click into "Client scopes" and remove any entry except the scope dedicated to the client you are adding.
In this example below, we are deleting the "role_list" entry.
Click into the "urn:amazon:cognito..." entry that represents the client scope for your client.
Click "Configure a new mapper"
Configure Mappers for the Roles
Configure the following 3 mappers:
When done with this you should have something that looks like this:
Move to the "Scope" tab and uncheck the "Full scope allowed" option so that it looks like this:
Assign Role to Groups (repeat as necessary)
Now you simply need to go to your groups in Keycloak, find the group you wish to add the Vectra role to, and the assign the role to the group.
In the below example we add the super_admins role to a test group.
You will need to search by client/role that you added earlier.
Repeat this to assign a Vectra role to each group you want to enable for SSO to your Vectra instance.
Collect Metadata Retrieval URL for Vectra
Vectra will require the IdP metadata URL to allow download of the federation metadata that includes the signing certificate.
In Realm settings > General > Metadata in Keycloak, you'll need to copy the "SAML 2.0 Identity Provider Metadata" URL and save this to complete the Vectra SAML authentication profile later.
This will be input in the "IDP Metadata URL" box in the Vectra SAML authentication profile.
This URL must be accessible from the internet so Vectra can retrieve the metadata required to complete the SAML profile.
Completing Configuration in the Respond UX
After Keycloak configuration and copying the SAML 2.0 Identity Provider Metadata URL in Keycloak, you can complete the configuration back in the Vectra UI.
Switch back to the browser tab or window with your Vectra UI and the partially completed "Create SAML Profile" dialog box.
Paste the Keycloak "SAML 2.0 Identity Provider Metadata" URL into the "IDP Metadata URL" in 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.
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 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.
Last updated
Was this helpful?