JsonSSO :: Configuration

JsonSSO allows for comprehensive configuration through a set of parameters in the WEB-INF/web.xml descriptor file. You may edit the original configuration to change the default web service behaviour. Remember to restart your web server when you're done for the modified configuration to take effect.

User identifier »	Client interface »
The name of the LDAP attribute used to uniquely identify users system / organisation-wide. `jsonsso.uidAttribute`	Parameters for managing web client access: connection security, client certificates, LDAP connection provision. `jsonsso.clients.requireSecureAccess` `jsonsso.clients.requireCertificate` `jsonsso.clients.provideJson2LdapCID` `jsonsso.clients.responseContentType`
Session settings »	Logout callbacks »
For managing session quotas, login policy, max duration and idle time. `jsonsso.session.maxTime` `jsonsso.session.maxIdleTime` `jsonsso.session.quotaPerUser` `jsonsso.session.onQuotaExhaustion`	Enables web clients to be notified when a user logs out or their session expires. `jsonsso.logoutCallbacks.allow` `jsonsso.logoutCallbacks.quotaPerSession` `jsonsso.logoutCallbacks.maxMessageSize` `jsonsso.logoutCallbacks.numWorkerThreads`
Json2Ldap details »	LDAP server details »
The connection details of the Json2Ldap service which handles LDAP requests over the web. `jsonsso.json2ldap.url` `jsonsso.json2ldap.trustSelfSignedCerts`	The connection details of the LDAP directory which stores the user identities. `jsonsso.ldapServer.useDefault` `jsonsso.ldapServer.url` `jsonsso.ldapServer.timeout` `jsonsso.ldapServer.security` `jsonsso.ldapServer.trustSelfSignedCerts`
Administrator details »	User DN resolution »
Specifies administrators of the JsonSSO service. `jsonsso.admin.attributeName` `jsonsso.admin.attributeValue`	Settings for resolving user DNs from the username, email or other unique attribute supplied at login. `jsonsso.dnResolution.method` `jsonsso.dnResolution.dnTemplate` `jsonsso.dnResolution.searchBaseDN` `jsonsso.dnResolution.searchScope` `jsonsso.dnResolution.searchFilter`
Search user details »
Specifies a search user account. `jsonsso.searchUser.dn` `jsonsso.searchUser.password`
Logging »	Cross-Origin Resource Sharing (CORS) »
Log4j configuration file location. `jsonsso.log4j.configurationFile`	Configures browser cross-domain (CORS) request handling. `cors.allowGenericHttpRequests` `cors.allowOrigin` `cors.supportedMethods` `cors.supportedHeaders` `cors.exposedHeaders` `cors.supportsCredentials` `cors.maxAge`

1. User identifier

A key parameter to every SSO and session service is the attribute used to identify across the participating applications. This can be a unique serial integer, a username issued by a central authority or the user's email address.

jsonsso.uidAttribute

The name of the LDAP attribute that identifies users system / organisation-wide. This attribute must be present in the directory entry of each user who is expected to log in. The corresponding value will be returned by the jsonsso.login, jsonsso.getSession and jsonsso.getUserID JSON-RPC 2.0 calls.

Directories typically use the "uid" or "userid" attribute (OID 0.9.2342.19200300.100.1.1) for this purpose. Web applications may identify users by their "mail" attribute (OID 0.9.2342.19200300.100.1.3).

uid

2. Client interface

The jsonsso.clients.* parameters manage the access of web clients to the JsonSSO service.

jsonsso.clients.requireSecureAccess

If true clients are required to connect securely via HTTPS to the JsonSSO service; requests received via plain HTTP will be refused.

To prevent eavesdropping on sensitive data such as passwords and session keys (SIDs) it is highly recommended to make HTTPS access mandatory.

jsonsso.clients.requireCertificate

If true clients are required to present a valid and trusted X.509 certificate with each JSON-RPC 2.0 request. This option allows for a secondary authentication mechanism (for the web client software or for the user).

jsonsso.clients.provideJson2LdapCID

If true logged-in users are provided with an open LDAP connection to the directory that is bound as their distinguished name (DN). The LDAP connection is represented by a Json2Ldap connection identifier (CID).

jsonsso.clients.responseContentType

The value of the HTTP "Content-Type" header for the JSON-RPC 2.0 responses.

Typically set to "application/json" or to "text/plain" to support browser CORS requests.

application/json

3. Session settings

The jsonsso.session.* set of parameters manage the JsonSSO user session policy.

jsonsso.session.maxTime

The maximum allowable session duration in minutes.

Default value: 1440 (24 hours)

jsonsso.session.maxIdleTime

The maximum allowable session idle time in minutes.

Default value: 15

jsonsso.session.quotaPerUser

The maximum number of concurrent sessions a user may have.

Default value: 3

jsonsso.session.onQuotaExhaustion

The login behaviour when the user exausts their session quota.

Accepted values:

DENY_LOGIN The login request will be rejected.
CLOSE_OLD_SESSION The next expiring session for the same user will be closed and the new login request will be allowed to succeed.

Default value: CLOSE_OLD_SESSION

4. Logout callbacks

The jsonsso.logoutCallbacks.* parameters control the subscription and handling of logout notifications for interested web clients.

jsonsso.logoutCallbacks.allow

If true clients may register logout callbacks with the JsonSSO service. The callback messages can be dispatched over HTTP GET or POST.

jsonsso.logoutCallbacks.quotaPerSession

The maximum number of logout callbacks a session may have. Once the quota is reached no additional callbacks may be registered.

jsonsso.logoutCallbacks.maxMessageSize

The maximum size of logout callback POST messages. Callbacks with a message body above this limit will be rejected.

jsonsso.logoutCallbacks.numWorkerThreads

The number of worker threads for processing logout callbacks.

5. Json2Ldap details

The jsonsso.json2ldap.* parameters specify the HTTP connection details for the Json2Ldap web service which handles LDAP requests over the web.

jsonsso.json2ldap.url

The HTTP(S) URL of the Json2Ldap web service.

https://my-web-services.net/json2ldap/

jsonsso.json2ldap.trustSelfSignedCerts

Determines whether to accept self-signed X.509 certificates presented by the Json2Ldap service (applies to HTTPS connections).

6. LDAP server details

The jsonsso.ldapServer.* parameters specify the details for establishing LDAP connections to the directory server.

jsonsso.ldapServer.useDefault

Determines whether to use the default LDAP server specified by the Json2Ldap web service.

If false the LDAP server details must be specified explicitly below (see the following jsonsso.ldapServer.* properties).

jsonsso.ldapServer.url

Specifies a directory server if a non-default is used. See jsonsso.ldapServer.useDefault.

The value must be an LDAP URL specifying the server hostname/IP address and port number. Valid ports are integers from 1 to 65535, if omitted a default value is taken, typically port 389 for plain and TLS connections or port 636 for SSL connections.

Example:

ldap://ds.mydomain.com:10389

jsonsso.ldapServer.timeout

The timeout in milliseconds for LDAP connect requests. If zero the Json2Ldap web service will handle this value.

This configuration parameter applies only if a non-default directory server is used, see jsonsso.ldapServer.useDefault.

jsonsso.ldapServer.security

The LDAP connection security (NONE, STARTTLS or SSL).

This configuration parameter applies only if a non-default directory server is used, see jsonsso.ldapServer.useDefault.

jsonsso.ldapServer.trustSelfSignedCerts

Determines whether Json2Ldap should accept self-signed certificates presented by the LDAP server (for secure SSL or StartTLS LDAP connections.

This configuration parameter applies only if a non-default directory server is used, see jsonsso.ldapServer.useDefault.

7. Administrator details

The jsonsso.admin.* parameters specify one or more administrators of the JsonSSO web service. Administrators may make JSON-RPC requests such as sso.forceLogout.

jsonsso.admin.attributeName

The directory attribute name used to specify JsonSSO users with access to the administative JSON-RPC 2.0 interface. If set to DN the distinguished name (DN) will be used instead. If left empty the JsonSSO admin interface will be disabled.

The corresponding attribute value is specified by jsonsso.admin.attributeValue.

Examples:

Set to uid to specify a single administator.
Set to memberOf to specify multiple administrators using group membership (OID 2.5.4.31).

jsonsso.admin.attributeValue

The admin user attribute value (see jsonsso.admin.attributeName). Ignored if the attribute name is empty.

Example of a group DN:

cn=admins,ou=groups,dc=wonderland,dc=net

8. Search user details

The jsonsso.searchUser.* parameters specify the search user details. These are required only if the DN resolution method is set to SEARCH.

jsonsso.searchUser.dn

The search user DN. If empty the user is assumed to be anonymous.

jsonsso.searchUser.password

The search user password. If empty signifies an anonymous user.

9. User DN resolution

The jsonsso.dnResolution.* parameters specify the procedure for resolving a user's distinguished name (DN) from the username / email supplied with the sso.login request.

jsonsso.dnResolution.method

The preferred user DN resolution method.

Set to TEMPLATE to resolve the DN by substituting the supplied username in a DN template. You then must also set a DN template. This is the most flexible method for DN resolution.
Set to SEARCH to resolve the DN by performing a search operation against the LDAP directory for the supplied username / email. You then must also set a search base DN, a search scope and a search filter. This is the most efficient method (the LDAP directory is not queried).
Set to NONE to authenticate users directly by making a plain SASL bind with username (RFC 4616) request to the LDAP directory. The directory must also support the Authorisation Identity (AuthzId) control (RFC 3829).

jsonsso.dnResolution.dnTemplate

The DN template (if jsonsso.dnResolution.method is set to TEMPLATE, otherwise ignored). Each occurence of %u is substituted by the trimmed input username. The resulting string represents the user's directory DN.

Example:

uid=%u,ou=people,dc=wonderland,dc=net

jsonsso.dnResolution.searchBaseDN

The search base DN (if jsonsso.dnResolution.method is set to SEARCH, otherwise ignored).

Example:

ou=people,dc=wonderland,dc=net

jsonsso.dnResolution.searchScope

The search scope (if jsonsso.dnResolution.method is set to SEARCH, otherwise ignored).

Set to ONE to indicate that only entries that are immediate subordinates of jsonsso.dnResolution.searchBaseDN (but not the base entry itself) should be considered.
Set to SUBTREE to indicate that any subordinate entries (to any depth) below the entry specified by jsonsso.dnResolution.searchBaseDN should be considered.

The search filter string (if jsonsso.dnResolution.method is set to SEARCH, otherwise ignored). Each occurence of %u is substituted by the trimmed input username. The resulting string represents the user search filter.

Example:

(|(uid=%u)(mail=%u))

10. Logging

JsonSSO uses the popular Log4j framework to handle logging. The WEB-INF/web.xml file contains just a single context parameter related to logging - it points to the location of the Log4j properties file where the actual behaviour of the logging subsystem is configured.

jsonsso.log4j.configurationFile

The location of the Log4j properties file, as an absolute path or relative to the web application home directory.

If no file location is specified logging is disabled.

The default Log4j properties file is WEB-INF/log4j.properties.

11. Cross-Origin Resource Sharing (CORS)

The JsonSSO web service includes a CORS Filter to allow transparent handling of browser cross-site requests according to the W3C Cross-Origin Resource Sharing (CORS) mechanism. To configure the CORS policy edit the init-params of the CORS filter entry in the WEB-INF/web.xml descriptor.

cors.allowGenericHttpRequests

Set to true to allow generic HTTP requests, else only valid and accepted CORS requests will be allowed (strict CORS filtering).

Recommended value: true

cors.allowOrigin

Lists the allowed CORS origins. They must be specified as whitespace-separated URLs. Requests from origins not included here will be refused with an HTTP 403 "Forbidden" response. If set to * all origins will be allowed.

cors.supportedMethods

Lists the supported HTTP methods. Requests for methods not included here will be refused by the CORS filter with an HTTP 405 "Method not allowed" response.

JsonSSO supports HTTP GET and POST only. Do not change this parameter.

cors.supportedHeaders

Lists the supported non-simple (according to the CORS standard) header names.

Applications that wish to specify an application/json request content type should be allowed so.

Recommended value: Content-Type

cors.exposedHeaders

Lists the non-simple headers (according to the CORS standard) that the web client (browser) should expose.

JsonSSO sets a custom X-Web-Service header to identify itself. Do not change this parameter.

cors.supportsCredentials

Indicates whether user credentials, such as cookies, HTTP authentication or client-side certificates, are supported.

JsonSSO may optionally be configured to require a client-side certificate.

cors.maxAge

Indicates how long the results of a CORS preflight request can be cached by the web client, in seconds. If -1 unspecified.

Recommended value: 1 day (86400 seconds).