Installation and Configuration
Microsoft SharePoint Online Azure Principal Resolution Service
Copyright ©
Mindbreeze GmbH, A-4020 Linz, 2023.
All rights reserved. All hardware and software names used are brand names and/or trademarks of their respective manufacturers.
These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes, or any other protected rights. The dissemination, publication, or reproduction hereof is prohibited.
For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.
Introduction
Microsoft SharePoint Online Azure Principal Resolution Service combines the SharePoint Online and Azure caches into one cache. Please refer to the documentation of Microsoft SharePoint Online and Microsoft Azure for the respective necessary server-side configuration.
Note: If both caches (SharePoint Online and Azure) are to be used simultaneously, this combination service is recommended instead of using the individual services.
Configuration of the Principal Resolution Service
Go to the "Indices" tab, scroll down and in the "Services" area and add a new service by clicking on "Add Service".
Select "SharepointOnlineAzurePrincipalCache" and assign a display name.
Section “Sharepoint Settings”
Server URL | The URL of the SharePoint Online instance, e.g.: https://mycompany.sharepoint.com Should be configured the same way as in the crawler. | ||||||
Admin Server URL | The admin URL of the SharePoint Online instance. Often this is just the server URL with the suffix -admin. e.g: https://mycompany-admin.sharepoint.com Should be configured the same way as in the crawler. | ||||||
Site Relative URL | The relative paths to the sites to be crawled, starting with a slash, e.g.: /sites/mysite. Each line contains one path. If this field is left blank, all sites in SharePoint Online are automatically found and indexed. If sites are specified, only the subsites of the specified sites are found. Should be configured the same way as in the crawler. | ||||||
Site Discovery Schedule | An extended cron expression that specifies when to run site discovery. The results are then used for the next crawl runs. This means that the potentially time-consuming site discovery does not have to be repeated for each crawl run. Documentation and examples of Cron Expressions can be found here . | ||||||
Background Site Discovery Parallel Request Count | Here you can set the maximum number of HTTP requests sent in parallel by the Site Discovery. | ||||||
Site Discovery Strategy | The strategy to be used to perform the Site Discovery.
| ||||||
Included Sites URL (regex) | Regular Expression that can be used to specify which subsites should be crawled. If this option is left empty, all subsites will be crawled. The regex matches relative URLs. e.g. /sites/mysite Should be configured the same way as in the crawler. | ||||||
Excluded Sites URL (regex) | Regular expression that can be used to specify which subsites should be excluded. The regex matches relative URLs. e.g. /sites/mysite Should be configured the same way as in the crawler. | ||||||
Enable Delta Update (Advanced Settings) | If enabled, only the changes to the groups are fetched from SharePoint Online after the first cache creation instead of fetching all groups each time. This is recommended especially for very large SharePoint instances, otherwise a regular cache update can take a very long time. Delta Updating with User-Based Authentication is not supported - if Delta Updating is required, App-Only Authentication must be used. | ||||||
User Agent | The specified value is sent in the user agent header during HTTP requests. | ||||||
Dump Change Responses | When enabled, the changes we receive from SharePoint Online during Delta Update are dumped to a file. This is very helpful for troubleshooting. | ||||||
Log All HTTP Requests | If set, all HTTP requests sent by the Principal Resolution Service during the cache update are written to a .csv file (sp-request-log.csv). | ||||||
Regex for your organization (used to determine authenticated users) | Regular Expression that defines whether a user belongs to your organization or not. This resolves the principal "everyone_except_external". The regular expression can refer to the e-mail address, the ObjectSID or the ObjectGUID from LDAP. | ||||||
Parallel Request Count | With this option you can define how many HTTP requests are sent by the crawler at the same time. The higher the value, the faster the crawl run should be, but too high a value can also lead to many "Too Many Requests" errors on SharePoint pages. A value above 30 is not recommended. | ||||||
Page Size | Maximum number of objects received per request to the API. A high value leads to higher performance, but also to higher memory consumption during the cache update, a low value leads to less memory consumption, but the performance is reduced. If the value is set to 0, no paging is used, so the crawler tries to fetch all objects at once with Request. | ||||||
Trust all SSL certificates | Allows the use of non-secured connections, for example for test systems. Must not be enabled in production. | ||||||
Heap Dump On Out Of Memory | When activated, the Principal Service will do a Heap Dump if it runs Out Of Memory | ||||||
Use App-Only authentication | If this option is selected, App-Only Authentication is used instead of User-Based Authentication. Also, if this option is selected, the "Client ID" and "Client secret" options below must be configured. In addition, all the steps of "App Registration in SharePoint" must be performed as described here. | ||||||
Client ID | The client ID that is generated as described here. | ||||||
Client secret | The client secret that is generated described here. |
Section “Azure Connection Settings”
Graph Service Root (Advanced Settings) | The endpoint/URL of the Microsoft Graph API. By default, "https://graph.microsoft.com". Change this setting only if you are using a national (non-international) Microsoft Cloud. A list of all available national Microsoft Graph endpoints can be found below. |
Azure AD Url (Advanced Settings) | The endpoint/URL to the Azure Active Directory. By default, "https://login.microsoftonline.com". Change this setting only if you are using a national (non-international) Microsoft Cloud. A list of all available national Azure AD endpoints can be found below. |
Tenant ID | The tenant ID of your Microsoft 365 instance. You can find this on the overview page of the created app in Azure. |
App ID | The application (client) ID of the app created in Azure. |
Client Secret | The credential created in the Network tab, which contains the created client secret. |
Crawler Thread Count | Number of threads used for processing the groups. |
Page Size | Maximum number of objects received per request to the API (max. 999). A high value leads to higher performance, but also to higher memory consumption during the cache update, a low value leads to less memory consumption, but the performance is reduced. If the value is empty or set to <=0, the default page size of the API is used (100). |
Resolve only teams | If this option is enabled, only groups that have an associated team in Microsoft Teams will be resolved. If this Principal Resolution Service is to be used only for Microsoft Teams, enable this setting for optimal performance. |
Regular Expression that can be used to specify which Azure groups are to be resolved. If this option is left empty, all groups will be resolved. The regex matches the group name. | |
Excluded Group Names (regex) | Regular expression that can be used to specify which Azure groups should be excluded. The regex matches the group name. |
Log All Requests | If this option is enabled, all requests against the Graph API are written to a log file. Should be enabled for troubleshooting only. |
Enable Delta Update | As long as this option is enabled, the Principal Service will only fetch all groups from Microsoft Teams during the first update, after which it will only fetch the changes to the groups, which significantly improves performance. Disable this option only if there is an inconsistency between the Principal Service and the actual groups in Microsoft Teams. |
[Deprecated] Exclusively Use Beta API | This option is deprecated and should not be enabled. If this option is enabled, the Principal Resolution Service uses the /beta API. Otherwise, the /v1.0 API is used. If this option is disabled, make sure that the app's permissions (as described here) are correct, as the /beta API sometimes allows API queries despite insufficient permissions. Note: If you enable/disable this option, the “Enable Delta Update” option must be disabled for at least one cache update. |
Available national Microsoft Graph endpoints
Microsoft Graph global service | https://graph.microsoft.com |
Microsoft Graph for US Government L4 | https://graph.microsoft.us |
Microsoft Graph for US Government L5 (DOD) | https://dod-graph.microsoft.us |
Microsoft Graph China operated by 21Vianet | https://microsoftgraph.chinacloudapi.cn |
Available national Azure AD endpoints
Azure AD (global service) | https://login.microsoftonline.com |
Azure AD for US Government | https://login.microsoftonline.us |
Azure AD China operated by 21Vianet | https://login.chinacloudapi.cn |
Section “Cache Settings”
Identity Encryption Credential | With this option you can display the user identity encrypted in the app.telemetry. |
Cache In Memory Items Size | Number of items stored in the cache. Depending on the available memory capacity of the JVM. |
Database Directory Path | The directory path for the cache. If using a Mindbreeze Enterprise product, a path must be set. If you are using a Mindbreeze InSpire product, the path does not need to be set. The cache is then located in /data/currentservices/<servicename>/data. |
Cache Update Interval (Minutes) | This option determines (in minutes) when the cache should be updated. (Default value: 60 minutes) Values below 0, disable the cache update. When starting the service, the last (persisted) cache update time is considered. This means that the cache is not necessarily updated when the service is stopped/started, for example, but only at the next time interval. |
Group Members Resolution And Inversion Threads | Number of threads that resolve group members in parallel and invert these groups. Values less than 1 are assumed to be 1. |
Retry Update Cache Run If Was Incomplete In (Minutes) | This option determines (in minutes) when the cache should perform a new update process if an update was incomplete. Values below 0, disable the cache retry update. |
In-Memory Containers Inversion Threshold | If the number of groups exceeds this number, further RAM memory consumption during inversion is avoided by using hard disks. |
Section “Health Check Settings”
Health Check Interval (Minutes) | This option sets the interval (in minutes) at which a connection request should be sent to the server. |
Health Check max. Retries On Failure | This option sets the maximum number of repeated connection requests to the server if the connection to the server fails. If there is still no connection, the service will be switched off. |
Health Check Request Timeout (ms) | Determines the maximum time of the connection request (in milliseconds) before a new attempt is started. |
Section “Parent Cache Settings”
Use Parent Principal Cache Service | If this option is enabled, additional groups of the user are resolved and delivered in another cache (parent cache). |
Parent Principal Cache Service Port | The port used for the "Use Parent Principal Cache Service" option if enabled. |
Section “Service Settings”
Webservice port | The service is available on the specified port. If multiple Principal Resolution Services are configured, make sure that they have different "Web Service Port" parameters and that they are available. |
Identity Alias Name Property | This option allows to use properties located in the identity to search for groups in the cache using their value. |
Lowercase Principals | With this option, all principals supplied by the cache will be lowercased. |
Preserve Case for Principals Matching Pattern | This option allows to keep certain principals (defined by regex patterns) in their original format, i.e. if "Lowercase Principals" is enabled, the principals specified here will not be lowercased. |
Resolve non anonymous principal to all registered users. | This option determines whether "normal" (non-anonymous) users belong to the group that contains all users. |
Exclude Principals Pattern | This option allows to remove certain principals (defined by regex pattern, case-insensitive) for all users from their principal list. |
Case Insensitive Member Resolution | This option determines if principals are checked in a case-insensitive manner. |
Suppress Anonymous Users Principals | If this option is enabled, anonymous users get an empty principal list or the "Everyone" principal is suppressed for anonymous users. |