How to setup an LDAP directory for Connect2id server use
The details of the registered OAuth 2.0 / OpenID Connect clients.
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:
- Long-lived authorisation schema:
[server] denotes the particular LDAP server implementation that you
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 the client registrations:
- For the authorisations:
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.
Avoid giving the LDAP user more permissions than necessary.
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.
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.
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.
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  ).
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
- 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
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:
Make sure the OpenDJ server is stopped. This can be done with the
bin/statusutility. To stop it run the
bin/stop-dsscript in the OpenDJ installation directory.
Save the schema LDIF files to the
config/schemadirectory, with a suitable prefix number to ensure they are loaded after all standard schema definitions, for example:
Start the OpenDJ server with
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).
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.
Get in touch with Connect2id support. We'll be glad to help!