How to setup an LDAP directory for Connect2id server use

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

1. The details of the registered OAuth 2.0 / OpenID Connect clients.

2. The long-lived end-user / client authorisations (or consent).

The server has been successfully tested with OpenDJ, OpenLDAP and the 389 Directory Server. Other LDAP directories, such as MS Active Directory and Oracle Internet Directory, should also work.

1. What does the setup involve?

Setting up an LDAP directory for Connect2id server use is a three step task.

1.1 Step one: Schemas

Supply the LDAP directory with the required schemas to store the client registration and the 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.

1.2 Step two: Directory branches

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

For example:

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

1.3 LDAP user

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

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

Avoid giving the LDAP user more permissions than necessary.

2. Recommendations

1. While it's possible to use an LDAP directory that is already shared with other applications, we recommend that you provision a separate LDAP directory for your Connect2id server. That way the applications would not affect the performance of one another under load or other critical circumstances.

2. 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) for a relatively long period of time with the backend LDAP directory being unavailable.

3. 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 is using the Connect2id server. If the registration data is lost each client application will have to be registered again. Loss of the persisted authorisations (consent) is relatively harmless and will simply result in end-users having to re-authorise their apps.

4. 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 [1] [2]).

3. Estimating the required LDAP storage

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

3.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
• Max storage: 10 GB

4. 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).

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

• For the client registrations: op.reg.ldapServer.url
• For the authorisations: authzStore.ldapServer.url

If you have an LDAP directory cluster setup of for round-robin or fail-over:

• For the client registrations: op.reg.ldapServer.selectionAlgorithm
• For the authorisations: authzStore.ldapServer.selectionAlgorithm

Provide a sensible LDAP connect timeout, in milliseconds:

• For the client registrations: op.reg.ldapServer.connectTimeout
• For the authorisations: authzStore.ldapServer.connectTimeout

Specify whether you're using SSL or StartTLS security:

• For the client registrations: op.reg.ldapServer.security
• For the authorisations: authzStore.ldapServer.security

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

• For the client registrations: op.reg.ldapServer.trustSelfSignedCerts
• For the authorisations: authzStore.ldapServer.trustSelfSignedCerts

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

• For the client registrations: op.reg.ldapServer.connectionPoolSize
• For the authorisations: authzStore.ldapServer.connectionPoolSize

The LDAP user credentials:

• For the client registrations: op.reg.ldapUser.dn and op.reg.ldapUser.password
• For the authorisations: authzStore.ldapUser.dn and authzStore.ldapUser.password

The directory branches:

• For the client registrations: op.reg.ldapDirectory.baseDN
• For the authorisations: authzStore.ldapDirectory.baseDN

5. Browsing the LDAP directory

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

One such excellent GUI browser is Apache Directory Studio.

Remember that the client registration and the authorisation entries should not be edited directly via LDAP. The Connect2id server employees aggressive caching and your changes may therefore not be seen or may be overwritten. You also run the risk of corrupting the data. Use the safer and dedicated Connect2id server web APIs instead.

6. Directory specific setup

6.1 OpenDJ setup

These setup instructions apply to OpenDJ 2.4 and later.

6.1.1 Schema installation

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.

6.2 OpenLDAP setup

These setup instructions apply to OpenLDAP 2.4 and later.

6.2.1 Schema installation

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 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. Questions?

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