How to Set Access and User Authentication

Selecting Authentication

There are 4 different types of authentication available in SmartHub, including None (No Authentication).

Note: No Authentication is not recommended for security reasons.

Select one of the following four authentication types:

 

Option 1: Azure Active Directory Authentication

Before You Begin

IMPORTANT!
If you're using SharePoint 2013/16/19/SPSE for search and Azure AD for authentication, you must complete the steps on this page before proceeding.

Authentication

There are 5 types of authentication you can select in SmartHub, one of which is Azure Active Directory. Before you can set "AzureActiveDirectory" for SmartHub authentication, you must do the following:

  1. Register your app for SharePoint Online O365 in Azure
  2. Grant permissions to the app
  3. Enter your Azure Authentication information in SmartHub under "Security Settings"

Use the following topics to register your app for SharePoint Online O365 in Azure and grant the app permissions.

Note! If you do not update your list of Trusted Sites in Microsoft IE, you may not be able to log-in to SmartHub.
For more information, see Update Trusted Sites list (only Internet Explorer).

Register the App for SharePoint Online in Azure

Create the App Registration in Azure

The following procedure registers your SmartHub application for SharePoint Online in Azure. This is required to use SharePoint Online as a results search engine in SmartHub.

  1. Login to your Azure portal as an administrator: http://portal.azure.com
  2. Click App registrations>New registration.

  3. Enter the new application details:
    1. Name: Smart Hub App for SP Online
    2. Supported account types: Sets the API access by account.
    3. Redirect URI:
      1. Select Singe-page application (SPA)
      2. Enter Your SmartHub URL home address (for example, https://search.company.com)


    4. Click the Register button at the bottom of the screen.
  4. Create the App ID URI.
    1. Click Expose an API section on the left side navigation menu.
      1. To manually set your App ID URI, click Set at the top of the page.
      2. To set your App ID URI automatically, continue to add a scope, below.

    2. Click the Add a Scope button.
    3. In the window that appears, note the Application ID URI is shown below the "Scope name" field (with the field empty). Configure a scope to be used by SmartHub to provide permissions-based access to its resources.

      1. Scope name: Enter a scope name

      2. Who can consent: See here for more information.

        1. Admins and users - Every user can themselves consent; they will see the message to “SmartHub wants to sign in as you”.
        2. Admins only - Admin consent serves as pre-consent for all users.

      3. Admin consent display name: Enter a consent display name.

      4. Admin consent description: Enter a description for the Admin consent.

      5. User consent display name: Enter a name for the user consent.

      6. User consent description: Enter a description for users consenting to the API.
      7. State: Enable or Disable the scope. This can be changed as needed.
    4. When done, click Add scope.

Grant the App Permissions

  • Granting your app permissions is a two-step process:

    1. Add the desired permissions to your app.

    2. Grant the permissions with a single mouse-click.

Add Permissions

Add permissions for the application:

  1. Click API permissions > Add a permission.

  2. If not already present add the Microsoft Graph user read permission.
    Click Select an API>Microsoft Graph>Delegated>User.Read.
  3. Add the following permissions by selecting API > SharePoint>Delegated.
    (Select "APIs my organization uses" as a shortcut, if you desire).
    4. Note: These are delegated permissions. SmartHub access is limited to the sites the user has access to. These options do not grant access to all sites in the tenancy, but all sites the user can access.
    1. User.Read.All
      1. Read user profiles
    2. Sites.Search.All (Required only for the SharePoint Online search engine)
      1. Run search queries as a user
    3. TermStore.Read.All (Required only for the SharePoint Online search engine)
      1. Read managed metadata
    4. Click Add permissions when done.

Grant Permissions

To apply the permissions you just added to your app, click the Grant Admin consent button under the Configured permissions heading.

Redirect URIs

Enter app Redirect URIs (previously called Reply URLs).

  1. Click Authentication from the left-side navigation.
  2. Click Add URI under Single-page application in the middle of the screen
  3. Enter <your app Redirect URIs> in the format: https://search.company.com/(OAuth/Login).aspx
    1. These addresses must start with https
    2. These addresses are case-sensitive.
    3. You must enter both Login and OAuth URIs.
  4. Logout URL: Enter the log-out URL in the format: http://search.company.com/Logout.aspx
    If you have existing Redirect URIs, recreate them anew instead of migrating them to the single-page application (SPA) platform configuration.
  5. Click Save at the top of the page.

Implicit Grant

If you use a SharePoint Online search engine enable Implicit Grant for ID tokens:

  1. Click Authentication from the left-side navigation.
  2. Scroll down to Implicit grant and hybrid flows.
  3. Ensure that the ID tokens option is enabled.

Generate a Client Secret Key for Your App

You need the client secret if you either:

  • You use Azure AD as the user profile provider in SmartHub
  • You have a SharePoint Online search engine configured.
  1. Click Certificates & secrets>New client secret to generate a client secret key for the app.
  2. In the window that appears (shown below) enter the following information.
    1. Description: Enter a name for the client secret. (Note: The name is your client secret).
    2. Expires: Select Never expires.


    3. A Value is generated after you click Add.
    4. Copy the new client secret value. You cannot retrieve the secret value after you perform another operation or leave this page.


  3. Click <YourApp > Overview and make a note of:
    1. Application ID: This is the "Client ID" that needs to be configured in the SmartHub Admin page.
    2. Tenant ID (optional): This is the Tenant name or ID is entered in the SmartHub Admin page.

Token Configuration

  1. Select Token configuration from the left-side navigation.
  2. Click Add optional claim.
  3. Select ID as *Token type.
  4. Select upn and sid under Claim.
  5. Click Add.

Enter Your Authentication Settings (Azure AD) in SmartHub

  1. Navigate back to the SmartHub Administration page by going to the _ADMIN folder and navigating to the SmartHub admin User interface (UI). Alternatively, enter: http(s)://[web-app-url]/_admin
  2. Select Security Settings.
  3. Authentication mode: Select Azure Active Directory.


    1. Tenant name or ID (required): Specify your Azure tenancy name in this format ("contoso" is BA Insight's fictitious example domain):

      1. contoso.onmicrosoft.com
        or

      2. Enter your tenant ID

    2. Client ID (required): The "Application ID" as shown in the Azure Portal App Registration page for your application.
    3. Enter permission scopes for Azure App separated by comma: Paste in the custom scope defined in your Azure App from the "Expose an API" section. See the screenshot below.
    4. Client secret of Azure App: Enter a client secret if you have configured a Sharepoint Online search engine.

    5. Authority Endpoint: The authority is a URL that indicates a directory that MSAL can request tokens from

    6. Extra Query Parameters (Optional): You can add extra query parameters before doing the MSAL authorization request. For example you can specify a domain hint for MSAL to use.

      7. Copy
      {
          "domain_hint": "yourCustomDomain.com"
      }

    7. Trusted App Registrations: In case that, you need to use another app between SmartHub and App used for authentication, you need to add a Trusted App Registration.

      1. Navigate to Azure APP → API Permissions → Add a permission → My APIs → Select your app used for Authentication in SmartHub → Choose Scope used in SmartHub for Authentication

      2. Client ID: The "Application ID" as shown in the Azure Portal App Registration page for your application

      3. Client Secret: The Client secret generated for your app

    8. Admins users (one per line): The local administrator account(s) email address (username@domain.com). Enter one user account email address per line.
    9. Trusted App Redirect URLs: List of application URLs that use SmartHub to validate the user's credentials.
      1. This also includes custom DNS names used for the server hosting SmartHub.
      2. All BA Insight applications integrated with SmartHub are listed here.
      3. For example, see the following application URLs (some optional):

        1. SmartHub site URL: The SmartHub site address, as accessed by users.
          Note: You must list any registered DNS names that access your SmartHub server. Otherwise, users will not be able to authenticate with SmartHub.

        2. Smart Previews site URL: Optional. The Smart Previews site address, as accessed by users.

        3. ConnectivityHub site URL: Optional. The ConnectivityHub site address, as accessed by users.

        4. Custom apps: Optional. The URLs of custom applications that are integrated with SmartHub.

  4. Click Save to return to General Settings to see the "Security settings: Secured" message.

Optional: Update Trusted Sites list (Internet Explorer only)

Note: If you do not update your list of Trusted Sites in Microsoft IE, you may not be able to log in to SmartHub.

Use the following steps to update your list of Trusted Sites in Microsoft IE:

  1. Navigate to Internet Options > Security > Trusted Sites > Sites.
  2. Add the following sites:
    1. https://login.microsoftonline.com/
    2. https://mydomain.com/

How to Extend the Lifetime of Your Azure Active Directory Token

This optional procedure extends the lifetime your Azure AD token in SmartHub.

  1. Open a Windows PowerShell with Administrative privileges.
  2. Install the AzureAdPreviewModule with the command Install-Module -Name AzureADPreview as shown below:


  3. Enter "[A] Yes to All".
  4. The package installs.


  5. Connect to Azure AD with the command Connect-AzureAD -Confirm as shown here:


  6. Get your app object ID.

    1. You need your SmartHub app ID from portal.azure.com.

    2. See the example (with example app ID) below:

      $app= Get-AzureADApplication-Filter"AppId eq 'cc95a12d-9923-4426-83ed-113293693d47'"

    3. Fetch the object ID of the app using the following command:

      $appobjectid= >$app.ObjectId

  7. Make a new token lifetime policy (set to 20 hours in the example below):

    1. 80 days and 30 minutes is represented as 80.00:30:00

Copy 
$policy = New-AzureADPolicy  -Definition
@('{"TokenLifetimePolicy":{"Version":1,"AccessTokenLifetime":"20:00:00"}}') -DisplayName
"MyTokenPolicy" -IsOrganizationDefault $false -Type "TokenLifetimePolicy"

  1. Get the policy's ObjectId by running the following command:

    $policyobjectid= Get-AzureADPolicy-Id$policy.Id

  2. Add the policy using the command below:

    Add-AzureADApplicationPolicy-Id$appobjectid-RefObjectId$policyobjectid.id

  3. Procedure complete.
  4. See the bonus commands below.
    1. Bonus commands:
      1. Retrieve the policy assigned to an app:
        Get-AzureADApplicationPolicy -Id <ObjectId of Application>
      2. Update the existing policy:
        Set-AzureADPolicy -Id <ObjectId of Policy> -DisplayName <string>

Restrict Access to SmartHub from Azure

Active Directory Authentication

If the option for user assignations is enabled (see here for more info), then everyone under the "Users" and "Groups" list in the App registration in Portal (portal.azure.com) has access.

  • Azure Active Directory enables you to restrict your SmartHub site (app) to a set of users by following these instructions: https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-restrict-your-app-to-a-set-of-users.



  • Any user not assigned to the app cannot access it.
  • Users, by name, are not strictly denied.
  • Any user not specifically assigned access is denied.

  • Login attempts that fail result in the user being prompted to re-login.

    Note: If a user attempts to login with an account that cannot access SmartHub, but then switches to one that can, the user must refresh their SmartHub page otherwise O365 may become stuck on the “logging you in” page.

Use the following information to configure Federated-type user authentication in SmartHub.

About Federated Authentication

SmartHub supports Federated-type authentication, which is any authentication service that is OAuth 2.0 compliant.

Supported identity providers include:

  • Microsoft ADFS
  • Okta
  • Auth0
  • others

Your Authentication Service must be configured using OAuth 2.0 with JWT tokens.

  • The JWT token generated by your authentication service needs to contain both the SID and UPN of the user.
  • Decode JWT tokens at https://jwt.io/.

SAML authentication is not supported.

Configure SmartHub Federated Authentication

  1. Navigate to the SmartHub Administration page by going to the _ADMIN folder and navigating to the SmartHub admin user interface (UI).
    1. Alternatively, enter: http(s)://[web-app-url]/_admin

  2. Security Settings: Click "Security Settings" and the Authentication settings page appears.

  3. Authentication mode: Select Federated Authentication from the drop-down menu.

      
  4. Tenant name (optional): Enter the name of the tenant for your federated authentication service.
  5. Federated Authentication URL (required): Specify your Federated Authentication service URL.

  6. Client ID (required): Specify your app ID.

  7. Trusted App Registrations: In the case that you need another app between SmartHub and your app used for authentication, you will need to add a trusted app registration:

    1. Navigate to your Azure app and click App Permissions > Add a permission > My APIs. Select your app used for authentication in SmartHub, and choose the scope used in SmartHub for authentication.

    2. Client ID: This is the "Application ID" as shown in the Azure Portal app registration page for your app.

    3. Client secret: This is the client secret generated for your app.

  8. Signing Certificate File (.pfx):

    1. Click Browse... to upload a valid certificate (.cer), without the private key.

      1. The certificate (.cer) must be exported from your authentication provider.

      2. The certificate is used to validate the tokens that your authentication provider generates

        You must ensure that your certificate has not expired. For more information about certificates, see What are Certificates? in the Microsoft documentation.
  9. Admin Users: Enter the list of users who will enjoy administrative rights to your SmartHub site.
    1. User credentials must be entered in the format Domain\username or Username@domain.
    2. 'Anonymous' may be entered, but it is not recommended for security reasons.
    3. Groups are not supported.
  10. Make sure your Federated Service includes the UPN property in its claims for the user.

  11. Click Save and return to General Settings to see the "Secured" message:

Example Identity Provider: Okta

The following example describes how to configure Okta as your identity provider.

Note: You must have access to your Okta application settings on the Okta website.

Tenant Name is not required.

  • Authentication mode:
    • Select Federated Authentication
  • Federated Authentication URL
    • URL of your Okta Authorization Server: the server configured with the UPN claim in the ID token for the open ID (or All) scope
    • For example: https://<tenant>.okta.com/oauth2/default
    • See the example screenshot below
  • Client ID
    • The active application Client ID, which can be found from the Applications page of the Okta web site. See below.

  • Signing Certificate File
  • Global Admins (one per line)
    • List of users to enjoy administrative rights to your SmartHub site. See Step 8, above.
  • Trusted App Redirect URLs
    • Click the link to the right of the field to add the current address.
  • Click Save when complete.

Use the following instructions to authenticate your SmartHub users using Microsoft Windows authentication.

Windows Authentication requires HTTPS and a URL with a fully qualified DNS name.

Set Your Authentication Mode in SmartHub

Navigate to the SmartHub Administration page by going to the _ADMIN folder and navigating to the SmartHub admin User interface (UI).
Alternatively, enter the following URL into your browser:
http(s)://[web-app-url]/_admin

  1. Click Security Settings. The Authentication settings page appears.
  2. From the Authentication mode drop-down menu, select Windows Authentication


  3. Provide Certificate Details: A certificate is required to keep the user credentials encrypted and secure. If a certificate is not found in the security configuration file, a new certificate will be automatically generated when clicking "Save". The newly generated certificate will be available for 100 years.
    1. Signing Certificate File
      1. Required
      2. The Name and Expiration date of the generated certificate (if these 2 fields are blank it means no certificate exists yet)

    2. Export: Export the generated certificate as a .cer file

      Note: Make sure that your certificate has not expired. For more information about certificates, see What Are Certificates? in the Microsoft documentation.

  4. Admin Users: Enter the list of users who will enjoy administrative rights to your SmartHub site.
    1. User credentials must be entered in the format Domain\username or Username@domain.
    2. 'Anonymous' may be entered, but it is not recommended for security reasons.
    3. Groups are not supported.
  5. Trusted App Redirect: Click the "<—Click to add current address" link on the page to enter your SmartHub site URL if it isn't currently there.
    1. Enter your SmartHub address. Include port number. The default HTTPS port is 443.
    2. This URL must be HTTPS and include a fully qualified DNS name. See the screenshot above in step 2.
    3. You can also enter the address (URL) of your SmartHub Analytics site.
  6. Click Save to return to General Settings to see the "Secured" message.

Set Your SmartHub Site to Use Windows Authentication

  1. Edit your SmartHub site in IIS Manager.
  2. Select IIS>Authentication.


  3. The Authentication window appears:


  4. Anonymous Authentication: MUST be set to Disabled.

  5. Windows Authentication: MUST be set to Enabled.

    1. Everyone that is configured in IIS under “Authorization rules” has access.

    2. Authorization rules are located next to "Authentication" from the IIS SmartHub site screen.

  6. In a text editor, edit the web.config file that is located in the root folder of your SmartHub site:

    1. Set the InternalAuthTokenLifeTimeMinute value under AppSettings if you wish to set the expiration time of the generated authentication token. (optional)

      Copy 
      <add key="InternalAuthTokenLifeTimeMinute" value="60"/>

Optional: How to Authorize or Restrict User Access to SmartHub

Once Windows has been set as your authentication mode in SmartHub, and set to Enabled in your SmartHub IIS site, set the rules for authorizing users using the steps below:

  1. Edit your SmartHub site in IIS Manager.
  2. Select IIS>Authorization rules.


  3. Add an "Allow" or "Deny" rule using the links under the Actions section in the right-side pane.


  4. Set user access as desired, and click OK.

Use the following instructions to disable authentication to your SmartHub site by using the authentication mode "None".

  • If you set your SmartHub Authentication mode to "None", everyone has access to the SmartHub site.

  • BA Insight does not recommend this setting for security reasons.

  1. Admin users (one per line): Enter the list of users to enjoy administrative rights to your SmartHub site.
    1. 'Anonymous' may be entered, but it is not recommended for security reasons.
    2. Groups are not supported.
    3. Typically, Admin users are set as the local farm account, SharePoint service account, or both.
    4. User credentials must be entered in the format Domain\username or Username@domain
      For example:
      1. Domain50\User12
      2. UserSmith@contoso.com
  2. Trusted App Redirect URLs (one per line)
    1. Click the "<—Click to add current address" link on the page to enter your SmartHub site URL if it isn't currently there.
      1. You also enter the address (URL) of your SmartHub Analytics site.
  3. Click Save to return to the General Settings menu to see the "Secured" message.

How to Setup the SmartHub Administrators Security Group

Use the following procedure to specify which of your users will enjoy administrator rights to the Administrator Console.

  1. Navigate to the SmartHub Administration page by going to the _ADMIN folder and navigating to the SmartHub admin User interface (UI).
    1. Alternatively, enter: http(s)://[web-app-url]/_admin

  2. Security Settings: Click "Security Settings" and the Authentication settings page appears.


  3. Admin users:

    1. This is the list of users that have access to this Admin site.

    2. Enter the users who can access the Administrator console, one user per line.

    3. If "Anonymous" is entered, or no admin users are selected, everyone is treated as an authorized user.

    4. Enter user names in the formats:

      • domain\username

      • username@domain

      • Example: So your Admin users entry box could look like the following:

           Mydomain.com\jsmith
           msmith@Mydomain.com
           jsmith@demoenv.onmicrosoft.com
           mjones@demoinv.onmicrosoft.com

      Note: If you have Analytics and/or Smart Previews installed, only this list of users can access the admin sites for these products and configure the applications.

Optional: How to Set Up Trust Relationships with Other BA Insight Applications

Use the following procedure to setup trust relationships with other BA Insight applications, such as Connectivity Hub, Smart Preview, and so on.

  1. Navigate to the SmartHub Administration page by going to the _ADMIN folder and navigating to the SmartHub admin User interface (UI).
    Alternatively, enter: http(s)://[web-app-url]/_admin
  2. Security Settings: Click "Security Settings" and the Authentication settings page appears.

  3. Trusted App Redirect URLs: Use this setting to restrict access.

    1. If, for example, you enter the URLs for SmartHub, Analytics, and Smart Previews, only these products can communicate with each other.

    2. If you enable authentication but do not configure any URL, validation requests pass and all authentication requests are trusted.

    3. The URLs you enter must be the exact URLs that are making the access request.

  4. Click the Save button and return to General Settings to see the Security Settings: Secured message: