Skip to main content
Matrix42 Self-Service Help Center

Configuring Azure AD / Office 365 integration with DWP: Advanced Settings

Overview

Matrix42 Digital Workspace Platform provides a simple way to configure Azure Active Directory / Office 365 integration and extended login configuration.

The configuration consists of two parts that include the configuration of the Azure portal and a new Azure Active Directory / Office 365 connection in your DWP instance

Start your integration with Configuring Azure Active Directory / Office365 integration with DWP page and refer to this article for advanced settings.

Prerequisites

  • DWP subscription is activated on your environment

  • You have Administrator access to DWP and Azure Portal

  • Azure Active Directory exists

Azure Portal Configuration

This section shows how to add and register an application in Microsoft Azure Portal and configure authentication. The configuration must be made with at least Application Administrator role. More details about the built-in Azure AD roles you can find here.

New application configuration

Log in to the appropriate Azure Portal tenant with at least an Application Administrator user role (https://portal.azure.com).

Enterprise applications: Add New Application

  1. In Azure portal, navigate to Azure Active Directory  Add new Enterprise application:
    enterprise_app_add.png
  2. Click on the Create your own application button:
    create_your_own_application.png
  3. Enter the display Name for your new Non-gallery application and click Create:
    new_app_name.png
     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:
    05manage_app1.png

  2. On the Single sign-on page Set up Single Sign-On with SAML, in Basic SAML Configuration section, click Edit:
    06SSO_with_Saml_basic_configuration1.png
    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

      07basic_saml_configuration1.png

      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:
    08save_basic_saml_configuration copy.png
  4. Skip the test configuration message: 
    08skip_test_sso1.png

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:
    09attributes_n_claims1.png
  2. In the Required claim section, click on the Unique User Identifier (Name ID) to edit properties:
    10_attributes_n_claims_edit1.png
  3. Change the Source attribute to user.mail as a source attribute for the claim. Thus the matching between DWP and Azure AD will be done via user email address:
    11manage_claim1.png
  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:
    12download_certificate1.png
  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:
    13Set_up_app_sso copy.png

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

Azure Portal DWP settings & corresponding fields
Azure AD Identifier SAML2 Identity Provider ID
Login URL Single Sign-on URI Endpoint
Logout URL DWP: Single Sign-out URI Endpoint


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

Properties: Assignment required configuration​​​​​​

Skip this step if your Azure AD integration does not require Single Sign-On and integration is used for data import only.

  1.  Navigate to the Manage section → Properties → disable User assignment by choosing "No" option:
    properties_assignment_required1.png
  2. Click Save.

App registrations

Proceed according to your Azure AD integration scenario:

  • Azure AD integration with import and login: on Azure portal, in All applications tab, search for your previously created Enterprise application by the display name and click on it to open the Overview page and continue with API permissions configuration step;
  • Azure AD integration with import only: create a new application registration as suggested in the next chapter.

New Application

You don't need to create a new application if you have already created an Enterprise application as described here, and configured SAML Single sign-on. Just search for your application and continue with API permissions configuration step.

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

API permissions

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

  1. In Azure portal, navigate to Azure Active Directory → App registrations;
  2. In All applications tab, search for your application by the display name and click on it to open the Overview page:
    02_app_registrations_search1.png
  3. From the app's Overview page, select API permissions:
    03_app_registration_overview1.png
  4. Click + Add a permission button:
    04_app_registration_add_permissions 1.png
  5. On the Request API permissions panel, select Microsoft Graph:
    05_request_api_permissions1.png
  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 Azure AD Import.
    • Delegated permissions: all the requests from the integrated application (Matrix42 Azure AD 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:
    06_app_user_permissions1.png
  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:
    07_app_group_permissions1.png
  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:
    08_grant_admin_consent1.png
    Thus, the only action required from the Global Administrator role is to access the target application and grant consent to requested permissions:
    09_grant_admin_consent_success1.png

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 Azure Active Directory → App registrations;
  2. In All applications tab, search for your application by the display name and click on it to open the Overview page:
    02_app_registrations_search1.png
  3. From the app's Overview page, select the Certificates & secrets section:
    10_certificates_n_secrets1.png
  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:
      11_add_client_secret1.png
  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 Azure Active Directory 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:
12_client_secret1.png

DWP Instance Configuration

Add a new Azure Active Directory / Office 365 connection

To configure Azure Active Directory integration in your DWP instance, open Administration application → Integration → Domains/Tenants → Add a new Azure Active Directory / Office 365 connection:

AAD_10_1_add.png

The action opens a wizard that allows configuring integration in 3 steps:

  1. Configure connector using data from the Azure Portal registered application;
  2. Define Users and Groups import settings;
  3. Configure login (if enabled) according to the Azure Portal authentication settings. 

When these steps are completed the wizard allows you to test the connection and in case of success immediately run the import.

Fill out the necessary fields as described below.

General

Azure Active Directory 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 Azure Active Directory → 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 Azure Active Directory / Office 365 connection can be created for the specified Directory (Tenant) ID.

Enable login with this Directory

Skip this step if your Azure AD integration does not require Single Sign-On and integration is used for data import only.

  • 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:

AAD wizard 10_1 login configuration1.png

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 Azure Active Directory → 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.   
    • Azure Active Directory (Delegated): this option is pre-selected by default. Setup Authentication for the Delegated Permissions additionally requires login and password, as the Azure Active Directory Data Provider will access the Azure API as the signed-in user.
    • Azure Active Directory (Application): The Azure Active Directory 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. 

Screen Shot 2022-01-25 at 2.15.23 PM.png

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 Azure Active Directory (Delegated) Permissions.  For instance, an additional form of identification such as entering a code from the cellphone may look as follows:

AAD_MFA.png

Proceed to the import configuration after the successful authentication:

successful_auth_application.png

Connector Configuration (import options)

To proceed, click on the Connector Configuration button. 

At this step, the system has already validated your credentials and checks the API permissions that were previously configured on the Azure Portal for your configuration. 

Not granted permissions

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

AAD_wizard_import_not_available.png

The import options are disabled as well. Adjust the API permissions for your application in Azure portal, cancel the current configuration and restart the Azure Active Directory / Office 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.

To change the import settings and configure Users and Group filtering see examples from Azure Active Directory Data Provider page.

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

Login Configuration

You will skip this step and proceed directly to the Test Connection section if your Azure AD integration does not require Single Sign-On and integration is used for data import only.

The following fields are pre-filled automatically:

  • Service Provider Issuer Name: refers to Identifier (Entity ID) provided in Azure AD SAML application, see also New application configuration section of this page.
  • Identity Provider ID: refers to Azure AD identifier
  • Single Sign-on URI Endpoint (refers to Login URL)
  • Single Sign-out URI Endpoint (refers to Logout URL)

To configure login provide the following information: 

  • Identity Provider Certificate: use the value for the Certificate (base64) file, downloaded during the new Azure application configuration, see SAML Signing Certificate section of this page.
  • Login button title: provide the title that will be used on the login page of the DWP for this connection;
  • SAML2 Name Id policy:  use default value "EmailAddress";
  • "AllowCreate" value for SAML2 NameID Policy: use default value "None".

Click Add Connection to finalize the configuration.

Test Connection

Before completing the configuration the system automatically tests the connection. The following statuses are possible:

  • Error: click on the error to see details. The connection settings are saved but import cannot be run. Fix the errors and proceed with the import.
    test_connection_error.png
  • Success: connection is available and you can proceed with the import:

AAD_wizard_10_1_success.png

 

 

Activate Azure Active Directory / Office 365 Data Provider

In Administration application → IntegrationData Providers → click on the Azure Active Directory / Office 365 connector configuration with status Active and run Activate action to start the Data Provider.

For more details, see Azure Active Directory Data Provider page.

Adjust Global System Settings to Use new Redirect URL

Make sure that the Use new Redirect URL option is enabled in your DWP. For this, open Administration application → Global System Settings → Secure Token Service → enable the Use new Redirect URL (/m42services/api/sts/login) checkbox option as shown on the example:

use_new_redirect-url.png

Matrix42 DWP Login Page Example

The login page with connector configurations created for the Azure application may look as follows:

login.png

Azure Active Directory B2C support

Azure AD B2C is supported by DWP Azure Active Directory Data Provider since 10.0.1 release, but its functionality is limited.

To enable import from Azure AD B2C, open Azure Active Directory / Office 365 Connector Configuration and mark checkbox "Skip Import Deleted Objects" in Settings view. 

As a result, Users and Groups will be imported. However, Import of deleted in AAD B2C users and groups will be not synced to DWP, due to current limitations.

AzureAD_B2C.png

Alternative Azure AD login configuration (Azure AD SAML Toolkit)

This scenario shows how to configure login and import using Azure AD SAML Toolkit. The flow and all steps are the same as in the recommended flow but in this case you will create a new application with Azure AD SAML Toolkit.

Use this video tutorial as a reference:

Configuration steps:

  1. Azure portal:
    1. New application configuration:
      1. Enterprise applications: Add New Application with Azure AD SAML Toolkit
      2. Set up SAML-based single sign-on
      3. Attributes & Claims configuration
      4. SAML Signing certificate
    2. Properties: Assignment required configuration
    3. App registrations:
      1. API permissions
      2. Certificates & secrets
  2. DWP instance:
    1. Add a new Azure Active Directory / Office 365 connection
    2. General settings 
    3. Connector Configuration (import options)
    4. Test Connection 
    5. Activate Azure Active Directory / Office 365  Data Provider
    6. Adjust Global System Settings to Use New Redirect URL
    7. Login Configuration 
    8. Test sign-in & sign-out
  • Was this article helpful?