Identity Management in Quercus<>

Example: Establishing the LDAP connection to a Microsoft Active Directory server


The precise steps required to establish an LDAP connection to an external IDM will vary according to the LDAP server type to which you are connecting and your local Quercus environment.

This chapter provides a detailed example of how these activities are executed when connecting to a Microsoft Active Directory server.

Connect to the server and test the connection

The first step is to enter the connection parameters in Quercus and then test that the connection actually works by telnetting from the Quercus environment to the LDAP server.

Note: The communication must be established from the Quercus database server environment.

1Set the server type using the LDAP_SERVER parameter in Quercus.

2Enter the address of the server using the LDAP_SERVER_HOST parameter.

Enter a fully qualified name, the shortened name, or the IP address.

3Enter the default port number.

Note: the default SSL port is 636 not 389.

4Test your connection to the server.

In the example below we are sending the ping command from the database server (using PuTTY) to test the connection.

5Once you have pinged the database server, telnet to the LDAP server to check that you can communicate from the database server to the Active Directory host.

Note: Many servers are configured not to respond to ping, so a ping failure is not a conclusive proof that the connection has not been established. For this reason you should attempt the telnet connection even if the ping has failed.

When establishing a telnet connection you will need to specify the port (the default telnet port 22 will not work).

In the screenshot below port 389 is used first to establish an open, unencrypted connection, followed by an encrypted connection over port 636.

Note: It is important you test your connections in the manner shown above, before moving on to set up the LDAP bind.

Now that you have established communication, you will need to authenticate as an admin user to the Active Directory.

Identify the Admin User in Quercus

If you wish to add users through services such as Apply Online you will require admin rights for writing to the LDAP directory. In order to perform the various read and write operations required in this scenario, Quercus must connect to the server as an admin user. To support this requirement you must enter details of the administrative user into Quercus.

1Create, in Active Directory, an admin user who will be identified in Quercus and will act as the broker for all activities involving communication between the two applications.

This administrative user will have the necessary authorisation level to create, read, update and delete (CRUD) user records and LDAP groups within the Active Directories.

This user can be located anywhere in the Active Directory.

2Enter details of the user into the LDAP_ADMIN_USER_NAME parameter in Quercus. Enter the distinguished name (DN) of the user.

3Enter the admin password into the LDAP_ADMIN_PASSWORD parameter.

Check the Admin User can authenticate to the LDAP server from Quercus

Once you have set up the admin user you should check that the user can authenticate to the LDAP server. You can use the Oracle SQL*Plus tool to perform this check.

1Set serveroutput to on and then execute the command.

If successful, you should receive connection and authentication confirmation messages.

Enable SSL communication if required

If you plan to encrypt communication using SSL, you must provide Quercus with the relevant domain certificate for the LDAP sever. In the case of Active Directory, SSL mode is mandatory for all connections. Although it is not mandatory for other LDAP servers we recommend that it is used if at all possible.

Specify the location of the Oracle LDAP Wallet

1To turn SSL on, specify the location of the Oracle LDAP Wallet.

The ‘Wallet’ is simply a named directory on the Quercus server in which certificates are stored.

See for more information.

2You must also enter the Wallet password.

Import the domain certificate into the Wallet

1Locate the domain certificate for the LDAP server and import the certificate.


Importing the certificate into the wallet automatically establishes SSL communication between the two servers.

If the wallet parameter is not filled in the system will operate in non-SSL (clear-text) mode.

Specify the location of the LDAP user base

Now you have fully operative SSL communication between Quercus and the LDAP server you can specify the location of the Quercus users within the LDAP directory.

1To specify the user location enter the DN of the user base as the value of the LDAP_USER_BASE parameter.

Important: If users are are spread across different directories you must specify the common root for all the directories.

Link Quercus accounts with Active Directory LDAP accounts

Next, you must establish the link between the users in Active Directory and the users in Quercus. So if a user authenticates using Active Directory and is granted access to Quercus, Quercus knows who that user is.

This link is maintained by using a field in the Quercus schema known as PERSON_LDAP.LDAP_ID. This field stores a unique LDAP identifier for each user which is compared to a corresponding unique identifier in the Active Directory.

Any suitable field holding a unique identifier can be used as the join field in Active Directory. For this reason it is necessary to specify which field is being used as the join using the LDAP_USER_ID_NUMBER parameter.

1To identify the join field, enter its name in the LDAP_USER_ID_NUMBER parameter.

In the example below the cn (common name) field is used as the join.

You can check the value of this field in Active Directory for any given user by using a tool such as Softerra LDAP Browser. In the example below the admin user’s cn (highlighted) is ‘admin’:

Once you have completed this step users should be able to log in.

Note: a user can only log into Quercus if he or she has a corresponding person account in Quercus.

Note: the admin user does not need a person account in Quercus.

Example of a user account

The screenshot shows the user record of James Gilbert in Quercus.

The screenshot below shows the same user record on the Active Directory server.

Note the join field: the cn in Active Directory, the LDAP ID in Quercus.

User Names

Note that in Active Directory you can hold the user name in either the sAMAccountName or the userPrincipalName fields.

You specify which name corresponds to the Quercus user ID via the MSAD.LDAP_USER_NAME parameter.

We recommend using the userPrincipalName rather than the sAMAccountName.

Set up LDAP groups

You have now established the user base and how Quercus users are joined to the LDAP server. At this stage student users can log into Quercus Gateway providing they are enrolled on a course instance.

Back-end staff, however, must be member of LDAP groups for authorisation purposes. For this reason the Quercus LDAP groups must be set up on the Active Directory server before staff members can authenticate and be authorised.

The groups are defined by Quercus and they need to be stored in a location in the Active Directory.

1To identify the location of the groups, enter the group DN as the LDAP_GROUP_BASE parameter.

The groups referenced in the DN above are shown below in the Active Directory.

These groups are updated with each maintenance release of Quercus by various scripts (e.g. ldap.quercus.sql, ldap.quercus.qlive, ldap.quercus.hesa) which use the oc_ldap API to create the required groups. Note that redundant existing groups are not deleted by these scripts.

Important: the admin user must always be added into an LDAP group. This is required to allow the Quercus administrator to add and remove LDAP groups from users. If the admin user was not added to an LDAP group it would not show up in the Available LDAP Groups pane below.

2Add users to LDAP groups.

You can do this:

through Quercus (as shown above)

through Active Directory (as shown below)

through batch scripts

3If you wish to separate Apply Online candidates from enrolled students within the LDAP server, complete the LDAP_NEW_USER_BASE parameter.

The parameter ensures that new users created via Apply Online will appear in a separate directory to the ‘full’ Quercus users (enrolled students and staff).

Note: the LDAP_NEW_USER_BASE must be below the LDAP_USER_BASE in the LDAP directory structure.

Test the installation

You have now completed all the steps in the LDAP set-up procedure.

You can now begin testing the installation.