The purpose of this document is to provide the steps necessary to configure a connection from the Digital Workplace to the O365 Graph API which is used to enable and display data for:
To learn more about how Akumina interfaces with Azure Graph App, please visit: /community/akumina-security-and-infrastructure-overview/
To learn more about how Akumina uses Azure Graph App to gather people data, please visit: /community/peoplesync-v5/
This document will describe how to create the Azure AD application that provides the required connection and authentication.
The qualified user to be able to perform the functions below needs to be an Azure Active Directory Global Administrator.
See article https://azure.microsoft.com/en-us/documentation/articles/active-directory-administer/
This document applies to installations of the Graph API connection to support Digital Workplaces running AppManager and Akumina Framework versions 4.0 and higher.
Access the Admin Console in your Office 365 tenant.
Under Admin Centers, select Azure AD. If you do not see this option, you must first sign up for the Azure AD Management console (see Azure AD Requirements section).
On the left nav, click on the Azure Active Directory. Then click on App registrations in the right pane.
Select “New Registration”
Enter App Graph Name
For "Support account types", usually "Single tenant" is appropriate.
Enter the Redirect URI. The Redirect URI is the {AppManagerURL}/oauth2/acs (note that /oauth2/acs must be lowercase) and click on Register.
Under "Manage" click on "Branding", the branding blade will open set the "Home page URL" to {AppManagerURL}/oauth2/signin, and SAVE.
For further understanding of “permissions and consent in the Azure Active directory v1.0 endpoint,” please see Microsoft’s documentation:
https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-permissions-and-consent
When the AppManager makes a call to the APIs, these calls are made using the identity of the current logged in user that is initiating the request (via the AppManager).
Setting the API permissions for the AAD App is important because this controls which services within O365 that the app will be able to access. There are four APIs we must request permissions from.
Note - For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (through consent) and the privileges of the currently signed-in user. Your app can never have more privileges than the signed-in user. Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. For example, assume your app has been granted the User.ReadWrite.All delegated permission in Microsoft Graph. This permission nominally grants your app permission to read and update the profile of every user in an organization. If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. However, if the signed-in user is not in an administrator role, your app will be able to update only the profile of the signed-in user. It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.
Click on “API permissions," “Microsoft Graph” will appear click on “Microsoft Graph,” the interface will display the “Delegated Permissions” by default.
Expand the following Categories and Check the box for the following permissions:
Please note the purpose of the permissions as it is selected to understand the purpose of the selection.
|
Category - Expand |
Permission Name |
Feature/Purpose |
|---|---|---|
| Calendar | Calendars.ReadWrite | (My Events | Company Calendar |Activity Stream). Write is used when the user accepts a calendar event via Activity Stream. |
| Channel | Channel.ReadBasic.All | (MyTeamsLinkWidget) Allows for the "Channel" names to be read and displayed. |
| Directory | Directory.AccessAsUser.All | (EmployeeDetailPage) |
| MailboxSettings | MailSettings.ReadWrite | (Company Calendar) |
| Mail.Read | (MyEmailWidget) This is a manual step to be configured if using the web app powershell deploy. | |
| Sites | Sites.Read.All | (MySitesWidget) Allows for the "frequent sites" and "following" tabs. |
| Team | Team.ReadBasic.All | (MyTeamsLinkWidget) Allows for the Teams and Channels to display. |
| User | User.Read | (EmployeeDetailPage) |
| User | User.Read.All | (EmployeeDetailPage) |
| Files | Files.Read.All | (MyRecentFiles) |
| Tasks | Tasks.Read | (MyTasks) |
| Presence | Presence.Read | (Multiple widgets to display users team presence) |
| Presence | Presence.Read.All | (Multiple widgets to display users team presence) |
Click on “Update permissions”
To add permissions to SharePoint, click on the “API permissions” click on “Add a Permissions.”
From the “Request API Permission” scroll and select “SharePoint."
Click on “Delegated permissions,” expand the categories, and check the permissions below:
|
Category - Expand |
Permission Name |
Feature/Purpose |
|---|---|---|
| AllSites | AllSites.Manage | Allows the app to manage all site collections on behalf of the signed-in user. If you leverage site creator to deploy your site, with inheriting permissions for visitor group access, we need “AllSites.Fullcontrol”. Breaking inheritance to set visitor access will fail on headless mode if full control is not set. To fix this issue, navigate to lists to break permissions and add visitor groups to the following lists: PageWidgets_AK,PageData_AK,WidgetProperties_AK,DashboardDragDrop_AK,AppDisplayOrder_AK, Comments_AK,MyDashboard_AK,NewIntranetFeedback_AK,IntranetSurvey_AK,NewsComments_AK |
| AllSites | AllSites.FullControl | Allows the app to have full control of all site collections on behalf of the signed-in user. Required for headless mode to index pages in PageData_AK and break inheritance for page permissions. |
| Sites | Site.Search.All | Allows the app to run search queries and to read basic site info on behalf of the current signed-in user. Search results are based on the user's permissions instead of the app's permissions. |
| TermStore | TermStore.ReadWrite.All | Allows the app to read, create, update, and delete managed metadata from the term store on behalf of the signed-in user. |
Click on “Microsoft Graph” and “Application Permissions”
Check each of the “Permission Name” as required for your site.
|
Category - Expand |
Permission Name |
Feature/Purpose |
|---|---|---|
| Calendars | Calendar.Read | (Activity Stream) Required if Outlook subscription enabled. Outlook subscription lets you stream outlook events directly to subscribed users. |
| Directory | Directory.Read.All | (People Sync) |
| Group | Group.ReadWrite.All | (Workspaces) v4.5 |
| User | User.Read.All | (People Sync) - Required for Schools and Skills |
Click on “Update permissions."
Click on “SharePoint” and “Application Permissions”
|
Category - Expand |
Permission Name |
Feature/Purpose |
|---|---|---|
| TermStore | TermStore.Read.All | Required for personas on version 5.0 and above (applying personas to content). |
| Sites | Sites.ReadWrite.All |
Forms processing (edit, record processing status), Employee Detail (edit), Activity Streams (read). SharePoint subscriptions in Activity Manager. If the intranet is not using Forms then this permissions can be reduced to "Sites.Read.All". |
The Sites.Selected permissions are currently only available when calling the Microsoft Graph APIs.
SharePoint REST and CSOM currently do not support Sites.Selected, our app uses SharePoint REST and CSOM hence currently, Sites.Selected cannot be used.
After all permissions have been selected, the “Azure Active Directory Global Administrator” needs to click on the “Grant admin consent for the API permissions” button and then click on the YES button.
Please verify the success message has been displayed else permissions will not have been granted.
Akumina can support both v1 and v2 tokens, but not simultaneously. If you upgrade to v2 tokens and your users are from multiple tenants, including live accounts, ensure that the Entra ID app created for the Akumina application is configured to support multi-tenancy.
Additionally, you must update the tenant settings in Akumina AppManager as shown below:
For 5.0 versions and above, the Graph App's "Certificates & secrets" must be configured to use a thumbprint. A purchased certificate or self signing certificate can be used.
If a purchased certificate is to be used, the certificate must be of length 2048, a text version of the certificate and password will be required for the AppManager tenant configuration.
If a self signing certificate is to be used please visit here to learn more about creating the certificate.
On the Graph Apps, under Management click on "Certificates & secrets", then click on "Upload certificates"
A "AAD Secret" is required to complete the installation. On the Graph App's "Certificate & secret" blade, click on "+ New client secret". Enter an appropriate name for the secret and click on Add.
Copy the value of the secret, this will be the only time you see this value.
This value is the AAD Client Secret - used in the Tenant Configuration of the AppManager.
On The Graph App, navigate to Overview, copy the value for the "Application (client) ID"
This value is the Application (Client) ID - used in the Tenant Configuration of the AppManager.