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:
internaluserrepo.bat -h
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.