Certificate-based Authentication

When using certificate-based authentication, you must create an App Registration in the organization's Azure Active Directory An identity and access management solution from Microsoft that helps organizations secure and manage identities for hybrid and multicloud environments..

• Since the connector will potentially crawl millions of records, please make sure to create a dedicated App Registration for the connector.

• Sharing the App Registration between the connector and another client may lead to excessive throttling for both clients and poor indexing speed.

Application Permissions

The Azure application must be granted one of the following SharePoint Application API permissions, depending on the level of access that you want to enable (see register the Azure application for more information):

• Sites.FullControl.All: This permission grants Full control of all site collections. This permission is the minimum required as this is the only permission which lets the SharePoint API caller fetch security permissions set on sites.

• Sites.Selected: This permission only grants access to the specified SharePoint site collections that you will be indexing.

  To use the Sites.Selected permission, you must run the appropriate PowerShell script to grant permissions to the Azure Active Directory A directory service for Windows domain networks. A hierarchical structure that stores information about objects on the network. Used to manage permissions and control access to critical network resources. app registration. For more information, see allowing access to only selected sites.
  
  If you are using the Sites.Selected permission, AutoFetch functionality is not supported.

The Azure application must be granted the following Microsoft Graph API Application permissions:

• Member.Read.Hidden: Allows the app to read the memberships of hidden groups and administrative units
• GroupMember.Read.All: Allows the app to read memberships and basic group properties for all groups.
• Directory.Read.All: Allows the app to read data in your organization's directory, such as users, groups and apps.

• User.Read.All: Allows the app to read all users' full profiles.

• Sites.FullControl.All or Sites.Selected (depending on the level of access you want to enable): Allows the application to either grant full control of all site collections or grant access to a subset of site collections. The specific site collections and the permissions granted are configured in SharePoint Online.

Certificate Requirements

For the following topics you need the signed certificate in PFX and CER formats (created here) as well as the password for the PFX certificate.

Register the Azure Application

1. Go to https://portal.azure.com/ and login with Azure Global Admin user credentials.
   
2. Click Azure Active Directory and click on the desired directory.
   
3. From the menu select App Registrations.
   
4. Click New registration to register a new app.
   
5. In the Name field, Enter a name for your app.
   
6. In the Redirect URI section, specify the Application type by select Web or API app from the drop-down list.
   
7.  Enter a URI of your choosing. The URI is not used in the SharePoint Online Authorization mechanism.
   
8. Click Register at the bottom of the page.
   
9. Within the app, go to API Permissions.
   
10. Under API Permissions >  Add a permission > Sharepoint.
    
11. Select the following permissions for the app depending on the Authentication mechanism used:
    1. Application permissions> "Sites.FullControl.All" or "Sites.Selected" if required
       
       
12. Click the Add Permissions button at the bottom of the screen.
13. In the Configured permissions menu, select the Sites.FullControlAll or Sites.Selected permission and click the Grant admin consent button to grant the selected permissions (requires admin rights).
    
    
    
14. Repeat this process (Steps 9 through 13) for each of the Microsoft Graph API permissions listed in the Application permissions:
    
15. Open the Azure app you created in the previous steps, above. Under Manage, click Certificates and secrets

16. Add your newly created certificate.
    
    

    There are multiple methods that can be used to create a certificate. BA Insight recommends the following instructions to create a certificate: How to Create a Self-Signed Certificate.

    If you use another program, such as IIS, when you export the certificate, ensure you do not mark the key as exportable:
    

    Also, when exporting your certificate using IIS, note that it MUST BE Base-64 encoded:
     

Allowing access to only selected sites

If you want to use the Sites.Selected permission to restrict access to only specified SharePoint site collections, you must run a PowerShell command for the site collections that you want to index. For example:

Grant-PnPAzureADAppSitePermission -AppId 44e4b33e-c6bf-4701-b877-26f642669687 -DisplayName "Upland BA Insight SharePoint Connector" -Permissions FullControl -Site 7c0bec7b-291e-4034-ac8b-e27f5f7306d0

Refer to the following table for more information on each parameter of the PowerShell command:

For more information, see Grant-PnPAzureADAppSitePermission in the PnP PowerShell documentation.

Install the PFX Certificate on the Server Where the Connector Is Installed

1. Run the Microsoft Management Console (MMC) as an Administrator.
   
2. Add the Certificates Snap-in.
   
3. Expand Trusted Root Certification Authority.
   
   
4. Use the Actions menu to import your PFX certificate.

How to Determine the Certificate Distinguished Name

1. Run the Microsoft Management Console (MMC) as an Administrator.
   
2. Add the Certificates Snap-in.
   
3. Locate the certificate in the Trusted Root Certification Authority and double-click the certificate name.
   
4. From the pop-up window select theDetailstab.
   
5. Locate the “Subject” field and click on it.
   
6. Identify in the text box below all the distinguished name components.
   

7. Build the distinguished name based on all the components separated by comma and space characters.
   For example: CN=Jeff Smith, OU=Sales, DC=Fabrikam, DC=COM

   If you copy your certificate details, as shown below, you must ensure you use syntaxwithout a spaceor your certificate will not work.
   

   CORRECT SYNTAX Example: "CN=Jeff Smith"
   INCORRECT SYNTAX Example: "CN = Jeff Smith"