Server JAAS Authentication with Software AG Security infrastructure component
Universal Messaging can use the Software AG Security Infrastructure component (SIN) to provide server JAAS authentication capabilities. The SIN component provides a variety of options for using different authentication back-ends and implementing flexible authentication scenarios.
Full details of the Software AG Security Infrastructure component are available in the Software AG documentation web site in the document Software AG Infrastructure Administrator's Guide . See the description of the predefined login modules in that guide for details of setting up authentication using JAAS login modules and a description of the parameters available for configuring the login modules.
Enabling JAAS authentication
By default the Universal Messaging server is configured to use a JAAS context named UM-Default. This JAAS context is pre-configured to use the Software AG default internal user repository as an authentication back-end.
The JAAS context UM-Default, as well as JAAS contexts for LDAP, X.509 and others, are all defined in a file jaas.conf, that resides under the server's bin directory at <InstallDir>/UniversalMessaging/server/<InstanceName>/bin.
The server configuration file Server_Common.conf (again under the server's bin directory) defines the path to the JAAS configuration file as the value of the system property java.security.auth.login.config. The name of the JAAS context to be used for authentication is configured through the system property Nirvana.auth.server.jaaskey.
Note:
When the property Nirvana.auth.server.jaaskey is present, the server will use JAAS authentication, overriding any configured legacy directory-based authenticators.
The default values that Server_Common.conf defines for its related Universal Messaging server instance are:
-DNirvana.auth.enabled=N
-DNirvana.auth.mandatory=N
-DNirvana.auth.server.jaaskey=UM-Default
-Djava.security.auth.login.config=jaas.conf
Important:
In order to enable the server authentication, you need to switch the flag Nirvana.auth.enabled to Y. Additionally, in order to make authentication mandatory, you need to switch the flag Nirvana.auth.mandatory to Y. The changes will take effect at the next restart of the Universal Messaging server.
SIN JAAS login modules
The supported SIN JAAS login modules are:
1. Internal user repository login module
The SIN internal user repository module (com.softwareag.security.jaas.login.internal.InternalLoginModule) provides a mechanism to authenticate a user by a username and a password against a user database file. Every Software AG installation would deliver a default user database file called users.txt under the <InstallDir>/common/conf directory. A newly created Universal Messaging realm server will come readily configured for authentication using the default user database file through the UM-default JAAS context listed in the jaas.conf file under the realm server bin directory.
2. LDAP login module
The SIN LDAP login module (com.softwareag.security.sin.is.ldap.lm.LDAPLoginModule) provides a mechanism to authenticate a user by a username and a password against an LDAP server. The login module offers various options for using an LDAP or an Active Directory server in different authentication scenarios, some of which we will cover in the JAAS authentication templates section below.
3. X.509 certificate login module
The SIN X.509 certificate login module (com.softwareag.security.jaas.login.modules.X509CertificateLoginModule) provides a mechanism to authenticate a user with a client X.509 certificate chain. This module allows users to access a Universal Messaging server that requires authentication over a SSL/TLS enabled interface with a client certificate.
SIN authentication templates for JAAS
Universal Messaging installation delivers a JAAS configuration file jaas.conf that comes with a pre-configured UM-Default JAAS context and templates for several other authentication scenarios. The UM-Default is selected by default due to the setting of the property Nirvana.auth.server.jaaskey in the Server_Common.conf file, as described above.
1. Internal user repository
The UM-Default JAAS context sets up authentication using the internal user repository that is stored in users.txt:
/*
* Authentication with SAG internal user repository - by default the user database file is located under
* <INSTALL_DIR>/common/conf/users.txt
* in a standard Software AG installation. Depending on how the product is started one may need to
* reconfigure the path to the database file (using an absolute path)
*/
UM-Default {
com.softwareag.security.jaas.login.internal.InternalLoginModule sufficient
template_section=INTERNAL
internalRepository="../../../../common/conf/users.txt";
};
The file users.txt is the internal user repository to be used for authentication when clients attach to the Universal Messaging server. It is located in <InstallDir>/common/conf. If you have multiple Universal Messaging servers, you can use the same users.txt file to unify client authentication for all of the servers.
You might wish to vary the client authentication depending on the Universal Messaging server being used. For example, you might want to define username USER1 with password PASSWORD1 on the first server, but on the second server you want to define the same username USER1 with a different password PASSWORD2. To do this, you will need two users.txt files, one for each server, and change the pathname "../../../../common/conf/" in each server's jaas.conf file to the path where the server-specific users.txt file is located. You can also provide custom names instead of the default users.txt.
To update the username/password definitions in each users.txt file as required, use the internaluserrepo.bat or internaluserrepo.sh script in <InstallDir>/common/bin. For example, to add a user with password "mypwd1" and username "myuser1", run this command on the command line:
internaluserrepo.bat -f <path_to_users.txt> -c -p mypwd1 myuser1
To get instructions on how to create and delete usernames/passwords, as well as how to display a list of existing usernames, run the script with the "-h" option:
2. LDAP Lookup
The LDAP look up method involves logging on to the LDAP server either anonymously (if allowed) or by using a predefined principal, and performing a lookup for a user entry matching a certain attribute. Finally the SIN-specific LDAP login module will attempt to bind with the retrieved user's distinguished name and the supplied password. The following template configuration is provided where you should fill in the required properties:
3. Active Directory direct bind
With active directory the SIN-specific LDAP login module offers the possibility for a direct bind with the supplied username and password, using the following configuration template where the user should fill in the active directory URL.
/*
* Authentication with an Active Directory server by binding directly with
* the supplied credentials.
* Active Directory allows for a direct bind with a principal in the
* format "domainPrefix\user".
*/
UM-AD-DirectBind {
com.softwareag.security.sin.is.ldap.lm.LDAPLoginModule sufficient
url="<LDAP URL>"
noPrinIsAnonymous=false
useFQDNForAuth=true;
};
4. LDAP direct bind
It is also possible to attempt a direct bind against an LDAP server where the bind DN will be constructed by the SIN-specific JAAS login module using a prefix and a suffix, with the supplied username in-between. In this case the user is required to configure the URL of the LDAP server, as well as the prefix and the suffix to be used for the construction of the bind DN:
/*
* Authentication with an LDAP server by building a complete DN and binding directly.
* The bind DN will be composed by prepending the supplied username with the
* value of the "dnprefix" parameter and appending the value
* of the "dnsuffix" parameter.
*/
UM-LDAP-DirectBind-Affixes {
com.softwareag.security.sin.is.ldap.lm.LDAPLoginModule sufficient
url="<LDAP URL>"
noPrinIsAnonymous=false
useaf=true
dnprefix="<Bind DN prefix>"
dnsuffix="<Bind DN suffix>";
};
5. Combination of any of the above
JAAS is extremely flexible and allows for using a combination of different back-ends, such as, several LDAP servers and/or repositories. For example it is possible to configure LDAP authentication with an internal user repository as a fallback mechanism:
6. Combining X.509 client certificate with a username/password authentication
Authentication is configured globally for a Universal Messaging realm server, which means that if a user connects over an SSL/TLS interface that requires a X.509 client certificate, the user would still have to undergo an authentication check in order to establish a viable session. This is where the SIN X.509 certificate login module comes in handy, as it would allow users to authenticate with a presented client certificate over an SSL/TLS interface, or alternatively, present a username and a password credentials if connecting over an interface that does not require a client certificate. This can be achieved using the following template of the X.509 client certificate login module in combination with either an internal user repository, or an LDAP login module (or both).
/*
* Authentication with a X.509 certificate chain, and a username/password, as a
* fallback mechanism. This configuration would first try to log in using an X.509
* certificate chain (if present), and if that fails, it would attempt
* authentication against an internal user repository. A certificate chain would
* only be present if the user connected through a TLS/SSL enabled interface that
* required a client certificate, and this login context will give precedence to
* the X.509 certificate chain credential.
*
* The same scenario can be implemented with an LDAP server by replacing the
* internal user repository login module with an LDAP login module configuration.
*
* This context would allow that in a server that has authentication enforced
* globally, users can connect with a username and a password through insecure
* interfaces (or TLS/SSL enabled interfaces using server certificates only), and
* using an X.509 certificate over an TLS/SSL interface that requires a client
* certificate.
*/
UM-X509-UsernamePassword {
com.softwareag.security.jaas.login.modules.X509CertificateLoginModule sufficient
truststore_url="<truststore file URL>"
truststore_password="<truststore password>"
create_user_principal=true;
com.softwareag.security.jaas.login.internal.InternalLoginModule sufficient
template_section=INTERNAL
internalRepository="../../../../common/conf/users.txt";
};
To use any custom JAAS context, or any of the predefined templates, you would need to modify the value of the Nirvana.auth.server.jaaskey system property inside the Server_Common.conf file in the server's bin directory, pointing it to the context to be used. At the moment the context name is globally defined for the entire server.
Note:
Since the jaas.conf file is edited manually and requires certain knowledge of the default JAAS configuration file format, there is always the possibility of a syntactic error. Such errors during parsing of the file will be printed to the UMRealmService.log file which resides under the server's bin directory.