Configuring Microsoft Entra ID / Microsoft 365 integration with DWP: Advanced Settings

Enterprise applications: Add New Application

1. In Azure portal, navigate to Microsoft Entra ID → Add new Enterprise application:
   
2. Click on the Create your own application button:
   

3. Enter the display Name for your new Non-gallery application and click Create:
   
    This application will be used to integrate SAML2 authentication on the Azure side.

Set up SAML-based single sign-on

1. Upon creating an application, navigate to the Manage section → Single sign-on → select SAML single sign-on method:
   

2. On the Single sign-on page Set up Single Sign-On with SAML, in Basic SAML Configuration section, click Edit:
   
   This section requires the following information about your DWP application endpoints:

   • Identifier (Entity ID): remove the default-suggested option and in the new field provide the hostname of your DWP application, for instance
      https://<discoveryHostName>

   • Reply URL (Assertion Consumer Service URL): modify the following URL and add your DWP application hostname, for example:
     https://<discoveryHostName>/M42Services/api/sts/login
     
     In some cases, the value depends on your Matrix42 system version. For more details, see Universal STS/SAML2 for all WM applications: ACS URL value section.

   • Sign on URL: the URL where the user will be redirected after sign-on, modify and add your DWP application host name in the following example:
     https://<discoveryHostName>/wm

   • Logout URL: modify the following URL and add your DWP application hostname 
     https://<discoveryHostName>/M42Services/api/sts/logout
     
     
     
     Basic SAML Configuration example for a DWP application with <discoveryHostName> imagoverum.m42cloud.biz

     You can find your discoveryHostName value in the SPS.config file.

3.  Save the configuration:
   
4. Skip the test configuration message: 
   

Attributes & Claims configuration

1. On the Single sign-on page Set up Single Sign-On with SAML, scroll down to Attributes & Claims section, and click Edit:
   
2. In the Required claim section, click on the Unique User Identifier (Name ID) to edit properties:
   
3. Change the Source attribute to user.mail as a source attribute for the claim. Thus the matching between DWP and Microsoft Entra ID will be done via user email address:
   
4. Click Save and close the Attributes & Claims configuration.

SAML Signing certificate

1. On the Single sign-on page Set up Single Sign-On with SAML, scroll down to SAML Signing Certificate section, and click the download link next to Certificate (base64) field:
   
2. On the Single sign-on page Set up Single Sign-On with SAML, scroll down to Set up your application SSO section and store URLs to the identity provider and sign-on/sign-out endpoints:
   

These URLs need to be defined in Digital Workspace Platform configuration. Azure portal and DWP application fields values match as follows:

These values will be used later for Login Configuration in DWP, see Login Configuration section of this page. 

New Application

1. In Azure portal, navigate to Microsoft Entra ID App registrations → New registration:
   
2. Provide a display Name for your application, use the default option for the Supported account types and click Register:
   

3. To set the Redirect URI, select a Web platform option. Modify the Redirect URI according to the example:

   https://{hostname}/wm/externalAuth/redirect.html

API permissions

To add permission(s) to access resource API from your client:

1. In Azure portal, navigate to Microsoft Entra ID → App registrations;
2. In All applications tab, search for your application by the display name and click on it to open the Overview page:
   
3. From the app's Overview page, select API permissions:
   
4. Click + Add a permission button:
   
5. On the Request API permissions panel, select Microsoft Graph:
   
6. Select the type of permissions used by the application to access Azure:  
   • Application permissions: the application runs as a background or daemon without a signed-in user. Ideally fits for background services like Microsoft Entra ID Import.
   • Delegated permissions: all the requests from the integrated application (Matrix42 Microsoft Entra ID Import) are executed under specific signed-in user. 

     Please make sure to pick the correspondent Application Permission type when setup the Authorization options in your DWP instance. For details, see Authorization options section of this page.

7. In the Select permissions search box type User.Read.All → select the permission checkbox → click Add permissions at the bottom of the page:
   
8. Similarly, add permissions for Group: in the Select permissions search box type Group.Read.All → select the permission checkbox → click Add permissions at the bottom of the page:
   
9. You will return to the API permissions page, where the permissions have been saved and added to the table.
   To get Global Administrator consent on selected Permissions, click Grant admin consent for your tenant and confirm:
   
   Thus, the only action required from the Global Administrator role is to access the target application and grant consent to requested permissions:
   

Certificates & secrets

Add credentials to your web application 

For a web/confidential client application to be able to participate in an authorization grant flow that requires authentication (and obtaining an access token), it must establish secure credentials. The default authentication method supported by the Azure portal is client ID + secret key.

To add credentials to your web application:

1. In Azure portal, navigate to Microsoft Entra ID → App registrations;
2. In All applications tab, search for your application by the display name and click on it to open the Overview page:
   
3. From the app's Overview page, select the Certificates & secrets section:
   
4. To add a client secret, follow these steps:
   • Select the + New client secret;
   • Add a description of your client secret;
   • Select the expiration period;
   • Select Add:
     
5. After the screen has been updated with the newly created client secret, copy the VALUE of the client secret and store it temporarily as you will need it later as this secure key is required for the configuration of Microsoft Entra ID integration in your DWP instance, see Client secret field in DWP Authorization options section of this page.

This secret string is never shown again, so make sure you copy it immediately after it has been generated. In production apps, you should always use certificates as your application secrets:

Microsoft Entra ID Domain

• Domain Name (mandatory): provide a unique name for the connection. This can be any name as it is used internally in the Matrix42 system only;

• Directory (Tenant) ID (mandatory): enter the unique directory tenant GUID that you want to request permission from. You may find this information on the Azure app registration overview page (in Azure portal, navigate to Microsoft Entra ID → App registrations → in All applications tab, search for your application by the display name and click on it to open the Overview page → copy the value from the Directory (tenant) ID field).

  Only one Microsoft Entra ID / Microsoft 365 connection can be created for the specified Directory (Tenant) ID.

Enable login with this Directory

• Enable login with this Directory: by default, this option is disabled. Select the checkbox to enable login for imported user accounts directly into DWP with this connection. The necessary settings will be made in the corresponding Login Configuration view:

Authorization options

• Application (Client) ID (mandatory): enter the Application ID.  Copy the ID from the app overview page of the Azure app registration portal. The Application ID has been assigned when you registered your app (in Azure portal, navigate to Microsoft Entra ID → App registrations → in All applications tab, search for your application by the display name and click on it to open the Overview page → copy the value from the Application (client) ID field).
• Client secret (mandatory): the Application Secret that you generated for your app in the Azure app registration portal. The value for this field was generated in Certificates & secrets area of the Azure portal configuration, see Certificates & secrets section of this page. 
• Permissions: choose from the suggested options. Choose the same option that is specified in the Azure App registration API permissions configuration step, for details see App registrations: API permissions section of this page.   
  • Microsoft Entra ID (Delegated): this option is pre-selected by default. Setup Authentication for the Delegated Permissions additionally requires login and password, as the Microsoft Entra ID Data Provider will access the Azure API as the signed-in user.
  • Microsoft Entra ID (Application): The Microsoft Entra ID Data Provider runs as a background service or daemon without a signed-in user. Application (Client) ID & Client secret only are required to establish the connection. 

Click Setup Authentication and in case of Delegated Permissions, enter your credentials.

Multi-Factor Authentication (MFA)

The system supports Multi-Factor Authentication (MFA/2FA) for Microsoft Entra ID (Delegated) Permissions.  For instance, an additional form of identification such as entering a code from the cellphone may look as follows:

Proceed to the import configuration after the successful authentication:

Not granted permissions

You will be informed if the permissions are not granted with the following messages: 

The import options are disabled as well. Adjust the API permissions for your application in Azure portal, cancel the current configuration and restart the Microsoft Entra ID / Microsoft 365 connection from the very beginning.

Granted permissions

Continue the configuration with granted permissions:

• Import Options: by default, the new connection imports all Users and all Groups.

Click Login Configuration if this option has been enabled in the General view or proceed directly to the  Add Connection step.