Copyright © TIBCO Software Inc. All Rights Reserved

> Extensible Authentication
> The extensible authentication feature uses the Java virtual machine (JVM) and the Java Authentication and Authorization Service (JAAS) to allow you to run your own Java-based authentication module in the EMS server.
> Your authentication module, or LoginModule, runs in the JVM within the EMS server, and is accessed by tibemsd using the JAAS interface. This is a flexible way to extend the security of your EMS application. The LoginModule can be used to augment existing authentication processes, or can be the sole method of authentication used by the EMS server. The user_auth parameter in the main configuration file determines when the LoginModule is used.
> Each time an EMS client attempts to create a connection to the server, the server will authenticate the client before accepting the connection. When extensible authentication is enabled, tibemsd passes the username and password to the LoginModule, which returns an allow or deny response.
> If more than one authentication mechanism is enabled, it’s important to note the order that the authentication processes are employed, as determined by their order in the user_auth parameter. The server will search each authentication source in order, and if the user does not exist there, tibemsd passes the username and password to the next source.
> For example, if local authentication appears before JAAS authentication, the server will search for the provided username and password first in the users.conf file. If the user does not exist there, tibemsd passes the username and password to the LoginModule, which allows or denies the connection attempt.
> Consider a connection request from a client with the username avogus. If avogus exists in the users.conf, the EMS server will either authenticate or deny access to avogus based on the username and password located there. Only if avogus does not exist in the users.conf does the server pass the username and password to the LoginModule.
> Enabling Extensible Authentication
> Extensible authentication is enabled in the EMS server, through parameters in the tibemsd.conf configuration file. The required parameters are:

> • | authorization—directs the server to verify user credentials and permissions on secure destinations.

> • | user_auth—directs the EMS server to use the LoginModule for authentication.

> • | jaas_classpath—specifies the JAR files and dependent classes used by the LoginModule.

> • | jaas_config_file—specifies the configuration file, usually jaas.conf, that loads the LoginModule. For more information, see the Example jaas.conf Configuration File.

> Because the LoginModule runs in the Java virtual machine, you must also enable the JVM in the EMS server. See Enabling the JVM for more information.
> Writing an Authentication Module
> The LoginModule is a custom module that runs inside the EMS server within a JVM. The LoginModule is written using JAAS, a set of APIs provided by Sun Microsystems, and used to create plugable Java applications. JAAS provides the interface between your code and the EMS server. JAAS is a standard part of JRE, and is installed with EMS.
> LoginModule Requirements
> In order to implement extensible authentication, you must write a LoginModule implementing the JAAS interface. There are some requirements for a LoginModule that will run in the EMS server:

> • | The LoginModule must accept the username and password from the EMS server by way of the NameCallback and PasswordCallback callbacks. The EMS server passes the username and password to the LoginModule using these callbacks, ignoring the prompt argument.

> • | If the username and password combination is invalid, the LoginModule must throw a FailedLoginException. The EMS server then rejects the corresponding connection attempt.

> • | The LoginModule must be thread-safe. That is, the LoginModule must be able to function both in a multi-threaded environment and in a single-threaded environment.

> • | The LoginModule should perform authentication only, by determining whether a username and password combination is valid. For information about custom permissions, see Extensible Permissions.

> • | The LoginModule, like the Permissions Module, should not perform long operations, and should return values quickly. As these modules become part of the EMS server’s message handling process, slow operations can have a severe effect on performance.

> • | The LoginModule must be named EMSUserAuthentication.

> More information about JAAS, including documentation of JAAS classes and interfaces, is available through http://java.sun.com/products/jaas/.
> Loading the LoginModule in the EMS Server
> The EMS server locates and loads the LoginModule based on the contents of the configuration file specified by the jaas_config_file parameter in the tibemsd.conf file. Usually, the JAAS configuration file is named jaas.conf. This file contains the configuration information used to invoke the LoginModule.
> The contents of the jaas.conf file should follow the JAAS configuration syntax, as documented at:
> http://java.sun.com/j2se/1.5.0/docs/api/javax/security/auth/login/Configuration.html

> | The LoginModule in the JAAS configuration file must have the name EMSUserAuthentication.

> Example jaas.conf Configuration File
> EMSUserAuthentication {
> com.tibco.tibems.tibemsd.security.example.FlatFileUserAuthLoginModule required debug=true filename=jaas_users.txt;
> };

Copyright © TIBCO Software Inc. All Rights Reserved