Secure Your Content Using the Advanced Security Module

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

About

  • ASM is the Advanced Security Module . ASM is used by:
    • SmartHub
    • Connectivity Hub

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 Active Directory
    • Windows authentication
  • Connectivity Hub Target Directories:
    • Azure Active Diectory
    • Active Directory
      • Must be on-premise AD if you use a connector with no security sync, such as FileShare

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. 

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

The default value is 0. The maximum value is 10.

debug

(optional)

Specify an internal parameter that is used for advanced troubleshooting.

The default value is false

domainRemapping

(optional)

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.

The default value is an empty string (no domain remapping).

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.

The default value is false.

excludeResultSources

(optional)

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

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

groupCacheTimeout

(optional)

This specifies the time in minutes for the group cache expiration time.

The default value is 5 minutes.

impersonateUser

(optional)

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.

The default value is an empty string (no impersonation).

includeResultSources

(optional)

This specifies 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;C0ustomSource. 

The default value is * , meaning all sources are processed.

showErrorWhenCHNotAvailable X

This controls whether an error is displayed if BA insight Connectivity Hub is unavailable. The default value is true.
userPrincipalNameProperty (optional)

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>

The default value is an empty string (uses the UPN property).

Note: Security validation using SID is supported

Configuration Examples

Option 1: Azure AD in SmartHub and Connectivity Hub

Configuration:

  • UPN is the default value for the userPrincipalNameProperty configuration setting.
    • 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.

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