AuthService :: Specification

JSON web service for authenticating and provisioning users

NimbusDS AuthService is a lightweight JSON-RPC 2.0 web service for authenticating and provisioning users from an LDAP v3 compatible directory.

LDAP compatibility

AuthService is compatible with directories supporting the current version 3 of the Lightweight Directory Access Protocol (LDAP).

Popular proprietary directory servers:

Active Directory from Microsoft
eDirectory from Novell
Tivoli Directory Server from IBM

Popular open source directory servers:

OpenLDAP, the first influential open source implementation
OpenDJ, originally from Sun and written in Java
389 Directory Server, a RedHat/Fedora project

Web API

NimbusDS AuthService handles JSON remote procedure call (RPC) requests for user authentication and for retrieving selected user details for the purpose of provisioning.

User authentication and details	Web service information
`user.auth` `user.get`	`ws.getName` `ws.getTime` `ws.getVersion`

Deployment

AuthService is packaged as a standard web application archive (WAR) ready for immediate deployment in a Java servlet container, such as the popular open source Apache Tomcat server.

Configuration

AuthService allows for comprehensive configuration by a set of properties located in the WEB-INF/authservice.properties text file.

Client interface	Authenticating backend
`authService.clients.allow` `authService.clients.requireSecureAccess` `authService.clients.requireCertificate` `authService.clients.certificatePrincipal` `authService.clients.responseContentType` `authService.clients.allowUserGetRequests` `authService.clients.allowDNProvision` `authService.clients.allowJson2LdapCIDProvision` `authService.clients.exposeExceptions` `authService.clients.reportRequestProcTime`	`authService.authBackend`
	Json2Ldap gateway / proxy
	`authService.json2ldap.url` `authService.json2ldap.useDefaultLDAPServer` `authService.json2ldap.trustSelfSignedCerts`
	LDAP server
	`authService.ldapServer.url` `authService.ldapServer.timeout` `authService.ldapServer.security` `authService.ldapServer.trustSelfSignedCerts` `authService.ldapServer.searchConnectionPoolSize`
User DN resolution	User attributes for retrieval
`authService.dnResolution.method` `authService.dnResolution.dnTemplate` `authService.dnResolution.searchUserDN` `authService.dnResolution.searchUserPassword` `authService.dnResolution.searchBaseDN` `authService.dnResolution.searchScope` `authService.dnResolution.searchFilter`	`authService.userAttributes.single.[...]` `authService.userAttributes.multi.[...]`
Custom trust and key store
`authService.ldap.customTrustStore.enable` `authService.ldap.customTrustStore.file` `authService.ldap.customTrustStore.type` `authService.ldap.customTrustStore.password` `authService.ldap.customKeyStore.enable` `authService.ldap.customKeyStore.file` `authService.ldap.customKeyStore.type` `authService.ldap.customKeyStore.password`

Logging

AuthService uses the popular log4j utility. Here are the event types that can be selectively logged (at various levels):

On a HTTP request: method name, client IP, client X.509 certificate principal.
On a JSON-RPC 2.0 request: method name, request parameters (passwords are hidden), response status (success or error code).
DN resolution operation.
Internal AuthService exceptions.

Logging is configured through the WEB-INF/log4j.properties file.

System requirements and dependencies

AuthService requires a web server conforming to the Java servlet specification, such as Apache Tomcat or Jetty:

Java 1.5+
Java servlet API 2.5+

User store and authentication:

LDAP v3 compatible directory

All package dependencies are conveniently included in the AuthService WAR distribution.

Change log

version 1.0 (2011-03-16)
- First official and stable release.
version 1.1 (2011-03-27)
- Renames the named "username" parameter to the shorter "user" ("user.auth" and "user.get" JSON-RPC).
- Adds configuration parameter "authService.clients.responseContentType".
- Adds Cross-Origin Resource Sharing (CORS) support.
version 1.1.1 (2011-05-20)
- Updates JSON-RPC 2.0 Base JAR to 1.16.
version 1.1.2 (2011-06-14)
- Thread-safe parsing of JSON-RPC 2.0 requests.
- Updates JSON-RPC 2.0 Base JAR to 1.17 (JSON Smart).
- Updates UnboundID SDK JAR to 2.2.0.
- Updates JSON-RPC 2.0 Shell to 1.7.
version 1.2 (2011-07-12)
- Renames configuration parameter authService.clients.requireHTTPS to authService.clients.requireSecureAccess to allow for alternative secure channel protocols besides HTTPS.
- Updates JSON Smart JAR to 1.0.9.
- Updates JSON-RPC 2.0 Base JAR to 1.21.
- Updates JSON-RPC 2.0 Server JAR to 1.4.1.
- Updates JSON-RPC 2.0 Shell to 1.9.
version 1.3 (2011-12-16)
- Updates DN-Resolver JAR to 1.2.
- Updates UnboundID SDK JAR to 2.3.0.
- Updates JSON Smart JAR to 1.0.9-1.
- Updates JSON-RPC 2.0 Base JAR to 1.24.
- Updates Property Util JAR to 1.5.
- Updates CORS Filter JAR to 1.3.1.
- Updates JSON-RPC 2.0 Shell to 1.12.
version 2.0 (2012-02-20)
- Introduces support for a Json2Ldap authentication backend in addition to direct LDAP connections.
- Changes signature of user.auth and user.get JSON-RPC 2.0 requests and responses.
- Adds support for returning multi-valued user entry attributes.
- Refactors code to use the common NimbusDS package.
- Updates DN-Resolver JAR to 1.3.
- Updates JSON Smart JAR to 1.1.
- Updates JSON-RPC 2.0 Base JAR to 1.25.
- Updates JSON-RPC 2.0 Server JAR to 1.5.
version 2.0.1 (2012-04-03)
- UTF-8 becomes the default and required character encoding for all JSON-RPC 2.0 responses. This is achieved by making "charset=utf-8" a mandatory part of the authService.clients.responseContentType configuration property.
- Updates JSON Smart JAR to 1.1.1.
- Updates JSON-RPC 2.0 Base JAR to 1.25.1.
- Updates JSON-RPC 2.0 Client JAR to 1.7.1.
- Updates JSON-RPC 2.0 Server JAR to 1.5.