Skip to main content
Matrix42 Self-Service Help Center

Azure Active Directory

Overview

Integration with Azure Active Directory is implemented by importing Azure Active Directory (AAD) objects to Matrix42 Software Asset and Service Management and synchronizing changes in these objects from Matrix42 Software Asset and Service Management to the AAD server.

Configure a client application to access web APIs

This quickstart shows you how to add and register an application using the App registrations experience in the Azure portal so that your app can be integrated with the Microsoft identity platform.

Register a new application using the Azure portal

  • Navigate to the Azure AD Portal. Login using a personal account (aka Microsoft Account) or Work or School Account with permissions to create app registrations.

    If you do not have permissions to create app registrations contact your Azure AD domain administrators.

  • If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the Azure AD tenant that you want.
  • In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations > New registration to add a new application.001 Add new application_.png
  • When the Register an application page appears, enter your application's registration information:

    002 Setting new application.png

    • Name - Enter a meaningful application name that will be displayed to users of the app.
    • Supported account types - Select which accounts you would like your application to support.

      Supported account types

      Description

      Accounts in this organizational directory only

      Select this option if you're building a line-of-business (LOB) application. This option is not available if you're not registering the application in a directory.

      This option maps to Azure AD only single-tenant.

      This is the default option unless you're registering the app outside of a directory. In cases where the app is registered outside of a directory, the default is Azure AD multi-tenant and personal Microsoft accounts.

      Accounts in any organizational directory

      Select this option if you would like to target all business and educational customers.

      This option maps to an Azure AD only multi-tenant.

      If you registered the app as Azure AD only single-tenant, you can update it to be Azure AD multi-tenant and back to single-tenant through the Authentication blade.
      Accounts in any organizational directory and personal Microsoft accounts Select this option to target the widest set of customers.

      This option maps to Azure AD multi-tenant and personal Microsoft accounts.

      If you registered the app as Azure AD multi-tenant and personal Microsoft accounts, you cannot change this in the UI. Instead, you must use the application manifest editor to change the supported account types.
  • When finished, select Register.
  • Once the app is created, copy the Application (client) ID and Directory (tenant) ID from the overview page and store it temporarily as you will need both later.

    003 Overview new application_.png

To add additional capabilities to your application, you can select other configuration options including branding, certificates and secrets, API permissions, and more.

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 obtain an access token), it must establish secure credentials. The default authentication method supported by the Azure portal is client ID + secret key.

From the app's Overview page, select the Certificates & secrets section:004 Certificates & secrets_.png

  1. To add a certificate, follow these steps:
    • Select Upload certificate.
    • Select the file you'd like to upload. It must be one of the following file types: .cer, .pem, .crt.
    • Select Add.
  2. To add a client secret, follow these steps:
    • Select New client secret.
    • Add a description of your client secret.
    • Select a duration.
    • Select Add.
  3. After the screen has updated with the newly created client secret copy the VALUE of the client secret and store it temporarily as you will need it later.

    This secret string is never shown again, so make sure you copy it now. In production apps, you should always use certificates as your application secrets, but for this sample, we will use a simple shared secret password.

    005 Certificates & secrets key_.png

Add permissions to access web APIs

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

  • From the app's Overview page, select API permissions.
  • Select the Add a permission button.
  • On the Request API permissions panel select Microsoft Graph.

    006 Add Permissionsl_.png

  • Select Delegated permissions.
  • In the "Select permissions" search box type "User".
  • Select User.Read.All.

    007 Permissions User.Read.All_.png

  • Click Add permissions at the bottom of the flyout.
  • Add the similar permission of Group.Read.All but only for Group.

    013 Permissions Group.Read.Alll.png

  • When finished, select Add permissions. You will return to the API permissions page, where the permissions have been saved and added to the table.
  • Grant admin consent on selected Permissions.

Grant Permissions User.Read.All and Group.Read.All

Granted Permissions for User.Read.All and Group.Read.All

Configuring the Azure AD Data Provider

The Azure Active Directory Data Provider is designed for establishing the integration between Matrix42 Software Asset and Service Management and an Azure AD server.

To configure the Azure Active Directory Data Provider:

  1. In Matrix42 Software Asset and Service Management, open the Data Providers search page under Administration → Integration.
  2. Double-click the Azure Active Directory Data Provider to open it. The General dialog page contains the Configurations list that can be managed for this provider.
  3. On the Implementation page, you can specify settings that will define the execution of all configurations.
    • Import Workflow: The workflow that enables data import from an Azure AD server.
    • Run Full Synchronization interval, days: Specify how often the system should execute the full import. By default, only updates are imported from the Azure AD server (only values between 1-7 are possible).
  4. To add a new configuration for the Data Provider, use the + action on the General page. The new properties dialog will open:

Fill in the General and Settings dialog pages for the new configuration.

General

  • Data Gateway: Select the Data Gateway instance that will execute the configuration.
  • Data Provider: The Data Provider for which the configuration is created. This field is for informational purposes only.
  • Description: Provide additional details about this configuration.
  • Enable import: Select the checkbox to activate this configuration for import. Otherwise, it will be used only for synchronization.
  • Login, Password: Provide the credentials for accessing the Azure AD portal.
  • Application (client) ID: The Application ID copied from the app overview page that the Azure app registration portal assigned when you registered your app.
  • Directory (tenant) ID: The directory tenant that you want to request permission from. This can be a GUID or a user-friendly name format.
  • Client Secret: The Application Secret that you generated for your app in the app registration portal.

010 Connector Configuration-General.png

Schedule

Default schedule for Azure Active Directory connector is active and set to run hourly.

Settings

This section contains a number of settings grouped as follows:

  • Domain: Use the single selection button to select the domain for which the integration should be established.
  • Import Users: Indicates whether users will be imported.

    If User Filter is active you can specify a collection of conditions based on a list of supported properties for filtering to retrieve just a subset of a collection.

    Supported properties

    Description

    Account Enabled

    true if the account is enabled; otherwise, false. This property is required when a user is created.

    City

    The city in which the user is located.
    Country The country/region in which the user is located; for example, “US” or “UK”.
    Department The name of the department where the user works.
    State The state or province in the user's address. 

    Country Code

    A two-letter country code (ISO standard 3166). Required for users that will be assigned licenses due to legal requirements

    to check for availability of services in countries. Examples include: "US", "JP", and "GB".

    Display Name

    The name displayed in the address book for the user.

    This is usually the combination of the user's first name, middle name, and last name.

    This property is required when a user is created and it cannot be cleared during updates.

    Employee ID The employee identifier assigned to the user by the organization.
    First Name The given name (first name) of the user.
    Last Name The user's surname (family name or last name).

    When the Last Name is not defined, the user's Display Name is used for filling Last Name (all parts after the first name are split with whitespace and added as the last name).

    Job Title The user’s job title.
    Mail The SMTP address for the user, for example, "jeff@contoso.onmicrosoft.com".
    Mail Nickname The mail alias for the user. This property must be specified when a user is created.

    On-Premises Immutable ID

    This property is used to associate an on-premises Active Directory user account to their Azure AD user object.

    This property must be specified when creating a new user account in the Graph if you are using a federated domain for the user’s userPrincipalName (UPN) property.

    The $ and _ characters cannot be used when specifying this property.

    Other Mails A list of additional email addresses for the user; for example: ["bob@contoso.com", "Robert@fabrikam.com"] 
    Proxy Addresses

    For example: ["SMTP: bob@contoso.com", "smtp: bob@sales.contoso.com"]

    User Principal Name (UPN)

    The User Principal Name (UPN) of the user.

    The UPN is an Internet-style login name for the user based on the Internet Standard RFC 822.

    By convention, this should map to the user's email name. 

    User Type A string value that can be used to classify user types in your directory, such as “Member” and “Guest”.
  • Import Groups: Indicates whether groups will be imported.

    If Group Filter is active you can specify a collection of conditions based on a list of supported properties for filtering to retrieve just a subset of a collection.

    Supported properties

    Description

    Display Name The display name for the group. This property is required when a group is created and cannot be cleared during updates.
    Group Types Specifies the group type and its membership. 

    If the collection contains Unified then the group is an Office 365 group; otherwise, it's a security group. 
    Mail The SMTP address for the group.
    Mail Nickname The mail alias for the group, unique in the organization. This property must be specified when a group is created.
    On-Premises Last Sync DateTime Indicates the last time at which the group was synced with the on-premises directory. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'
    On-Premises Sync Enabled
    • true if this group is synced from an on-premises directory; 
    • false if this group was originally synced from an on-premises directory but is no longer synced; 
    • null if this object has never been synced from an on-premises directory (default).
    Proxy Addresses Email addresses for the group that direct to the same group mailbox. For example: ["SMTP: bob@contoso.com", "smtp: bob@sales.contoso.com"]
    Security Enabled Specifies whether the group is a security group.

To add a filter condition, follow these steps:

  • Click Add Condition.
  • Select the property you'd like to filter.
  • Select an operator.

    The following operators are supported:

    • Equals
    • Starts With.

    You can also combine the filter conditions with the following logical operators:

    • AND
    • OR

    You can also combine the conditions by groups.

    Only one kind of logical operator can be defined on each level

010 Connector Configuration-Settings-New condition.png

Import from Azure Active Directory

As a rule, Matrix42 Software Asset and Service Management cannot access corporate networks and collect their data. Therefore, the Data Gateway service is installed within the corporate network that is managed by an Azure AD server. The gateway collects the data on the Azure AD server and sends it to Matrix42 Software Asset and Service Management.

1 - Activating the Azure Active Directory Data Provider

The Azure AD import can be triggered in several ways in Matrix42 Software Asset and Service Management:

  • Manually run Azure AD connector data import with the Activate action available in Administration application → Integration → Data Providers → Active Directory. It retrieves all data available at the configured remote Azure AD server(s).
  • Scheduled: configured AD Connector engine activation runs the import and triggers the Active Directory Data Provider according to the specified import schedule.

2 - Launching the Directory Domain Services Server Workflow

The Azure Active Directory Data Provider launches the Directory Domain Services workflow. It is a server workflow that is run in Matrix42 Software Asset and Service Management.

3 - Launching the Azure AD Collect Data Command

The Directory Domain Services workflow creates jobs according to the specified configurations of the Data Provider. The Data Provider configurations contain the information on the target domain and stipulate the conditions of import. When the Data Gateway finds the jobs, it starts the Azure AD Collect Data command.

4 - Retrieving Azure AD Objects

The Azure AD Collect Data command is run on the Data Gateway server and therefore it can access the network data. Based on settings in the Data Provider configuration, the command activity collects data on Azure AD objects and saves it as a package of XML files. A separate XML file is created for each imported object and for each type of deleted objects. If the import is configured for accounts, groups, the command activity generates the following list of files:

  • Account.xml contains all Azure AD users that are currently active.
  • Group.xml contains all Azure AD groups that are currently active.
  • DeletedAccount.xml is relevant for partial import and contains users that have been deleted on an Azure AD server since the last import.
  • DeletedGroups.xml is relevant for partial import and contains groups that have been deleted on an Azure AD server since the last import.
  • Membership.xml contains the relations between Azure AD groups and their members. 

5 - Passing Azure AD Objects to Matrix42 Software Asset and Service Management

The Data Gateway passes XML files to the Directory Domain Services workflow in Matrix42 Software Asset and Service Management.

6 - Creating and Updating Objects Based on Imported Data

The Directory Domain Services workflow executes import definitions for each imported object. It uses the XML files as the data source to either update Matrix42 Software Asset and Service Management objects with new values from Azure AD objects or create new objects in Matrix42 Software Asset and Service Management.

The following import definitions are executed:

  • AD: Import Accounts
    The import definition updates the existing accounts and creates new ones based on active users on an Azure AD server. It uses the Account.xml file as a data source.
  • AD: Import Groups
    The import definition updates existing groups and creates new ones based on active groups on an Azure AD server. It uses the Group.xml file as a data source.
  • AD: Import Persons
    The import definition updates existing persons and creates new ones based on active users on an Azure AD server. It uses the Person.xml file as a data source.
  • AD: Membership
    The import definition updates group membership for accounts, groups based on data from an Azure AD server. It uses the Members.xml file as a data source.
  • AD: Update Deleted Accounts
    If some Azure AD users have been deleted since the last import, this import definition changes the Status field value to Deleted for corresponding accounts in Matrix42 Software Asset and Service Management. It uses the DeletedAccount.xmlfile as a data source.
  • AD: Update Deleted Persons 
    If some Azure AD users have been deleted since the last import, this import definition changes the Status field value to Deleted for corresponding persons in Matrix42 Software Asset and Service Management. It uses the DeletedAccount.xml file as a data source.
  • AD: Update Deleted Groups
    If some Azure AD groups have been deleted since the last import, this import definition changes the Status field value to Deleted for corresponding groups in Matrix42 Software Asset and Service Management. It uses the DeletedGroups.xml file as a data source.

Azure AD Data Provider Attribute Mapping

Users

Rules

  • Account attributes including state are imported from Azure Active Directory
  • Corresponding Person is created for every Account that is imported from Azure Active Directory
  • If Account is already associated with an existing Person, Person is not updated
  • Person attributes are set only in case when new Person is created during import from Azure Active Directory
  • Person attributes are never updated during Import if Person already exists
  • Person attributes are not synchronized back to Azure Active Directory

Account

Mapping
SPSAccountClassAD.Sid = sid

or

(SPSAccountClassBase.NBAccountName = sAMAccountName AND Domain)

where Domain:

SPSAccountClassAD.Domain = @DomainId
Attributes
Name Azure AD Data Definition Attribute Note
State 512 NORMAL_ACCOUNT SPSCommonClassBase State  
Locked CASE WHEN accountEnabled = 'true' THEN 0 ELSE 1 END SPSAccountClassAD Locked  
Domain - SPSAccountClassAD Domain taken from Relation, @DomainID
Account Name

CASE WHEN userPrincipal
​Name IS NULL THEN onPremisesSamAccountName ELSE SubString(userPrincipal
​Name,0, PATINDEX(”%@%”, userPrincipalName)) END

SPSAccountClassBase AccountName  
NETBIOS Name onPremisesSamAccountName SPSAccountClassBase NBAccountName  
Person - SPSAccountClassBase Owner taken from Relation
Federal State state SPSAccountClassBase FederalState  
Address streetAddress SPSAddressClassBase Street  
Country country SPSAddressClassBase Country  
Fax faxNumber SPSAddressClassBase Facsimile  
P.O. postalCode SPSAddressClassBase ZIP  
City city SPSAddressClassBase City  
Email mail SPSAddressClassBase eMail  
Sid id SPSAccountClassAD Sid  
Distinguished Name onPremisesDistinguishedName SPSAccountClassAD ADCN  
First Name givenName SPSAccountClassADUser FirstName  
Last Name surname SPSAccountClassADUser LastName  
Position jobTitle SPSAccountClassADUser Position  
Cell Phone mobilePhone SPSAccountClassADUser MobilePhone  
Office officeLocation SPSAccountClassADUser Office  
Department department SPSAccountClassADUser Department  
Company companyName SPSAccountClassADUser Company  

Person

Mapping
SPSUserClassLdap.Sid = sid
Attributes
Name Azure AD Data Definition Attribute Note
Display Name displayName SPSUserClassBase DisplayName  
Federal State state SPSAddressClassBase State  
Address streetAddress SPSAddressClassBase Street  
Country country SPSAddressClassBase Country  
Fax faxNumber SPSUserClassBase Fax  
P.O. postalCode SPSAddressClassBase POBoxZIP  
City city SPSAddressClassBase City  
Email mail SPSAddressClassBase eMail  
Accounts id SPSUserClassBase Accounts Relation
Distinguished Name onPremisesDistinguishedName SPSUserClassLdap DistinguishedName  
First Name givenName SPSUserClassBase FirstName  
Last Name surname SPSUserClassBase LastName  
Position jobTitle SPSUserClassBase Position  
Cell Phone mobilePhone SPSUserClassBase MobilePhone  
Business Phone businessPhone SPSUserClassBase BusinessPhone  
Office officeLocation SPSUserClassBase Office  
Department department SPSUserClassBase Department  
Company companyName SPSUserClassBase Company  

Groups

Rules

  • All specified attributes including state are imported from Azure Active Directory
  • All specified attributes  are synchronized to active Directory (except system attributes (sid) and other attributes from section Common Azure AD Attributes)

Mapping

(SPSSecurityGroupClassAD.Sid = sid AND Domain)

or

(SPSSecurityGroupClassAD.NT4Name = sAMAccountName AND Domain)

or

(SPSSecurityGroupClassAD.Name = name AND Domain)

Where Domain:

SPSSecurityGroupClassAD.Domain =@DomainId

Attributes

Name Azure AD Data Definition Attribute Note
State 2080 SPSCommonClassBase State  
Domain - SPSSecurityGroupClassAD Domain Relation, @DomainID
Name displayName SPSSecurityGroupClassAD Name  
NETBIOS Name displayName SPSSecurityGroupClassAD NT4Name  
Group Type groupTypes.Contains("Unified") ? 16 : 48 SPSSecurityGroupClassAD GroupType  
Security Group CASE WHEN groupType & 32 = 32 THEN 1 ELSE 0 END SPSSecurityGroupClassAD IsSecurityGroup  
Sid id SPSSecurityGroupClassAD Sid  
Description description SPSSecurityGroupClassAD Description  

Common Azure AD Attbitutes

Name

Azure AD

AD

Data Definition

Attribute

Note

Last Sync Date - - SPSCommonClassLdap LastSyncDate Current date
Object GUID id objectGuid SPSCommonClassLdap ObjectGuid  
Deleted - - SPSCommonClassLdap Deleted 0 (False)
Synchronizable - - SPSCommonClassLdap Synchronizable @Synchronizable

 

Configuring Authentication with Azure AD Account

Upon importing AAD users, Software Asset & Service Management provides authentication possibility using Azure Active Directory account directly into SASM.

In this case, SAML2 protocol should be configured on both AAD and SASM sides.

Prerequisites

Setting up SAML Application in AAD

Login to appropriate Azure Portal tenant with Admin User (https://portal.azure.com)

  1. Navigate to Azure Active Directory → Enterprise Applications
  2. Create New  “Non-gallery ” Application. It will be used to integrate SAML2 authentication on Azure side.
    clipboard_e2669cdd07724254f034eabe018784aee.png
  3. Upon creating application, navigate to ManageSingle Sign-on
  4. Select "SAML" single sign-on method:

clipboard_ec983a43ba4c0270c46f60b672e98c478.png

5. On the Single sign-on page Set up Single Sign-On with SAML. This requires the next information about your SASM application endpoints:

clipboard_ec73070811b6b394514f364805875d2e8.png

6. Save the configuration.

7. Edit User Attributes & Claims. Define user.mail as a source Attribute for the claim. Thus the matching between SASM and Azure AD will be done via user email address:

clipboard_ed0a72418be27df2fef4cfeaaa72b16ca.png

8. Click Save.

9. Download Federation Metadata XML. It will be used later for SAML2 configuration on the SASM side:

clipboard_e361cae1b1eedd06079683223132ab9d5.png

10. Assign users to the application or disable User assignment in application properties via Manage Properties:

555.png

Setting up SAML2 Settings in Software Asset & Service Management

Upon successful Azure AD SAML configuration, let's proceed to the Software Asset & Service Management.

  1. Login to Software Asset & Service Management application with admin user.
  2. Proceed to Administration application → Settings Edit Secure Token Service.
  3. Provide the following information:
    • SAML2 Login Button title
    • SAML2 Identity Provider ID (refers to Azure AD identifier)
    • Service Provider Issuer Name (refers to Entity ID provided in Azure AD SAML application, e.g. https://wmpreview03.imagoverum.com)
    • Single Sign-on URI Endpoint (refers to login URL)
    • Single Sign-out URI Endpoint (refers to Logout URL)
    • You can find these values in the recently configured Azure AD SAML application:clipboard_ee64dc448709a536515860de767157774.png
    • Identity provider certificate: use the "x509Cerrificate" key in recently downloaded Federation Metadata XML file
  4. Set SAML2 Name Id policy to "EmailAddress"
  5. Set "SAML2 enabled" to true:
    clipboard_e96f2a2160f51e20eef630b254a3f7dd2.png

Now it is possible to log in/log out via Azure AD account. Use the provided "Azure Active Directory" button on the login page in order to perform the login.
clipboard_e0742f5933743ae45ade703c0f17c0fad.png

Since the email address attribute is used to match Azure AD accounts with SASM users, duplicated email users should be avoided in order to perform successful login to SASM.

  • Was this article helpful?