Skip to content
Connect2id

Claims sources

The Connect2id server comes with connectors for retrieving OpenID Connect claims (attributes) for end-users from the following sources:

  • LDAP directory – All LDAP v3 compatible directories are supported, such as Microsoft Active Directory and OpenLDAP. Virtual directory servers which let relational and other database types to be accessed via LDAP are also supported.

  • HTTP endpoint – Enables retrieval of claims from arbitrary sources by exposing a simple web service to them.

The Connect2id server can retrieve claims from multiple sources if the claims reside in different databases.

To implement your own connector consult the claims sourcing guide.

1. LDAP claims source

Connector for sourcing OpenID Connect claims (attributes) from an LDAP v3 compatible directory. Implements the ClaimsSource SPI from the Connect2id server SDK.

To enable / disable and configure the LDAP claims source connector edit the following properties file in the WEB-INF directory of the web application:

WEB-INF/ldapClaimsSource.properties

The configuration properties are grouped into sections:

  1. General settings – to enable / disable the LDAP claims source, set an alternative LDAP attribute mapping.
  2. LDAP server connection details – LDAP server connection details.
  3. LDAP user credentials – LDAP server connection credentials.
  4. LDAP search configuration – LDAP search parameters, such as filter, for retrieving the user entries and attributes.
  5. Custom LDAP server trust and key store – custom certificate trust and / or key key for secure LDAP connections.

Any configuration file property can be overridden with a Java system property, e.g. by setting the optional -D argument at JVM startup:

-Dop.ldapClaimsSource.enable=false

The external configuration guide has tips for setting system properties from environment variables, local files and other locations.

To set the mapping of the LDAP attributes to OpenID Connect claims edit the following JSON file:

WEB-INF/ldapClaimsMap.json

The LDAP connector is open sourced (Apache 2.0 licensed):

https://bitbucket.org/connect2id/openid-connect-ldap-claims-source

1.1 General settings

For enabling / disabling the LDAP claims source and setting an alternative location for the LDAP attribute map.

op.ldapClaimsSource.enable

If true the LDAP claims source is enabled. If the property isn’t specified or set to false the LDAP claims source is disabled.

To enable the LDAP claims source:

op.ldapClaimsSource.enable=true

op.ldapClaimsSource.attributeMap

Optional property for passing the LDAP attribute map by value or from an alternative resource location:

  • Set the property value to the JSON object representation of the LDAP attribute map. The JSON string can be additionally BASE-64 encoded to ease passing the value as a Java system property (the claims source will automatically detect that and decode it back to a JSON string).

  • Set the property value to a file location relative to the web application root.

If the property isn’t set the LDAP claims source will load the attribute map from the default /WEB-INF/ldapClaimsMap.json location.

Passing the LDAP attribute map inline, the JSON string is BASE-64 encoded to avoid dealing with escaping issues on the command line:

op.ldapClaimsSource.attributeMap=ewogICJzdWIiICAgICAgICAgICAgOiB7ICJsZGFwQXR0ciIgOiAi...

1.2 LDAP server details

The op.ldapClaimsSource.server.* properties set the LDAP server connection details.

op.ldapClaimsSource.server.url

The LDAP URL of the directory server for sourcing the claims. The schema must be ldap or ldaps, it must specify a valid host name or IP address as well as the port number if a non-default is used.

If the directory is replicated across several LDAP servers for the purpose of failover or load-balancing, the value is a space-separated list of the corresponding LDAP URLs. Server selection is handled according to op.ldapClaimsSource.ldapServer.selectionAlgorithm.

Example single LDAP server URL pointing to the local host:

op.ldapClaimsSource.server.url=ldap://localhost:1389

Example list of two LDAP server URLs (for use in a failover or load-balancing configuration):

op.ldapClaimsSource.server.url=ldap://192.168.1.10:1389 ldap://192.168.1.11:1389

op.ldapClaimsSource.server.selectionAlgorithm

The preferred server selection algorithm in case op.ldapClaimsSource.server. url is an LDAP server set:

  • FAILOVER – Establish connections to the LDAP servers in the order they are provided. If the first server is unavailable, then it will attempt to connect to the second, then to the third and so on.

  • ROUND-ROBIN – Use a round-robin algorithm to select the LDAP server to which the connection should be established. Any number of servers may be included in the set and each request will attempt to retrieve a connection to the next server in the list, circling back to the beginning of the list as necessary. If a server is unavailable when an attempt is made to establish a connection to it, then the connection will be established to the next available server in the list.

To specify failover server selection:

op.ldapClaimsSource.server.selectionAlgorithm=FAILOVER

op.ldapClaimsSource.server.connectTimeout

The timeout in milliseconds for LDAP connect requests. If zero the underlying LDAP client library will handle this value.

To specify a connect timeout of 250 ms:

op.ldapClaimsSource.server.connectTimeout=250

op.ldapClaimsSource.server.security

The LDAP connection security:

  • NONE – Establish a plain insecure connection.

  • SSL – Establish a secure connection over SSL.

  • StartTLS – Establish a secure connection using the StartTLS protocol (recommended method).

To use StartTLS for LDAP connections:

op.ldapClaimsSource.server.security=StartTLS

op.ldapClaimsSource.server.trustSelfSignedCerts

Determines whether to accept self-signed certificates presented by the LDAP server (for secure SSL or StartTLS connections). Self-signed certificates are not trusted by default.

To reject self-signed certificates:

op.ldapClaimsSource.server.trustSelfSignedCerts=false

op.ldapClaimsSource.server.connectionPoolSize

The maximum LDAP connection pool size. The default value is five connections.

To create a pool for 5 LDAP connections:

op.ldapClaimsSource.server.connectionPoolSize=5

op.ldapClaimsSource.server.connectionPoolInitialSize

The initial LDAP connection pool size. The acceptable range is between zero and the maximum LDAP connection pool size (inclusive).

Set it to zero to enable startup of the Connect2id server without the backend LDAP directory being available.

op.ldapClaimsSource.server.connectionPoolInitialSize=5

op.ldapClaimsSource.server.connectionPoolMaxWaitTime

The maximum length of time in milliseconds to wait for a connection to become available when trying to obtain an LDAP connection from the pool. A value of zero should be used to indicate that the pool should not block at all if no connections are available and that it should either create a new connection or throw an exception.

To set the max LDAP connection pool wait time to 250ms:

op.ldapClaimsSource.server.connectionPoolMaxWaitTime=250

op.ldapClaimsSource.server.connectionMaxAge

The maximum time in milliseconds that an LDAP connection in the pool may be established before it should be closed and replaced with another connection. A value of zero indicates that no maximum age should be enforced. Defaults to no maximum age (zero).

To disable LDAP connection expiration:

op.ldapClaimsSource.server.connectionMaxAge=0

1.3 LDAP user details

The op.ldapClaimsSource.directory.user.* set the LDAP server connection credentials.

op.ldapClaimsSource.directory.user.dn

The distinguished name (DN) of the LDAP directory user to perform the claims retrieval operations. Must have search and read access to the directory branch containing the subject entries. An empty value implies an anonymous user.

Example user DN:

op.ldapClaimsSource.directory.user.dn=cn=Directory Manager

op.ldapClaimsSource.directory.user.password

The directory user password. An empty value implies an anonymous user.

Example password:

op.ldapClaimsSource.directory.user.password=secret

The op.ldapClaimsSource.directory.* properties set the LDAP search parameters, such as filter, for retrieving the user entries and attributes.

op.ldapClaimsSource.directory.baseDN

The base distinguished name (DN) of the LDAP directory branch where the subject (user) entries are stored.

op.ldapClaimsSource.directory.baseDN=ou=people,dc=wonderland,dc=net

op.ldapClaimsSource.directory.scope

The LDAP search scope for the subject entries with respect to the base DN specified in op.ldapClaimsSource.directory.baseDN:

  • ONE – indicates that only entries that are immediate subordinates of the base entry (but not the base entry itself) should be considered.

  • SUB – Indicates that the base entry itself and any subordinate entries (to any depth) should be considered.

  • SUBORDINATE_SUBTREE – Indicates that any subordinate entries (to any depth) below the base entry should be considered, but the base entry itself should not be considered, as described in draft-sermersheim-ldap-subordinate-scope.

op.ldapClaimsSource.directory.scope=ONE

op.ldapClaimsSource.directory.filter

The LDAP search filter to retrieve the subject entries. The %u placeholder will be substituted with the subject identifier (sub).

op.ldapClaimsSource.directory.filter=(uid=%u)

1.5 Custom LDAP server trust and key store

The op.ldapClaimsSource.customTrustStore.* and op.ldapClaimsSource.customKeyStore.* properties specify custom trust and key stores (apart from those provided by the underlying JVM) to establish the security context of TLS/SSL connections to the LDAP servers.

op.ldapClaimsSource.customTrustStore.enable

Set to true to use your custom trust store file for determining the acceptable security certificates presented by the remote LDAP server.

Set to false to use the default trust store of the web server / host system (if one has been provided and correctly configured).

If you set this to true you must also specify a trust store file, type and password (see the corresponding parameters below).

op.ldapClaimsSource.customTrustStore.enable=false

op.ldapClaimsSource.customTrustStore.file

The location of the custom trust store file.

Example:

op.ldapClaimsSource.customTrustStore.file=WEB-INF/truststore.jks

op.ldapClaimsSource.customTrustStore.password

The password required to unlock the trust store file. Leave it empty if none is required.

Example:

op.ldapClaimsSource.customTrustStore.password=secret

op.ldapClaimsSource.customTrustStore.type

The type of the trust store file, typically JKS or PKCS12. Leave it empty to assume the system default type.

Example:

op.ldapClaimsSource.customTrustStore.type=JKS

op.ldapClaimsSource.customKeyStore.enable

Set to true to use your custom key store file for client security certificates to be presented to the remote LDAP server requiring such authentication.

Set to false to use the default key store of the web server / host system (if one has been provided and correctly configured).

If you set this to true you must also specify a key store file, type and password (see the corresponding parameters below).

op.ldapClaimsSource.customKeyStore.enable=false

The location of the custom key store file.

Example:

op.ldapClaimsSource.customKeyStore.file=WEB-INF/keystore.jks

op.ldapClaimsSource.customKeyStore.password

The password required to unlock the key store file. Leave it empty if none is required.

Example:

op.ldapClaimsSource.customKeyStore.password=

op.ldapClaimsSource.customKeyStore.type

The type of the trust store file, typically JKS or PKCS12. Leave it empty to assume the system default type.

Example:

op.ldapClaimsSource.customKeyStore.type=JKS

2. HTTP claims source

Connector for sourcing OpenID Connect claims (attributes) from an HTTP endpoint. Implements the AdvancedClaimsSource SPI from the Connect2id server SDK.

  • Supports retrieval of arbitrary OpenID Connect claim types.

  • Supports multiple scripts and languages via language tags.

  • Access to the HTTP endpoint requires a non-expiring bearer token.

  • Utilises an HTTP POST request for obtaining the claims in order to prevent leaking of the request parameters (subject identifier and claim names) into HTTP server logs.

2.1 Configuration

The HTTP claims source is configured from Java system properties or from a properties file /WEB-INF/httpClaimsSource.properties. The Java system properties have precedence. If no configuration properties are found the HTTP claims source is disabled.

The external configuration guide has tips for setting system properties from environment variables, local files and other locations.

Example configuration properties:

op.httpClaimsSource.enable=true
op.httpClaimsSource.supportedClaims=email,email_verified,name,given_name,family_name
op.httpClaimsSource.url=https://example.com/claims-source
op.httpClaimsSource.connectTimeout=500
op.httpClaimsSource.readTimeout=500
op.httpClaimsSource.trustSelfSignedCerts=false
op.httpClaimsSource.apiAccessToken=ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

op.httpClaimsSource.enable

Enables / disables the HTTP claims source. Disabled by default.

To enable the HTTP claims source:

op.httpClaimsSource.enable=true

op.httpClaimsSource.supportedClaims

The names of the supported (standard and custom) OpenID Connect claims, as a comma and / or space separated list. A wildcard character (*) can be used to specify a name pattern, e.g. id4me.*.

Example:

op.httpClaimsSource.supportedClaims=email,email_verified,name,given_name,family_name

op.httpClaimsSource.url

The URL of the HTTP endpoint for sourcing the OpenID Connect claims. Should be HTTPS.

Example URL:

https://example.com/claims-source

op.httpClaimsSource.connectTimeout

The timeout in milliseconds for establishing HTTP connections. If zero the underlying HTTP client library will determine the timeout.

To set a connect timeout of 500 ms:

op.httpClaimsSource.connectTimeout=500

op.httpClaimsSource.readTimeout

The timeout in milliseconds for obtaining HTTP responses after connection. If zero the underlying HTTP client library will determine the timeout.

To set a read timeout of 500 ms:

op.httpClaimsSource.readTimeout=500

op.httpClaimsSource.trustSelfSignedCerts

Determines whether to accept self-signed X.509 / TLS certificates presented by the HTTP server. Self-signed certificates are not trusted by default.

To trust self-signed certificates:

op.httpClaimsSource.trustSelfSignedCerts=true

op.httpClaimsSource.apiAccessToken

Access token of type bearer (non-expiring) for accessing the HTTP endpoint. Should contain at least 32 random alphanumeric characters to make brute force guessing impractical.

Example token for the endpoint:

op.httpClaimsSource.apiAccessToken=ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

2.2 Web API

2.2.1 Claims request

The claims request is authorised with a Bearer token and POSTed as a JSON object with members:

  • iss {string} – The OpenID provider issuer URL.
  • sub {string} – The subject (end-user) for which OpenID claims are requested.
  • claims {string array} – The names of the requested OpenID claims, with optional language tags.
  • claims_data {object} – Optional data to aid the claims provision, omitted if none (maps from ClaimsSourceRequestContext.getClaimsData).

Example claims request to the HTTP endpoint:

POST /claims-source HTTP/1.1
Host: www.example.com
Content-Type: application/json; charset=UTF-8
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "iss"    : "https://c2id.com",
  "sub"    : "alice",
  "claims" : [ "email", "email_verified", "name", "given_name", "family_name" ]
}

2.2.2 Claims response

The claims must be returned in UserInfo response format, specifying the subject (“sub”) and all requested claims that can be fulfilled. If a particular claim is not available it is simply omitted from the response.

Example response:

HTTP/1.1 200 OK
Date: Mon, 23 May 2016 22:38:34 GMT
Content-Type: application/json; charset=UTF-8

{
  "sub"            : "alice",
  "email"          : "alice@wonderland.net",
  "email_verified" : true,
  "name"           : "Alice Adams",
  "given_name"     : "Alice",
  "family_name"    : "Adams"
}

If the subject is not found or invalid (e.g. end-user account deleted) the response must be an empty JSON object.

HTTP/1.1 200 OK
Date: Mon, 23 May 2016 22:38:34 GMT
Content-Type: application/json; charset=UTF-8

{}