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 SmartHub

  • 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 AD 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 Connectivity Hub 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

Add the Advanced Security Module Tuning Stage

To use the Advanced Security Module, you must add a Tuning stage.

Use the following steps to add the ASM Tuning stage.

Caution: This stage must be the first stage executed among your search engine tuning stages.

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

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 search engine which should be secured.
  3. Click ADD QUERY TUNING.
  4. User Experience Tuning: Use the down arrow to select Advanced Security Module.
  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>
        <userPrincipalNameProperty>upn</userPrincipalNameProperty> 
        <domainRemapping>domain=domain.local</domainRemapping> 
        <groupCacheTimeout>10</groupCacheTimeout> 
        <additionalSecurityLevels>0</additionalSecurityLevels> 
        <enableSidSecurity>true</enableSidSecurity> 
        <includeResultSources>ASM</includeResultSources> 
        <excludeResultSources>XYZ</excludeResultSources> 
        <impersonateUser>domain\uA=domain\uB</impersonateUser> 
        <debug>false</debug> 
        <showErrorWhenCHNotAvailable>true</showErrorWhenCHNotAvailable>
    </config>

 

Parameter

Required

Description and Value

additionalSecurityLevels

(optional)

  • Values

    • The default value is 0

    • The 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.

debug

(optional)

  • The default value is false

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

domainRemapping

(optional)

  • The 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

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.

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

groupCacheTimeout

(optional)

  • Default value is 5 minutes.

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

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.

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  
showErrorWhenCHNotAvailable X

  • Default value is true

  • Controls whether an error is displayed if BA insight Connectivity Hub is unavailable
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