Accounts and extra configuration

Basic configuration

When you configure LDAP, you obtain the LDAP configuration values, use the ldapedit command to enter the values, enter the user password, and enable LDAP on a SOAR organization.

1. Make sure that you have the following values available. You might need to consult with your LDAP administrator to get the appropriate values for your setup.

   Value	Example
   LDAP server name.	myldap.example.com
   Distinguished Name (DN) of the user account that the SOAR Platform can use to run LDAP queries, such as determining whether the user who is accessing the system is managed by LDAP. The account must have at least Read-Only permission to view all the necessary users. You also need the user password.	"cn=John Smith,cn=Users,dc=Example,dc=com"
   LDAP search root for all directory searches. If not specified, the SOAR Platform attempts to locate and use the Root DSE. If you want to constrain all queries to a sub-tree in the LDAP, you can specify it here. For performance reasons, select the lowest search root in the directory that contains all users and groups that you want included in the queries.	cn=Users,dc=Example,dc=com
   LDAP server port number. Determine whether it is an SSL port, such as port 636.	389 (No SSL)
   LDAP config name.	resilientLDAP
   LDAP domain name. Only used when you have an LDAP configuration with multiple trees and you want to extend LDAP searches to different trees. The LDAP domain name is the name that the platform matches when it receives an LDAP search reference. You must provide the actual hostname for each domain.	sales.division.company.com marketing.division.company.comexecutive.division.company.com

2. Use the ldapedit command to enter the LDAP values. For example, if you use the values in the previous table, the command would be:

   
   sudo resutil ldapedit -name myLDAP -bindname "cn=John Smith,
   cn=Users,dc=Example,dc=com" -host myldap.example.com -port 389
   

   If you are enabling LDAP over SSL/TLS (with port 636), see the LDAP Over SSL/TLS section.

3. When prompted, enter the password of the user to complete the setup.
4. Test the LDAP configuration.

   sudo resutil ldaptest -name myLDAP
   

5. After you complete the configuration, you must enable it in your SOAR organization as follows.
   1. Log in to your organization as an administrator with the permissions to view and modify administrator settings and customization settings.
   2. Click Administrator settings (from the menu by your username).
   3. Click the Organization tab.
   4. Locate the LDAP Authentication section, under Settings.
   5. Switch the indicator to On.
   6. Select the LDAP group that you want to have access to the SOAR organization.

LDAP trees

The SOAR Platform primary LDAP configuration points to a single LDAP tree. By default, all LDAP queries are sent to this tree. If you have an LDAP configuration with multiple trees, you can configure the platform to have a search in this LDAP tree point to a different tree. It is called an LDAP search reference, and it is usually in the form of an LDAP URL, ldap://<domainname>:<port>/<optional parameters>. You need to provide one or more domain names with the host and port. When you have an LDAP reference to ldap://<domainname>, the platform searches for a sub-configuration that has that domain name. When the platform finds a match, it sends the LDAP query to that sub-configuration’s host and port.

The LDAP domain name is the name that the platform matches when it receives an LDAP search reference. The LDAP domain name does not have to be the same as the hostname of that LDAP server.

sudo resutil ldapedit -name salesSub -bindname "cn=John 
Smith,cn=Users,dc=Example,dc=com" -domainname sales.division.company.com -
subdomainof myLDAP -host host1.sales.division.company.com -port 389 

sudo resutil ldapedit -name marketingSub -bindname "cn=John 
Smith,cn=Users,dc=Example,dc=com" -domainname sales.division.company.com -
subdomainof myLDAP -host host2.marketing.division.company.com –port 389 

sudo resutil ldapedit -name execSub -bindname "cn=John 
Smith,cn=Users,dc=Example,dc=com" -domainname sales.division.company.com 
-subdomainof myLDAP -host host3.executive.division.company.com –port 389

If prompted, enter the password of the user to complete the setup.

Using the examples in the basic procedure, you now have four LDAP configurations. The configuration that is defined in step 2 of the basic procedure is the primary configuration.

sudo resutil configset -key ldap.ref_limit -ivalue <VALUE>

LDAP over SSL/TLS

Additional information

Create a SAML federation

SAML federations are created in the SOAR Platform with the resutil tool. To create the SAML federation, you need the following information from your identity provider.

• Identity Provider Authentication URL
• Identity Provider public certificate

The commands that follow use the following values.

• The authentication URL for your identity provider is https://adfs.example.com/adfs/ls/.
• You copied the Identity Provider's certificate file to the system by using a tool such as scp and the file name of the certificate file is idp.cer in the current working directory.
• The "alias" for the SAML federation is soar.
• The organization name on the SOAR Platform is My Test Org.

  sudo resutil samledit -alias soar -certfile idp.cer -org "My Test Org" 
  -createusers -loginurl https://adfs.example.com/adfs/ls/

• If your identity provider configured a single logout function, you can have the SOAR Platform specify that as well in the samledit command.

  sudo resutil samledit -alias soar -org "Production" -org "Development" 
  -certfile idp.cer -loginurl https://adfs.example.com/adfs/ls/ -logouturl 
  https://adfs.example.com/adfs/ls/

This command prints the SAML federation to the console. It also writes out the following files.

• alias-metadata.xml - SAML XML metadata that can be imported into the Identity Provider to complete the configuration.
• alias-sp-cert.pem - Service Provider certificate that was automatically generated.

By default, the SOAR Platform verifies the signature on all incoming identity provider messages. If an incoming message is not signed, the SOAR Platform rejects the message. To have the SOAR Platform not verify identity provider message signatures, use the command option, -requiresignedidprequests false.

A federation can be associated with multiple organizations. Consider the situation where your SOAR Platform is configured to have two organizations: Production and Development. You can create a single federation that allows access to both organizations. For example:

sudo resutil samledit -alias soar -org "Production" -org "Development" 
-certfile idp.cer -loginurl https://adfs.example.com/adfs/ls/

By default, users are only granted access to the organization through the federation if they exist in that organization. Therefore, in the previous example, users would need to exist in both "Production" and "Development" organizations for the users to access them. However, if you want users to automatically be added to the Production organization then you would specify –createusers for just that organization, as shown in the following example.

sudo resutil samledit -alias soar -org "Production" -createusers

If the –createusers argument is specified for both organizations, then users who authenticate through the federation are automatically created in both organizations.

You can unlink the federation from an organization by using the -clearorgs flag.

Import the SAML metadata into your identity provider

The SAML metadata that was written in the previous step can now be imported into your SAML Identity Provider. The specific instructions vary by product. Consult the documentation for your Identity Provider for instructions on how to create a federation (also called a "relying party").

The SOAR Platform requires that the Identity Provider provide the following attributes.

• Email address
• First name (given name)
• Last name (surname)

The SOAR Platform does not function if the attributes are missing.

The SOAR Platform uses the following attributes if they are present (they are not needed for proper operation):

• Phone number
• Mobile phone
• Title
• Groups

Consult your Identity Provider documentation for details on configuring which attributes are sent during authentication.

Authenticated users are added to the groups listed by the Identity Provider in the SAML response. For example, if the user is a member of the "IT" group and it is sent then the user is added to the "IT" group in the SOAR Platform, if it exists. Groups that are in the SAML response that do not exist in the SOAR Platform are not automatically created.

After you configure SAML in Identity Provider, you can test the authentication by using the Authentication URL for your organization. You can check this value by running the following command.

sudo resutil samlshow

For example:

https://resilient.example/saml2/resilient

The URL redirects you to the Identity Provider for authentication. After you authenticate, you are redirected to the SOAR Platform and logged in to the SOAR Platform. Authentication might be done without prompting (single sign-on).

You can send the URL to users who you want to grant access to the SOAR Platform. All users who are authorized to use the Identity Provider are granted access to the SOAR Platform. If you want to restrict access, you must do so through the Identity Provider configuration.

Update certificate

sudo resutil samledit -alias <alias_name> -org "<org_name>"  
-certfile idp.cer -loginurl <path_to_file>
sudo systemctl restart resilient

sudo resutil samledit -alias soar -org "Production" -org "Development" 
-certfile idp.cer -loginurl https://adfs.example.com/adfs/ls/
sudo systemctl restart resilient

Alternatively, to avoid replacing the IdP's SSL certificates when they expire, you can use -idpmetadataurl only if the IdP's metadata is available to the SOAR Platform from the https://<protocol>. This way, the SOAR Platform imports any changes to the IdP's SSL certificate embedded in its metadata, dynamically avoiding this process.

How to set up two-factor authentication

1. Sign-up for a Duo Account at https://www.duosecurity.com/pricing.
2. Create and configure a Duo application to use with the SOAR Platform.

   During this stage, you receive a Client ID, Client Secret, and API host name. You need these items to configure two-factor authentication on the SOAR Platform.

   When prompted for the application type, select Web SDK.

3. Locate the Client ID, Client Secret, and API host name from your Duo application.
4. Determine the names of one or more SOAR organizations that can enable the two-factor domain. (When this procedure completes, a system administrator can then choose to enable the two-factor domain for each of those organizations. The administrator needs the permissions to view and modify administrator settings and customization settings.)
5. Use resutil to create a two-factor domain:

   sudo resutil twofactoredit -name <domain_name> -org <org_name> 
   -clientid <duo_client_id> -host <duo_api_hostname> 
   -clientsecret <duo_client_secret> 

   <domain_name> is the name of the two-factor authentication domain. The name is presented to your Organization Administrator in a menu.

   <duo_clientid_key>, <duo_api_hostname>, and <duo_client_secret> are values that are obtained from Duo Security to complete the configuration.

   <org_name> is the name of an organization in the SOAR Platform that can use the two-factor domain. Multiple -org <org_name> arguments can be provided.

6. Ensure that your firewall was not modified by the Duo certificate using the following curl command:

   curl https://[api-to-duo-app].duosecurity.com/auth/v2/ping --verbose

   If your firewall is not configured correctly or you notice any problems, implement the steps described in the Duo documentation.

sudo resutil twofactoredit -help

You can display the details of an existing two-factor domain.

sudo resutil twofactorshow -name <domain_name>

You can delete a two-factor domain.

sudo resutil twofactordel -name <domain_name>

In some cases, you might want to exclude a specific user who belongs to an organization configured for two-factor authentication. For example, you want to programmatically access the SOAR REST API with a system account. You can use the following command.

sudo resutil twofactorexcluser -email user@example.com

It enables user@example.com to access the two-factor org without providing the Duo authentication.

You can re-enable two-factor authentication by using the -clearemail flag. For example,

sudo resutil twofactorexcluser -clearemail user@example.com

Enabling your authentication domain

As a system administrator with the permission to view and modify administrator settings and customization settings, you can enable a two-factor authentication domain under organizational settings on the administrator's settings page. If you configured multiple two-factor authentication domains, you can select which domain you would like to authenticate your users against here. You can also set the cookie lifetime, which sets an expiration in days for when a user needs to reauthenticate with two-factor authentication.

Registering users

When two-factor authentication is configured, users need an account on the SOAR Platform and a corresponding account in your Duo Security account.

Management of user registration with Duo security is handled in the Policy settings of your Duo Security application. The "New user policy" allows you to select the following settings.

• Require Enrollment. Users who are not already registered with Duo security are provided a self-enrollment process where they can register their devices and install the Duo mobile app (if necessary). When a user logs in to the SOAR Platform for the first time after two-factor authentication is enabled, Duo Security begins this self-enrollment process.
• Allow Access. Not recommended. Users who are not already registered with Duo security are not challenged.
• Deny Access. Only users who are already configured with the Duo account are allowed access. It means that you need to configure your users who use your Duo account in the "Users" tab.

The email address of the SOAR Platform must match the Duo account username. In the Duo application settings, you can use "Username normalization" to specify whether "DOMAIN\username", "username@example.com" and "username" are all treated as the same user.

Two-factor authentication and user experience

When two-factor authentication is enabled, if a user was not "previously authenticated" through two-factor authentication, they are presented with a two-factor challenge whenever they try to access an organization.

A user is considered as being "previously authenticated" under the following circumstances.

• They successfully pass the challenge presented by two-factor authentication in their current session.
• They successfully pass the challenge that is presented by two-factor authentication in a session then started a new session within the number of days set by the cookie lifetime value. In this situation, the user authenticates as normal (email and password) when they start the new session, but is not presented with the challenge. The system administrator sets the cookie lifetime value in the Organization page.