Windows Active Directory

This topic describes FileNet P8's support for integrating with Windows Active Directory.

NOTE  FileNet 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.

Support matrix

Use this support matrix as a quick lookup of supported directory features.

Active Directory Features

Supported By
Content Engine

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/domains

Y

Support multiple forests

Y

Support users/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
If true: shortname@authentication.domain
If false: full DN

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/groups in sorted order: either ascending or descending order.

Paging/Continuation

Y – Return users/groups page by page. Page continuation happens automatically in the back end.

Windows NT domains (versions 4.0 and earlier). N
Group search returns Domain Local Groups Y

Top of page

Directory Configuration Properties

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 username 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 Group object generated by the authentication provider. The default property value is dependent on the authentication provider and is specified by the provider's configuration.

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 on 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.

Top of page

Realm Configuration (WebLogic)

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.

Single-Realm Configuration

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.

Authentication Provider Configuration for single-realm, using WebLogic

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

Top of page

GCD Configuration for single-realm

com.filenet.api.admin.DirectoryConfigurationAD

Top of page

Configuration Result for single-realm

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.

Top of page

Multi-Realm Configuration

This section configures all or some domains in a single forest.

In a single 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 Global Catalog. The forward group membership search (given a group, find all its member groups and member users) is easy. Given a group in one domain, you can easily find all its members in other domains. However, the backward group membership search (given a group or user, find all parent groups that it belongs to) is expensive. You must iterate through all other domains to find all the parent groups to which this group belongs. Since large enterprises may have 30 or more domains in one forest, this iterative approach for cross-domain backward group membership search is too expensive and so is not acceptable.

As a result, you should split this cross-domain membership and add an extra group in between. Let's say a domain local group in Domain A contains a global group in Domain B. You can create a universal group in Domain A, make the domain local group containing the universal group its member, and then make the universal group in Domain A to contain the global group in Domain B. This is because:

Top of page

Entire Forest Configuration

This section assumes Content Engine accesses every domain in a forest. This is a quick and easy configuration.

Authentication Provider Configuration for entire forest, using WebLogic

Create one Active Directory authentication provider in WebLogic, and then make the following changes:

  1. In "Active Directory" tab, for the "Host" field, pick a domain controller which has the Global Catalog (GC) server running on it.
  2. Change the "Port" to 3268 which is the port number of Global Catalog server on that host.
  3. For the "Principal" field, make sure you pick a user who can be authenticated in every domain in the forest, and has read-access to any group and user in the forest. This principal will be used to access every domain in the forest. Normally, a user in "Domain Admins" or "Enterprise Admins" group is a good choice.
  4. In the "Users" tab, set "User Base DN" field to blank. This sets the user base DN to the root of the GC. Therefore, this provider can authenticate any user in this forest.
  5. In the "Group" tab, set "Group Base DN" field to blank. This sets the group base DN to the root of the GC.

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

Top of page

GCD Configuration for entire forest

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.

Top of page

Configuration Result for entire 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):

  • DC=mycompany,DC=com
  • DC=ca,DC=mycompany,DC=com
  • DC=wa,DC=mycompany,DC=com
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.

  • Local-domain group membership.
  • Cross-domain group membership (within this forest)
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.

Partial Forest Configuration

In some cases, you may 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.

Top of page

Authentication Provider Configuration for partial forest

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

Top of page

GCD Configuration for partial forest

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:

Top of page

Configuration Result for partial forest

Authentication

FileNet P8 can authenticate any user in any of these two domains.

Realm set

Two realms:

  • DC=mycompany,DC=com
  • DC=ca,DC=mycompany,DC=com

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.

  • Local-domain group membership.
  • Group membership across these two domains.

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.

Multi-Forest Configuration

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.com (root domain)
  • ca.mycompany.com
  • wa.mycompany.com

"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.com (root domain)
  • hr.mynewcompany.com

"mynewcompany-dc1" is the host name of a domain controller for the root domain, and has global catalog server running on it.

Authentication Provider Configuration for multi-forest

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

Top of page

GCD Configuration for multi forest

Here are the two DirectoryConfiguration objects for the above two forests:

DirectoryConfigurationAD object 1:

DirectoryConfigurationAD object 2:

Configuration Result for multi forest

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):

  • DC=mycompany,DC=com
  • DC=ca,DC=mycompany,DC=com
  • DC=wa,DC=mycompany,DC=com
  • DC=mynewcompany,DC=com
  • DC=hr,DC=mynewcompany,DC=com

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.

  • Local-domain group membership.
  • Cross-domain group membership.
  • Cross-forest group membership.

Top of page

Operation

Get User or Group by Short Name

Iterate through all forests. For each forest:

If more than one user/group is found, Content Engine logs an error and returns the first user found.

Get User or Group by DN

Get User or Group by UPN

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.

Get User or Group by SID

Search Users or Groups in a Given Realm

Top of page