Integrating Novell Access Manager with Oracle Internet Directory


  Related Documents
NAM Schema Requirements for User Store
  NAM User Stores and Schema Requirements
  Schema Choice for OID
OID Schema Configuration
  Schema Extension
  Attribute Aliasing – An alternative approach
  Key considerations for choice of approach
Configuring NAM with OID
  Configuring OID as a Local User Store in NAM
  Configuring an Authentication Contract using OID
Configuring a Protected Resource to Use the Contract
Access Manager LDAP Subsystem Architecture
Troubleshooting NAM with OID


At the time of this writing, Novell Access Manager (NAM) is configurable and has been tested to work with three different back-end LDAP user stores:

- Novell eDirectory
- Microsoft Active Directory
- Sun SunOne Directory

Many other third-party, back-end LDAP servers exist in the market that are different from the list above. One such example is the Oracle Internet Directory (OID). OID is not an LDAP store that has been tested to be used as a local user store with Novell Access Manager, and no option exists to add it as a user store. In order to get OID or any of these third-party LDAP servers to interoperate with Novell Access Manager, you must first understand the interaction between the LDAP user store and the Novell Identity (NIDP) server that will communicate with that LDAP user store.
This documentation has been written to describe how to integrate Novell Access Manager with a third-party LDAP server. The specific LDAP server chosen in the document is the Oracle Internet Directory (OID). The document’s primary aims are as follows:

- Outline the key schema requirements to prepare OID for use with NAM
- Provide two tested approaches for implementing Schema updates to OID
- Provide steps required to configure OID as the local user store for NAM


The intended audience for this document includes:

- Novell Principals and partners who plan and execute engagements implementing Federation, Web-SSO, and Remote Access solutions using Novell Access Manager and have a need to use OID as the user store
- NAM practitioners who analyze requirements and design and implement the solutions
- NAM customers who have a need to use OID as the user store

Note: This pertains to local authentication on the Identity Server with provisioning and federation. We will also interact and write information to the remote user store, although we have not tested this yet.

Related Documents

A full list of the current Novell product documentation is available for download from the Novell website at In particular, the NAM-related documents are listed in Table 1. These can be considered live documents. As service packs and interim software releases are posted, so too are these documents.


Installation Guide

Basic Setup Guide

Administration Guide

SSL VPN User Guide

J2EE Agent Guide

Error Codes

NAM Developer Tools and Examples

The following Oracle documentation is relevant for understanding Oracle Internet directory in order to administer it and configure it for use with NAM.

Directory Schema Administration

OracleRegistered Internet Directory Administrator's Guide - 10g (9.0.4)

NAM Schema Requirements for User Store

NAM User Stores and Schema Requirements

NAM uses LDAP v3 to authenticate users to the local user store via the Identity Server as well as to retrieve user-specific information to be used in policies. Currently, NAM officially supports eDirectory, Microsoft Active Directory and SunOne Directory as the built-in configurations handled by the Identity Server code.
In order for the users to be authenticated, the Identity Server performs an LDAP Search to locate the user to be authenticated as. This is followed by an LDAP Bind to the user store via LDAP v3 protocol, using this user’s userid and password if the Name / Password contract is used as the authentication contract. At this time, the Identity Server performs a LDAP read from the user store asking for specific attributes from the user store depending on the kind of user store, per the table below:

Attribute Type eDirectory Active Directory SunOne
GUID Attribute Name GUID objectGUID nsuniqueid
User Object Class Name user user inetorgperson
User Object Naming Attribute cn samAccountName uid
User's Preferred Name fullName fullName fullName

Table: NAM Required Attributes by User Store Type

As a result, when an LDAPv3-compliant directory is configured as a specific user store, the Identity Server uses the above attribute names to query the user store. If the remote directory is LDAPv3-compliant but does not have the specific attributes on the user object, the Identity Server will fail to authenticate the user and will generate errors, even if it is able to validate the user store at configuration time. This is because it initially does an LDAP bind with the admin user ID and password provided as part of the user store configuration in the Administration Console, before searching for above attributes of the user we are trying to authenticate with. When we get the LDAP response with all the required attributes, the final stage is an LDAP bind as this user.

With the following trace output shown in Figure 1, packet 4 shows the simple LDAP bind with the LDAP admin user defined for this LDAP replica store, with the corresponding response coming in packet 6. Packets 8 and 10 show the search request and response for the above LDAP attributes of the user we are authenticating as (ncashell). Figure 2 below will show this in more detail. Packet 14 shows the LDAP bind with this new user. Only with the success response in packet 16 will we consider the user authenticated to the LDAP store.

Figure 1: Default LDAP traffic from Identity Server to LDAP store during authentication stage

The following is a sample search query sent by the Identity Server to SunOne LDAP server for the default required user attributes:

Figure 2: LDAP search query for required user attributes from Identity Server to SunOne

When dealing with a third-party LDAP server that is not capable of responding successfully with the LDAP user attributes we require, some changes are required on the remote user store to make it respond with the info required by the Identity server.

Schema Choice for OID

Analyzing the Oracle OID schema, it was noted that OID's schema is fairly close to SunOne (Netscape Directory). Hence, it already associates the user objects with the "inetorgperson" class. It also has a “uid” attribute with the same value as “cn” and can therefore be directly used.
However, OID uses “orclGUID” as the unique identifier and does not have “fullName” attribute on the user object or the “inetorgperson” class. As a result, the schema needs to be updated to present “orclGUID” as “nsuniqueid” and “displayName” as “fullName”. Both of these are case- independent alphanumeric strings.

The next section presents two approaches to accomplishing the schema updates in order to prepare the schema to be configured as SunOne directory to NAM.

OID Schema Configuration

The following are two approaches to updating the OID schema to contain the “nsquiqueid” and “fullName” attributes in order for it to masquerade as “SunOne” directory to NAM.

- Schema Extension: In this approach, we merely add the two needed attributes and associate them with inetorgperson. To make this simple, we use the OID Administration GUI.
- Attribute Aliasing: OID has a documented approach to creating attribute aliases which can then be used in LDAP queries. This is more complicated and prone to issues. The approach is to alias orclGUID as nsuniqueid and displayName as fullName.

Schema Extension

The schema extension approach entails creating the two attributes, nsquiqueid and fullName, using the syntax of orclGUID and displayName. This can be accomplished via the OID Administration GUI by using the “Create Like” function. As a result, you don’t need to know the exact underlying schema syntax information in OID for these attributes. It is sufficient that NAM expects these to be alphanumeric strings, and these are already in that category.
The following screen shots show how the OID Administration GUI can be used to create these needed attributes:

Figure 3: Create nsquiqueid General Tab – use “Create Like” orclGUID

Figure 4: Create nsquiqueid Advanced Tab

Figure 5: Create fullName General Tab – use “Create Like” displayName

Figure 6: Create fullName Advanced Tab

1. Make sure you associate both these attributes with the “inetorgperson” class via the OID Administration GUI.

2. Populate the values of these attributes by cutting and pasting the values of user attributes orclGUID and displayName.
Following is a screenshot of how 'nsuniqueid' is added as an attrubute to the “inetorgperson” class:

Figure 7: Associating nsuniqueid with inetorperson class

Attribute Aliasing – An alternative approach

OID has a feature that allows the schema administrator to create aliases for attributes. However, these aliases need to be created when the attribute is created. Because orclGUID and displayName will already exist in a fully installed OID, this poses a complicated challenge of having to drop and re-add these attributes with full original syntaxes in addition to the aliases.

Additionally, this cannot be accomplished via the OID Administration GUI at this time. It needs to be performed via the ldapmodify command line utility using an LDIF file.
Moreover, it all needs to happen in one unit of work because, once the orclGUID is dropped, users cannot authenticate to OID. This could happen if you have syntax errors or permission errors in the re-add command that follows the delete command. As a result, OID allows for a specific format of LDIF that will keep the drop and add operations as one unit of work.

Warning: Do not attempt this if you are not willing to reinstall OID if it gets corrupted or gets into an unstable state. Keep an OID Administration GUI screen open as an administrator with full privileges before attempting this command.

Use the ldapmodify command as follows:

ldapmodify -h host -p port -D bind_dn -w password -a -f ldif_file_name

The LDIF file will contain the following commands:

dn: cn=subschemasubentry
attributetypes:( 2.16.840.1.113730.3.1.241 NAME 'displayName' )
attributetypes:( 2.16.840.1.113730.3.1.241 NAME ( 'displayName' 'fullName' ) DESC 'Preferred Name of a person to be used when displaying entries' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX '' SINGLE-VALUE )

Figure 8: Create fullName alias to displaName - LDIF Script

dn: cn=subschemasubentry
attributetypes:( 2.16.840.1.113894.1.1.37 NAME 'orclGUID' )
attributetypes:( 2.16.840.1.113894.1.1.37 NAME ( 'orclGUID' 'nsuniqueid' ) DESC '

This is the global unique identifier for an entry within Oracle Internet Directory. The value for this attribute is automatically generated when an entry is created and remains constant, even if an entry is moved.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX' SINGLE-VALUE )

Figure 9: Create nsuniqueid alias to orclGUID – LDIF script

Once you've finished, go back on the OID Administration screen (which was left open before the ldapmodify was attempted), refresh the contents and then do the following immediately:

1. Associate 'orclGUID' back with the “Top” class.

2. Associate the attribute displayName back with the “inetorgperson” class.

This is a very difficult one to accomplish; it occasionally corrupts OID and will elicit unpredictable behavior. So this should be attempted on a virgin OID installation before any users or applications start using it.

Key Considerations for Choice of Approach

There are two basic approaches you can use: 1) the Schema Extension approach, and 2) the Attribute Alias approach. The first approach is the easiest to accomplish. It will need some application or mechanism to keep the nsuniqueid and fullName populated on the user object.

The second approach is the most complicated and is error-prone. It has the tendency to corrupt the directory. Part of the command needs to be executed from the command line and part of it from the administration GUI. The administration GUI needs to be kept open before attempting the approach. Once accomplished, the attributes do not need special population and maintenance.

Configuring NAM with OID

Once the necessary schema extensions are done, and the user objects have the necessary attribution, OID is ready for integration with NAM as a local LDAP user store. With all the schema extensions made OID look like SunOne, the natural choice is to configure it as SunOne in the NAM administration console. The process is straightforward and follows the textbook steps in the NAM administration manual. For completeness of this document, appropriate screen shots have been included in this section with an example that was used to test this integration.

Configuring OID as a Local User Store in NAM

The following figure shows how OID is configured as a SunOne local user store in the NAM administration console:

Figure 10: Configure OID as a local store in NAM Admin Console

Configuring an Authentication Contract using OID

The following shows how an authentication method is created against the OID user store.

Figure 11: Configure Authentication Method to use OID in NAM Admin Console

The following shows how an authentication contract is created using the method created against OID.

Figure 12: Configure Authentication Contract to Use OID Method in NAM Admin Console

Configuring a Protected Resource to Use the Contract

The following shows how a protected resource uses the authentication contract created against OID.

Figure 13: Configure Protected Resource to use OID Authentication Contract in NAM

Access Manager LDAP Subsystem Architecture

This section describes some of the architecture of the Novell Access Manager LDAP Subsystem, with emphasis on how user store configuration data items are used by that subsystem.

When configuring a user store using iManager, the admin enters the data items listed and explained below.

User Store Configuration:

LDAP Timeout Settings:
LDAP Operations
Idle Connections

User Store Replica Configuration:

Connection Limit

All LDAP accesses performed by NAM are done using the Novell Access Manager LDAP Subsystem. The configuration of the LDAP subsystem comes from the list of user stores and user store replicas that the admin configures using iManager.

When NAM makes an LDAP call, the call is directed to a user store. The LDAP subsystem handles obtaining a connection to a replica of that user store and executing the LDAP call. Replica selection is discussed below.

Each user store contains one or more user store replicas. The replicas must be exact copies of each other. Each user store replica maintains two connection pools: an authentication pool and an admin pool. Authentication pool connections are used only for authenticating users. Admin connections are used to perform all other LDAP tasks on behalf of a user or the NAM system itself.

The other large difference between the Authentication pool and the Admin pool is that connections in the Authentication pool are closed immediately after use; they are not kept around. You may think of the Authentication pool more as a counter that makes sure no more than X number of Authentication connections are active at any given time. The Admin pool, on the other hand, actually saves connections to be used for multiple LDAP requests. So, the Admin pool may have X active connections and the connections may be "checked out" and then "checked in" once an operation is complete. Again, the Admin pool makes sure that the maximum number of connections is not exceeded.

During NAM startup, the LDAP subsystem is initialized. The initial maximum number of connections allocated to each connection pool is half of the Connection Limit value entered by the administrator. So, for example, if the Connection Limit is 20, then the Authentication pool will be limited to 10 concurrent authentication connections, and the Admin pool will be limited to 10 "pooled" admin connections.

At startup, each Admin pool is fully populated with the maximum number of connections allowed. The Authentication pool is simply initialized with the number of maximum allowable authentication connections, but no connection is actually created until the applicable user name/password is received for authentication.

For user authentication, a connection is checked out of the Authentication pool. What this means for the Authentication Pool is that the count of current number of connections checked out is incremented. If that count equals the maximum allowed, then the requesting thread is forced to wait until another thread completes the authentication process and "checks in" their connection. Bumping up against the maximum number of Authentication pool allowed connections is one situation that can make NAM run slower.

For an Admin operation, such as an LDAP search, read, or write, a real physical connection object is checked out of the Admin pool. The operation is performed using the connection, and then the same connection is checked in to the Admin pool for potential reuse. Again, if there are zero connections available when a checkout request is made to the pool, the requesting thread must wait until another thread checks in a connection.

The configuration data item Idle Connections provides a timeout value for idle connections in the Admin pool. When a checkout request reaches the Admin pool, the pool will check the connection to see if it has been idle for at least the Idle Connections time period. If it has, then that connection will be closed, and a new one will be created. This is an attempt to circumvent problems with old, stale connections that, when used, take a long time to timeout or return an error.

The configuration data item LDAP Operations applies to all LDAP operations performed by connections from both pools. The problem that this configuration item addresses is that, on some systems, up to 17 minutes may be required for an LDAP request to timeout. NAM cannot hold onto a user thread that long. Therefore, all LDAP requests are done on LDAP Subsystem threads. Each LDAP operation is timed by the LDAP Subsystem, and if the operation takes longer than the configured LDAP Operations time period, then the LDAP Subsystem thread making the request is abandoned, and the operation fails. So, in general, making the LDAP Operations smaller will make replica failover work faster, because a down replica will be recognized faster; however, false abandonments may occur. Conversely, making the value larger will minimize the number of false abandonments but will cause replica failover to take longer.

Replica selection is done by hashing the name of the user for which the operation will be performed and converting that hash into an index into the table of available replicas. Therefore, the same user should always be sent to the same replica. This is an attempt to avoid situations where a write happens to replica A, then a read happens to replica B, but system replication has not moved the data from A to B.

Troubleshooting NAM with OID

If the above setup has been completed successfully, and users still cannot authenticate, a few simple troubleshooting steps may be required to validate where the problem is coming from. The most basic approaches are to look at the following things:

- IDP health status for the user store and make sure that everything is running correctly (green light)
- LDAP interaction between the Identity server and the remote LDAP user store, making sure the required LDAP search attributes are received, and that an LDAP bind as the authenticated user has been successful (see Figures 1 and 2 above).

If the search request for the required attributes fails, use the ldapsearch utility from the Identity server to confirm that the back end LDAP server actually sends the data back. Running the following command and make sure that the nsuniqueid and fullname are returned:

ldapsearch -x -h <$OID_IP_Address> -D cn=<$OID_UserStore_Administrator_Username> ,cn=Users,dc=nam,dc=novell,dc=com -w <$OID_UserStore_Administrator_password> -b <$User_we_are_authenticating_as>'

For example, the following ldapsearch command shows that the OID LDAP server is sending back the required fullname user attribute:

linuxlab5:~ # ldapsearch -x -h -D cn=nam,cn=users,dc=whq,dc=ual,dc=com -w novell -b cn=ncashell,cn=users,dc=whq,dc=ual,dc=com |grep -i fullname
fullName: Neil Cashell
linuxlab5:~ #

In cases where the LDAP server appears to be sending back the correct information, and authentication continues to fail, you may have to enable more verbose logging at the Identity server. The following diagram shows the recommended Identity Server log settings when troubleshooting LDAP authentication errors:

Figure 14: Enabling debug logging on Identity Server

After applying these settings to the Identity server, the /var/opt/novell/tomcat4/logs/catalina.out file will include a lot more details regarding the user authenticating.
As the Identity server initializes, it creates TCP connections to all user stores defined, which should be visible through netstat:

linuxlab5:~ # netstat -patune|grep 389
tcp 0 0 ESTABLISHED 100 1604938 3254/java
tcp 0 0 ESTABLISHED 100 1604937 3254/java
tcp 0 0 ESTABLISHED 100 1604939 3254/java
tcp 0 0 ESTABLISHED 100 1604823 3254/java
tcp 0 0 ESTABLISHED 100 1604933 3254/java
tcp 0 0 ESTABLISHED 100 1604934 3254/java
tcp 0 0 ESTABLISHED 100 1604935 3254/java
tcp 0 0 ESTABLISHED 100 1604936 3254/java
tcp 0 0 ESTABLISHED 100 1604931 3254/java
tcp 0 0 ESTABLISHED 100 1604932 3254/java

If the Identity server initializes successfully, the following entry will be written to the catalina.out file. If the user stores are not operating properly, search for the IP address or name of the user store in the log file and identify errors. Common errors include certificate-related errors, in the case of secure LDAP, or connectivity errors due to firewalls blocking traffic.

<amLogEntry> 2008-04-03T17:08:24Z NIDS Trace: Method: NIDPServletContext.healthCheckUserStores()
Thread: RMI TCP Connection(1)-
(1 of 4):
User Store Count: 1
(2 of 4):
For User Store #0: Name: Paddy User Store, Replica Count: 1
(3 of 4):
For User Store #1: Name: OID User Store, Replica Count: 1
(4 of 4):
User Stores operating properly!

When the user hits a protected resource and is required to authenticate (e.g., user ncashell in the log below), a Liberty or SAML authentication request is made to the Novell Identity server. The log file will indicate the type of authentication contract to be executed (Secure Name/Password - Form), as in the example below.

<amLogEntry> 2008-04-04T11:21:00Z VERBOSE NIDS Application: Session has consumed authentications: false </amLogEntry>
<amLogEntry> 2008-04-04T11:21:00Z VERBOSE NIDS Application: Executing authentication method
Secure Name/Password - Form

Next, in the case of the LDAP authentication, an LDAP search request must be generated to identify that user in the user store. The following entries show that the search request is being generated with the corresponding base and filter:

<amLogEntry> 2008-04-04T11:21:04Z NIDS Trace: Method: LocalAuthenticationClass.authenticateWithPassword()Thread: http-0/
Attempted authenticateWithPassword - id = ncashell
<amLogEntry> 2008-04-04T11:21:04Z VERBOSE NIDS Application: Performing LDAP search (&(objectClass=inetorgperson)(cn=ncashell)) in context <nidsc:SearchContext(novell:nids:config:1:0:0)>: Context: o=novell Order: 0, Scope: 1
<amLogEntry> 2008-04-04T11:21:04Z NIDS Trace: Method: JNDIUserStore.doAdminSearch()
Thread: http-0/
Base context: o=novell, Filter: (&(objectClass=inetorgperson)(cn=ncashell)), Scope: 1, Request Controls: null, UserId: abc </amLogEntry>
<amLogEntry> 2008-04-04T11:21:04Z NIDS Trace: Method:
Thread: USSearchThread-felkzlt6uaz21
(1 of 5):Interrupted to begin another operation! Die: false
(2 of 5):Starting user store operation! UserStore: OID User Store, replica: Paddy Server Replica
(3 of 5):Successfully completed user store operation in 7 millis!
(4 of 5):Interrupting owner thread: http-0/
(5 of 5): JNDIUserStoreOperationSearchThread:
User Store: OID User Store
User Store Replica: OID Server Replica
User Store Replica Connection: femo1smyz9bu3
Suspicious period: 7 millis.
Thread Owner: http-0/
Search Base: o=novell
Scope: 1
Filter: (&(objectClass=inetorgperson)(cn=ncashell))
Result NamingEnumeration: com.sun.jndi.ldap.LdapSearchEnumeration@1778a52

In the case where the LDAP request gets the required response i.e locates a matching user, we will log the fact that we got a result.

<amLogEntry> 2008-04-04T11:21:04Z NIDS Trace: Method: JNDIUserStore.doAdminSearch()
Thread: http-0/
Found 1 results!

Next we need to to the LDAP bind as the user, with the password inserted into the login page, and perform additional searches for the attributes defined in Table 3 above.

<amLogEntry> 2008-04-04T11:21:04Z INFO NIDS Application: AM#500105014: AMDEVICEID#D5AF8CA5FBDB5813: AMAUTHID#72EB4508217D10885536C9EA8C5CA381: Attempting to authenticate user cn=ncashell,cn=users,dc=whq,dc=ual,dc=com with provided credentials.
<amLogEntry> 2008-04-04T11:21:04Z NIDS Trace: Method:
Thread: USCreateConnectionThread-felkzlsy8t4f
(1 of 3):Successfully completed user store operation in 12 millis!
(2 of 3):Interrupting owner thread: http-0/
(3 of 3):JNDIUserStoreOperationConnectionThread:
User Store: OID User Store
User Store Replica: OID Server Replica
User Store Replica Connection: femo1snu7hnu4
Suspicious period: 13 millis.
Thread Owner: http-0/
User Name: cn=ncashell,cn=users,dc=whq,dc=ual,dc=com
User Password: ******
<amLogEntry> 2008-04-04T11:21:04Z NIDS Trace: Method: JNDIUserStoreReplicaConnectionPool.A()
Thread: http-0/
(1 of 2):WAIT on create user connection interrupted due to an InterruptedException! Pool Id: Plfelkzml2r9i2w:felkzml19jo2u
(2 of 2):Pool Id: PLfelkzml2r9i2w:felkzml19jo2u, Got Connection! Connection Id: femo1snu7hnu4
Host: ldap://
Allocate Speed: 17
Connection Type: User
Connections Checked Out: 1
MaxConnections: 10
User: cn=ncashell,cn=users,dc=whq,dc=ual,dc=com
Stats: Gets: 2 (Existing: 0, New: 2), Puts: 1, Waits: 0

Next, with eDirectory users stores only, we do some additional checks on whether the user's password will expire. To do this, we check the loginGraceLimit and loginGraceRemaining attributes of the user we are logging in as. The result of this query will determine whether one is redirected to the password management servlet associated with the authentication contract or not. This snippet will not appear when dealing with other user stores!

<amLogEntry> 2008-04-04T11:21:04Z NIDS Trace: Method: JNDIUserStore.getObject()
Thread: http-0/
Target object dn: cn=ncashell,o=novell
Acting as: cn=admin,o=novell
Attr: loginGraceLimit
Attr: loginGraceRemaining
<amLogEntry> 2008-04-04T11:21:04Z NIDS Trace: Method:
Thread: USGetThread-felkzlt73du27
(1 of 5):Interrupted to begin another operation! Die: false
(2 of 5):Starting user store operation! UserStore: Paddy User Store, replica: Paddy Server Replica
(3 of 5):Successfully completed user store operation in 4 millis!
(4 of 5):Interrupting owner thread: http-0/
(5 of 5):JNDIUserStoreOperationGetThread:
User Store: eDir User Store
User Store Replica: eDir Server Replica
User Store Replica Connection: femo1smyz9bu3
Suspicious period: 4 millis.
Thread Owner: http-0/
DN: cn=ncashell,o=novell

The various checks carried out have been successful and the user's credentials validated. A success message is logged to the log file.

<amLogEntry> 2008-04-04T11:21:04Z VERBOSE NIDS Application: Authentication method Secure Name/Password - Form succeeded

Finally, an entry is created for the user in the Novell Identity Server authentication table. This indicates that the user has been authenticated by the local Identity server.

<amLogEntry> 2008-04-04T14:39:20Z NIDS Trace: Method: NIDPAuthentication.()
Thread: http-0/
Created new Authentication:
protocol: Local
expiration: 0



How To-Best Practice
Comment List