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 to enable LDAP access to relational and other database types are also supported.

• HTTP endpoint – Enables retrieval of claims from arbitrary sources by setting up a simple web service for them.

• Subject session – Retrieves claims from the session of the end-user. Suitable for lightweight Connect2id server deployments.

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.

The connector source code is open (Apache 2.0 licensed):

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

1.1 Configuration

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

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

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.

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

/WEB-INF/ldapClaimsMap.json

1.1.1 General settings

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

op.ldapClaimsSource.enable

Enables / disables the claims source. Disabled by default.

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

1.1.4 LDAP search configuration

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

The connector source code is open (Apache 2.0 licensed):

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

2.1 Configuration

The 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 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=1000
op.httpClaimsSource.readTimeout=1000
op.httpClaimsSource.apiAccessToken=ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

op.httpClaimsSource.enable

Enables / disables the 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.

Support for a pattern of claims can be indicated with the * wildcard character, for example as https://idp.example.com/* for a set of claims having a common URI prefix in their name. A single claim set to * indicates support for all claims supported by the OpenID provider without explicitly listing them.

Example:

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

Example for a source that will handle all claims supported by the OpenID provider without explicitly listing them:

op.httpClaimsSource.supportedClaims=*

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

op.httpClaimsSource.includeSubjectSessionID

Enables / disables inclusion in the request of the subject (end-user) session ID where the claims sourcing was authorised. Disabled by default. Since v15.2.

To enable inclusion of subject session IDs:

op.httpClaimsSource.includeSubjectSessionID=true

op.httpClaimsSource.includeSubjectSession

Enables / disables inclusion in the request of the subject (end-user) session where the claims sourcing was authorised. Disabled by default. Since v15.2.

To enable inclusion of subject session objects:

op.httpClaimsSource.includeSubjectSession=true

op.httpClaimsSource.includeScope

Enables / disables inclusion in the request of the associated consented scope. Disabled by default. Since v15.5.

To enable inclusion of subject session objects:

op.httpClaimsSource.includeSubjectSession=true

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).
• [ claims_transport ] {string} – Hints how the requested claims are going to be transported to the relying party: “userinfo” for the UserInfo endpoint, “id_token” for the ID token, omitted if not applicable (for claims requested by an internal plugin, such as an access token codec).
• [ sub_sid ] {string} – Optional subject (end-user) session ID. Included when the op.httpClaimsSource.includeSubjectSessionID configuration property is enabled and the subject session where the claims sourcing was authorised is still active (not closed or expired). Since v15.2.
• [ sub_session ] {object} – Optional subject (end-user) session details. The JSON object structure is identical to the subject session object of the Connect2id server subject session store web API. Included when the op.httpClaimsSource.includeSubjectSession configuration property is enabled and the subject session where the claims sourcing was authorised is still active (not closed or expired). Since v15.2.
• [ scope ] {string array} – Optional associated consented scope. Included when the op.httpClaimsSource.includeScope configuration property is enabled and the scope is available. Since v15.5.

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" ],
  "claims_transport" : "userinfo"
}

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. due to a deleted end-user account) 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

{}

3. Subject session claims source

Connector for sourcing OpenID Connect claims (attributes) from the subject session of a logged-in end-user. Implements the AdvancedClaimsSource SPI from the Connect2id server SDK. Available since v16.0.

• Supports retrieval of arbitrary OpenID Connect claims, which can be conveniently stored in the subject session when the end-user is authenticated with the Connect2id server.

• Supports multiple scripts and languages via language tags.

• If the subject’s session was closed or expired the source returns no claims.

The connector source code is open (Apache 2.0 licensed):

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

3.1 Configuration

The claims source is configured from Java system properties or from a properties file /WEB-INF/sessionClaimsSource.properties. The Java system properties have precedence. If no configuration properties are found the 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.sessionClaimsSource.enable=true
op.sessionClaimsSource.supportedClaims=email,email_verified,name,given_name,family_name

Important: The default op.idToken.includeSubjectSessionClaims configuration is at cross-purposes with this plugin. It must therefore be disabled, or, if the automatic inclusion of certain claims from the subject session into the issued ID tokens is still desired, specify their exact names.

To disable the automatic inclusion of all session claims in issued ID tokens set it to an empty value:

op.idToken.includeSubjectSessionClaims=

To specify an explicit set of names of claims to always include in the ID tokens, making the rest available for release by the session claims source, subject to explicit end-user consent:

# Session claims to automatically include in ID tokens
op.idToken.includeSubjectSessionClaims=email,email_verified
# Session claims made available to the claims source
op.sessionClaimsSource.supportedClaims=name,given_name,family_name

op.sessionClaimsSource.enable

Enables / disables the claims source. Disabled by default.

To enable the session claims source:

op.sessionClaimsSource.enable=true

op.sessionClaimsSource.supportedClaims

The names of the supported (standard and custom) OpenID Connect claims, as a comma and / or space separated list.

Support for a pattern of claims can be indicated with the * wildcard character, for example as https://idp.example.com/* for a set of claims having a common URI prefix in their name. A single claim set to * indicates support for all claims supported by the OpenID provider without explicitly listing them.

Example:

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

Example for a source that will handle all claims supported by the OpenID provider without explicitly listing them:

op.sessionClaimsSource.supportedClaims=*

3.2 Usage

The claims field of a subject session can be conveniently populated with attributes at the time of its creation, which occurs when the end-user is authenticated with the Connect2id server.

Example session with saved email and email_verified claims:

{
  "sub"           : "alice",
  "ctx"           : "web",
  "auth_time"     : 1727774063,
  "creation_time" : 1727774063,
  "max_life"      : 20160,
  "auth_life"     : 1440,
  "max_idle"      : 15,
  "rps"           : [ "eedi8jah", "ahp9xei5", "ioj6agah" ],
  "claims"        : { "email"          : "alice@example.com",
                      "email_verified" : true }
}

For a closed or expired subject session the source returns no claims.

This makes the claims source suitable for client applications that require UserInfo endpoint access only when the end-user is logged in with the OpenID provider. ID tokens are always issued in the presence of a subject session, thus any ID token bound sourcing of claims by this plugin is guaranteed.