Relevance

This article is relevant for you if you want to use the SharePoint/One Drive Excel-Link feature of empower® Charts. Furthermore, the following information is only relevant to you if your organization uses a SharePoint-online instance. The information in this document is not relevant if your organization uses a SharePoint-onPremises instance. Lastly, there are scenarios where the configuration described below is not required, even though users work with online Excel-files.

Scenarios where working with online Excel-files do not require the configuration described below.

Scenario: Working with an open online Excel-file 

Description: The online Excel-file is open on the user’s computer during both the creation of the Excel- Link and every time they perform an Excel-Link update. 

Scenario: Locally synchronized OneDrive Excel-file 

Description: The Excel-file is located in the user’s OneDrive and is locally synchronized on their computer. 

If users in your organization only work according to the scenarios outlined above, you can omit the configuration described below.

Context

Hereafter, this article covers those Excel-Link scenarios that are not covered by the scenarios above and consequently require a SharePoint login. 

Example: A user wants to update a chart that is linked to an online Excel-file which is not currently open on the user’s computer. 

When working with online Excel-files (excluding those covered by the scenarios above) empower® Charts will always require a SharePoint-login. This is due to the fact that the Excel-files in those cases are exclusively available via an online source and must therefore be downloaded by empower® Charts. Access to such an online source requires the user to authenticate.

Technical Necessity

To perform authentication, empower® Charts uses the Microsoft Authentication Library (MSAL). 

https://learn.microsoft.com/en-us/azure/active- directory/develop/msal-overview 

When using MSAL, users are authenticated against the Azure Active Directory (AAD) tenant in which the respective accounts were created. This is usually your organization’s AAD. 

In order for empower® Charts to be allowed to request such authentication, we need a so-called Azure-app. This is not a software developed by empower, but a set of configuration parameters created in the empower® AAD, which Microsoft summarizes under the term "app". 

- This Azure-app already exists in the empower® AAD, so you do not need to create your own Azure-app. 

The way MSAL works requires empower® Charts to use the aforementioned Azure-app to identify itself to the Microsoft Identity Platform as an app which is authorized to accept authentication tokens for users from your organization’s AAD. 

In order to create a relation between the empower® Charts Azure-app and your organization’s AAD, it is necessary to register the empower® Charts Azure-app in your AAD as a so-called "Service Principal". 

This is the standard procedure prescribed by Microsoft. You can find more information about Service Principals here: 

https://learn.microsoft.com/en-us/azure/active- directory/develop/app-objects-and-service-principals 

https://learn.microsoft.com/en-us/azure/active- directory/develop/how-applications-are-added 

Next, the Service Principal must be granted the read permissions requested by the empower® Charts Azure-app. This can either be done by all users individually upon their first login or by an Azure admin on an organization-wide level.

Registration of the Service Principal

Depending on how your organization's AAD is configured, the Service Principal is either registered automatically when the very first user logs in via empower® Charts, or the registration must be performed manually by an Azure admin. The Service Principal is always registered in your organization’s AAD when some user grants permissions to the empower® Charts Azure-app. From the perspective of the users only the requested permissions are displayed while the Service Principal is automatically registered by Microsoft in your organization’s AAD. General information about granting permissions can be found here: 

https://learn.microsoft.com/en-us/azure/active- directory/develop/application-consent-experience 

For an overview of the permissions required by the empower® Charts Azure-app, see below.

Permission may be granted by the User

In this case, when a user logs in for the first time, a window is displayed that looks like the one shown below (Note: The image below is an example representation from Microsoft. The name of the app, as well as the requested permissions are exemplary): 

This window displays the name of the Azure-app, its publisher, as well as the requested permissions. If the user clicks Accept, the empower® Charts Azure-app is automatically registered as a Service Principal in your organization’s AAD and the requested permissions are granted for the current user. To simplify the process for the users, an Azure admin may grant organization-wide permission. As a result, no individual user would have to go through the aforementioned steps.

Granting permissions as Azure-Admin 

If the users are not authorized to grant the permissions themselves, or if the permissions are to be granted organization-wide for other reasons, an Azure admin can grant the permissions via one of the following ways.

Login via empower® Charts:

1. Log in via empower® Charts as an Azure admin.
2. The following window will then appear (Microsoft example).

   3. Check Consent on behalf of your organization and click Accept.

The empower® Charts Azure app will be registered in organizations AAD and permission will be granted for all users organization-wide. 

Granting Permissions via Browser-Link:

1. The tenant-ID of your organization’s AAD is required. 
2. Then navigate to this URL:                         
   https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id=f05a4e72-4760-458e-a39b-88740cdd932e
   
   Please note: The {tenant-id} must be replaced with the tenant-ID of your organization’s AAD.
   The Client-Id must remain unchanged.
    
3. Modify the link and paste it into web browser.
4. Log in with an Azure admin account. 
5. Navigate to Enterprise Applications. The empower® Chart Azure-app must be visible now.
6. Select the empower® charts application so that you can grant client-wide administrator consent.
7. Select Permissions, and then click Grant Administrator Consent.
8. Additionally, select Grant (Scopes: MyFiles.Read and AllSites.Read) and set for all users.

Please note: Even when you host empower® on-premises, an Azure app registration for empower® Charts might be required.

Explanation of the permissions used

Permissions, also called “Scopes” in the AAD-context, are embedded in authentication tokens when they are issued. Since empower® Charts will subsequently use these authentication tokens to retrieve the requested Excel-files it is necessary that the tokens contain certain read permissions. All required permissions are already configured in the empower® Charts Azure- app. The configured scopes are listed below:

Scope: MyFiles.Read 

Description: Gain read access to the user’s SharePoint/OneDrive files. 

Scope: AllSites.Read 

Description: Gain read access to files that are stored on different subsites in SharePoint and are not directly stored in the user’s personal domain.

All permissions used by the empower® Charts Azure-app are so-called "delegated permissions". Microsoft's permission system works by creating an intersection of the permissions of the currently active user and the permissions requested by the empower® Charts Azure-app.

Important: This means that when using empower® Charts no user will ever gain access to any files that he or she does not have access to anyway.

More information on delegated permissions is provided here: 

https://learn.microsoft.com/en-us/azure/active- directory/develop/delegated-access-primer