This article contains the following sections:
- General
- Configuring App Registration
-
Required Information for Login Link Configuration
- Advanced Configurations
- Troubleshooting
General
For integrations with Microsoft 365, authentication must be configured. Microsoft 365 uses Microsoft Entra ID for this purpose.
It is therefore also possible for customers who do not have Microsoft 365 but do have a Microsoft Entra ID to log in to Embrace via the procedure below.
This document assumes that the organisation already has Microsoft 365 / Microsoft Entra ID and that authentication has already been arranged with it. If not, it is advisable for the organisation to arrange this first, possibly with the help of a Microsoft 365 specialist. Microsoft 365 has 3 variants of authentication described here: https://blogs.office.com/en-us/2014/05/13/choosing-a-sign-in-model-for-office-365/. All three variants are supported by Embrace.
Embrace can then be configured. Embrace offers the following 2 options:
- Option 1: Configure Embrace so that users can log in to Embrace with their Microsoft 365 account.
- Option 2: Configure Embrace so that users can log in with another account (Embrace Forms, AD, ADFS, etc) and link their Microsoft 365 account to their user profile once.
For both options, an app application must be created in Azure. This document describes the actions the customer must take to create an app application.
Configuring App Registration
Creating a New App Registration
- Go to https://portal.azure.com or https://aad.portal.azure.com and log in.
- Go to "Microsoft Entra ID" and then to "App registrations"
-
You will now see an overview of registrations and can add a new registration:
- Choose "New registration"
- Fill in the following fields:
- Name: enter a descriptive name for the app registration, e.g. Embrace intranet or intranet name.
- Supported account types: select the option " Accounts in this organizational directory only (Embrace Facilities B.V. (Office) only - Single tenant)"
- Redirect URI: Select the option --> Web
Enter a login URL. This login URL must look as follows:
https://auth.embracecloud.nl/auth/realms/[organisationname]*/broker/employees/endpoint - This also sets the OAuth callback URL. See further below under callback URLs on how you can possibly change or extend this later.
-
Click Register.
The new app registration is displayed. From the screen that now appears, the clientId (application ID) can be retrieved, which must be passed on to Embrace.
* For the organisation name, we use the domain of your organisation. You can find this, for example, in the email addresses after the @. For example: the domain of Embrace is embracecloud, see also our email addresses: ...@embracecloud.nl.
Granting Permissions
For every type of API call that Embrace wants to use, permissions must be configured. This section describes which ones these are and can be expanded in the future with more. See the paragraph at the end of this document explaining why Embrace needs these rights.
-
Go to API permissions. One permission is already configured here by default and must not be removed. Furthermore, depending on which integrations are desired, one or more must be added. NOTE! The table below distinguishes between delegated and application permissions.
Permissions Authentication M365 widget M365 Teams integration Linking of files/folders M365 connector Guest users (only in combination with M365 connector) M365 migration Delegated - Microsoft Graph Calendars.Read ✓ ✓ Calendars.Read.Shared ✓ Directory.Read.All ✓ ✓ Email ✓ Files.ReadWrite ✓ Files.ReadWrite.All ✓ Group.Read.All ✓ Group.ReadWrite.All ✓ Mail.Read ✓ Presence.Read.All ✓ Profile ✓ Sites.Manage.All ✓ Subscription.Read.All ✓ Tasks.ReadWrite ✓ Team.ReadBasic.All ✓ User.Invite.All ✓ User.Read ✓ ✓ ✓ ✓ ✓ User.Read.All ✓ Delegated - SharePoint AllSites.FullControl ✓ Application - Microsoft Graph Directory.Read.All ✓ Files.ReadWrite.All ✓ Group.Read.All ✓ Group.ReadWrite.All ✓ User.Invite.All ✓ User.ReadWrite.All ✓ ✓ ✓ - Click the button to add a permission to update permissions.
- You can now also choose whether it is desired that every user (once, during login) grants permission for the Embrace Microsoft 365 integration or that an administrator does this on behalf of all users. For more explanation, see the consent paragraph.
Selecting Id Tokens
- Go to "Authentication" and check Id tokens under "Implicit grant and hybrid flows". Save the change.
Redirect URIs
- Go to >Manage >Authentication >Platform configurations >Redirect URIs.
Add two more redirect URIs besides the already created redirect URI:
Consent
The first time a user logs in, they must give consent for the permissions the app registration requires. This screen looks like this, for example:
As Embrace performs more integrations with Office 365, more permissions will also be needed and this list can become quite long:
This can lead to confusion and questions among users. To prevent this, an Azure administrator can give this consent on behalf of all users and this screen will not be shown.
- Click API Permissions and click on "Grant admin consent for..."
Required Information for Login Link Configuration
Authority: tenantID
For the connection, Embrace needs the Authority. This looks as follows: https://login.windows.net/[tenantid]. The tenantid can be found by clicking on overview and then Directory-Id (tenant-id).
Creating a Secret
- Go to "Certificates & secrets" and choose "new client secret".
-
Enter a description and choose a validity. If you choose a limited validity, make a note somewhere that a new key will be created and configured in time.
- Choose save and the key (value) that now appears must be passed on to Embrace together with the ClientID of the app registration and the tenantID.
Advanced Configurations
Restricting Access to Certain Entra ID Groups
By default, every Entra ID user (including guest accounts) can log in to Embrace via the Entra ID connection. Within Embrace, no restriction is possible on specific (groups of) users. This must be configured within the identity provider (in this case Entra ID). Microsoft has several resources available on how to set this up within Entra ID:
Excluding M365 Users from Access to "Public" SharePoint Sites
By default, a user with M365 rights and an associated license has rights to all open SharePoint groups. This can be undesirable. Think, for example, of council members who have an M365 license (for using Office and OneDrive). Through OneDrive, these users then get access to documents in all open groups, because that is the default setting of SharePoint. The blog below explains how you can restrict this:
Troubleshooting
Wrong Tenant
If authentication is configured, it is for one specific Office 365 environment / tenant. Only users in that tenant can then log in. However, many users have multiple Office 365 accounts and sometimes even multiple with the same email address. If during login the user is asked whether it is a "work / school" or "personal" account, the user must always answer "work / school". This screen looks like this:
If a user logs in with an Office 365 account that is not part of the configured tenant or has chosen a personal account, the following error message appears:
There are 3 fields circled that are important to identify the problem:
- Email address: this is the account the user is trying to log in with
- Live.com: the account the user is trying to log in with is part of this tenant (in this example, a private account and not a business account)
- Malengo: this is the tenant that is configured and only accounts from this tenant are allowed.
There is a lot of confusion among users about Office 365 accounts. For more reading see:
Crypto Errors
As mentioned earlier, the OAuth tokens are encrypted with the machine key. The Azure configuration in environment management is also encrypted in this way.
If the machine key changes, all OAuth tokens can no longer be decrypted. Also, the environment management configuration of Azure can no longer be decrypted.
In the Embrace log file, this kind of information will then be logged:
- Error decrypting Azure OAuth token
System.Security.Cryptography.CryptographicException: Error occurred during a cryptographic operation
Users will then have to log in again or manually re-establish the connection (depending on which of the two authentication methods is in use, see the beginning of this document). And the configuration in environment management must be re-entered (depending on which of the two authentication methods is in use, see the beginning of this document).
The same applies when the Embrace website moves to another web server.
MsalUiRequiredException
The user gets an error screen during login and this error message appears in the log files:
Microsoft.Identity.Client.MsalUiRequiredException: AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access '00000003-0000-0000-c000-000000000000'.
If this message appears, it means that the authentication requirements set for Embrace are different from those set for Office 365. Since Embrace displays data from Office 365, Microsoft requires that Embrace has the same level of security as Office 365 (Outlook widget, MS Teams status, Office 365 1-on-1 connection, etc).
So if MFA is required for Office 365, it must also be enabled for Embrace. Or if Office 365 may only be used from certain devices or locations, this must also be enabled for Embrace.
So if a user goes to https://embrace.klant.nl, they must have the same authentication requirements as when they go to, for example, https://klant.sharepoint.com.
Error Message About Insufficient Permissions
Check whether the permissions in the app registration are set correctly and adjust them if necessary. After changing the rights, users must log in again before this takes effect.
From Embrace 1.33, app registration rights that are not correct are also reported on the dashboard in environment management.
Granting Permissions for the Suite
- Calendars.Read
- Calendars.Read.Shared
- Mail.Read
- Presence.Read.All
- Tasks.ReadWrite
- User.Read
Explanation of Permissions
Embrace requires various rights for the Microsoft Graph API. Microsoft documentation often explains which rights are needed for which Graph API call, see for example: https://docs.microsoft.com/en-us/graph/api/directoryrole-list?view=graph-rest-1.0&tabs=http. Sometimes it may seem illogical that Embrace needs both Files.ReadWrite and Files.ReadWrite.All. The reason we chose this is because this is how it is stated in Microsoft's documentation and we adhere to it for safety.
Office 365 distinguishes between delegated and application permissions. With delegated, Graph API calls are made with the rights (OAuth token) of the current user. With application, the Embrace app registration is used to make the API call. Delegated is preferred because it prevents a user from accidentally seeing more than they have rights to. However, this is not always possible. For example, sometimes Embrace must perform tasks without a user being known, for example in scheduled jobs for a sync or something similar.
The table below provides a brief explanation of why certain permissions are needed.
| Permissions | Explanation | |
|---|---|---|
| Delegated - Microsoft Graph | ||
| Calendars.Read.Shared | Ability to read a shared calendar of a user; if user1 shares their calendar with user2 | |
| Calendars.Read | Ability to read a user's calendar. | |
| Directory.Read.All | Ability to read all groups in Entra ID, for example to determine if a group already exists before Embrace creates one. Or when an Embrace group is linked to an existing Office 365 group. | |
| Files.ReadWrite | Read and write access to all files in a group so that files requested or placed in Embrace can be placed or retrieved in Office 365 by Embrace. | |
| Files.ReadWrite.All | Read and write access to all files in a group so that files requested or placed in Embrace can be placed or retrieved in Office 365 by Embrace. | |
| Group.Read.All | Reading properties of a group such as title and description so that Embrace can adopt these in Embrace. | |
| Group.ReadWrite.All | Editing properties of a group so that when the title of a group is changed in Embrace, Embrace can also update it in Office 365. | |
| Subscription.Read.All | Embrace uses WebHooks to synchronize groups in Office 365 with groups in Embrace. These WebHooks are called subscriptions and Embrace needs this right to maintain the WebHook that Embrace registers with Office 365. | |
| Sites.Manage.All | TODO | |
| Presence.Read.All | Reading Microsoft Teams presence status | |
Ability to read and update a user's To-Do tasks |
||
| User.Read | Ability to read profile information. | |
| User.Invite.All | Create a Guest account in Entra ID on behalf of the current user | |
| User.Read.All | Ability to look up a user in Entra ID based on email address (for MS Teams integration) | |
| Team.ReadBasic.All | Ability to retrieve properties of a Team for the MS Teams widget. | |
| Delegated - SharePoint | ||
| AllSites.FullControl | To be able to create a "Shared with Embrace" folder in every user's OneDrive and adjust rights on this folder so that everyone has read rights to this folder. | |
| Delegated - Exchange | ||
| EWS.AccessAsUser.All | Ability to read Exchange information via the Exchange Web Service (EWS) | |
| Application - Microsoft Graph | ||
| Directory.Read.All | For synchronising title and description and members of a group | |
| Files.ReadWrite.All | Ability to create a timeline folder in every group. | |
| Group.Read.All | For synchronising title and description and members of a group | |
| Group.ReadWrite.All | For synchronising title and description and members of a group | |
| User.Invite.All | To be able to create Guest accounts in Entra ID during migration. |
Error Message: the term 'az' is not recognized
az : the term 'az' is not recognized as the name of a cmdlet, function, script file, or operatable program. Check the spelling of the name, or if a path was included, verify that path is correct and try again.
The script uses the AZ module within Powershell. That module must be installed on the computer where the powershell script is executed. Install Azure Az via: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-windows?view=azure-cli-latest