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.
- When the Register an application page appears, enter your application's registration information:
- 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
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.
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:
- 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.
- To add a client secret, follow these steps:
- Select New client secret.
- Add a description of your client secret.
- Select a duration.
- Select Add.
- 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.
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.
- Select Delegated permissions.
- In the "Select permissions" search box type "User".
- Select User.Read.All.
- Click Add permissions at the bottom of the flyout.
- Add the similar permission of Group.Read.All but only for Group.
- 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.
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:
- In Matrix42 Software Asset and Service Management, open the Data Providers search page under Administration → Integration.
- 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.
- 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).
- 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.
- 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.
Default schedule for Azure Active Directory connector is active and set to run hourly.
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.
true if the account is enabled; otherwise, false. This property is required when a user is created.
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.
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".
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. The SMTP address for the user, for example, "firstname.lastname@example.org". 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:
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.
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
Unifiedthen the group is an Office 365 group; otherwise, it's a security group.
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:
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: email@example.com", "smtp: firstname.lastname@example.org"].
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:
- Starts With.
You can also combine the filter conditions with the following logical operators:
You can also combine the conditions by groups.
Only one kind of logical operator can be defined on each level
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
- 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
SPSAccountClassAD.Sid = sid
(SPSAccountClassBase.NBAccountName = sAMAccountName AND Domain)
SPSAccountClassAD.Domain = @DomainId
|Name||Azure AD||Data Definition||Attribute||Note|
|Locked||CASE WHEN accountEnabled = 'true' THEN 0 ELSE 1 END||SPSAccountClassAD||Locked|
|Domain||-||SPSAccountClassAD||Domain||taken from Relation, @DomainID|
CASE WHEN userPrincipal
|Person||-||SPSAccountClassBase||Owner||taken from Relation|
SPSUserClassLdap.Sid = sid
|Name||Azure AD||Data Definition||Attribute||Note|
- 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)
(SPSSecurityGroupClassAD.Sid = sid AND Domain)
(SPSSecurityGroupClassAD.NT4Name = sAMAccountName AND Domain)
(SPSSecurityGroupClassAD.Name = name AND Domain)
|Name||Azure AD||Data Definition||Attribute||Note|
|Group Type||groupTypes.Contains("Unified") ? 16 : 48||SPSSecurityGroupClassAD||GroupType|
|Security Group||CASE WHEN groupType & 32 = 32 THEN 1 ELSE 0 END||SPSSecurityGroupClassAD||IsSecurityGroup|
Common Azure AD Attbitutes
|Last Sync Date||-||-||SPSCommonClassLdap||LastSyncDate||Current date|
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.
- Enabled STS feature for Software Asset & Service Management (see STS/SAML2 for all WM applications)
- Azure Active Directory Tenant with Admin Access
Setting up SAML Application in AAD
Login to appropriate Azure Portal tenant with Admin User (https://portal.azure.com)
- Navigate to Azure Active Directory → Enterprise Applications
- Create New “Non-gallery ” Application. It will be used to integrate SAML2 authentication on Azure side.
- Upon creating application, navigate to Manage → Single Sign-on
- Select "SAML" single sign-on method:
5. On the Single sign-on page Set up Single Sign-On with SAML. This requires the next information about your SASM application endpoints:
- Identifier(Entity ID): usually, the hostname of your SASM application should be provided in there, e.g. https://wmpreview03.imagoverum.com
- Reply url: e.g. https://wmpreview03.imagoverum.com/m...uthorize/login
- Sign on URL: the URL where the user will be redirected after sign-on, e.g. https://wmpreview03.imagoverum.com/wm
- Logout URL: https://wmpreview03.imagoverum.com/m...thorize/logout
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:
8. Click Save.
9. Download Federation Metadata XML. It will be used later for SAML2 configuration on the SASM side:
10. Assign users to the application or disable User assignment in application properties via Manage → Properties:
Setting up SAML2 Settings in Software Asset & Service Management
Upon successful Azure AD SAML configuration, let's proceed to the Software Asset & Service Management.
- Login to Software Asset & Service Management application with admin user.
- Proceed to Administration application → Settings → Edit → Secure Token Service.
- 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:
- Identity provider certificate: use the "x509Cerrificate" key in recently downloaded Federation Metadata XML file
- Set SAML2 Name Id policy to "EmailAddress"
- Set "SAML2 enabled" to true:
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.
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.