Matrix42 Digital Workspace Platform 10.1 release version provides a simplified way to configure Azure Active Directory (AAD) / Office 365 integration and extended login configuration.
Use Azure Active Directory / Office365 page as a starting point and introduction to the set of articles related to the Azure integration with Matrix42 Digital Workspace Platform (DWP).
- 10.1.0 DWP release version
- Service Connections feature is available in your system
- Azure App Registration: make sure you have pre-configured the Azure Portal. For further integration of the Digital Workspace Platform with Azure Active Directory, an Azure App Registration is required. For more details, see Azure Portal Configuration page.
New Azure Active Directory / Office 365 connection configuration
To configure integration open Administration application → Integration → Domains/Tenants → Add a new Azure Active Directory / Office 365 connection:
The action opens a wizard that allows configuring integration in 3 steps:
- Configure connector using data from the Azure Portal registered application;
- Define Users and Groups import settings;
- 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.
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.
Only one Azure Active Directory / Office 365 connection can be created for the specified Directory (Tenant) ID.
- 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:
- 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.
- Client secret (mandatory): the Application Secret that you generated for your app in the Azure app registration portal.
- Permissions: choose from the suggested options
- 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.
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:
Proceed to the import configuration after the successful authentication:
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.
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, cancel the current configuration and restart the Azure Active Directory / Office 365 connection from the very beginning.
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 AAD Data Provider Settings page.
For other advanced settings see also:
Click Login Configuration if this option has been enabled in the General view or proceed directly to the Add Connection step.
Azure Active Directory (Azure AD) organizes objects like users and apps into groups called tenants.
Azure portal allows you to register and configure applications either single-tenant or multi-tenant. The Login Configuration to DWP should be modified according to the Azure portal tenant settings.
To configure login for a single-tenant application provide the following information:
- Service Provider Issuer Name: refers to Entity ID provided in Azure AD SAML application
- 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)
- Identity Provider Certificate: use the "x509Certificate" key from the Federation Metadata XML file
The following fields are pre-filled automatically:
- Service Provider Issuer Name
- Identity Provider ID
- Single Sign-on URI Endpoint
- Single Sign-out URI Endpoint
You can find these values in the previously configured Azure AD SAML application. Navigate to the provided links and finalize the Login Configuration settings in DWP according to your Azure subscription type:
- Free subscription: endpoints and Identity Provider Certificate;
- Premium subscription: endpoints and Identity Provider Certificate;
- 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 Proceed to Test Connection section.
The set of configured fields is the same both for single-tenant and multi-tenant Login Configuration and the data is retrieved to the fields automatically as well.
The main difference for the multi-tenant configuration is in the following fields:
- Service Provider Issuer Name: this field takes an endpoint value like:
- Single Sign-on URI Endpoint: instead of tenant ID in the URI use
/commonendpoint that is shared across all Azure AD tenants. When Microsoft identity platform receives a request on the
/commonendpoint, it signs the user in and, as a consequence, discovers which tenant the user is from.
Click Add Connection to finalize the configuration.
Test Connection & Run Import
Before completing the configuration the system automatically tests the connection.
- 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.
- Success: connection is available and you can proceed with "Run Import" action at the bottom of the page: