This topic describes FileNet P8's support for integrating with Windows Active Directory.
NOTE IBM highly recommends that you configure SSL between your application server that hosts Content Engine and your Active Directory servers. This will include making changes in the application server to the authentication provider's DirectoryConfigurationAD object that was created while running Configuration Manager. Consult your application server's documentation for instructions.
Use this support matrix as a quick lookup of supported directory features.
Active Directory Features |
Supported By |
One-way SSL |
Y |
Two-way SSL |
N |
Universal Groups |
Y |
Security Groups |
Y |
Distribution Groups |
Y |
Nested Groups |
Y |
Builtin Groups |
N |
Users and groups belonging to custom Active Directory objects |
Y |
Supported User type (objectClass) |
user |
Supported Static Group types (objectClass) |
group |
Follow referrals for Search (for User/Group retrieval) |
N |
Roles |
N |
Directory aliases |
N |
Native Mode Active Directory |
Y |
Mixed Mode Active Directory |
Y – No support for NT4. |
Restrict to single realm |
Y - By configuring just one realm. |
Support multiple realms and domains |
Y |
Support multiple forests |
Y |
Support users and groups migrate from domain to domain within a forest |
N |
Support domains across multiple forests |
Y |
Configurable user short name attribute |
Y - Because the short name does not contain realm information, short names must be unique across all your configured domains and realms. |
Configurable group short name attribute |
Y |
Configurable user display name attribute |
Y |
Configurable group display name attribute | Y |
Configurable principal Name - Boolean flag |
Y |
DNS Site |
Y – Resolve domain controllers in a given DNS site. |
Multiple authenticating attributes support |
Y – Can authenticate against the same Active Directory server using multiple attributes, such as samAccountName, userPrincipalName, or distinguishedName. See Configure multiple authenticating attributes. |
Sorting |
Y – Return users and groups in sorted order: either ascending or descending order. |
Paging/Continuation |
Y – Return users and groups page by page. Page continuation happens automatically in the back end. |
Server side sorting | Y (Required) - Server Side Sorting (SSS) must be enabled. This is because Process Engine and other P8 components call on Content Engine to perform searches using a sorted paging mechanism. Without SSS, you will experience errors such as in Workplace when retrieving a document, when trying to open Process Designer via Workplace, or when starting a Connection Point on Application Engine. Note that SSS is normally enabled by default but is sometimes disabled due to concerns with performance. |
Windows NT domains (versions 4.0 and earlier). | N |
Group search returns Domain Local Groups | Y |
The following is an alphabetic list of the properties in the DirectoryConfigurationAD class. Use Enterprise Manager to view all properties and modify editable properties.
Property Name | Editable? | Description |
---|---|---|
ClassDescription | N | A ClassDescription object containing the fixed description of the class from which a given object is instantiated. |
ConnectionTimeout |
Y | Specifies the Active Directory Service provider connection timeout in milliseconds. The default is 500 milliseconds. If the connection is across a WAN, consider increasing the value. |
DirectoryServerHost |
Y | Specifies the name of the host that is running the directory server product. |
DirectoryServerPassword |
Y | Specifies the user password used to authenticate to a given directory server. |
DirectoryServerPort |
Y | Specifies the port number of the directory server. The value of this property defaults to port 389 for all supported directory server types. |
DirectoryServerProviderClass |
Y | Specifies the directory server provider class name: com.filenet.engine.security.ActiveDirectoryProvider |
DirectoryServerType | N | Specifies the type of directory server: AD |
DirectoryServerUserName | Y | Specifies the user name for authenticating to the directory server. Example: "CN=test1,CN=Users,DC=myCompany,DC=com" |
DisplayName |
Y | The user-readable, provider-specific name of an object. This property is usually the designated Name property of the object's class. |
GroupBaseDN |
Y | The base DN for searching for groups in the directory server. |
GroupDisplayNameAttribute |
Y | Specifies the display name for a |
GroupMembershipSearchFilter |
Y | The search filter for group membership queries. |
GroupNameAttribute |
Y | Defines the directory server attribute to be used as the short name for a group. |
GroupSearchFilter |
Y | Specifies search filter for groups. Example: "(&(objectclass=group)(samAccountName={0}))", where samAccountName will serve as the short name. |
Id |
N | An object's globally unique ID (GUID). |
IsSSLEnabled |
Y | Defines whether or not Secure Sockets Layer (SSL) protocol is enabled for a given DirectoryConfiguration object. The default value is false, indicating that SSL is disabled. |
RestrictMembershipToConfiguredRealms | Y | Restricts group lookups to configured realms only. A user can be in a configured realm but belong to a group in an unconfigured realm. If set to Yes, that user cannot log in because the system cannot look up all the user's group memberships. If set to No, group memberships in unconfigured realms are ignored. |
ReturnNameAsDN |
Y | Specifies whether to return the user or group name in Distinguished Name (DN) format for Active Directory Service provider. By default, the Active Directory Service provider returns the user and group names in UPN format. If set to true, the service provider returns the names in DN format, which is consistent with other types of directory service providers. |
SearchCrossForestGroupMembership |
Y | Specifies whether the Active Directory Service provider performs cross-forest group membership searches. The default is false. To enable cross-forest group membership searches, set this property to true. |
UserBaseDN |
Y | The base DN for searching for users in the directory server. |
UserDisplayNameAttribute |
Y | Specifies the display name for a User object generated by the authentication provider. The default property value is dependent on the authentication provider and is specified by the provider's configuration. |
UserNameAttribute |
Y | Defines the directory server attribute to be used as the short name for a user. |
UserSearchFilter |
Y | Specifies search filter for users. Example: "(&(objectclass=user)(samAccountName={0}))", where samAccountName will serve as the short name. |
Active Directory consists of forests, each forest consisting of trees, and each tree consisting of domains. Each domain has one data naming context, called the default naming context. Each Active Directory domain equate to one Content Engine realm, and the value of the default naming context attribute is the name of the Content Engine realm. For example:
DefaultNamingContext: DC=paperwork2,DC=eng,DC=filenet,DC=com
Content Engine realm name: DC=paperwork2,DC=eng,DC=filenet,DC=com
For an Active Directory forest, all its domain controllers register to one DNS server. This DNS server normally runs on a domain controller of the root domain. Make sure the machine on which your application server is running points to this DNS server.
Active Directory service provider can be configured in three different levels: single-realm, multi-realm, and multi-forest. Each is explained in the following sections.
This section demonstrates LDAP configuration for a domain named "paperwork2" and uses WebLogic 8.1 for application server examples. Any field that is not listed in the following table takes its default value.
Provider Name | Tab | Field Name | Field Value |
domain_samAccountName | General | Control Flag | Sufficient |
Active Directory | Host | Host_name | |
Port | 389 | ||
Principal | CN=test1,CN=Users,DC=paperwork2,DC=eng,DC=filenet,DC=com | ||
Credential | <password> | ||
Users | User Name Attribute | sAMAccountName | |
User Base DN | CN=Users,DC=paperwork2,DC=eng,DC=filenet,DC=com | ||
User From Name Filter | (&(objectclass=user)( sAMAccountName =%u)) | ||
Groups | Group Base DN | CN=Users,DC=paperwork2,DC=eng,DC=filenet,DC=com | |
Group From Name Filter | (&(sAMAccountName=%g)(objectclass=group)) | ||
Static Group Name Attribute | sAMAccountName | ||
domain_userPrincipalName | General | Control Flag | Sufficient |
Active Directory | Host | ||
Port | 389 | ||
Principal | |||
Credential | <password> | ||
Users | User Base Attribute | userPrincipalName | |
User Base DN | CN=Users,DC=paperwork2,DC=eng,DC=filenet,DC=com | ||
User From Name Filter | (&(objectclass=user)( userPrincipalName =%u)) | ||
Groups | Group Base DN | CN=Users,DC=paperwork2,DC=eng,DC=filenet,DC=com | |
Group From Name Filter | (&(sAMAccountName=%g)(objectclass=group)) | ||
Static Group Name Attribute | sAMAccountName |
com.filenet.api.admin.DirectoryConfigurationAD
Authentication |
FileNet P8 can authenticate any user in this domain under CN=Users,DC=domain,DC=eng,DC=filenet,DC=com. FileNet P8 can authenticate the users by either samAccountName or userPrincipalName. |
Realm set | One realm: DC=paperwork2,DC=eng,DC=filenet,DC=com |
User/Group retrieval | FileNet P8 can retrieve any user or group in this realm under CN=Users,DC=paperwork2,DC=eng,DC=filenet,DC=com |
Group Membership | FileNet P8 can search any group membership in this local domain. But if the membership involves other domains, an error is returned. |
This section describes how to configure some or all domains in a single forest.
In an Active Directory forest, if a cross-domain group membership involves any Domain Local Group, the group membership is one-way, and it is not replicated to the Active Directory Global Catalog. The forward group membership search presents no problems: given a group in one domain, FileNet P8 can easily find all its members in other domains.
However, the backward group membership search can be very resource intensive. FileNet P8 would have to iterate through all other domains to find all the parent groups of which this group is a member. Since large enterprises might have 30 or more domains in a single forest, this iterative approach for cross-domain backward group membership search can be unacceptably slow.
In order to address this problem, you can split the cross-domain group membership and add a new group in between. For example, a Domain Local Group in Domain A might contain a Global Group in Domain B. The following figure shows a Universal Group in Domain A that has been configured as a member of the Domain Local Group. Then the Global Group in Domain B has been configured to be a member of the newly created Universal Group.
To summarize:
This section assumes Content Engine accesses every domain in a forest. This is a quick and easy configuration.
Create one Active Directory authentication provider in WebLogic, and then make the following changes:
Example: assume you have a forest consisting of the following three domains:
"mycompany.com" is the root domain of this forest. "mycompany-dc1" is the host name of a domain controller for the root domain, and has global catalog server running on it. Here is the provider for this entire forest:
Provider Name | Tab | Field Name | Field Value |
MyCompany_samAccountName | General | Control Flag | Sufficient |
Active Directory | Host | Host_name | |
Port | 3289 | ||
Principal | CN=Administrator,CN=Users,DC=mycompany,DC=com | ||
Credential | <password> | ||
Users | User Name Attribute | sAMAccountName | |
User Base DN | <Set to blank> | ||
User From Name Filter | (&(objectclass=user)(sAMAccountName=%u)) | ||
Groups | Group Base DN | <Set to blank> | |
Group From Name Filter | (&(sAMAccountName=%g)(objectclass=group)) | ||
Static Group Name Attribute | sAMAccountName |
Here is the GCD configuration for the example in the above section.
com.filenet.api.admin.DirectoryConfigurationAD
When the Active Directory service provider sees that this DirectoryConfiguration object is pointing to a global catalog server of a forest (by checking the port), it will pick up this one and ignore all other DirectoryConfiguration objects configured for the same forest. It will search in the GC for all domains in this forest, and treat each domain as a Content Engine realm. The domain distinguished name will be used as the realm name, the user base DN, and group base DN for this realm.
When searching for domains, Active Directory provider does not check any trust relationship. By definition, if a domain joins any forest, it has to establish two-way transitive trust relationships with other domains in the forest.
Authentication | FileNet P8 can authenticate any user by samAccountName in any domain within this single forest. |
Realm set | Three realms (that is, all the domains in this forest):
|
User/Group retrieval | FileNet P8 can retrieve any user or group in any domain within this forest. |
Group Membership | FileNet P8 can search the following two types of group membership.
|
In some cases, you might not want every domain in the forest to be accessed by Content Engine. For example, a company might have 30 domains in its forest, but only 3 of them should be accessed by Content Engine. In this case, you can create 3 authentication providers in the WebLogic server. Each provider points to one of the domains accessed by Content Engine. At the same time, you create three DirectoryConfiguration objects to point to the same set of domains.
The steps are the same as mentioned in single realm, except you create multiple providers here. Make sure none of them points to a Global Catalog server.
Example: using the example in the previous section, among all the domains in the forest, you want only the following two to be accessed by Content Engine system:
So you create two WebLogic authentication providers as shown below. Assume "ca-dc1" is the host name of a domain controller for domain "ca.mycompany.com".
Provider Name | Tab | Field Name | Field Value |
MyCompany_samAccountName | General | Control Flag | Sufficient |
Active Directory | Host | mycompany-dc1 | |
Port | 389 | ||
Principal | CN=Administrator,CN=Users,DC=mycompany,DC=com | ||
Credential | <password> | ||
Users | User Name Attribute | sAMAccountName | |
User Base DN | DC=mycompany,DC=com | ||
User From Name Filter | (&(objectclass=user)(sAMAccountName=%u)) | ||
Groups | Group Base DN | DC=mycompany,DC=com | |
Group From Name Filter | (&(sAMAccountName=%g)(objectclass=group)) | ||
Static Group Name Attribute | sAMAccountName | ||
CA_samAccountName | General | Control Flag | Sufficient |
Active Directory | Host | ca-dc1 | |
Port | 389 | ||
Principal | CN=Administrator,CN=Users,DC=ca,DC=mycompany,DC=com | ||
Credential | <password> | ||
Users | User Name Attribute | sAMAccountName | |
User Base DN | DC=ca,DC=mycompany,DC=com | ||
User From Name Filter | (&(objectclass=user)(sAMAccountName=%u)) | ||
Groups | Group Base DN | DC=ca,DC=mycompany,DC=com | |
Group From Name Filter | (&(sAMAccountName=%g)(objectclass=group)) | ||
Static Group Name Attribute | sAMAccountName |
The steps are the same as mentioned in GCD configuration for single realm, except you create multiple DirectoryConfiguration objects. Make sure none points to a Global Catalog server.
Here is the GCD configuration for the example in the above section:
DirectoryConfigurationAD object 1:
DirectoryConfigurationAD object 2:
Authentication |
FileNet P8 can authenticate any user in any of these two domains. |
Realm set |
Two realms:
|
User/group retrieval |
FileNet P8 can retrieve any user or group in these two domains. |
Group membership |
FileNet P8 can search the following two types of group membership.
If the membership involves other domains in this forest, make sure you have other domains configured as well. Otherwise, an error is returned. If the membership involves other forests and flag SearchCrossForestGroupMembership is enabled, make sure you have other forests configured as well. Otherwise, an error is returned. |
Let's say you have two forests. You can follow steps specified in Entire Forest to create two entire forest configurations. Or you can follow the steps in Partial Forest to create the partial forest configuration for each forest. Or you can create a mixture of these two configurations.
Example: assume you have the following two forests. Note that forest name is the root domain name.
Forest |
Domain |
Domain Controller |
mycompany.com |
This forest consists of the following domains.
|
"mycompany-dc1" is the host name of a domain controller for the root domain, and has global catalog server running on it. |
mynewcompany.com |
This forest consists of the following domains.
|
"mynewcompany-dc1" is the host name of a domain controller for the root domain, and has global catalog server running on it. |
Below are the authentication providers for these two forests. Each provider covers all domains in the corresponding forest.
Provider Name | Tab | Field Name | Field Value |
MyCompany_samAccountName | General | Control Flag | Sufficient |
Active Directory | Host | mycompany-dc1 | |
Port | 3268 | ||
Principal | CN=Administrator,CN=Users,DC=mycompany,DC=com | ||
Credential | <password> | ||
Users | User Name Attribute | sAMAccountName | |
User Base DN | <Set to blank> | ||
User From Name Filter | (&(objectclass=user)(sAMAccountName=%u)) | ||
Groups | Group Base DN | <Set to blank> | |
Group From Name Filter | (&(sAMAccountName=%g)(objectclass=group)) | ||
Static Group Name Attribute | sAMAccountName | ||
MyNewCompany_samAccountName | General | Control Flag | Sufficient |
Active Directory | Host | mynewcompany-dc1 | |
Port | 3268 | ||
Principal | CN=Administrator,CN=Users,DC=mynewcompany,DC=com | ||
Credential | <password> | ||
Users | User Base Attribute | sAMAccountName | |
User Base DN | <Set to blank> | ||
User From Name Filter | (&(objectclass=user)(sAMAccountName=%u)) | ||
Groups | Group Base DN | <Set to blank> | |
Group From Name Filter | (&(sAMAccountName=%g)(objectclass=group)) | ||
Static Group Name Attribute | sAMAccountName |
Here are the two DirectoryConfiguration objects for the above two forests:
DirectoryConfigurationAD object 1:
DirectoryConfigurationAD object 2:
Authentication |
FileNet P8 can authenticate any user by samAccountName in any of these two forests. |
Realm set |
Five realms (that is, all the domains in these two forests):
|
User/group retrieval |
FileNet P8 can retrieve any user or group in any of these two forests |
Group membership |
FileNet P8 can search the following three types of group membership.
|
Iterate through all forests. For each forest:
If more than one user or group is found, Content Engine logs an error and returns the first user found.
Note: Microsoft defines the user principal name (UPN) format to consist of the user name, the "at" sign (@), and a user principal name suffix. In Content Engine, the user name part is always the short name, and the suffix part is always the DNS domain name of the domain the user belongs to.