Search Google Appliance

Home >> Services >> Oak >> Sp >> Ldap >> Oak LDAP Service

Oak LDAP Service

1. Introduction

1.1. Overview

The Oak LDAP service is intended to enable authorisation decisions to be taken by service providers in the University. Data on unit affiliations (departments and colleges), and the nature of people's relationships with the University (student, staff, etc) are provided. The directory information in Oak LDAP can also be used to map between people's different identifiers (SSO username, barcode, etc), and to retrieve contact data and names for people and units.

It is possible to look up people by their card's barcode number, by their email address, or by their Oak single sign-on (SSO) username. This ability to look someone up by their Oak SSO username makes the service especially useful in conjunction with the Oak Kerberos and Webauth Authentication Services.

An example of the type of policy that can be implemented with data from the Oak LDAP service is "only people affiliated with Department X can use Service Y". Another example is "only members of the University can use Service Z".

The directory contains entries about all University members, and some non-members, such as virtual access card holders. In principle, it could contain entries about anyone whose relationship with the University justifies inclusion.

1.2. See Also

The following documents are also relevant to Oak LDAP.

2. Registering as an Oak LDAP consumer

Service providers must register before being able to query the Oak LDAP service.

To register, please send an email to with the following information. Please send a separate request for each service where you're interested in using Oak LDAP.

  • Which Kerberos principal(s) should be granted access to Oak LDAP for this service?
    • If you're adding simple authorisation to an existing WebAuth-protected site using mod_webauthldap, we can grant access to the existing WebAuth principal(s)
    • Otherwise, we'll create a new principal named like oak-ldap/<HOSTNAME>@OX.AC.UK for this purpose
    • See the ITSS Wiki authentication page for some background.
  • Will the principal(s) need access to the personal LDAP entries of all people, or only of people affiliated to your unit(s)?
  • A confirmation that you have read the terms of usage

3. Terms of Usage

The Oak authorisation service provides, in the first instance, LDAP access to a directory of user and unit attributes. The service is primarily intended to be used in conjunction with the existing Kerberos/Webauth authentication service. Your use of the Oak authorisation service is subject to the following conditions:

  1. You are an IT Support person who is either registered to provide a service to one or more clearly defined units OR you are registered as a University-wide service provider.
  2. You are registered with IT Services to be an Oak data consumer (see registration process).
  3. You have read and understood the Regulations Relating to the use of Information Technology Facilities. In particular, your attention is drawn to clauses 9-10 of the Regulations relating to the confidentiality of information and the holding or processing of data relating to living individuals.
  4. You have read and understand the University Policy on Data Protection. In particular, your attention is drawn to the following paragraphs:
    1. All staff or other individuals who have access to, or who use, personal data, have a responsibility to exercise care in the treatment of that data and to ensure that such information is not disclosed to any unauthorised person. Examples of data include address lists and contact details as well as individual files.

    2. Under principle 8, which restricts the transfer of material outside the European Area, personal data about an individual placed on the world wide web is likely to breach the provisions of the Act unless the individual whose data is used has given his or her express consent. It is important that all those preparing web pages, address lists and the like, are aware of these provisions, and seek advice from the Data Protection Officer if in doubt.

  5. Your use of the Service and any data obtained from the Service is in accordance with the Oak LDAP Schema and Attribute Release Policy.

4. Recommended Usage

This section gives recommendations on how to achieve particular goals using the Oak LDAP service, independently of any particular LDAP client software. To apply this advice using your OpenLDAP client software, please refer to Using LDAP Client Software With the Oak LDAP Service.

4.1. What it Means for a Person to Have an Oak LDAP Entry

You shouldn't infer anything from the mere existence of an Oak LDAP entry for a person. In particular, just because someone is in the Oak LDAP directory doesn't mean they're a member of the University (but see How to Authorise Based on Membership of the University), nor does it imply that they're entitled to use any University resources.

4.2. How to Look Up a Person by SSO Username

Perform an LDAP search with a base of ou=people,dc=oak,dc=ox,dc=ac,dc=uk and a filter of oakPrincipal=krbPrincipalName=<USERNAME>@OX.AC.UK,cn=OX.AC.UK,cn=KerberosRealms,dc=oak,dc=ox,dc=ac,dc=uk.

4.3. How to Look Up a Person by oakPersonID

You should do an LDAP search with a base of ou=people,dc=oak,dc=ox,dc=ac,dc=uk and a filter of oakPersonID=<ID>.

You should not do an LDAP search with a base of oakPrimaryPersonID=<ID>,ou=people,dc=oak,dc=ox,dc=ac,dc=uk. This is because in some cases a person may have multiple oakPersonIDs. Only one of these will be present in the distinguished name of the person's entry as the oakPrimaryPersonID.

4.4. How to Look Up a Person by Their Card's Barcode

If the card reader you're using reads the whole barcode including the check digit, then perform an LDAP search with a base of ou=people,dc=oak,dc=ox,dc=ac,dc=uk and a filter of oakUniversityBarcodeFull=BARCODE. Otherwise, use the oakUniversityBarcode attribute instead.

4.5. How to Authorise Based on Membership of the University

To query whether someone is a member of the University, perform an LDAP compare query to compare the eduPersonAffiliation attribute of the person's entry to the string member.

4.6. How to Authorise Based on Membership of a Particular Unit

Often, authorisation decisions will be taken on the basis of membership of a particular unit (college or department).

4.6.1. With a Query About the Person's Entry

Perform an LDAP compare query to compare the eduPersonOrgUnitDN attribute on the person's entry with the known distinguished name of the unit's entry. For example, to see whether person 38463 is a member of OUCS, one would perform an LDAP compare to ask whether the eduPersonOrgUnitDN attribute of oakPrimaryPersonID=38463,ou=people,dc=oak,dc=ox,dc=ac,dc=uk has a value of oakUnitCode=oucs,ou=units,dc=oak,dc=ox,dc=ac,dc=uk.

4.6.2. With a Query About the Unit's Entry

Equally valid is to perform an LDAP compare query to compare the member attribute on the unit's entry with the known distinguished name of the person's entry. Using the same example as above, one would perform an LDAP compare to ask whether the member attribute of oakUnitCode=oucs,ou=units,dc=oak,dc=ox,dc=ac,dc=uk has a value of oakPrimaryPersonID=38463,ou=people,dc=oak,dc=ox,dc=ac,dc=uk

4.7. How to Authorise Based on ITSS Membership

4.7.1. Simple ITSS Status Check

Perform an LDAP compare query to compare the member attribute on the oakGN=ITSS,ou=oucscentral,dc=oak,dc=ox,dc=ac,dc=uk entry with the known distinguished name of the person's entry

4.7.2. Check for ITSS Status at a Particular Unit

Check the oakGN=ITSS,oakUnitCode=<CODE>,ou=units,dc=oak,dc=ox,dc=ac,dc=uk group for the unit of interest.

4.8. Find all the Units for Which a Person is ITSS

Query the person's oakITSSFor attribute.

4.9. How to Display Someone's Name

Some applications need to display a person's name, for example in a welcome message. The correct attribute to use for this is displayName.

4.10. How to Keep Persistent References to a Person in Your Application

You should use the oakPrimaryPersonID and oakPersonID attributes for this (bearing in mind how to look up a person by ID). None of the other unique attributes are guaranteed to be present on every person entry.

You should not treat the oakPrimaryPrincipal as a persistent reference to a person; principal names may be used to store persistent references to particular principals, but this is different from treating oakPrimaryPrincipal as a persistent reference to a person.

5. Resilience

Oak LDAP is normally provided by around four IP addresses spread across two or more data centres (look up the DNS record for current details).

In order to take advantage of the resilience offered, clients need to implement these related behaviours:

  • If a node refuses the connection, or if the initial connection fails due to a timeout or any other reason, try connecting to a different node from the pool. Don't give up until all nodes in the pool have been tried
  • If the node you're connected to closes the connection, or the connection breaks or expires for other reasons, open a new connection to a node currently in the pool (taking care to expire any cached DNS responses according to their TTLs), and reissue any incomplete queries

The exact way to achieve this differs from client to client. Clients not implementing the above behaviours will still work properly a lot of the time, but will not exhibit continuous operation when individual nodes become unavailable, for example due to maintenance operations or component failures.

6. Mailing List

There is an Oak LDAP mailing list. This is an open list for both announcements about the service (schema changes, technology-related changes) and for general discussion relevant to Oak LDAP.

You can subscribe by sending mail to The posting address is


Written by IT Services. Latest revision 30 November 2018