How to integrate an OpenID Connect claims source

1. OpenID Connect claims

With OpenID Connect client applications can retrieve consented claims, or assertions, about the logged in end-user. These are encoded in a JSON object, and made available by the OpenID Connect provider (the Connect2id server) at the UserInfo endpoint or included in the ID token:

  "sub"        : "83692",
  "name"       : "Alice Adams",
  "email"      : "[email protected]",
  "department" : "Engineering",
  "birthdate"  : "1975-12-31"

2. The claims source SPI

An enterprise IdP should be able to pull claims from any type of data source. Connect2id has devised a claims source interface to enable claims aggregation from various sources, such as an Active Directory / LDAP server, an SQL database or an HR management system.

The Connect2id server is shipped with a ready Active Directory / LDAP connector. You can read more about it in the configuration docs.

3. How to develop your own claims source connector

For other types of data sources a custom connector will be required.

  1. Get the Connect2id server toolkit. The read-me provides info about the Maven artifact if you want to use that build system.

  2. Implement the ClaimsSource interface.

  3. Package your classes in a SPI jar with a suitable manifest.

  4. Put the jar in the WEB-INF/lib directory of the Connect2id server.

  5. Restart the Connect2id server.

  6. The Connect2id server will automatically load the new claims source, and add it to the existing ones (if any).

The source code for the LDAP connector is freely available, you can use it as an example when developing your own connectors.

4. How to aggregate claims from multiple sources

The Connect2id server can collect claims from multiple source, e.g. certain claims may come from an LDAP directory and others from an SQL database. To do that you just need to provide the additional ClaimsSource connectors.

5. How to disable the LDAP connector

There are to possible ways to do that.

By removing the LDAP connector:

  1. Stop the Connect2id server.

  2. Remove oidc-claims-source-ldap-[version].jar from the WEB-INF/lib/ directory.

  3. Start the Connect2id server.

By disabling the LDAP connector from its settings:

  1. Open WEB-INF/

  2. Set op.ldapClaimsSource.enable = false

  3. Restart the Connect2id server.

  4. The Connect2id server will still load the LDAP claims source, but it will not be used.

See the LDAP connector config docs for for more details.