Microsoft Active Directory

Follow this procedure to set up Microsoft Active Directory as a source system.

Prerequisites

Note:

If you have purchased the Identity Provisioning service between September 1, 2020 and October 20, 2020, and you want to make a connection to this on-premise system, follow the procedure in: Connect to On-Premise Systems in SAP Cloud Identity Infrastructure.

You have installed the Cloud Connector in your corporate environment and have done the initial configuration. For more information, see: Cloud Connector (Neo)
You have the credentials of a technical user in the Microsoft Active Directory, which is used to call the Microsoft Active Directory API to read the users and their attributes.

Context

You can configure Microsoft Active Directory (Microsoft AD) as a source system to read users, groups and permission assignments.

There are two versions of the Microsoft AD connector. Both consume the LDAP Server API to read and write users and groups. The versions are handled by the ldap.api.version property as follows:

When the value is set to 1 or the property is not defined (typical for systems created before versioning was introduced on June 19, 2023) LDAP Server API version 1 is used. This is the default value of ldap.api.version.

When using this version of the connector, the entities (users and groups) are read with all attributes.

In this version, the group members attribute mapping in the proxy read transformation does not include type sub-attribute. In this case, all members are considered of type User, which is the sub-attribute fallback value. As a consequence, if the external system includes nested groups, they will not be handled properly.
When the value is set to 2 – LDAP Server API version 2 is used.

Тhis version of the connector is with improved performance of the read operation for user and group attributes. You are now able to define which user and group attributes to be read. This is possible by adding values to the properties ldap.user.attributes or ldap.group.attributes.

Via these properties, you are able to add also user and group operational attributes (attributes which the directory organizes for internal use). For more information, refer to the official LDAP server documentation. After the additional values of the properties are set, the default read or proxy read transformations should also be adjusted accordingly.

In this version, the group members attribute mapping in the proxy read transformation is enhanced with type sub-attribute. The sub-attribute has two possible values – User and Group. This allows you to read and preserve nested groups.

For more information on how to update to Microsoft Active Directory version 2, see Update Connector Version.

Procedure

Add an access control system mapping for the Microsoft Active Directory in the Cloud Connector. This is needed to allow the Identity Provisioning service to access Microsoft AD as a back-end system on the intranet. For more information, see Configure Access Control (LDAP).
Access the Identity Provisioning UI.
- Access Identity Provisioning UI of Bundle Tenants ↗️
- Access Identity Provisioning UI of Standalone Tenants ↗️
Sign in to the administration console of SAP Cloud Identity Services and navigate to Identity Provisioning > Source Systems.
Add Microsoft Active Directory as a source system. For more information, see Add New Systems.

Choose the Properties tab to configure the connection settings for your system.

Note:

If your tenant is running on SAP BTP, Neo environment, you can create a connectivity destination in your subaccount in the SAP BTP cockpit, and then select it from the Destination Name combo box in your Identity Provisioning User Interface.

If one and the same property exists both in the cockpit and in the Properties tab, the value set in the Properties tab is considered with higher priority.

We recommend that you use the Properties tab. Use a connectivity destination only if you need to reuse one and the same configuration for multiple provisioning systems.

Mandatory Properties

Property Name	Description & Value
`Type`	Enter: LDAP
`ldap.url`	Specify a destination URL. It must be in the following format: `ldap://<ext_host>:<ext_port>`
`ldap.proxyType`	Enter: OnPremise
`ldap.authentication`	Enter: BasicAuthentication
`ldap.attribute.user.id`	Default property, which denotes the ID of a user. By default, it's set to: cn
`ldap.attribute.group.id`	Default property, which denotes the ID of a group. By default, it's set to: cn
`ldap.attribute.dn`	Default property, which denotes the distinguished name of a user or a group. Only possible value: distinguishedName
`ldap.user`	Enter the distinguishedName or the userPrincipalName of the Microsoft AD technical user. This is the user you need to establish the connection and to perform all queries.
`ldap.password`	(Credential) Enter the password for the Microsoft AD technical user.
`ldap.group.path`	Enter the complete path to the node containing the groups in Microsoft AD.
`ldap.user.path`	Enter the complete path to the users in Microsoft AD.
`ldap.api.version`	Defines the version of LDAP Server API. Possible values: `1` - Indicates that LDAP Server API version 1 is used. `2` - Indicates that LDAP Server API version 2 is used. If the property is not defined - LDAP Server API version 1 is used.
`ldap.user.attributes`	Shows which user attributes from the source system to be included in the Microsoft AD read result (and respectively, in the intermediate JSON data). Separate the attributes by comma (,). Possible values: Microsoft AD version 1 - Even though you specified the attributes to be included in the Microsoft AD read result, Identity Provisioning will return all attributes from the Microsoft AD. Microsoft AD version 2 - Only the specified attributes will be included in the Microsoft AD read result. sAMAccountName is always included as mandatory user attribute for Microsoft AD version 2.
`ldap.group.attributes`	Shows which group attributes from the source system to be included in the Microsoft AD read result (and respectively, in the intermediate JSON data). Separate the attributes by comma (,). Possible values: Microsoft AD version 1 - Even though you specified the attributes to be included in the Microsoft AD read result, Identity Provisioning will return all attributes from the Microsoft AD. Microsoft AD version 2 - Only the specified attributes will be included in the or Microsoft AD. If nothing is set, all attributes are included.
(Optional) `ad.group.flatten`	There are target systems that do not support nested groups (group structures). Therefore, if your Microsoft AD system contains such groups, they will not be resolved properly during the provisioning job. Such target systems are: SAP Jam Collaboration Identity Authentication To enable reading of group structures, you can use the `ad.group.flatten` property and set it to true. It will read the group structure recursively and will "flatten" it so that all users from all groups and subgroups will be resolved and written in the target system as members of the main parent group. Note: Performance might be affected when `ad.group.flatten` is set to true and group structure is very complex (contains a lot of nested groups). For best results, we recommend you also set the system property `ldap.group.filter` whose value is one or multiple Microsoft AD parent groups. For example, if a parent group is named Canteen, the property should be set as: `ldap.group.filter`= (cn=Canteen) See the example below with multiple parent groups.

Example for a destination or a set of properties:

Type=LDAP

Name=MyADDestination

ldap.user=john.smith@some.dummy.domain.com

ldap.password=********

ldap.attribute.user.id=cn

ldap.attribute.group.id=cn

ldap.attribute.dn=distinguishedName

ldap.url=ldap://abcd:123

ldap.proxyType=OnPremise

ldap.authentication=BasicAuthentication

ldap.group.path=OU=Groups,OU=IAS,DC=global,DC=corp,DC=mycompany

ldap.user.path=OU=Users,OU=IAS,DC=global,DC=corp,DC=mycompany

ldap.group.filter=(|(cn=Canteen)(cn=Finance)(cn=Support_Team))

ad.group.flatten=true

To learn what additional properties are relevant to this system, see List of Properties. You can use the main search, or filter properties by the Name or System Type columns.

(Optional) Configure the transformations.

Transformations are used to map the user attributes from the data model of the source system to the data model of the target system, and the other way around. The Identity Provisioning offers a default transformation for the Microsoft Active Directory source system, whose settings are displayed under the Transformations tab after saving its initial configuration.

Before the read transformation, the Microsoft Active Directory attributes are represented as arrays – single-element arrays, or multi-value arrays separated by comma (,). After the read transformation (in the intermediate JSON data), the attributes are in SCIM format. For more information about Microsoft AD schema attributes, see the Related Information section.

Currently, the default read transformations of the two connector versions have no differences, so there is no need to update them.

You can change the default transformation mapping rules to reflect your current setup of entities in Microsoft Active Directory. For more information, see:

Manage Transformations

Default transformation:

Code Syntax:


{
  "user": {
    "mappings": [
      {
        "sourcePath": "$.%ldap.attribute.user.id%[0]",
        "targetVariable": "entityIdSourceSystem",
        "correlationAttribute": true
      },
      {
        "condition": "('%ldap.attribute.user.id%' == '%ldap.attribute.dn%')",
        "constant": "",
        "functions": [
          {
            "function": "concatString",
            "prefix": "(?i)cn=.*?,(.*?)",
            "suffix": ",%ldap.user.path%"
          }
        ],
        "targetVariable": "nestedPathRegex"
      },

// If a user is not a direct member of the configured user base path, then function getMatchedRegexGroup extracts the nested path from the distinguishedName of this user, 
// and maps the nested path to attribute ['urn:sap:cloud:scim:schemas:extension:ad:2.0:User']['nestedPath']
      {
        "condition": "('%ldap.attribute.user.id%' == '%ldap.attribute.dn%')",
        "sourcePath": "$.%ldap.attribute.user.id%[0]",
        "functions": [
          {
            "function": "getMatchedRegexGroup",
            "regex": "${nestedPathRegex}",
            "groupIndex": 1
          }
        ],
        "targetPath": "$['urn:sap:cloud:scim:schemas:extension:ad:2.0:User']['nestedPath']",
        "defaultValue": ""
      },
      {
        "sourcePath": "$.sAMAccountName[0]",
        "targetPath": "$.userName",
        "correlationAttribute": true
      },
      {
        "sourcePath": "$.displayName[0]",
        "targetPath": "$.displayName",
        "optional": true
      },
      {
        "constant": "urn:ietf:params:scim:schemas:core:2.0:User",
        "targetPath": "$.schemas[0]"
      },
      {
        "sourcePath": "$.mail[0]",
        "targetPath": "$.emails[0].value",
        "optional": true,
        "correlationAttribute": true
      },
      {
        "sourcePath": "$.givenName[0]",
        "targetPath": "$.name.givenName",
        "optional": true
      },
      {
        "sourcePath": "$.sn[0]",
        "targetPath": "$.name.familyName",
        "optional": true
      },
      {
        "sourcePath": "$.memberOf",
        "preserveArrayWithSingleElement": true,
        "optional": true,
        "targetPath": "$.groups[?(@.value)]"
      },
      {
        "sourcePath": "$.mobile[0]",
        "optional": true,
        "targetPath": "$.phoneNumbers[0].value"
      },
      {
        "condition": "$.mobile.length() > 0",
        "constant": "mobile",
        "targetPath": "$.phoneNumbers[0].type"
      },
      {
        "sourcePath": "$.telephoneNumber[0]",
        "optional": true,
        "targetPath": "$.phoneNumbers[1].value"
      },
      {
        "condition": "$.telephoneNumber.length() > 0",
        "constant": "work",
        "targetPath": "$.phoneNumbers[1].type"
      }
    ]
  },
  "group": {
    "ignore": true,
    "mappings": [
      {
        "sourcePath": "$.%ldap.attribute.group.id%[0]",
        "targetVariable": "entityIdSourceSystem"
      },
      {
        "condition": "('%ldap.attribute.group.id%' == '%ldap.attribute.dn%')",
        "constant": "",
        "functions": [
          {
            "function": "concatString",
            "prefix": "(?i)cn=.*?,(.*?)",
            "suffix": ",%ldap.group.path%"
          }
        ],
        "targetVariable": "nestedPathRegex"
      },

// If a group is not a direct member of the configured group base path, then function getMatchedRegexGroup extracts the nested path from the distinguishedName of this group, 
// and maps the nested path to attribute ['urn:sap:cloud:scim:schemas:extension:ad:2.0:Group']['nestedPath']
      {
        "condition": "('%ldap.attribute.group.id%' == '%ldap.attribute.dn%')",
        "sourcePath": "$.%ldap.attribute.group.id%[0]",
        "functions": [
          {
            "function": "getMatchedRegexGroup",
            "regex": "${nestedPathRegex}",
            "groupIndex": 1
          }
        ],
        "targetPath": "$['urn:sap:cloud:scim:schemas:extension:ad:2.0:Group']['nestedPath']",
        "defaultValue": ""
      },
      {
        "sourcePath": "$.sAMAccountName[0]",
        "targetPath": "$.displayName"
      },
      {
        "constant": "urn:ietf:params:scim:schemas:core:2.0:Group",
        "targetPath": "$.schemas[0]"
      },
      {
        "sourcePath": "$.member",
        "preserveArrayWithSingleElement": true,
        "targetPath": "$.members[?(@.value)]",
        "optional": true
      }
    ]
  }
}

As result of this mapping, that is how the data from Microsoft Active Directory looks like before and after the read transformation:

Source JSON Data

(as read from Microsoft Active Directory)

Intermediate JSON Data

(as a result from the transformation)

Sample Code:

...
"memberOf": [
"SALES_US",
"SALES_EU"
]
…

Sample Code:

...
"groups":[
  {
    "value": "SALES_US"
  },
  {
    "value": "SALES_EU"
  },
]
…

Now, add a target system to provision users and groups into it. Choose from: Target Systems

Next Steps

Before starting a provisioning job, you can first subscribe for e-mail notifications from the source system you use in your scenario. This way, you will be notified by e-mail about eventual failed entities during the jobs. For more information, see Manage Job Notifications.
Now, start an identity provisioning job. For more information, see Monitor Provisioning Job Logs.

Related Information

Technical Documents

Setting Timeout for Ldap Operations

Connection Pooling Configuration

Active Directory Domain Services Overview

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

microsoft-active-directory-ab474a8.md

microsoft-active-directory-ab474a8.md

Microsoft Active Directory

Prerequisites

Note:

Context

Procedure

Note:

Note:

Code Syntax:

Sample Code:

Sample Code:

Next Steps

Files

microsoft-active-directory-ab474a8.md

Latest commit

History

microsoft-active-directory-ab474a8.md

File metadata and controls

Microsoft Active Directory

Prerequisites

Note:

Context

Procedure

Note:

Note:

Code Syntax:

Sample Code:

Sample Code:

Next Steps