AuthService Configuration
AuthService allows for comprehensive configuration through a set of
parameters in the WEB-INF/authservice.properties 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.
| Client interface » | Authenticating backend » |
|---|---|
|
Parameters for controlling web client access: connection security, client filtering, user attribute provision.
|
Specifies the authenticating backend type. |
| Json2Ldap gateway / proxy » | |
|
The Json2Ldap URL and other connection details. |
|
| LDAP server » | |
|
The LDAP directory URL and other connection details. |
|
| User DN resolution » | User attributes for retrieval » |
|
Configures resolution of user DNs from the supplied username, email or other unique user identifier. |
The names of the LDAP attributes to retrieve on a successfully authenticated user.get request. |
| Custom trust and key store » | |
|
For setting a custom trust or key store for TLS/SSL LDAP connections.
|
|
1. Client interface
The authService.clients.* properties control the access
policy for the AuthService.
authService.clients.allow
Space-separated list of client IP and / or hostnames that are allowed to
use the web service. If set to * (asterisk) any IP address is
allowed.
Example: Allow access from any IP:
authService.clients.allow=*
Example: Allow only the specified client IPs:
authService.clients.allow=192.168.0.1 192.168.0.2 192.168.0.3
authService.clients.requireSecureAccess
If true requires clients to connect using HTTP secure
(HTTPS). Plain HTTP connections will not be allowed.
It's recommended that HTTPS use is enforced at all times:
authService.clients.requireSecureAccess=true
authService.clients.requireCertificate
If true requires clients to authenticate with a valid X.509
certificate issued by a trusted certificate authority (CA).
authService.clients.requireCertificate=true
authService.clients.certificatePrincipal
If specified, requires the X.509 client certificate subject to match the specified distinct name (DN).
authService.clients.certificatePrincipal= CN=AuthServiceClient, OU=apps, DC=wonderland, DC=net
responseContentType
Sets the value of the HTTP "Content-Type" header for the JSON-RPC 2.0 responses. The character set option must be explicitly set to UTF-8.
Typically set to application/json;charset=utf-8 or to
text/plain;charset=utf-8 to support browser CORS requests.
authService.clients.responseContentType=application/json;charset=utf-8
authService.clients.allowUserGetRequests
If true clients may make user.get
calls to authenticate a user and retrieve selected user attributes as specified by
authService.userAttributes.*.
authService.clients.allowUserGetRequests=true
authService.clients.allowDNProvision
If true clients are provided with the user's distinguished
name (DN) on a successfull
user.get call.
authService.clients.allowDNProvision=true
authService.clients.allowJson2LdapCIDProvision
If true clients may request a Json2Ldap connection
identifier (CID) bound as the authenticated user. Applies to
user.get calls when
the authService.authBackend
is set to JSON2LDAP.
Web clients may use the Json2Ldap directory connection (CID) to obtain attributes from the user's entry, make searches, or update information.
authService.clients.allowJson2LdapCIDProvision=true
authService.clients.exposeExceptions
This setting controls reporting of details in JSON-RPC 2.0 "General back-end service exception" messages (code -1200).
If true AuthService will expose the cause of the back-end
exception in the "data" field of the JSON-RPC 2.0 error. Use this setting
for debugging or if the web clients are trusted.
If false AuthService will not provide any additional
information about back-end exceptions. The exact cause can be found out from
the AuthService log. Use this setting if the web are generally not trusted
or they don't need to know any details about encountered exceptions.
To allow your web clients to inspect the cause of back-end exceptions:
authService.clients.exposeExceptions=true
authService.clients.reportRequestProcTime
If true enables reporting of request processing time by
appending a non-standard "xProcTime" attribute to the JSON-RPC 2.0
responses.
Intended for debugging and testing purposes. Disabled by default to prevent parse exceptions by clients which don't allow unexpected JSON attributes in the JSON-RPC 2.0 response messages.
2. Authenticating backend
AuthService authenticates users against an LDAP directory. This can be done directly or through a Json2Ldap web proxy / gateway.
authService.authBackend
This setting specifies how the AuthService connects to the back-end LDAP directory.
If set to LDAP AuthService will establish direct LDAPv3
connections to the back-end directory. You must then also specify the
directory details in the
authService.ldapServer.* section.
authService.authBackend=LDAP
If set to JSON2LDAP AuthService will use a
Json2Ldap web gateway / proxy to connect to the
back-end directory. You must then also specify the Json2Ldap details in the
authService.json2ldap.* section.
authService.authBackend=JSON2LDAP
3. Json2Ldap gateway / proxy
The authService.json2ldap.* properties specify the
Json2Ldap web service details. Required
only if authService.authBackend
is set to JSON2LDAP.
authService.json2ldap.url
The HTTP(S) URL of the Json2Ldap web service.
authService.json2ldap.url=http://localhost:8080/json2ldap/
authService.json2ldap.useDefaultLDAPServer
Determines whether to use the default LDAP server specified by the Json2Ldap web service.
If false the LDAP server details must be specified
explicitly in the authService.ldapServer.*
configuration.
authService.json2ldap.trustSelfSignedCerts
Specifies whether to accept self-signed X.509 certificates presented by the Json2Ldap web service (for HTTPS connections).
4. LDAP server
The authService.ldapServer.* properties specify the
LDAP directory server details. Required if
authService.authBackend
is set to LDAP or if the back-end is set to
JSON2LDAP and a non-default directory is used.
authService.ldapServer.url
The LDAP URL of the directory server. The schema must be ldap
or ldaps, it must specify a valid host name or IP address, and
an optional port number of a non-default is used.
The LDAP URL of a directory server that listens on the default 389 port:
authService.ldapServer.host=ldap://ldap.mydomain.com
To specify a non-standard port:
authService.ldapServer.host=ldap://ldap.mydomain.com:10389
authService.ldapServer.timeout
The timeout in milliseconds for LDAP connect requests. If zero the underlying LDAP client library will handle this value.
authService.ldapServer.security
The LDAP connection security.
Set to none to establish a plain insecure connection.
Set to SSL to establish a secure connection over SSL.
Set to StartTLS to establish a secure connection using the
StartTLS protocol (recommended method).
Choose StartTLS or SSL for secure LDAP connections:
authService.ldapServer.security=StartTLS
authService.ldapServer.trustSelfSignedCerts
Determines whether to accept self-signed certificates presented by the LDAP server (for secure SSL or StartTLS connections).
authService.ldapServer.searchConnectionPoolSize
The target search connection pool size. Applies only if
authService.dnResolution.method
is set to SEARCH and
authService.authBackend
is LDAP.
5. User DN resolution
The authService.dnResolution.* properties specify the
procedure for resolving a user's distinguished name (DN) from the username /
email supplied with the auth request.
authService.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.
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 user DN,
search user password,
search base DN, a
search scope and a
search filter.
Set to NONE to let the back-end directory resolve the
user DN. Requires directory support for plain SASL bind with usernames
(RFC 4616).
To use a simple DN template:
authService.dnResolution.method=TEMPLATE
authService.dnResolution.dnTemplate
The DN template (if method
TEMPLATE is selected, otherwise ignored). Each occurence of %u
is substituted by the supplied username (leading and trailing whitespace
trimmed), the resulting string then becomes the user DN.
Example:
authService.dnResolution.dnTemplate= UID=%u, OU=people, DC=example, DC=com
authService.dnResolution.searchUserDN
The search user DN (if method SEARCH is selected, otherwise ignored). A blank value signifies an anonymous user.
Example:
authService.searchUser.dn= CN=Search User, DC=Example, DC=com
authService.dnResolution.searchUserPassword
The search user password (if method SEARCH is selected, otherwise ignored). A blank value signifies an anonymous user.
authService.dnResolution.searchBaseDN
The search base DN (if method SEARCH is selected, otherwise ignored).
Example:
authService.dnResolution.searchBaseDN= OU=people, DC=example, DC=com
authService.dnResolution.searchScope
The search scope (if method SEARCH is selected, otherwise ignored).
Set to BASE to consider only the entry specified by the
base DN.
Set to ONE to consider only entries that are immediate
subordinates of the entry specified by the
base DN
(but not the base entry itself).
Set to SUB to consider the
base entry
itself and any subordinate entries (to any depth).
Example:
authService.dnResolution.searchScope=ONE
authService.dnResolution.searchFilter
The search filter string (if method
SEARCH is selected, otherwise ignored). Each occurence of %u
is substituted by the supplied username / email (leading and trailing whitespace
trimmed), the resulting string then becomes the final search filter.
Example: Authenticate users by username and email:
authService.dnResolution.searchFilter=(|(uid=%u)(mail=%u))
6. User attributes for retrieval
The authService.userAttributes.* properties
specify the user attributes to return with a
user.get
response. The
authService.clients.allowUserGetRequests
setting must also be enabled.
authService.userAttributes.single.*
Specifies single-valued user entry attributes to retrieve. Use for attributes such as name, initials and IDs.
These must be key/value pairs where the keys define the JSON attribute names and the values the corresponding LDAP attribute names, e.g.
JSON-field-name = LDAP-attribute-name
Example:
authService.userAttributes.single.userID=uid authService.userAttributes.single.name=cn
authService.userAttributes.multi.*
Specifies multi-valued user entry attributes to retrieve. User for attributes such as email addresses, contact details and permissiongs / authorisations.
These must be key/value pairs where the keys define the JSON attribute names and the values are one or more corresponding LDAP attribute names, e.g.
JSON-field-name = LDAP-attribute-name-1 LDAP-attribute-name-2 ...
Example:
authService.userAttributes.single.phone=telephoneNumber mobile homePhone authService.userAttributes.single.groups=memberOf
7. Custom trust and key store for TLS/SSL LDAP
The authService.customTrustStore.* and authService.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 back-end LDAP server.
authService.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).
authService.customTrustStore.file
The location of the custom trust store file.
Example:
WEB-INF/truststore.jks
authService.customTrustStore.type
The type of the trust store file, typically JKS or PKCS12.
Set to an empty string to assume the system default type.
authService.customTrustStore.password
The password required to unlock the trust store file.
Set to an empty string if none is required.
authService.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).
authService.customKeyStore.file
The location of the custom key store file.
Example:
WEB-INF/keystore.jks
authService.customKeyStore.type
The type of the trust store file, typically JKS or PKCS12.
Set to an empty string to assume the system default type.
authService.customKeyStore.password
The password required to unlock the key store file.
Set to an empty string if none is required.
