How to configure AD and common use cases - Identity as a Service

This topic describes how to connect your corporate Active Directory (AD) as an inbound identity provider. This allows you to synchronize AD organizations and accounts to IDaaS and use AD identities to log on to IDaaS or its connected applications.

Active Directory basics

Active Directory is a core directory service in the Microsoft Windows Server operating system that provides centralized identity authentication, authorization, and directory management for enterprise network environments. By using the network endpoint feature, you can synchronize AD data and perform delegated authentication without exposing public ports.

Connect to AD

Step 1: Connect to AD

Log on to the IDaaS console, select the target IDaaS instance, and click Console in the Actions column.
Click IdPs > Inbound > Add Inbound. Then, find AD in the list and click Add.
On the Bind AD panel, configure the following parameters.
- Display Name: The name shown to users when they log on to or use IDaaS.
- Network Access Endpoint: To allow only IDaaS to send requests to your AD, configure an IP address whitelist on your server. A shared endpoint uses shared, fixed public egress IP addresses. A dedicated endpoint uses dedicated, custom private and public egress IP addresses. With a dedicated endpoint, IDaaS can access your Alibaba Cloud VPC over a private network, which allows you to access your AD without opening public ports. For more information, see Network Endpoints.
- Server address: The address of your AD server. AD typically uses port 389 (e.g., 127.0.0.1:389), while port 636 is used when LDAPS or StartTLS is enabled.
- Enable StartTLS: Enabling this option significantly improves connection security and is highly recommended. To learn how to enable it, see AD security configuration.
- Administrator Account: The AD administrator account IDaaS uses to read information for data synchronization or delegated authentication. This account must have at least read permissions. Both User Principal Name (UPN) format (for example, example@example.com) and Distinguished Name (DN) format (for example, cn=admin,ou=TechDepartment,dc=example,dc=com) are supported.
- Administrator Password: The logon password for the administrator account.

Step 2: Select a scenario

Next, select the capabilities to enable for the AD connection.

Features

Synchronization Direction: IDaaS imports user and organization data from the selected AD source to this node. The Source Node must be the base DN of the AD node. The base DN of the AD root node is typically dc=example,dc=com, where example.com is your domain.
Incremental Synchronization: IDaaS monitors your AD for changes to user or organization data and runs a synchronization task approximately every 10 minutes to import the changes. Large data volumes in a single incremental synchronization can cause processing delays. We recommend performing a full synchronization periodically to ensure data consistency.
- In field mapping, you can set a mapping identifier to match a field from an IDaaS account with a field from an AD user, such as a mobile number. If the fields match, the accounts are bound and the IDaaS account is overwritten. Otherwise, a new IDaaS account is created.
- When you run an incremental synchronization for the first time, a full synchronization is automatically performed.
- The failure to import one account record does not affect the import of others.
- You can view failure information in the Synchronization logs.
- You must enable the AD Recycle Bin to receive events for deleted AD objects. To learn how to enable it, see incremental synchronization.
Delegated Authentication: Allows users to log on to IDaaS with their AD username and password.
Automatic Password Update: When a user authenticates to IDaaS through AD delegated authentication, if the IDaaS account has no password, IDaaS updates it with the AD user's password. The AD password must meet the IDaaS password policy; otherwise, it will not be updated automatically.

Advanced settings

User or organization objectClass: The objectClass attribute defines whether an object is a user or an organization. For example, an object in the query result with objectClass=user is treated as a user. You usually do not need to modify this setting.
User logon identity: When a user uses AD delegated authentication to log on to IDaaS, IDaaS uses these attributes to query for the user in AD and verify the password. If the password is correct, the user is allowed to log on. You can separate multiple attributes with a comma, which creates an OR relationship, meaning the user can log on with any of the specified attributes. Ensure that these attributes map to the same unique AD user; otherwise, logon will fail.
User filter: If you need to synchronize only a subset of users from different organizations, you can create a custom filter statement. Only users who meet the filter conditions are synchronized to IDaaS. By default, the filter statement includes an objectClass condition combined with an AND operator. You can click View details to see the complete statement. For more information and common usage examples, see Filter.
The complete filter statement is (&(objectclass=top)(objectclass=person)(objectclass=organizationalPerson)(objectclass=user)(cn=cn*)), where (cn=cn*) specifies a wildcard match on the cn attribute.

Step 3: Field mapping

If you need to link AD users and organizations with existing accounts and organizations in IDaaS, configure field mapping. You can also use this feature to populate IDaaS account data with values from AD user fields, such as using an AD user's mobile number as the IDaaS account name. To use the mapping identifier feature, you must manually enable it for the desired field, such as the mobile field.

The field mapping page is divided into Account and Organization sections. In the Account section, you can map AD user attributes (such as sAMAccountName, userPrincipalName, and cn) to IDaaS account fields. The mapping rules support Select Field, Expression, and No Mapping. To enable a mapping identifier, click the Mapping Identifier toggle in the corresponding field row to turn it on. In the Organization section, you can map organizational units to Organization Name. After the configuration is complete, click Save and Sync or Save Only.

For more information about field mapping, see field mapping.

AD security configuration

By default, LDAP data is transmitted in plaintext, which risks data interception. Using LDAPS or StartTLS can significantly improve data transmission security. After you configure a certificate in AD, you can use LDAPS or StartTLS in IDaaS. We strongly recommend that you enable one of these options.

In Server Manager, complete the certificate configuration by installing roles, promoting the server to a domain controller, and adding a certificate that uses the SHA256 signature algorithm.

After the certificate is configured, you can retrieve the certificate fingerprint in IDaaS with a single click. This establishes a trust relationship between IDaaS and the AD certificate, reducing the risk of certificate forgery.

In the Server Configuration section, select ldap:// as the protocol, set the port to 389, and select Enable StartTLS. For Certificate Verification, two options are available: Do Not Verify and Verify by Certificate Fingerprint. After you select Verify by Certificate Fingerprint, click Auto Obtain to automatically populate the certificate fingerprint.

Note

To quickly verify that the certificate fingerprint shown in the AD interface is the same as the one retrieved by IDaaS, run the following script:

openssl s_client -connect server_host:port | openssl x509 -noout -pubkey | openssl pkey -pubin -outform DER | openssl dgst -sha256

AD custom configuration

objectClass

In AD, an objectClass is a collection of attributes, and every object must have an objectClass. You can use objectClass to define an object as a user, organization, or computer. For example, you can find the user by using the filter statements objectclass=person or objectclass=user. You can view the objectClass in the Properties of an AD object.

In Active Directory Users and Computers, right-click the target user (for example, shufen), choose Properties, switch to the Attribute Editor tab, and find the objectClass attribute. Its value is top; person; organizationalPerson; user.

Logon identity

When a user uses AD delegated authentication to log on to IDaaS, IDaaS uses these attributes to look up the user in AD and verify their password. If the password is correct, the user is allowed to log on.

Common attributes used for logon include userPrincipalName, sAMAccountName, mobile number, email, and employee ID. You can define these attributes during creation or in the delegated authentication settings. If you use multiple attributes, ensure they are unique and map to the same AD user; otherwise, delegated authentication will fail.

Filter

Important

Modifying the objectClass and filter settings affects the AD filter conditions. When a full synchronization is performed, IDaaS deletes accounts and organizations that do not match the new filter conditions. Before making changes, we recommend that you adjust the synchronization protection threshold and thoroughly test the filter results to ensure they are as expected, for example, by using a separate IDaaS instance for testing.

Introduction

If you need to synchronize only a subset of users from different organizations into IDaaS, you can define a custom filter statement. IDaaS synchronizes only users who satisfy the conditions. By default, the filter statement includes an objectClass condition combined with an AND operator. You can click View details to see the complete statement.

The following sections describe common syntax and statements for AD filter.

Common syntax

Operator	Description	Example
=	Equals	(cn=Alice)
>=	Greater than or equal to	(pwdLastSet>=1319563845000000000)
<=	Less than or equal to	(sAMAccountName<=a)
&	AND, all conditions must be met	(&(cn=CN*)(memberOf=cn=Test,ou=HQ,dc=Domain,dc=com))
\|	OR, any one condition must be met	(\|(cn=Test)(cn=Admin))
!	NOT, conditions must not be met	(!(memberOf=cn=Test,ou=HQ,dc=Domain,dc=com))

Common statements

Scenario	Example
Username starts with "CN"	(cn=CN*)
User with a specific email address	(\|(proxyAddresses=*:alice@example.com)(mail=alice@example.com))
User in a specific group	(memberOf=cn=Test,ou=HQ,dc=Domain,dc=com)

AD sync configuration

Get base DN

The base DN is a path identifier for a specific node in AD. IDaaS performs queries and data synchronization only within that node. You can set the base DN for the source node in the Synchronization Direction settings.

The DN format is ou=SomeOrganization,dc=example,dc=com. The root node DN is typically dc=example,dc=com, where example.com is your domain. You can also view a node's DN directly in the AD management center.

In Active Directory Administrative Center, expand the (local) node on the left, select the target container (for example, Users). The Base DN of the node is displayed in the navigation path bar at the top, in a format such as CN=Users,DC=xxx,DC=xxx.

When a node's path changes, its base DN also changes. To prevent synchronization errors caused by path adjustments, IDaaS also records the node's objectGUID as a node fingerprint when you configure the source node's base DN. If the base DN changes and no longer matches the fingerprint, data synchronization is blocked. Synchronization resumes after you reconfigure the source node.

Incremental sync

When user or organization data in AD changes within the configured source node scope, IDaaS detects the changes and synchronizes the modified data to IDaaS.