Products » Connect2id server » Documentation » Old versions » Connect2id server 5.x » How-tos »

How to setup an LDAP directory for Connect2id server use

The Connect2id server requires an LDAP directory to persist two types of data:

  1. Registration details of its OAuth and OpenID Connect clients.

  2. Long-lived authorisations (where end-user consent must be remembered or refresh tokens issued).

1. Compatible LDAP directory servers

The Connect2id server works with any directory that implements LDAP v3 as specified in RFC 4510. The server has been successfully tested with the following open source directory software:

  • OpenLDAP
  • OpenDJ
  • 389 Directory Server

Other LDAP directories, such as MS Active Directory and Oracle Internet will also work.

2. LDAP directory setup

These are the general steps for setting an up an LDAP directory for use by a Connect2id server. Check the bottom of this guide for directory specific instructions.

  1. Add required schemas

    Supply the LDAP directory with the required schemas to store the client registration and the long-lived authorisation entries:

    • Client registration schema: oidc-client-schema-[server].ldif
    • Long-lived authorisation schema: oidc-authz-schema-[server].ldif

    Where [server] denotes the particular LDAP server implementation that you have, e.g. openldap.

  2. Add required indices

    The following attributes should be indexed to speed up LDAP searches:

    • authzSubject -- for retrieving long-lived authorisations by subject (end-user)
    • authzClientID -- for retrieving long-lived authorisations by client identifier

  3. Create the base directory branches for data

    Create two directory branches -- one to store the client registration entries and another to store the long-lived authorisation entries.

    For example:

    • Branch for the client registrations: ou=clients,dc=wonderland,dc=net
    • Branch for the authorisations: ou=authorizations,dc=wonderland,dc=net

  4. Create an LDAP user

    Create an LDAP user for the Connect2id server with permissions to read, search, and write entries in the above mentioned branches.

    For example: cn=c2id,dc=wonderland,dc=net

    Avoid giving the LDAP user more permissions than necessary.

3. Recommendations

  • While it's possible to share an LDAP directory with other applications, we recommend that you provision the Connect2id server with its own LDAP directory. This is good for security and ensures performance will not suffer when another application loads the directory with its own requests.

  • For high-availability we recommend that you set up an LDAP cluster configured for multi-master or fail-over (hot-standby) operation. Note that the Connect2id server caches extensively LDAP data, and may sustain basic service (single sign-on and token issue) with the backend LDAP directory being unavailable.

  • Make regular backups of your LDAP data. Of the two types of data the client registrations are critical, since they hold the credentials of each client application that relies on the Connect2id server. If the registration data is lost each client application will have to be registered again. Loss of persisted authorisations (consent) has less of an impact -- refresh tokens will have to reissued and end-users will have to re-authorise their apps.

  • Provision the LDAP directory with an SSL / TLS certificate to protect the communication with the Connect2id server. CA-issued as well as self-signed certificates are accepted (the latter require an extra setting, see [1] and [2]).

4. Estimating LDAP storage requirements

4.1 Client registrations storage

The size of a typical OAuth 2.0 / OpenID Connect client registration is about 2 KBytes. The storage requirements for the registrations are therefore minuscule unless you intend to provide open registration with potentially thousands or millions of client applications. In such a case it may make sense to use a separate LDAP directory or cluster to store the client registrations.

4.2 Long-lived authorisations storage

The size of a typical persisted authorisation begins at 1 KByte and may be take up to several KB with multiple or longer scope values.

The maximum storage requirement can be calculated with the following formula:

Total client count X total end-user count X average authorisation size

For example:

  • 100 client applications
  • 100'000 end-users
  • 1 KB average authorisation size
  • Required storage: 10 GB

5. LDAP configuration settings

Once you have setup the LDAP directory record its details in the Connect2id server configuration.

Note that the client registrations and the authorisations may be stored in two separate LDAP directories (hence the separate settings).

  1. The LDAP directory URL(s) (host and port):

  2. If you have an LDAP directory cluster the Connect2id can make connections in round-robin or fail-over mode:

  3. Provide a sensible LDAP connect timeout, in milliseconds:

  4. Specify whether the LDAP connections use SSL or StartTLS security:

    Set to true if you're using self-signed certs:

  5. Set an LDAP connection pool size (larger for the authorisations):

  6. The LDAP user credentials:

  7. The directory branches:

6. Browsing the LDAP directory

One benefit of using an LDAP directory is that you can use standard tools to monitor and inspect the stored client registrations and authorisations.

A fine GUI browser to consider is Apache Directory Studio.

Warning: Remember that the client registration and the authorisation entries must not be edited directly via LDAP, unless the Connect2id server is shut down. The Connect2id server caches data extensively and your changes may not be seen or may be overwritten. You also run the risk of corrupting the data. Use the dedicated Connect2id server web APIs instead.

7. Directory specific setup

Below you can find specific setup instructions for OpenDJ and OpenLDAP directory servers.

7.1 OpenDJ setup

These setup instructions apply to OpenDJ 2.4 and later.

7.1.1 Add required schemas

A simple offline method to add the required client registration and authorisation schemas to an OpenDJ directory:

  1. Make sure the OpenDJ server is stopped. This can be done with the bin/status utility. To stop it run the bin/stop-ds script in the OpenDJ installation directory.

  2. Save the schema LDIF files to the config/schema directory, with a suitable prefix number to ensure they are loaded after all standard schema definitions, for example:

    • 90-oidc-client-schema-opendj.ldif

    • 91-oidc-authz-schema-opendj.ldif

  3. Start the OpenDJ server with bin/start-ds.

7.1.2 Add indices

Use the OpenDJ dsconfig utility to create indices for the authzSubject and the authzClientID attributes (assuming the admin connector is running on localhost at port 4444, and has the following admin credentials):

opendj/bin/dsconfig  create-local-db-index \
    --hostname localhost \
    --port 4444 \
    --trustAll \
    --bindDN "cn=Directory Manager" \
    --bindPassword secret \
    --backend-name userRoot \
    --index-name authzSubject \
    --set index-type:equality \
    --set index-entry-limit:1000000

opendj/bin/dsconfig  create-local-db-index \
    --hostname localhost \
    --port 4444 \
    --trustAll \
    --bindDN "cn=Directory Manager" \
    --bindPassword secret \
    --backend-name userRoot \
    --index-name authzClientID \
    --set index-type:equality \
    --set index-entry-limit:1000000

The dsconfig utility will present you with a prompt. Press f to confirm and finish:

        Property                        Value(s)
        -----------------------------------------------------------------------
    1)  attribute                       authzclientid
    2)  index-entry-limit               1000000
    3)  index-extensible-matching-rule  No extensible matching rules will be
                                        indexed.
    4)  index-type                      equality

    ?)  help
    f)  finish - create the new Local DB Index
    q)  quit

7.2 OpenLDAP setup

These setup instructions apply to OpenLDAP 2.4 and later. Its on-line configuration permits changes during runtime and uses standard LDAP client commands to make them.

7.2.1 Add required schemas

To import the required schema files from a command line on the OpenLDAP server host:

sudo ldapadd -Y EXTERNAL -H ldapi:/// -f oidc-client-schema-openldap.ldif
sudo ldapadd -Y EXTERNAL -H ldapi:/// -f oidc-authz-schema-openldap.ldif

Note that the OpenLDAP server must be online (running).

The ldapadd client utility can also be used to access a remote OpenLDAP server. For that you need to specify the host name / IP and a bind DN / password for the configuration super user (e.g. cn=admin,cn=config).

7.2.2 Add indices

OpenLDAP can serve data from multiple backends. To create an index for a particular backend you need to know its name (DN) in the cn=config tree. OpenLDAP is typically created with a single backend using an LMDB database which is given the name {1}mdb.

You can list the available backends with ldapsearch:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config '(olcDatabase=*)' dn

Create an LDIF text file add-index.ldif containing instructions to add equality (eq) indices for the specified attributes (assuming Connect2id data is stored in the {1}mdb backend):

dn: olcDatabase={1}mdb,cn=config
add: olcDbIndex
olcDbIndex: authzSubject eq
olcDbIndex: authzClientID eq

Apply the config changes to the OpenLDAP directory using the standard ldapmodify command:

sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f add-index.ldif

To verify that the indices have been created:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config '(olcDatabase={1}mdb)' olcDbIndex

The resulting listing of the indices for the backend should like this:

dn: olcDatabase={1}mdb,cn=config
olcDbIndex: objectClass eq
olcDbIndex: cn,uid eq
olcDbIndex: uidNumber,gidNumber eq
olcDbIndex: member,memberUid eq
olcDbIndex: authzSubject eq
olcDbIndex: authzClientID eq

7.2.3 Create user

LDAP connections from the Connect2id server can be made under a dedicated user account, to avoid using the privileged admin account. To do that create an LDIF file specifying the account DN and password.

Example LDIF for a dedicated LDAP directory account for the Connect2id server:

dn: uid=c2id,dc=wonderland,dc=net
objectClass: account
objectClass: top
objectClass: simpleSecurityObject
uid: c2id
userPassword: secret
description: Connect2id server account

Add the user entry with the ldapadd command (or your favourite LDAP browser):

sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f add-user.ldif

The password may set set or updated separately with the ldappasswd command, or again with your favourite LDAP browser.

7.2.4 Give user appropriate permissions

Connect to the configuration tree (with root cn=config) of the LDAP directory, and add 2 new access control list (ACL) attributes to the backend configuration (e.g. olcDatabase={1}mdb,cn=config, see above), in order to give tne newly created user manage access to the directory branches where the client and authorisation entries will be stored.

Example:

olcAccess: {0}to dn.subtree="ou=clients,dc=wonderland,dc=net" by dn.base="uid=c2id,dc=wonderland,dc=net" manage by * none
olcAccess: {1}to dn.subtree="ou=authorizations,dc=wonderland,dc=net" by dn.base="uid=c2id,dc=wonderland,dc=net" manage by * none

Make sure the new ACL attributes are prefixed with a number that puts them before any more general ACL rules. To do that you may have to increment the prefixes of existing LDAP ACL rules.

8. Questions?

Get in touch with Connect2id support. We'll be delighted to help!