Universal Messaging 10.3 | Developer Guide | Enterprise APIs | Enterprise Developer's Guide for Java | Basic Authentication | Server-side Authentication
 
Server-side Authentication
There is a much broader range of configuration options on the server, controlling every aspect of authentication from whether it's enabled in the first place, to how to look up user credentials.
Client Negotiation
Authentication is disabled by default on the server for backward compatibility, meaning that even if clients do supply user credentials, they will be accepted without verification.
This is controlled by the Nirvana.auth.enabled system property, which must be explicitly set to "Y" or "y" to enable authentication.
System administrators have to set up various other configuration options when enabling authentication, so they would set Nirvana.auth.enabled as part of that effort.
Even when authentication is enabled, authenticating clients can exist side-by-side with non-authenticating ones, meaning it is entirely optional for clients to supply any user credentials, and if they don't they will be handled in the traditional Universal Messaging manner.
The Nirvana.auth.mandatory system property controls this behaviour, and should be explicitly set to "Y" or "y" to make authentication mandatory, meaning clients that don't supply a username and password will be rejected.
There are two exemptions from mandatory authentication, in order to prevent Enterprise Manager getting locked out.
One of them is the super-user on localhost, and the other is a set of users in a file pointed at by the optional JVM property -DNirvana.auth.exempt=/path/to/file.
The users in the latter file are listed one per line in ACL-style notation, e.g. username1@10.140.2.95.
If -DNirvana.auth.exempt is not set, the optional -DSECURITYFILE JVM property is processed in the same way, but to enable decoupling, if -DNirvana.auth.exempt is set to "-" (hyphen) then there are no exempt users and -DSECURITYFILE is not processed.
When a client does authenticate, the Universal Messaging client-server protocol automatically signals the server whether they're using SASL+Directory or JAAS. If JAAS, then the Nirvana.auth.server.jaaskey system property must be set on the server, and it specifies the name of the entry to use in the server-side JAAS-LCF file.
As in the client case, the pathname of the JAAS-LCF is specified by the standard JAAS system property, java.security.auth.login.config.
If the Nirvana.auth.server.jaaskey system property is not set on the server, then it will reject all attempts to authenticate via JAAS.
Directory Backend
The Universal Messaging server can make use of a variety of backend Directory servers or mechanisms, as controlled by the Nirvana.directory.provider system property, which specifies the pluggable Java class representing the Directory.
Usernames are case-sensitive and are used in the form supplied to do the Directory lookup. This is the authentication step, and is followed by an authorisation step in which the username is normalised to lowercase to match against Universal Messaging ACLs. Universal Messaging ACLs are case-insensitive but expressed in lower-case, and any ACLs created via the Enterprise Manager will be forced to lower case.
Internal User Repository
If the Nirvana.directory.provider system property is set to com.pcbsys.foundation.security.auth.fSAGInternalUserRepositoryAdapter, then usernames will be looked up in a standard Software AG store called the 'Internal User Repository', which is a flat file maintained by the Software AG command-line utility internaluserrepo.bat (Windows platforms) or internaluserrepo.sh (UNIX-based platforms). This utility is located in <InstallDir>/common/bin.
This mechanism is the default user repository if the Nirvana.directory.provider property is not set.
You can use the following syntax to add a user myuser1 with a password mypwd1 to the internal user repository.
internaluserrepo.bat -f <path_to_users.txt> -c -p mypwd1 myuser1
The location of the file containing the internal user repository is given by the system property Nirvana.auth.sagrepo.path, and would default to ./users.txt (relative to the runtime directory of the Universal Messaging server), but the Server_Common.conf file shipped with Universal Messaging overrides this as ../users.txt, locating it in the same <InstallDir>/UniversalMessaging/server/<InstanceName> directory as the licence.xml file.
The entry in Server_Common.conf looks like this:
wrapper.java.additional.18=-DNirvana.auth.sagrepo.path=../users.txt
The Server_Common.conf file may of course be edited as usual to move the users.txt file into a location that is shared by all the realms of an installed Universal Messaging instance.
You should also set up the following configurations in the Server_Common.conf file, to ensure that basic authentication is activated and mandatory:

wrapper.java.additional.19=-DNirvana.auth.mandatory=Y
// This makes basic authentication mandatory.
// Calls not supplying the credentials in this case will be rejected.
wrapper.java.additional.20=-DNirvana.auth.enabled=Y
// This enables the basic authentication feature,
// but it is not mandatory to supply credentials.
If you add users to the internal user repository, you should also set up Universal Messaging server ACLs for these users, specifying e.g. myuser1@hostname, and give appropriate or full control.
Note: 
*To activate any changes you make, you need to restart the Universal Messaging server.
*More details about the utility internaluserrepo and its options are available in the Software AG document Command Central Help.
LDAP
If the Nirvana.directory.provider system property is set to com.pcbsys.foundation.security.auth.fLDAPAdapter, then LDAP will be used as the source of user information.
Interaction with the LDAP server is configured via the following Java system properties:
*Nirvana.ldap.provider:
The LDAP client class - defaults to the JDK's built-in provider, com.sun.jndi.ldap.LdapCtxFactory
*Nirvana.ldap.url:
The address of the LDAP server. This has no default and must be specified, using syntax such as ldap://localhost:389/dc=sag,dc=com.
*Nirvana.ldap.suffix:
The suffix to apply to LDAP queries. This has no default and may be null, but if non-null it qualifies the URL above. E.g. Nirvana.ldap.url=ldap://localhost:389/dc=sag and Nirvana.ldap.suffix=dc=com will result in the same effective query root as Nirvana.ldap.url=ldap://localhost:389/dc=sag,dc=com when the Nirvana.ldap.suffix property is not set.
*Nirvana.ldap.rootcreds:
The privileged-administrator login credentials to use on the LDAP server, in order to perform user queries. There is no default and if not set it means there is no need to specify any such credentials, but if present the format must be username:password.
The remaining system properties relate to the LDAP schema and default to the standard COSINE schema:
*Nirvana.ldap.attribute.username:
This specifies the LDAP attribute which represents the username, and defaults to the standard schema convention of "cn".
*Nirvana.ldap.attribute.password:
This specifies the LDAP attribute which represents the password, and defaults to the standard schema convention of "userPassword".
*Nirvana.ldap.search.username:
This specifies the search expression to use for a given username, and defaults to cn=%U%, where %U% gets substituted by the username.