DeepSurface: Authentication Providers

Documentation
Installation Guide
Overview
Let DeepSurface Host For You
Getting Started
System Requirements
Self Hosted Quick Start - Installing to Cloud Platforms
Self Hosted - Installation Using an OVA
Registration, Package Installation, and Initialization
First Steps After Initialization of the Console
Deployment Options
Main and Subordinate Consoles
Agent-Based Deployment
User Managed Scan Deployment
Credentialed Scanning Deployment
Mixed Environment
Deployment Tools
Active Directory Group Policy
Microsoft Endpoint Configuration Manager (part of InTune)
Tanium Deploy
HCL BigFix
Ivanti
Virtual Machines
VMWare
Virtual Box
VirtualBox Guest Additions
AWS EC2 (BYOL)
AWS EC2 (Usage Based)
Azure Cloud
Google Cloud
Additional Items to Consider
Main Console Server Certificates
LDAP
TOFU
Clock Sync
DeepSurface Commands
Multiple Vulnerability Sources
API Documentation
User Guide
Reporting
Dashboards
Exports
Risk Insight
Hosts
Patches
Vulnerabilities
Vulnerability Instances
Users
Remediation Workflow Manager
Plans
Settings
Integrations
Workflow
Exporting
Accepted Risk Plans
Accepted Risk Workflow
Explore
Model
Paths
Activity
Tasks
Configuration Alerts
Scan Logs
Notification Settings
Scanning
Status
Agents
User Managed
Credentialed Scanning Settings
Credentials
Scan Groups
General Settings
Cloud Scanning
Network Connectivity
Subordinates
Vulnerability Sources
Setup
Sensitive Assets: Polices
Sensitive Assets: Manual
Admin Settings
SMTP Settings
Certificates
Outbound Proxy
Authentication Providers
Users
Tags
Integrations Guide
Vulnerability Sources
CrowdStrike Spotlight
SentinelOne
Carbon Black Cloud
Microsoft Defender for Endpoint
Wazuh
Lansweeper Cloud
Nessus API
Tenable.io API
Security Center/Tenable.sc API
Rapid7 InsightVM API
Qualys API
Nozomi Guardian
Eclypsium
AWS Inspector
Remediation
Jira Software
Tanium (BETA)
Authentication Providers
LDAP (Active Directory)
SAML (Azure Active Directory)
SAML (Google)
SAML (Okta)
PAM
CyberArk
Delinea (Thycotic)
Microsoft LAPS
Security Guide
Firewall Configuration
Base Network Requirements
Agent Network Requirements
Credentialed Scanning Network Requirements
API Network Requirements
How DeepSurface Scans Work
Domain (LDAP) Scanning
Host Scanning Routine
Reasons for the Administrative Access Requirement
Endpoint Protection Considerations
Other Items
Scope of Data Storage and Retention
IPS/IDS Considerations
Logging
Resetting the DSADMIN password
Product Information
Changelogs
Open source Licenses
End User License Agreement (EULA)

This section of the application is where you can optionally configure third-party services to act as identity providers for the DeepSurface web console. Once an authentication provider is created, existing or new user accounts can be associated with the new provider, causing DeepSurface to use the provider to authenticate those specific user accounts.

To access the authentication providers page, navigate to Setup > Authentication > Providers, which should present a page like:

provider

Click on the big '+ Authentication Provider' button to add an authentication provider. You will see a screen like the following.

provider

Autoprovision Authentication Provider

If you have any SAML 2.0 authentication providers configured, you may choose to allow DeepSurface to automatically create a user that exists in your IDP of choice. At this time, we allow you to choose one SAML 2.0 Authentication provider to be configured at a time.

General configuration guidelines

The following are generic guidelines that apply to any Id provider you might want to set up.

Entity ID

Whenever prompted for the entity id for your saml application, enter the full Assertion Consumer Service URL as given in the Add Authentication provider form.

Attribute mapping

To ensure a good matching between user data in DeepSurface and in your identity provider some attributes mapping is required. The following table summarizes what mapping would suffice to get the best onboarding possible for new users.

DeepSurface attributes	IdProvider attributes
saml_subject	Username
emailaddress	Email Address
givenname	Given Name
surname	Family Name

Each authentication provider type has somewhat unique behaviors and requirements that you can learn more about in the provider's specific documentation page, as listed below:

LDAP for Active Directory

The Lightweight Directory Access Protocol (LDAP) can be used to communicate with Microsoft Active Directory service to authenticate web console users. Under this authentication provider configuration, a user's username and password must match their domain username and password exactly.

SAML 2.0 with Azure Active Directory

DeepSurface can be configured to leverage a third-party identity provider (IdP) to authenticate users when they access the DeepSurface web management console. One option is to use Microsoft's Azure Active Directory as SAML-based IdP that is available with an Azure subscription. Use the following steps to create a new DeepSurface Authentication Provider configuration to enable this integration.

Create the Authentication Provider record in DeepSurface
- Navigate to Setup > Authentication > Providers
- Click the button "+ Authentication Provider" in the top-right of the screen
- In the pop-up, select "SAML 2.0" in the drop-down
- Fill in an appropriate label for this authentication provider (such as "Azure AD")
- Enter an appropriate value for the domain name of the "ASSERTION CONSUMER SERVICE URL" field. This domain name must match the one users will navigate to when accessing DeepSurface.
- Click the "copy to clipboard" icon next to the ASSERTION CONSUMER SERVICE URL field to make a copy of this ACS URL. Paste this in a temporary location, such as a text editor, as we'll need this in later steps.
- Do not enter any values in the METADATA XML at this stage. We'll come back to this in a minute.
- Save the new authentication provider.
Configure Azure AD
- Log in to Azure Portal and navigate to Azure Active Directory from the Azure services menu.
- Click on the Enterprise Applications in the left hand menu and click on the "+ New application button".
- It might be easiest to use a template to setup your first application, to do so, enter "toolkit" into the search bar and click on the "Azure AD SAML Toolkit" application and give it a friendly name such as "DeepSurface".
- Enter a friendly name in the App name field, such as "DeepSurface". Select other options as appropriate and click Next.
- Once the app is created and you are on the app's setup screen, click on the "Single Sign On" menu item on the left.
- You will see several panes, the first one to focus on is the "Basic SAML Configuration" pane, click the "Edit" icon in the top left of this pane to edit the details
- In the edit form, enter the ASSERTION CONSUMER SERVICE URL you obtained in step 1 above into both the Identifier (Entitiy ID) and Reply URL (Assertion Consumer Service URL) fields. Optionally, you can add the login URL, but this is probably not necessary for this configuration. Do not modify any other fields.
- Next, in the "SAML Signing Certificate" pane, locate the "Federation Metadata XML" download button and save that for use in step 3 below.
- To add users to this application click on the "Users and Groups" in the left menu and click the "+ Add User/Group" Button to add users
- Click on the "None Selected" to bring up a list of all of your AD users and select whichever ones you want to add to this application.
Finalize DeepSurface Authentication Provider
- Return to the Setup > Authentication > Providers area in DeepSurface and edit the provider created in step 1l
- Upload or paste the XML file into the METADATA XML field, as obtained from Azure AD in step 2.
- Save the updated authentication provider record.
Create DeepSurface users associated with the Azure AD authentication provider
- In DeepSurface, navigate to Setup > Authentication > Users.
- For any user who needs to log in via Azure AD, create a user with exactly the same username they would use with Azure AD. Be sure to select your newly created authentication provider in the dropdown at the top of the user editing pop-up.
Test Azure-based login
- To test a DeepSurface user linked with an Azure AD authentication provider, first log out of DeepSurface.
- On the login form, enter the username of a user who should be authenticated against Azure AD, and click Next.
- You should now be redirected to Azure AD. Log in with your Azure AD credentials.
- After successfully authenticating to Azure AD, your browser should be redirected back to DeepSurface and you should be automatically logged in to the DeepSurface console.

For more information, consider consulting the following:

SAML

Having trouble? Don't hesitate to contact support.

SAML 2.0 with Google

DeepSurface can be configured to leverage a third-party identity provider (IdP) to authenticate users when they access the DeepSurface web management console. One option is to use Google's service as SAML-based IdP that is available with a G Suite subscription. Use the following steps to create a new DeepSurface Authentication Provider configuration to enable this integration.

Create the Authentication Provider record in DeepSurface
- Navigate to Setup > Authentication > Providers
- Click the button "+ Authentication Provider" in the top-right of the screen
- In the pop-up, select "SAML 2.0" in the drop-down
- Fill in an appropriate label for this authentication provider (such as "Google")
- Enter an appropriate value for the domain name of the "ASSERTION CONSUMER SERVICE URL" field. This domain name must match the one users will navigate to when accessing DeepSurface.
- Click the "copy to clipboard" icon next to the ASSERTION CONSUMER SERVICE URL field to make a copy of this ACS URL. Paste this in a temporary location, such as a text editor, as we'll need this in later steps.
- Do not enter any values in the METADATA XML at this stage. We'll come back to this in a minute.
- Save the new authentication provider.
Configure Google
- Log in to G Suite's admin interface and navigate to Apps > Overview > Web and mobile apps.
- Click the "Add App" dropdown and select "Add custom SAML app".
- Enter a friendly name in the App name field, such as "DeepSurface". Select other options as appropriate and click Next.
- Next, click the "Download Metadata" button and save this file for use in Step 3 below.
- On the Google screen, enter the ASSERTION CONSUMER SERVICE URL you obtained in step 1 above into both the ACS URL and Entity ID fields. Do not modify any other fields, and then click Next.
- On the fourth Google screen, you may click Finish without any other changes.
- Next, you should arrive at a summary screen for your newly created SAML app. Click on the "User access" tile to grant users access to the DeepSurface application in Google. You may either enable the app for everyone, or use the panel on the left side to search for specific Google Groups or users and grant access to those groups and users selectively. Save your selections when completed.
Finalize DeepSurface Authentication Provider
- Return to the Setup > Authentication > Providers area in DeepSurface and edit the provider created in step 1l
- Upload or paste the XML file into the METADATA XML field, as obtained from Google in step 2.
- Save the updated authentication provider record.
Create DeepSurface users associated with the Google authentication provider
- In DeepSurface, navigate to Setup > Authentication > Users.
- For any user who needs to log in via Google, create a user with exactly the same username they would use with Google. Be sure to select your newly created authentication provider in the dropdown at the top of the user editing pop-up.
Test Google-based login
- To test a DeepSurface user linked with an Google authentication provider, first log out of DeepSurface.
- On the login form, enter the username of a user who should be authenticated against Google, and click Next.
- You should now be redirected to Google. Log in with your Google credentials.
- After successfully authenticating to Google, your browser should be redirected back to DeepSurface and you should be automatically logged in to the DeepSurface console.

For more information, consider consulting the following:

Having trouble? Don't hesitate to contact support.

SAML 2.0 with Okta

DeepSurface can be configured to leverage a third-party identity provider (IdP) to authenticate users when they access the DeepSurface web management console. One option is to use Okta's service as SAML-based IdP. Use the following steps to create a new DeepSurface Authentication Provider configuration to enable this integration.

Create the Authentication Provider record in DeepSurface
- Navigate to Setup > Authentication > Providers
- Click the button "+ Authentication Provider" in the top-right of the screen
- In the pop-up, select "SAML 2.0" in the drop-down
- Fill in an appropriate label for this authentication provider (such as "Okta")
- Enter an appropriate value for the domain name of the "ASSERTION CONSUMER SERVICE URL" field. This domain name must match the one users will navigate to when accessing DeepSurface.
- Click the "copy to clipboard" icon next to the ASSERTION CONSUMER SERVICE URL field to make a copy of this ACS URL. Paste this in a temporary location, such as a text editor, as we'll need this in later steps.
- Do not enter any values in the METADATA XML at this stage. We'll come back to this in a minute.
- Save the new authentication provider.
Configure Okta
- Log in to your Okta portal and navigate to Applications > Applications > Create App Integration
- Select SAML 2.0 and click Next
- Enter a friendly name in the App name field, such as "DeepSurface". Select other options as appropriate and click Next.
- On the Okta screen, enter the ASSERTION CONSUMER SERVICE URL you obtained in step 1 above into both the Single sign on URL and Audience URI (SP Entity ID) fields. Do not modify any other fields, and then click Next.
- On the third Okta screen, answer the feedback questions as appropriate and click Finish.
- Next, you should arrive at the new application's "Sign On" tab. In this area, find the link for "Identity Provider metadata" and download it. You may need to right click on the link and select "Save link as..." Store this in a file for use in Step 3 below.
- Finally, navigate to the "Assignments" tab within this application. Use the "Assign" dropdown to select users or groups to assign to the application. This will grant those users or groups access to authenticate to DeepSurface within the Okta platform.

Finalize DeepSurface Authentication Provider
- Return to the Setup > Authentication > Providers area in DeepSurface and edit the provider created in step 1.
- Upload or paste the XML file into the METADATA XML field, as obtained from Okta in step 2.
- Save the updated authentication provider record.
Create DeepSurface users associated with the Okta authentication provider
- In DeepSurface, navigate to Setup > Authentication > Users.
- For any user who needs to log in via Okta, create a user with exactly the same username they would use with Okta. Be sure to select your newly created authentication provider in the dropdown at the top of the user editing pop-up.
Test Okta-based login
- To test a DeepSurface user linked with an Okta authentication provider, first log out of DeepSurface.
- On the login form, enter the username of a user who should be authenticated against Okta, and click Next.
- You should now be redirected to Okta. Log in with your Okta credentials.
- After successfully authenticating to Okta, your browser should be redirected back to DeepSurface and you should be automatically logged in to the DeepSurface console.

For more information, consider consulting the following:

Having trouble? Don't hesitate to contact support.