Secure Your Content Using the Advanced Security Module

Security trimming requires that you setup the ACL properties for your connector.

About

  • ASM = Advanced Security Module
  • ASM is used by:
    • SmartHub
    • Connectivity Hub
  • For a video walk-thru of the ASM see BA Insight ASM walk-thru.

Overview

For a high-level conceptual explanation of the Advanced Security Module, with graphics, see Security Trimming in SmartHub and Connectivity Hub.

Configuration Options

Any combination of the following authentication modes are valid:

  • SmartHub Authentication Modes:
    • Azure AD
    • Windows authentication
  • Connectivity Hub Target Directories:
    • Azure AD
    • Active Directory
      • Must be on-premise AD if you use a connector with no security sync, such as FileShare

Configuration Examples

Option 1: Azure AD in SmartHub and Connectivity Hub

Configuration:

  • UPN is the default value for userPrincipalNameProperty.
    • For userPrincipalNameProperty, specify:
      • upn, id, or leave it empty
    • No domain remapping required

 

User claims in Smart Hub

  • SmartHub extracts only the On-Premise ID and UPN for the current user
  • The user property id is not be present by default. To retrieve it use the Graph Claims Provider Stage, shown below.
    • Graph Claims Provider Stage
      • Use to extract any user property from graph, such as id


Option 2: Azure Active Directory in SmartHub/Local AD in Connectivity Hub

  • Configuration:
    • UPN is the default value for userPrincipalNameProperty.
      • For userPrincipalNameProperty, specify:
        • upn, onprem_sid, or leave it empty
    • Domain remapping required
      • MyDomain.com=MyOtherDomain.local
        (SmartHub)=(ConnectivityHub)

Option 3: Windows Authentication in SmartHub*/Local AD in Connectivity Hub

  • *Windows Authentication in SmartHub uses local AD
  • Configuration:
    • This option works out-of-the-box.
      • UPN is the default value for userPrincipalNameProperty.
        • For userPrincipalNameProperty, specify:
          • upn, onprem_sid, or leave it empty
    • No domain remapping required if SmartHub and ConnectivityHub are connected to the same domain. 

Option 4: Windows Authentication in SmartHub*/Azure AD in Connectivity Hub

  • *Windows Authentication in SmartHub uses local AD
  • Configuration:
    • For userPrincipalNameProperty, specify:
      • upn, onprem_sid, or leave it empty
    • Domain remapping required
      • MyDomain.com=MyOtherDomain.local
        (SmartHub)=(ConnectivityHub)

ASM User Format Based on Connectivity Hub Target Directory

Azure AD Target Directory

  • UPN:
    • user@domain
    • domain\user: Somesite.local\a_sharepoint_user
  • ID: ########-####-####-####-############

Active Directory Target Directory

  • Distinguished name: 
    • full_domain\user
  • UPN: user@full_domain
  • SID: S-1-5-32-573

To find out the user format, check the SmartHub log for these entries and make sure the requirements listed above are met: 

DEBUG - GetGroupInfo Started
DEBUG - User: a_sharepoint_user@azuredomain.com
DEBUG - Complete list of users, including domain remapping
DEBUG - Remapped user: a_sharepoint_user@azuredomain.com
DEBUG - Remapped user: a_sharepoint_user@localdomain.local
DEBUG - Retrieving Security Map
DEBUG - GetGroupsList Started

How to Install the Advanced Security Module (ASM)

Use the following steps to install the Advanced Security Module (ASM).

  1. Download the ASM package for your environment from the Upland Community Support Portal.
  2. Add the Advanced Security Module (ASM) package (DLL files) to the SmartHub /bin directory.
  3. Navigate to the SmartHub administration page >Registered Pipeline Stages
  4. Click Federator Settings.
  5. The Properties for Federator SSA page appears.
  6. Click Register New Pipeline Stage.

    See the SSA page.
  7. In the Federator Search Service Application screen, add the following values:
    • Class Name: BAInsight.AdvancedSecurityModule.SecurityPipeline
    • Assembly Name: BAInsight.AdvancedSecurityModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8b346c7a0df406fd
  8. Click OK.

Add the Advanced Security Module Pipeline Stage

To use the Advanced Security Module, you must add a pipeline stage. Use the following steps to add the ASM pipeline stage.

Caution: This stage must be the first stage executed in the backend The search engine your SmartHub instance uses to perform queries. SmartHub can be configured to use more than one search engine. pipeline.

  • You can change the order of the stages by using the up and down arrows.

Caution: Applies to content secured with Active Directory users and groups

  • If you're using Advanced Security Module to secure content from a Connector which relies on Active Directory for users and groups, such as (FileShare, FileNet, SharePoint), you must set "enableSidSecurity" to "true".

  • See more details in the configuration table below.

  1. Navigate to the SmartHub Administration page at http(s)://[web-app-url]/_admin. For example: http://smarthub.azurewebsites.net/_admin.
  2. Click on the Backend which should be secured: typically, Main Backend
  3. Click Add New Query Stage.
  4. Pipeline Stage: Use the down arrow to select Longitude Security Trimmer.
  5. Name: Complete a name for your stage.

  6. Parameters: Copy and paste the following code, replacing the sample values with the appropriate values.

    Copy 
    <config>   
        <pathToGroupService>http:...</pathToGroupService>   
        <domainRemapping>domain=domain.local</domainRemapping>   
        <userPrincipalNameProperty></userPrincipalNameProperty>   
        <groupCacheTimeout>5</groupCacheTimeout>   
        <additionalSecurityLevels>0</additionalSecurityLevels>   
        <enableSidSecurity>false</enableSidSecurity>   
        <includeResultSources>*</includeResultSources>   
        <excludeResultSources></excludeResultSources>   
        <impersonateUser>domain\uA=domain\uB</impersonateUser>   
        <debug>false</debug>   
        <userForGroupService>user</userForGroupService>   
        <passForGroupService>password</passForGroupService>
    </config>

Parameter

Required

Description and Value

pathToGroupService

X

This URL must point to the usernativegroups.asmx file in your BA Insight Connectivity Hub (or Connector Framework for SharePoint Online) Administration site.

  • For Connectivity Hub, the URL path should be similar to: <connectivityHubURL>/legacy-api/usernativegroups.asmx
    • For example: http://localhost:55001/legacy-api/usernativegroups.asmx
  • For Connector Framework for SharePoint, the URL path should be similar to: <SharePoint Central Administration Site>/longitude.connectors/_layouts/15/esc.search.services/usernativegroups.asmx
    • For example: http://server:2016/longitude.connectors/_layouts/15/esc.search.services/usernativegroups.asmx

userForGroupService

X

  • This is the user that is used to get users and groups from Connectivity Hub.

  • You must specify this parameter using the format DOMAIN\USER.

passForGroupService  

X

  • This is the password for the userForGroupService.

  • Make sure the password is properly encoded for XML.

  • Use the <![CDATA[password]]> syntax if your password contains special characters.

userPrincipalNameProperty (optional)

  • Default value is an empty string (uses the UPN property).

  • This property reads the user name for the current user from the token.

  • If SmartHub is configured to use Azure AD Authentication and you want to pass the onpremise sid for security validation, then specify the onprem_sid value for userPrincipalNameProperty

    • <userPrincipalNameProperty>onprem_sid</userPrincipalNameProperty>

Note: Security validation using SID is supported

domainRemapping

(optional)

Default value is an empty string (no domain remapping).

  • Use this parameter to remap the possible combinations of user login domains to the BA Insight Connectors mapped domains, such as:
    • SourceDomain1=TargetDomain1&SourceDomain2=TargetDomain2&…
  • The user from the source domain is treated as if this user was one of the users for from target domain.
    • For example: domain=domain.local&corp=corp.local

impersonateUser

(optional)

Default value is an empty string (in other words, no impersonation).

  • Enter the domain and user name of a user that you want to impersonate in the search results.
  • This parameter can contain a string with one user specified using the following format: domain\user
  • Alternatively, specify the user mapping string using the following format:
    • SourceDomain1\SourceUser1=TargetDomain1\TargetUser1;SourceDomain2\SourceUser2=TargetDomain2\TargetUser2;

In the first example, the security level for this user is applied to all users.

This specification overrides the current user security level so that all users have the same access as this user.

In the second case, if mapping is found for the user under which the request is performed, the target user security is applied.

groupCacheTimeout

(optional)

Default value is 5 minutes.

Specify the time in minutes for the group cache expiration time.

additionalSecurityLevels

(optional)

Default value is 0. Maximum value is 10.

  • For BA Insight Connectors that use multilevel security, the value should be greater than 0.
  • Connectivity Hub calculates this value automatically, but you can override this value by specifying a new value.
  • Increase this value if items that are secured with multiple levels are returned incorrectly in the search results.
  • The higher the value, the slower the query.

enableSidSecurity

(optional)

Default value is false.

  • Set this parameter to trueif the source systems rely on Active Directory for both its users and groups, such as FileNet and FileShare.
  • This setting also implements multilevel security:
    • For example, multilevel security is implemented for a FileNet source system using the marking sets capability.

includeResultSources

(optional)

Default value is *  (in other words, all sources are processed).

  • Specify a list of result source names for which this stage transforms the query.
  • This parameter must include all the result sources returning results from content sources that are secured using the native security model. Specify your values using a semicolon-separated (;) list of names.
    • For example: Local SharePoint Sites;CustomSource  

excludeResultSources

(optional)

Default value is an empty string (in other words, no source is excluded)

  • Specify a list of result sources for which the security transformation is not applied. Use this list when you want to apply security on all but some specific sources.
  • Specify your values using a semicolon-separated (;) list of names.
    • For example: Local SharePoint Sites;CustomSource

debug

(optional)

Default value is false.

  • Specify an internal parameter that is used for advanced troubleshooting.