Overview
The entire set of session creation methods of the Universal Messaging client API for Java (nsp/ nsps/ nhp/ nhps, native and JMS) have been extended in Universal Messaging 9.6 with overloaded variants that accept username/password credentials which are then supplied to the UM server, and the UM server has been enhanced to enable those credentials to be authenticated against pluggable Directory backends, ranging from LDAP to flat files.
The exchange of user credentials can be performed by means of either SASL (embedded within the Universal Messaging SDK) or JAAS (controlled by user-configurable
pluggable modules).
The configuration is determined by a set of Java system properties on both the client and server side, the laer typically centralized in the nserver.conf configuration file.
Note that authentication does not supplant the traditional Universal Messaging ACLs and is merely an additional security step performed before the relevant ACLs are
(assuming the server is configured to allow that), i.e. by defaulting the user identity to the username under whose identity the client process is running (as reflected in the Java
"user.name" system property). The client API is controlled by two main Java system properties.
Nirvana.auth.client.jaaskey
If set, this means that any authentication should be performed via JAAS and its value specifies the name of the entry to use in the JAAS login configuration file. JAAS is an established Java standard which is beyond the scope of the UM documentation and the login configuration file's pathname is specified by the usual JAAS system property, java.security.auth.login.config. The Nirvana client SDK supplies the username and password to the JDK's built-in JAAS subsystem, and the JAAS login config file specifies one or more pluggable JAAS modules that will perform the authentication. The precise modules to use are a maer of site-specific policies determined by the Nirvana admins, and the JAAS modules configured into a client should obviously be aligned with those configured on the server. If Nirvana.auth.client.jaaskey is not set, then the authentication mechanism defaults to SASL.
nirvana.sasl.client.mech
This specifies which SASL mechanism to use, and the supported options are Plain or CRAM-MD5. The mechanism defaults to Plain if this system property is not set, and the usual SASL trade-offs apply. SASL-Plain transmits the user password in cleartext, so it is advisable to only use it over an SSL connection, while Cram-MD5 does not transmit it in cleartext, but does require it to be stored in plaintext on the server (whereas Plain can work with stored passwords in either plain or encrypted format).
One of the JAAS modules available is the Nirvana class,
com.pcbsys.foundation.security.sasl.fSaslClientLoginModule, which will result in the authentication being performed via SASL after all, despite initially being routed via JAAS. From the server's perspective, the authentication negotiation is conducted entirely in SASL.
The fSaslClientLoginModule class is integrated with the Software AG family of JAAS modules, and one reason you might opt for this JAAS-SASL hybrid is to chain it with other SAG modules.
Server
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 admins have to set up various other config 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 (with the exception of the super-user on localhost, so that Enterprise Manager doesn't get locked out). When a client does authenticate, the UM client-server protocol automatically signals the server whether they're using SASL or JAAS and 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 JAAS login configuration file. As in the client case, the pathname of this file is specified by the standard JAAS java.security.auth.login.config property. If the Nirvana.auth.server.jaaskey system property is not set, then all aempts to authenticate via JAAS will be rejected.
Directory Backend
The UM 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 authorization step in which the username is normalized to lowercase to match against Nirvana ACLs.
Nirvana 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 SAG command-line utility internaluserrepo.sh (found in INSTALLROOT/common/bin).
This mechanism is the default Directory, if the Nirvana.directory.provider property is not set.
The location of the file is given by the system property, Nirvana.auth.sagrepo.path, and would default to ./users.txt (relative to runtime directory of UM server), but the nserver.conf shipped with UM overrides this as ../users.txt, locating it in the same INSTALLROOT/nirvana/server/umserver directory as the licence.xml file. The nserver.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 UM instance.
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. Eg.
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.suffix=ldap://localhost:389/
dc=sag,dc=com when the Nirvana.ldap.suffix property is not set.
Nirvana.ldap.rootcreds: The privileged-admin 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 aribute which represents the username, and defaults to the standard schema convention of "cn".
Nirvana.ldap.attribute.password: This specifies the LDAP aribute 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.