Muokkaa

Jaa


Configuring Microsoft Entra ID to provision users into LDAP directories

The following documentation provides configuration and tutorial information demonstrating how to provision users from Microsoft Entra ID into an LDAP directory.

This document describes the steps you need to perform to automatically provision and deprovision users from Microsoft Entra ID into an LDAP directory. The document illustrates how you can provision users into AD LDS as an example LDAP directory, but you can provision into any of the supported LDAP directory servers mentioned in the following sections. Provisioning users into Active Directory Domain Services through this solution isn't supported.

For important details on what this service does, how it works, and frequently asked questions, see Automate user provisioning and deprovisioning to SaaS applications with Microsoft Entra ID and on-premises application provisioning architecture. The following video provides an overview of on-premises provisioning.

Prerequisites for provisioning users into an LDAP directory

On-premises prerequisites

  • An application that uses a directory server to query users.
  • A target directory, other than Active Directory Domain Services, in which users can be created, updated, and deleted. For example, Active Directory Lightweight Services (AD LDS). This directory instance should not be a directory that is also used to provision users into Microsoft Entra ID, because having both scenarios may create a loop with Microsoft Entra Connect.
  • A computer with at least 3 GB of RAM, to host a provisioning agent. The computer should have Windows Server 2016 or a later version of Windows Server, with connectivity to the target directory, and with outbound connectivity to login.microsoftonline.com, other Microsoft Online Services and Azure domains. An example is a Windows Server 2016 virtual machine hosted in Azure IaaS or behind a proxy.
  • The .NET Framework 4.7.2 needs to be installed.
  • Optional: Although it isn't required, it's recommended to download Microsoft Edge for Windows Server and use it in-place of Internet Explorer.

Supported LDAP directory servers

The connector relies upon various techniques to detect and identify the LDAP server. The connector uses the Root DSE, vendor name/version, and it inspects the schema to find unique objects and attributes known to exist in certain LDAP servers.

  • OpenLDAP
  • Microsoft Active Directory Lightweight Directory Services
  • 389 Directory Server
  • Apache Directory Server
  • IBM Tivoli DS
  • Isode Directory
  • NetIQ eDirectory
  • Novell eDirectory
  • Open DJ
  • Open DS
  • Oracle (previously Sun ONE) Directory Server Enterprise Edition
  • RadiantOne Virtual Directory Server (VDS)

For more information, see the Generic LDAP Connector reference.

Cloud requirements

  • A Microsoft Entra tenant with Microsoft Entra ID P1 or Premium P2 (or EMS E3 or E5).

    Using this feature requires Microsoft Entra ID P1 licenses. To find the right license for your requirements, see Compare generally available features of Microsoft Entra ID.

  • The Hybrid Identity Administrator role for configuring the provisioning agent and the Application Administrator or Cloud Application Administrator roles for configuring provisioning in the Azure portal.

  • The Microsoft Entra users to be provisioned to the LDAP directory must already be populated with the attributes that will be required by the directory server schema and are specific to each user. For example, if the directory server requires each user to have a unique number between 10000 and 30000 as their User ID number to support a POSIX workload, then you would need to either generate that number from an existing attribute on the user, or extend the Microsoft Entra schema and populate that attribute on the users in scope of the LDAP-based application. See Graph extensibility for how to create additional directory extensions.

More recommendations and limitations

The following bullet points are more recommendations and limitations.

  • It isn't recommended to use the same agent for cloud sync and on-premises app provisioning. Microsoft recommends using a separate agent for cloud sync and one for on-premises app provisioning.
  • For AD LDS currently, users cannot be provisioned with passwords. So you'll need to either disable the password policy for AD LDS or provision the users in a disabled state.
  • For other directory servers, an initial random password can be set, but it isn't possible to provision a Microsoft Entra user's password to a directory server.
  • Provisioning users from Microsoft Entra ID to Active Directory Domains Services isn't supported.
  • Provisioning users from LDAP to Microsoft Entra ID isn't supported.
  • Provisioning groups and user memberships to a directory server isn't supported.

Selecting run profiles

When you create the configuration for the connector to interact with a directory server, you'll configure first for the connector to read the schema of your directory, map that schema to that of Microsoft Entra ID, and then configure the approach the connector should use on an ongoing basis, via run profiles. Each run profile you'll configure specifies how the connector will generate LDAP requests to import or export data from the directory server. Before deploying the connector to an existing directory server, you'll need to discuss with the directory server operator in your organization the pattern of operations that will be performed with their directory server.

  • After configuration, when the provisioning service starts, it will automatically perform the interactions configured in the Full Import run profile. In this run profile, the connector will read in all the records for users from the directory, using an LDAP Search operation. This run profile is necessary so that later, if Microsoft Entra ID needs to make a change for a user, Microsoft Entra ID will update an existing object for that user in the directory, rather than create a new object for that user.

  • Each time changes are made in Microsoft Entra ID, such as to assign a new user to the application or update an existing user, the provisioning service will perform the LDAP interactions in the Export run profile. In the Export run profile, Microsoft Entra ID will issue LDAP requests to Add, Modify, Remove or Rename objects in the directory, in order to bring the contents of the directory in sync with Microsoft Entra ID.

  • If your directory supports it, you can also optionally configure a Delta Import run profile. In this run profile, Microsoft Entra ID will read in changes that were made in the directory, other than by Microsoft Entra ID, since the last full or delta import. This run profile is optional since the directory may not have been configured to support a delta import. For example, if your organization is using OpenLDAP, OpenLDAP must have been deployed with the access log overlay feature enabled.

Determine how the Microsoft Entra LDAP Connector will interact with the directory server

Before deploying the connector to an existing directory server, you'll need to discuss with the directory server operator in your organization how to integrate with their directory server. The information you'll gather includes the network information of how to connect to the directory server, how the connector should authenticate itself to the directory server, what schema the directory server has selected to model users, the naming context's base distinguished name and directory hierarchy rules, how to associate users in the directory server with users in Microsoft Entra ID, and what should happen when a user goes out of scope in Microsoft Entra ID. Deploying this connector may require changes to the configuration of the directory server as well as configuration changes to Microsoft Entra ID. For deployments involving integrating Microsoft Entra ID with a third-party directory server in a production environment, we recommend customers work with their directory server vendor, or a deployment partner for help, guidance, and support for this integration. This article uses the following sample values for two directories, for AD LDS and for OpenLDAP.

Configuration setting Where the value is set Example value
hostname of the directory server Configuration wizard Connectivity page APP3
port number of the directory server Configuration wizard Connectivity page 636. For LDAP over SSL or TLS (LDAPS), use port 636. For Start TLS, use port 389.
account for the connector to identify itself to the directory server Configuration wizard Connectivity page For AD LDS, CN=svcAccountLDAP,CN=ServiceAccounts,CN=App,DC=contoso,DC=lab and for OpenLDAP, cn=admin,dc=contoso,dc=lab
password for the connector to authenticate itself to the directory server Configuration wizard Connectivity page
structural object class for a user in the directory server Configuration wizard Object Types page For AD LDS User and for OpenLDAP inetOrgPerson
auxiliary object classes for a user in the directory server Azure portal Provisioning page attribute mappings For OpenLDAP with the POSIX schema, posixAccount andshadowAccount
attributes to populate on a new user Configuration wizard Select Attributes page and Azure portal Provisioning page attribute mappings For AD LDS msDS-UserAccountDisabled, userPrincipalName, displayName and for OpenLDAP cn, gidNumber, homeDirectory, mail, objectClass, sn, uid, uidNumber, userPassword
naming hierarchy required by the directory server Azure portal Provisioning page attribute mappings Set the DN of a newly created user to be immediately below CN=CloudUsers,CN=App,DC=Contoso,DC=lab for AD LDS and DC=Contoso,DC=lab for OpenLDAP
attributes for correlating users across Microsoft Entra ID and the directory server Azure portal Provisioning page attribute mappings For AD LDS, not configured as this example is for an initially empty directory, and for OpenLDAP, mail
deprovisioning behavior when a user goes out of scope in Microsoft Entra ID Configuration wizard Deprovisioning page Delete the user from the directory server

The network address of a directory server is a hostname and a TCP port number, typically port 389 or 636. Except where the directory server is co-located with the connector on the same Windows Server, or you're using network level security, the network connections from the connector to a directory server need to be protected using SSL or TLS. The connector supports connecting to a directory server on port 389, and using Start TLS to enable TLS within the session. The connector also supports connecting to a directory server on port 636 for LDAPS - LDAP over TLS.

You'll need to have an identified account for the connector to authenticate to the directory server already configured in the directory server. This account is typically identified with a distinguished name and has an associated password or client certificate. To perform import and export operations on the objects in the connected directory, the connector account must have sufficient permissions within the directory's access control model. The connector needs to have write permissions to be able to export, and read permissions to be able to import. Permission configuration is performed within the management experiences of the target directory itself.

A directory schema specifies the object classes and attributes that represent a real-world entity in the directory. The connector supports a user being represented with a structural object class, such as inetOrgPerson, and optionally additional auxiliary object classes. In order for the connector to be able to provision users into the directory server, during configuration in the Azure portal you'll define mappings from the Microsoft Entra schema to all of the mandatory attributes. This includes the mandatory attributes of the structural object class, any superclasses of that structural object class, and the mandatory attributes of any auxiliary object classes. In addition, you'll likely also configure mappings to some of the optional attributes of these classes. For example, an OpenLDAP directory server might require an object for a new user to have attributes like the following example.

dn: cn=bsimon,dc=Contoso,dc=lab
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
cn: bsimon
gidNumber: 10000
homeDirectory: /home/bsimon
sn: simon
uid: bsimon
uidNumber: 10011
mail: bsimon@contoso.com
userPassword: initial-password

The directory hierarchy rules implemented by a directory server describe how the objects for each user relate to each other and to existing objects in the directory. In most deployments, the organization chose to have a flat hierarchy in their directory server, in which each object for each user is located immediately underneath a common base object. For example, if the base distinguished name for the naming context in a directory server is dc=contoso,dc=com then a new user would have a distinguished name like cn=alice,dc=contoso,dc=com. However, some organizations may have a more complex directory hierarchy, in which case you'll need to implement the rules when specifying the distinguished name mapping for the connector. For example, a directory server may expect users to be in organizational units by department, so a new user would have a distinguished name like cn=alice,ou=London,dc=contoso,dc=com. Since the connector doesn't create intermediate objects for organizational units, any intermediate objects the directory server rule hierarchy expects must already exist in the directory server.

Next, you'll need to define the rules for how the connector should determine if there's already a user in the directory server corresponding to a Microsoft Entra user. Every LDAP directory has a distinguished name that is unique for each object in the directory server, however that distinguished name is often not present for users in Microsoft Entra ID. Instead, an organization may have a different attribute, such as mail or employeeId, in their directory server schema that is also present on their users in Microsoft Entra ID. Then, when the connector is provisioning a new user into a directory server, the connector can search whether there's already a user in that directory that has a specific value of that attribute, and only create a new user in the directory server if one isn't present.

If your scenario involves creating new users in the LDAP directory, not just updating or deleting existing users, then you'll need to also determine how the applications that use that directory server will handle authentication. The recommended approach is for the applications to use a federation or SSO protocol such as SAML, OAuth, or OpenID Connect to authenticate to Microsoft Entra ID, and only rely upon the directory server for attributes. Traditionally LDAP directories could be used by applications to authenticate users by checking a password, but this use case isn't possible for multifactor authentication or when the user has already been authenticated. Some applications can query a user's SSH public key or certificate from the directory, which may be appropriate of the users already hold credentials of those forms. However, if your application that relies upon the directory server doesn't support modern authentication protocols or stronger credentials, then you'll need to set an application-specific password when creating a new user in the directory, as Microsoft Entra ID doesn't support provisioning a user's Microsoft Entra password.

Finally, you'll need to agree on the deprovisioning behavior. When the connector is configured, and Microsoft Entra ID has established a link between a user in Microsoft Entra ID and a user in the directory, either for a user already in the directory or a new user, then Microsoft Entra ID can provision attribute changes from the Microsoft Entra user into the directory. If a user that is assigned to the application is deleted in Microsoft Entra ID, then Microsoft Entra ID will send a delete operation to the directory server. You may also wish to have Microsoft Entra ID update the object in the directory server when a user goes out of scope of being able to use the application. This behavior depends upon the application that will be using the directory server, as many directories, such as OpenLDAP, may not have a default way of indicating a user's account is inactivated.

Prepare the LDAP directory

If you do not already have a directory server, and wish to try out this feature, then Prepare Active Directory Lightweight Directory Services for provisioning from Microsoft Entra ID shows how to create a test AD LDS environment. If you already have another directory server deployed, you can skip that article, and continue installing and configuring the ECMA connector host.

Install and configure the Microsoft Entra Connect Provisioning Agent

If you have already downloaded the provisioning agent and configured it for another on-premises application, then continue reading in the next section.

  1. Sign in to the Azure portal.
  2. Go to Enterprise applications and select New application.
  3. Search for the On-premises ECMA app application, give the app a name, and select Create to add it to your tenant.
  4. From the menu, navigate to the Provisioning page of your application.
  5. Select Get started.
  6. On the Provisioning page, change the mode to Automatic.

Screenshot of selecting Automatic.

  1. Under On-premises Connectivity, select Download and install, and select Accept terms & download.

Screenshot of download location for agent.

  1. Leave the portal and open the provisioning agent installer, agree to the terms of service, and select Install.
  2. Wait for the Microsoft Entra provisioning agent configuration wizard and then select Next.
  3. In the Select Extension step, select On-premises application provisioning and then select Next.
  4. The provisioning agent will use the operating system's web browser to display a popup window for you to authenticate to Microsoft Entra ID, and potentially also your organization's identity provider. If you're using Internet Explorer as the browser on Windows Server, then you may need to add Microsoft web sites to your browser's trusted site list to allow JavaScript to run correctly.
  5. Provide credentials for a Microsoft Entra administrator when you're prompted to authorize. The user is required to have at least the Hybrid Identity Administrator role.
  6. Select Confirm to confirm the setting. Once installation is successful, you can select Exit, and also close the Provisioning Agent Package installer.

Configure the On-premises ECMA app

  1. Back in the portal, on the On-Premises Connectivity section, select the agent that you deployed and select Assign Agent(s).

    Screenshot that shows how to select and assign and agent.

  2. Keep this browser window open, as you complete the next step of configuration using the configuration wizard.

Configure the Microsoft Entra ECMA Connector Host certificate

  1. On the Windows Server where the provisioning agent is installed, right click the Microsoft ECMA2Host Configuration Wizard from the start menu, and run as administrator. Running as a Windows administrator is necessary for the wizard to create the necessary Windows event logs.
  2. After the ECMA Connector Host Configuration starts, if this is the first time you have run the wizard, it will ask you to create a certificate. Leave the default port 8585 and select Generate certificate to generate a certificate. The autogenerated certificate will be self-signed as part of the trusted root. The SAN matches the host name. Screenshot that shows configuring your settings.
  3. Select Save.

Note

If you have chosen to generate a new certificate, please record the certificate expiration date, to ensure that you schedule to return to the configuration wizard and re-generate the certificate before it expires.

Configure a generic LDAP connector

Depending on the options you select, some of the wizard screens might not be available and the information might be slightly different. For purposes of this example configuration, provisioning users with the User object class is shown for AD LDS, and the inetOrgPerson object class for OpenLDAP. Use the following information to guide you in your configuration.

  1. Generate a secret token that will be used for authenticating Microsoft Entra ID to the connector. It should be 12 characters minimum and unique for each application. If you do not already have a secret generator, you can use a PowerShell command such as the following to generate an example random string.

    -join (((48..90) + (96..122)) * 16 | Get-Random -Count 16 | % {[char]$_})
    
  2. If you have not already done so, launch the Microsoft ECMA2Host Configuration Wizard from the start menu.

  3. Select New Connector. Screenshot that shows choosing New Connector.

  4. On the Properties page, fill in the boxes with the values specified in the table that follows the image and select Next. Screenshot that shows entering properties.

    Property Value
    Name The name you chose for the connector, which should be unique across all connectors in your environment. For example, LDAP.
    Autosync timer (minutes) 120
    Secret Token Enter your secret token here. It should be 12 characters minimum.
    Extension DLL For the generic LDAP connector, select Microsoft.IAM.Connector.GenericLdap.dll.
  5. On the Connectivity page, you'll configure how the ECMA Connector Host will communicate with the directory server, and set some of the configuration options. Fill in the boxes with the values specified in the table that follows the image and select Next. When you select Next, the connector will query the directory server for its configuration. Screenshot that shows the Connectivity page.

    Property Description
    Host The host name where the LDAP server is located. This sample uses APP3 as the example hostname.
    Port The TCP port number. If the directory server is configured for LDAP over SSL, use port 636. For Start TLS, or if you're using network-level security, use port 389.
    Connection Timeout 180
    Binding This property specifies how the connector will authenticate to the directory server. With the Basic setting, or with the SSL or TLS setting and no client certificate configured, the connector will send an LDAP simple bind to authenticate with a distinguished name and a password. With the SSL or TLS setting and a client certificate specified, the connector will send an LDAP SASL EXTERNAL bind to authenticate with a client certificate.
    User Name How the ECMA Connector will authenticate itself to the directory server. In this sample for AD LDS, the example username is CN=svcAccount,CN=ServiceAccounts,CN=App,DC=contoso,DC=lab and for OpenLDAP, cn=admin,dc=contoso,dc=lab
    Password The password of the user that the ECMA Connector will authenticate itself to the directory server.
    Realm/Domain This setting is only required if you selected Kerberos as the Binding option, to provide the Realm/Domain of the user.
    Certificate The settings in this section are only used if you selected SSL or TLS as the Binding option.
    Attribute Aliases The attribute aliases text box is used for attributes defined in the schema with RFC4522 syntax. These attributes cannot be detected during schema detection and the connector needs help with identifying those attributes. For example, if the directory server doesn't publish userCertificate;binary and you wish to provision that attribute, the following string must be entered in the attribute aliases box to correctly identify the userCertificate attribute as a binary attribute: userCertificate;binary. If you do not require any special attributes not in the schema, you can leave this blank.
    Include operational attributes Select the Include operational attributes in schema checkbox to also include attributes created by the directory server. These include attributes such as when the object was created and last update time.
    Include extensible attributes Select the Include extensible attributes in schema checkbox if extensible objects (RFC4512/4.3) are used in the directory server. Enabling this option allows every attribute to be used on all object. Selecting this option makes the schema very large so unless the connected directory is using this feature the recommendation is to keep the option unselected.
    Allow manual anchor selection Leave unchecked.

    Note

    If you experience an issue trying to connect, and cannot proceed to the Global page, ensure that the service account in AD LDS or the other directory server is enabled.

  6. On the Global page, you'll configure the distinguished name of the delta change log, if needed, and additional LDAP features. The page is pre-populated with the information provided by the LDAP server. Review the values shown, and then select Next.

    Property Description
    Supported SASL Mechanisms The top section shows information provided by the server itself, including the list of SASL mechanisms.
    Server Certificate Details If SSL or TLS was specified, the wizard will display the certificate returned by the directory server. Confirm that the issuer, subject and thumbprint are for the correct directory server.
    Mandatory Features Found The connector also verifies that the mandatory controls are present in the Root DSE. If these controls aren't listed, a warning is presented. Some LDAP directories do not list all features in the Root DSE and it's possible that the connector works without issues even if a warning is present.
    Supported Controls The supported controls checkboxes control the behavior for certain operations
    Delta Import The change log DN is the naming context used by the delta change log, for example cn=changelog. This value must be specified to be able to do delta import.
    Password Attribute If the directory server supports a different password attribute or password hashing, you can specify the destination for password changes.
    Partition Names In the additional partitions list, it's possible to add additional namespaces not automatically detected. For example, this setting can be used if several servers make up a logical cluster, which should all be imported at the same time. Just as Active Directory can have multiple domains in one forest but all domains share one schema, the same can be simulated by entering the additional namespaces in this box. Each namespace can import from different servers and is further configured on the Configure Partitions and Hierarchies page.
  7. On the Partitions page, keep the default and select Next.

  8. On the Run Profiles page, ensure the Export checkbox and the Full import checkbox are both selected. Then select Next. Screenshot that shows the Run Profiles page.

    Property Description
    Export Run profile that will export data to the LDAP directory server. This run profile is required.
    Full import Run profile that will import all data from LDAP sources specified earlier. This run profile is required.
    Delta import Run profile that will import only changes from LDAP since the last full or delta import. Only enable this run profile if you have confirmed that the directory server meets the necessary requirements. For more information, see the Generic LDAP Connector reference.
  9. On the Export page, leave the defaults unchanged and click Next.

  10. On the Full Import page, leave the defaults unchanged and click Next.

  11. On the DeltaImport page, if present, leave the defaults unchanged and click Next.

  12. On the Object Types page, fill in the boxes and select Next.

    Property Description
    Target object This value is the structural object class of a user in the LDAP directory server. For example, inetOrgPerson for OpenLDAP, or User for AD LDS. Do not specify an auxiliary object class in this field. If the directory server requires auxiliary object classes, they'll be configured with the attribute mappings in the Azure portal.
    Anchor The values of this attribute should be unique for each object in the target directory. The Microsoft Entra provisioning service will query the ECMA connector host by using this attribute after the initial cycle. For AD LDS, use ObjectGUID, and for other directory servers, see the following table. Note that the distinguished name may be selected as -dn-. Multi-valued attributes, such as the uid attribute in the OpenLDAP schema, cannot be used as anchors.
    Query Attribute This attribute should be the same as the Anchor, such as objectGUID if AD LDS is the directory server, or _distinguishedName if OpenLDAP.
    DN The distinguishedName of the target object. Keep -dn-.
    Autogenerated unchecked

    The following table lists the LDAP servers and the anchor being used:

    Directory Anchor
    Microsoft AD LDS and AD GC objectGUID. You must be using agent version 1.1.846.0 or above for ObjectGUID to be used as the anchor.
    389 Directory Server dn
    Apache Directory dn
    IBM Tivoli DS dn
    Isode Directory dn
    Novell/NetIQ eDirectory GUID
    Open DJ/DS dn
    Open LDAP dn
    Oracle ODSEE dn
    RadiantOne VDS dn
    Sun One Directory Server dn
  13. The ECMA host discovers the attributes supported by the target directory. You can choose which of those attributes you want to expose to Microsoft Entra ID. These attributes can then be configured in the Azure portal for provisioning. On the Select Attributes page, add all the attributes in the dropdown list, one at a time, that are required as mandatory attributes or that you wish to provision from Microsoft Entra ID. Screenshot that shows the Select Attributes page.
    The Attribute dropdown list shows any attribute that was discovered in the target directory and wasn't chosen on the previous use of the configuration wizard Select Attributes page.

    Make sure that Treat as single value checkbox is unchecked for the objectClass attribute, and if userPassword is being set, is either unselectable or checked for the userPassword attribute.

    If you're using OpenLDAP with the inetOrgPerson schema, please configure visibility for the following attributes.

    Attribute Treat as single value
    cn Y
    mail Y
    objectClass
    sn Y
    userPassword Y

    If you're using OpenLDAP with the POSIX schema, please configure visibility for the following attributes.

    Attribute Treat as single value
    _distinguishedName
    -dn-
    export_password
    cn Y
    gidNumber
    homeDirectory
    mail Y
    objectClass
    sn Y
    uid Y
    uidNumber
    userPassword Y

    Once all the relevant attributes have been added, select Next.

  14. On the Deprovisioning page, you can specify if you wish to have Microsoft Entra ID remove users from the directory when they go out of scope of the application. If so, under Disable flow, select Delete, and under Delete flow, select Delete. If Set attribute value is chosen, the attributes selected on the previous page won't be available to select on the Deprovisioning page.

Note

If you use the Set attribute value be aware that only boolean values are allowed.

  1. Select Finish.

Ensure ECMA2Host service is running and can read from the directory server

Follow these steps to confirm that the connector host has started and has read any existing users from the directory server into the connector host.

  1. On the server running the Microsoft Entra ECMA Connector Host, select Start.
  2. Select run if needed, then enter services.msc in the box.
  3. In the Services list, ensure that Microsoft ECMA2Host is present and running. If it isn't running, select Start. Screenshot that shows the service is running.
  4. If you have recently started the service, and have many user objects in the directory server, then wait several minutes for the connector to establish a connection with the directory server.
  5. On the server running the Microsoft Entra ECMA Connector Host, launch PowerShell.
  6. Change to the folder where the ECMA host was installed, such as C:\Program Files\Microsoft ECMA2Host.
  7. Change to the subdirectory Troubleshooting.
  8. Run the script TestECMA2HostConnection.ps1 in that directory as shown in the following example, and provide as arguments the connector name and the ObjectTypePath value cache. If your connector host isn't listening on TCP port 8585, then you may also need to provide the -Port argument as well. When prompted, type the secret token configured for that connector.
    PS C:\Program Files\Microsoft ECMA2Host\Troubleshooting> $cout = .\TestECMA2HostConnection.ps1 -ConnectorName LDAP -ObjectTypePath cache; $cout.length -gt 9
    Supply values for the following parameters:
    SecretToken: ************
    
  9. If the script displays an error or warning message, then check that the service is running, and the connector name and secret token match those values you configured in the configuration wizard.
  10. If the script displays the output False, then the connector has not seen any entries in the source directory server for existing users. If this is a new directory server installation, then this behavior is to be expected, and you can continue at the next section.
  11. However, if the directory server already contains one or more users but the script displayed False, then this status indicates the connector could not read from the directory server. If you attempt to provision, then Microsoft Entra ID may not correctly match users in that source directory with users in Microsoft Entra ID. Wait several minutes for the connector host to finish reading objects from the existing directory server, and then rerun the script. If the output continues to be False, then check the configuration of your connector and the permissions in the directory server are allowing the connector to read existing users.

Test the connection from Microsoft Entra ID to the connector host

  1. Return to the web browser window where you were configuring the application provisioning in the portal.

    Note

    If the window had timed out, then you'll need to re-select the agent.

    1. Sign in to the Azure portal.
    2. Go to Enterprise applications and the On-premises ECMA app application.
    3. Click on Provisioning.
    4. If Get started appears, then change the mode to Automatic, on the On-Premises Connectivity section, select the agent that you just deployed and select Assign Agent(s), and wait 10 minutes. Otherwise go to Edit Provisioning.
  2. Under the Admin credentials section, enter the following URL. Replace the connectorName portion with the name of the connector on the ECMA host, such as LDAP. If you provided a certificate from your certificate authority for the ECMA host, then replace localhost with the host name of the server where the ECMA host is installed.

    Property Value
    Tenant URL https://localhost:8585/ecma2host_connectorName/scim
  3. Enter the Secret Token value that you defined when you created the connector.

    Note

    If you just assigned the agent to the application, please wait 10 minutes for the registration to complete. The connectivity test won't work until the registration completes. Forcing the agent registration to complete by restarting the provisioning agent on your server can speed up the registration process. Go to your server, search for services in the Windows search bar, identify the Microsoft Entra Connect Provisioning Agent service, right-click the service, and restart.

  4. Select Test Connection, and wait one minute.

  5. After the connection test is successful and indicates that the supplied credentials are authorized to enable provisioning, select Save.
    Screenshot that shows testing an agent.

Extend the Microsoft Entra schema (optional)

If your directory server requires additional attributes that aren't part of the default Microsoft Entra schema for users, then when provisioning you can configure to supply values of those attributes from a constant, from an expression transformed from other Microsoft Entra attributes, or by extending the Microsoft Entra schema.

If the directory server requires users to have an attribute, such as uidNumber for the OpenLDAP POSIX schema, and that attribute isn't already part of your Microsoft Entra schema for a user, and must be unique for each user, then you'll need to either generate that attribute from other attributes of the user via an expression, or use the directory extension feature to add that attribute as an extension.

If your users originate in Active Directory Domain Services, and has the attribute in that directory, then you can use Microsoft Entra Connect or Microsoft Entra Connect cloud sync to configure that the attribute should be synched from Active Directory Domain Services to Microsoft Entra ID, so that it's available for provisioning to other systems.

If your users originate in Microsoft Entra ID, then for each new attribute you'll need to store on a user, you'll need to define a directory extension. Then, update the Microsoft Entra users that are planned to be provisioned, to give each user a value of those attributes.

Configure attribute mapping

In this section, you'll configure the mapping between the Microsoft Entra user's attributes and the attributes that you previously selected in the ECMA Host configuration wizard. Later when the connector creates an object in a directory server, the attributes of a Microsoft Entra user will then be sent through the connector to the directory server to be part of that new object.

  1. In the Microsoft Entra admin center, under Enterprise applications, select the On-premises ECMA app application, and then select the Provisioning page.

  2. Select Edit provisioning.

  3. Expand Mappings and select Provision Microsoft Entra users. If this is the first time you've configured the attribute mappings for this application, there will be only one mapping present, for a placeholder.

  4. To confirm that the schema of the directory server is available in Microsoft Entra ID, select the Show advanced options checkbox and select Edit attribute list for ScimOnPremises. Ensure that all the attributes selected in the configuration wizard are listed. If not, then wait several minutes for the schema to refresh, then select Attribute Mapping in the navigation line, and then select Edit attribute list for ScimOnPremises again to reload the page. Once you see the attributes listed, then cancel from this page to return to the mappings list.

  5. Every user in a directory must have a unique distinguished name. You can specify how the connector should construct a distinguished name by using an attribute mapping. Select Add New Mapping. Use the values in the following example to create the mapping, changing the distinguished names in the expression to match that of the organizational unit or other container in your target directory.

    • Mapping type: expression
    • Expression, if provisioning into AD LDS: Join("", "CN=", Word([userPrincipalName], 1, "@"), ",CN=CloudUsers,CN=App,DC=Contoso,DC=lab")
    • Expression, if provisioning into OpenLDAP: Join("", "CN=", Word([userPrincipalName], 1, "@"), ",DC=Contoso,DC=lab")
    • Target attribute: urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:-dn-
    • Apply this mapping: only during object creation
  6. If the directory server requires multiple structural object class values, or auxiliary object class values, to be supplied in the objectClass attribute, then add a mapping to that attribute. For this example of provisioning into AD LDS, mapping the objectClass isn't required, but may be necessary for other directory servers or other schemas. To add a mapping for objectClass, select Add New Mapping. Use the values in the following example to create the mapping, changing the object class names in the expression to match that of the target directory schema.

    • Mapping type: expression
    • Expression, if provisioning the inetOrgPerson schema: Split("inetOrgPerson",",")
    • Expression, if provisioning the POSIX schema: Split("inetOrgPerson,posixAccount,shadowAccount",",")
    • Target attribute: urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:objectClass
    • Apply this mapping: only during object creation
  7. If you're provisioning into AD LDS, and there's a mapping from userPrincipalName to PLACEHOLDER, then click on that mapping and edit it. Use the values below to update the mapping.

    • Mapping type: direct
    • Source attribute: userPrincipalName
    • Target attribute: urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:userPrincipalName
    • Matching precedence: 1
    • Apply this mapping: only during object creation
  8. If you're provisioning into AD LDS, then add a mapping for isSoftDeleted. Select Add New Mapping. Use the values below to create the mapping.

    • Mapping type: direct
    • Source attribute: isSoftDeleted
    • Target attribute: urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:msDS-UserAccountDisabled
  9. For each of the mappings in the following table for your directory server, Select Add New Mapping, and specify the source and target attributes. If you're provisioning into an existing directory with existing users, you'll need to edit the mapping for the attribute that is in common to set the Match objects using this attribute for that attribute. Learn more about attribute mapping here.

    For AD LDS:

    Mapping type Source attribute Target attribute
    Direct displayName urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:displayName

    For OpenLDAP:

    Mapping type Source attribute Target attribute
    Direct displayName urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:cn
    Direct surname urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:sn
    Direct userPrincipalName urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:mail

    For OpenLDAP with the POSIX schema, you'll also need to supply the gidNumber, homeDirectory, uid and uidNumber attributes. Each user requires a unique uid and a unique uidNumber. Typically the homeDirectory is set by an expression derived from the user's userID. For example, if the uid of a user is generated by an expression derived from their user principal name, then the value for that user's home directory could be generated by a similar expression also derived from their user principal name. And depending on your use case you may wish to have all the users be in the same group, so would assign the gidNumber from a constant.

    Mapping type Source attribute Target attribute
    Expression ToLower(Word([userPrincipalName], 1, "@"), ) urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:uid
    Direct (attribute specific to your directory) urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:uidNumber
    Expression Join("/", "/home", ToLower(Word([userPrincipalName], 1, "@"), )) urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:homeDirectory
    Constant 10000 urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:gidNumber
  10. If provisioning into a directory other than AD LDS, then add a mapping to urn:ietf:params:scim:schemas:extension:ECMA2Host:2.0:User:userPassword that sets an initial random password for the user. For AD LDS, there's no mapping for userPassword.

  11. Select Save.

Ensure users to be provisioned to the application have required attributes in Microsoft Entra ID

If there are people who have existing user accounts in the LDAP directory, then you'll need to ensure that the Microsoft Entra user representation has the attributes required for matching.

If you're planning on creating new users in the LDAP directory, then you'll need to ensure that the Microsoft Entra representations of those users have the source attributes required by the user schema of the target directory.

You can use the Microsoft Graph PowerShell cmdlets to automate checking users for the required attributes.

For example, suppose your provisioning required users to have three attributes DisplayName,surname and extension_656b1c479a814b1789844e76b2f459c3_MyNewProperty. You could use the Get-MgUser cmdlet to retrieve each user and check if the required attributes are present. Note that the Graph v1.0 Get-MgUser cmdlet doesn't by default return any of a user's directory extension attributes, unless the attributes are specified in the request as one of the properties to return.

$userPrincipalNames = (
 "alice@contoso.com",
 "bob@contoso.com",
 "carol@contoso.com" )

$requiredBaseAttributes = ("DisplayName","surname")
$requiredExtensionAttributes = ("extension_656b1c479a814b1789844e76b2f459c3_MyNewProperty")

$select = "id"
foreach ($a in $requiredExtensionAttributes) { $select += ","; $select += $a;}
foreach ($a in $requiredBaseAttributes) { $select += ","; $select += $a;}

foreach ($un in $userPrincipalNames) {
   $nu = Get-MgUser -UserId $un -Property $select -ErrorAction Stop
   foreach ($a in $requiredBaseAttributes) { if ($nu.$a -eq $null) { write-output "$un missing $a"} }
   foreach ($a in $requiredExtensionAttributes) { if ($nu.AdditionalProperties.ContainsKey($a) -eq $false) { write-output "$un missing $a" } }
}

Collect existing users from the LDAP directory

Many LDAP directories, such as Active Directory, include a command that outputs a list of users.

  1. Identify which of the users in that directory are in scope for being users of the application. This choice will depend on your application's configuration. For some applications, any user who exists in an LDAP directory is a valid user. Other applications might require the user to have a particular attribute or be a member of a group in that directory.

  2. Run the command that retrieves that subset of users from your LDAP directory. Ensure that the output includes the attributes of users that will be used for matching with Microsoft Entra ID. Examples of these attributes are employee ID, account name, and email address.

    For example, this command on Windows using the AD LDS csvde program would produce a CSV file in the current file system directory with the userPrincipalName attribute of every person in the directory:

    $out_filename = ".\users.csv"
    csvde -f $out_filename -l userPrincipalName,cn -r "(objectclass=person)"
    
  3. If needed, transfer the CSV file that contains the list of users to a system with the Microsoft Graph PowerShell cmdlets installed.

  4. Now that you have a list of all the users obtained from the application, you'll match those users from the application's data store with users in Microsoft Entra ID. Before you proceed, review the information about matching users in the source and target systems.

Retrieve the IDs of the users in Microsoft Entra ID

This section shows how to interact with Microsoft Entra ID by using Microsoft Graph PowerShell cmdlets.

The first time your organization uses these cmdlets for this scenario, you need to be in a Global Administrator role to allow Microsoft Graph PowerShell to be used in your tenant. Subsequent interactions can use a lower-privileged role, such as:

  • User Administrator, if you anticipate creating new users.
  • Application Administrator or Identity Governance Administrator, if you're just managing application role assignments.
  1. Open PowerShell.

  2. If you don't have the Microsoft Graph PowerShell modules already installed, install the Microsoft.Graph.Users module and others by using this command:

    Install-Module Microsoft.Graph
    

    If you already have the modules installed, ensure that you're using a recent version:

    Update-Module microsoft.graph.users,microsoft.graph.identity.governance,microsoft.graph.applications
    
  3. Connect to Microsoft Entra ID:

    $msg = Connect-MgGraph -ContextScope Process -Scopes "User.ReadWrite.All,Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All,EntitlementManagement.ReadWrite.All"
    
  4. If this is the first time you have used this command, you may need to consent to allow the Microsoft Graph Command Line tools to have these permissions.

  5. Read the list of users obtained from the application's data store into the PowerShell session. If the list of users was in a CSV file, you can use the PowerShell cmdlet Import-Csv and provide the name of the file from the previous section as an argument.

    For example, if the file obtained from SAP Cloud Identity Services is named Users-exported-from-sap.csv and is located in the current directory, enter this command.

    $filename = ".\Users-exported-from-sap.csv"
    $dbusers = Import-Csv -Path $filename -Encoding UTF8
    

    For another example if you are using a database or directory, if the file is named users.csv and located in the current directory, enter this command:

    $filename = ".\users.csv"
    $dbusers = Import-Csv -Path $filename -Encoding UTF8
    
  6. Choose the column of the users.csv file that will match with an attribute of a user in Microsoft Entra ID.

    If you are using SAP Cloud Identity Services, then the default mapping is the SAP SCIM attribute userName with the Microsoft Entra ID attribute userPrincipalName:

    $db_match_column_name = "userName"
    $azuread_match_attr_name = "userPrincipalName"
    

    For another example if you are using a database or directory, you might have users in a database where the value in the column named EMail is the same value as in the Microsoft Entra attribute userPrincipalName:

    $db_match_column_name = "EMail"
    $azuread_match_attr_name = "userPrincipalName"
    
  7. Retrieve the IDs of those users in Microsoft Entra ID.

    The following PowerShell script uses the $dbusers, $db_match_column_name, and $azuread_match_attr_name values specified earlier. It will query Microsoft Entra ID to locate a user that has an attribute with a matching value for each record in the source file. If there are many users in the file obtained from the source SAP Cloud Identity Services, database, or directory, this script might take several minutes to finish. If you don't have an attribute in Microsoft Entra ID that has the value, and need to use a contains or other filter expression, then you will need to customize this script and that in step 11 below to use a different filter expression.

    $dbu_not_queried_list = @()
    $dbu_not_matched_list = @()
    $dbu_match_ambiguous_list = @()
    $dbu_query_failed_list = @()
    $azuread_match_id_list = @()
    $azuread_not_enabled_list = @()
    $dbu_values = @()
    $dbu_duplicate_list = @()
    
    foreach ($dbu in $dbusers) { 
       if ($null -ne $dbu.$db_match_column_name -and $dbu.$db_match_column_name.Length -gt 0) { 
          $val = $dbu.$db_match_column_name
          $escval = $val -replace "'","''"
          if ($dbu_values -contains $escval) { $dbu_duplicate_list += $dbu; continue } else { $dbu_values += $escval }
          $filter = $azuread_match_attr_name + " eq '" + $escval + "'"
          try {
             $ul = @(Get-MgUser -Filter $filter -All -Property Id,accountEnabled -ErrorAction Stop)
             if ($ul.length -eq 0) { $dbu_not_matched_list += $dbu; } elseif ($ul.length -gt 1) {$dbu_match_ambiguous_list += $dbu } else {
                $id = $ul[0].id; 
                $azuread_match_id_list += $id;
                if ($ul[0].accountEnabled -eq $false) {$azuread_not_enabled_list += $id }
             } 
          } catch { $dbu_query_failed_list += $dbu } 
        } else { $dbu_not_queried_list += $dbu }
    }
    
    
  8. View the results of the previous queries. See if any of the users in SAP Cloud Identity Services, the database, or directory couldn't be located in Microsoft Entra ID, because of errors or missing matches.

    The following PowerShell script will display the counts of records that weren't located:

    $dbu_not_queried_count = $dbu_not_queried_list.Count
    if ($dbu_not_queried_count -ne 0) {
      Write-Error "Unable to query for $dbu_not_queried_count records as rows lacked values for $db_match_column_name."
    }
    $dbu_duplicate_count = $dbu_duplicate_list.Count
    if ($dbu_duplicate_count -ne 0) {
      Write-Error "Unable to locate Microsoft Entra ID users for $dbu_duplicate_count rows as multiple rows have the same value"
    }
    $dbu_not_matched_count = $dbu_not_matched_list.Count
    if ($dbu_not_matched_count -ne 0) {
      Write-Error "Unable to locate $dbu_not_matched_count records in Microsoft Entra ID by querying for $db_match_column_name values in $azuread_match_attr_name."
    }
    $dbu_match_ambiguous_count = $dbu_match_ambiguous_list.Count
    if ($dbu_match_ambiguous_count -ne 0) {
      Write-Error "Unable to locate $dbu_match_ambiguous_count records in Microsoft Entra ID as attribute match ambiguous."
    }
    $dbu_query_failed_count = $dbu_query_failed_list.Count
    if ($dbu_query_failed_count -ne 0) {
      Write-Error "Unable to locate $dbu_query_failed_count records in Microsoft Entra ID as queries returned errors."
    }
    $azuread_not_enabled_count = $azuread_not_enabled_list.Count
    if ($azuread_not_enabled_count -ne 0) {
     Write-Error "$azuread_not_enabled_count users in Microsoft Entra ID are blocked from sign-in."
    }
    if ($dbu_not_queried_count -ne 0 -or $dbu_duplicate_count -ne 0 -or $dbu_not_matched_count -ne 0 -or $dbu_match_ambiguous_count -ne 0 -or $dbu_query_failed_count -ne 0 -or $azuread_not_enabled_count) {
     Write-Output "You will need to resolve those issues before access of all existing users can be reviewed."
    }
    $azuread_match_count = $azuread_match_id_list.Count
    Write-Output "Users corresponding to $azuread_match_count records were located in Microsoft Entra ID." 
    
  9. When the script finishes, it will indicate an error if any records from the data source weren't located in Microsoft Entra ID. If not all the records for users from the application's data store could be located as users in Microsoft Entra ID, you'll need to investigate which records didn't match and why.

    For example, someone's email address and userPrincipalName might have been changed in Microsoft Entra ID without their corresponding mail property being updated in the application's data source. Or, the user might have already left the organization but is still in the application's data source. Or there might be a vendor or super-admin account in the application's data source that does not correspond to any specific person in Microsoft Entra ID.

  10. If there were users who couldn't be located in Microsoft Entra ID, or weren't active and able to sign in, but you want to have their access reviewed or their attributes updated in SAP Cloud Identity Services, the database, or directory, you'll need to update the application, the matching rule, or update or create Microsoft Entra users for them. For more information on which change to make, see manage mappings and user accounts in applications that did not match to users in Microsoft Entra ID.

    If you choose the option of creating users in Microsoft Entra ID, you can create users in bulk by using either:

    Ensure that these new users are populated with the attributes required for Microsoft Entra ID to later match them to the existing users in the application, and the attributes required by Microsoft Entra ID, including userPrincipalName, mailNickname and displayName. The userPrincipalName must be unique among all the users in the directory.

    For example, you might have users in a database where the value in the column named EMail is the value you want to use as the Microsoft Entra user principal Name, the value in the column Alias contains the Microsoft Entra ID mail nickname, and the value in the column Full name contains the user's display name:

    $db_display_name_column_name = "Full name"
    $db_user_principal_name_column_name = "Email"
    $db_mail_nickname_column_name = "Alias"
    

    Then you can use this script to create Microsoft Entra users for those in SAP Cloud Identity Services, the database, or directory that didn't match with users in Microsoft Entra ID. Note that you may need to modify this script to add additional Microsoft Entra attributes needed in your organization, or if the $azuread_match_attr_name is neither mailNickname nor userPrincipalName, in order to supply that Microsoft Entra attribute.

    $dbu_missing_columns_list = @()
    $dbu_creation_failed_list = @()
    foreach ($dbu in $dbu_not_matched_list) {
       if (($null -ne $dbu.$db_display_name_column_name -and $dbu.$db_display_name_column_name.Length -gt 0) -and
           ($null -ne $dbu.$db_user_principal_name_column_name -and $dbu.$db_user_principal_name_column_name.Length -gt 0) -and
           ($null -ne $dbu.$db_mail_nickname_column_name -and $dbu.$db_mail_nickname_column_name.Length -gt 0)) {
          $params = @{
             accountEnabled = $false
             displayName = $dbu.$db_display_name_column_name
             mailNickname = $dbu.$db_mail_nickname_column_name
             userPrincipalName = $dbu.$db_user_principal_name_column_name
             passwordProfile = @{
               Password = -join (((48..90) + (96..122)) * 16 | Get-Random -Count 16 | % {[char]$_})
             }
          }
          try {
            New-MgUser -BodyParameter $params
          } catch { $dbu_creation_failed_list += $dbu; throw }
       } else {
          $dbu_missing_columns_list += $dbu
       }
    }
    
  11. After you add any missing users to Microsoft Entra ID, run the script from step 7 again. Then run the script from step 8. Check that no errors are reported.

    $dbu_not_queried_list = @()
    $dbu_not_matched_list = @()
    $dbu_match_ambiguous_list = @()
    $dbu_query_failed_list = @()
    $azuread_match_id_list = @()
    $azuread_not_enabled_list = @()
    $dbu_values = @()
    $dbu_duplicate_list = @()
    
    foreach ($dbu in $dbusers) { 
       if ($null -ne $dbu.$db_match_column_name -and $dbu.$db_match_column_name.Length -gt 0) { 
          $val = $dbu.$db_match_column_name
          $escval = $val -replace "'","''"
          if ($dbu_values -contains $escval) { $dbu_duplicate_list += $dbu; continue } else { $dbu_values += $escval }
          $filter = $azuread_match_attr_name + " eq '" + $escval + "'"
          try {
             $ul = @(Get-MgUser -Filter $filter -All -Property Id,accountEnabled -ErrorAction Stop)
             if ($ul.length -eq 0) { $dbu_not_matched_list += $dbu; } elseif ($ul.length -gt 1) {$dbu_match_ambiguous_list += $dbu } else {
                $id = $ul[0].id; 
                $azuread_match_id_list += $id;
                if ($ul[0].accountEnabled -eq $false) {$azuread_not_enabled_list += $id }
             } 
          } catch { $dbu_query_failed_list += $dbu } 
        } else { $dbu_not_queried_list += $dbu }
    }
    
    $dbu_not_queried_count = $dbu_not_queried_list.Count
    if ($dbu_not_queried_count -ne 0) {
      Write-Error "Unable to query for $dbu_not_queried_count records as rows lacked values for $db_match_column_name."
    }
    $dbu_duplicate_count = $dbu_duplicate_list.Count
    if ($dbu_duplicate_count -ne 0) {
      Write-Error "Unable to locate Microsoft Entra ID users for $dbu_duplicate_count rows as multiple rows have the same value"
    }
    $dbu_not_matched_count = $dbu_not_matched_list.Count
    if ($dbu_not_matched_count -ne 0) {
      Write-Error "Unable to locate $dbu_not_matched_count records in Microsoft Entra ID by querying for $db_match_column_name values in $azuread_match_attr_name."
    }
    $dbu_match_ambiguous_count = $dbu_match_ambiguous_list.Count
    if ($dbu_match_ambiguous_count -ne 0) {
      Write-Error "Unable to locate $dbu_match_ambiguous_count records in Microsoft Entra ID as attribute match ambiguous."
    }
    $dbu_query_failed_count = $dbu_query_failed_list.Count
    if ($dbu_query_failed_count -ne 0) {
      Write-Error "Unable to locate $dbu_query_failed_count records in Microsoft Entra ID as queries returned errors."
    }
    $azuread_not_enabled_count = $azuread_not_enabled_list.Count
    if ($azuread_not_enabled_count -ne 0) {
     Write-Warning "$azuread_not_enabled_count users in Microsoft Entra ID are blocked from sign-in."
    }
    if ($dbu_not_queried_count -ne 0 -or $dbu_duplicate_count -ne 0 -or $dbu_not_matched_count -ne 0 -or $dbu_match_ambiguous_count -ne 0 -or $dbu_query_failed_count -ne 0 -or $azuread_not_enabled_count -ne 0) {
     Write-Output "You will need to resolve those issues before access of all existing users can be reviewed."
    }
    $azuread_match_count = $azuread_match_id_list.Count
    Write-Output "Users corresponding to $azuread_match_count records were located in Microsoft Entra ID." 
    

Assign users to an application

Now that you have the Microsoft Entra ECMA Connector Host talking with Microsoft Entra ID, and the attribute mapping configured, you can move on to configuring who's in scope for provisioning.

Important

If you were signed in using a Hybrid Identity Administrator role, you need to sign-out and sign-in with an account that has the at least the Application Administrator role for this section. The Hybrid Identity Administrator role doesn't have permissions to assign users to applications.

If there are existing users in the LDAP directory, then you should create application role assignments for those existing users in Microsoft Entra ID. To learn more about how to create application role assignments in bulk using New-MgServicePrincipalAppRoleAssignedTo, see governing an application's existing users in Microsoft Entra ID.

Otherwise, if the LDAP directory is empty, then select a test user from Microsoft Entra ID who has the required attributes and will be provisioned to the application's directory server.

  1. Ensure that the user will select has all the properties that will be mapped to the required attributes of the directory server schema.
  2. In the Azure portal, select Enterprise applications.
  3. Select the On-premises ECMA app application.
  4. On the left, under Manage, select Users and groups.
  5. Select Add user/group. Screenshot that shows adding a user.
  6. Under Users, select None Selected. Screenshot that shows None Selected.
  7. Select a user from the right and select the Select button.
    Screenshot that shows Select users.
  8. Now select Assign. Screenshot that shows Assign users.

Test provisioning

Now that your attributes are mapped and an initial user is assigned, you can test on-demand provisioning with one of your users.

  1. On the server the running the Microsoft Entra ECMA Connector Host, select Start.

  2. Enter run and enter services.msc in the box.

  3. In the Services list, ensure that both the Microsoft Entra Connect Provisioning Agent service and the Microsoft ECMA2Host services are running. If not, select Start.

  4. In the Azure portal, select Enterprise applications.

  5. Select the On-premises ECMA app application.

  6. On the left, select Provisioning.

  7. Select Provision on demand.

  8. Search for one of your test users, and select Provision. Screenshot that shows testing on-demand provisioning.

  9. After several seconds, then the message Successfully created user in target system will appear, with a list of the user attributes. If an error appears instead, see troubleshooting provisioning errors.

Start provisioning users

After the test of on-demand provisioning is successful, add the remaining users.

  1. In the Azure portal, select the application.
  2. On the left, under Manage, select Users and groups.
  3. Ensure that all users are assigned to the application role.
  4. Change back to the provisioning configuration page.
  5. Ensure that the scope is set to only assigned users and groups, turn provisioning status to On, and select Save.
  6. Wait several minutes for provisioning to start. It might take up to 40 minutes. After the provisioning job has been completed, as described in the next section,

Troubleshooting provisioning errors

If an error is shown, then select View provisioning logs. Look in the log for a row in which the Status is Failure, and click on that row.

If the error message is Failed to create User, then check the attributes that are shown against the requirements of the directory schema.

For more information, change to the Troubleshooting & Recommendations tab.

If the troubleshooting error message includes that an objectClass value is invalid per syntax, then ensure that the provisioning attribute mapping to the objectClass attribute includes only names of object classes recognized by the directory server.

For other errors, see troubleshooting on-premises application provisioning.

If you wish to pause provisioning to this application, on the provisioning configuration page, you can change the provisioning status to Off, and select Save. This action stops the provisioning service from running in the future.

Check that users were successfully provisioned

After waiting, check the directory server to ensure users are being provisioned. The query you perform to the directory server will depend on what commands your directory server provides.

The following instructions illustrate how to check AD LDS.

  1. Open Server Manager and select AD LDS on the left.
  2. Right-click your instance of AD LDS and select ldp.exe from the pop-up. Screenshot of the Ldp tool location.
  3. At the top of ldp.exe, select Connection and Connect.
  4. Enter the following information and click OK.
    • Server: APP3
    • Port: 636
    • Place a check in the SSL box Screenshot showing the Ldp connection for checking users.
  5. At the top, under Connection select Bind.
  6. Leave the defaults and click OK.
  7. At the top, select View and Tree
  8. For the BaseDN enter CN=App,DC=contoso,DC=lab and click OK.
  9. On the left, expand the DN and click on CN=CloudUsers,CN=App,DC=contoso,DC=lab. You should see your users who were provisioned from Microsoft Entra ID. Screenshot showing Ldp binding for users.

The following instructions illustrate how to check OpenLDAP.

  1. Open a terminal window with a command shell on the system with OpenLDAP.
  2. Type the command ldapsearch -D "cn=admin,dc=contoso,dc=lab" -W -s sub -b dc=contoso,dc=lab -LLL (objectclass=inetOrgPerson)
  3. Check that the resulting LDIF includes the users provisioned from Microsoft Entra ID.

Next steps