Once the application has obtained the credentials from the user, they must be verified and the user's security roles must be determined. In iSM, this function is performed by authentication realms. A realm represents a database of information about valid users of the system, containing, at a minimum, the user ID, password, and the names of any security roles that have been assigned to the user. iSM supplies five different realm implementations, which can be configured in the Provider section of the iSM Administration Console.

1. Properties Realm

   This realm is configured with the path to a properties file that contains properties like username=password and username.role=rolename. For example:

   steve=password
   steve.role0=user
   judy=secret
   judy.role0=admin
   judy.role1=bigdocs

   Judy has two access tokens, while Steve has one. Unlike Steve, Judy can work with bigdocs. The meaning of bigdocs is subject to tests in the process flow, and is not defined by iWay.

   Obviously, this provides minimal security and is intended for use in testing and debugging only.

2. Console Realm

   This realm wraps the iSM console security systems, authenticating users that have been defined on the Managed Servers page of the console. If the user has been granted power user rights, the Principal returned will include the admin role. The console realm is not configured as a provider. An instance of the console realm is always available to the system under the name, consolerealm.

3. JDBC Realm

   This realm authenticates users using a JNDI data source, which could be an iWay JDBC Provider. The following table lists and describes the configuration parameters for the JDBC authentication realm:

   Parameter	Description
   JNDI Factory Name	Initial Context Factory class to access the data source using JNDI. To use an iWay JDBC provider, enter com.ibi.jndi.XDInitialContextFactory.
   JNDI Name	Name for the data source in the JNDI directory. For iWay JDBC providers, use the following format: jdbc/[provider_name]
   Users Table	Table with at least one row for each valid user in this realm. The table must include at least two columns, containing user name and password. The names of these columns are specified by the Username and User Credential Column parameters. The table may include other columns if the application requires them.
   User Roles Table	Table with at least one row for each security role assigned to a user. The table must contain at least two columns, for user name and role. The names of these columns are specified by the Username and Role Column parameters. The table may include other columns if required by the application.
   Username Column	Name of the column that contains the user name in the Users and User Roles tables.
   User Credential Column	Name of the column that contains the password in the Users table.
   Role Column	Name of the column that contains the name of the user security role in the User Roles table.

   The simplest tables that could be used with this realm might look as follows:

   CREATE TABLE users
   (
   username varchar(25),
   password varchar(25)
   )
   CREATE TABLE user_roles
   (
   username varchar(25),
   role varchar(25)
   )

   To look up the password for a user, the realm constructs an SQL statement. For example:

   SELECT password FROM users WHERE username = ?

   And it finds roles with the following statement:

   SELECT role FROM user_roles WHERE username = ?

4. JAAS Realm

   This realm wraps a JAAS logon context that must be configured externally in the JAAS logon configuration file. The JAAS realm does not support digest authentication. The following table lists and describes the configuration parameters for the JAAS authentication realm:

   Parameter	Description
   JAAS Config File	Path to the standard JAAS configuration file. If the system variable java.security.auth.login.config is not set when the realm is initialized, the realm will set it to this value. Consult JAAS documentation for the structure of this file.
   Application Entry	The entry in the JAAS configuration to which this realm will delegate authentication requests.
   User Principal	A successful JAAS logon results in a Subject that can contain one or more Principal objects. Specify the class name of the Principal object that should be understood as representing the authenticated user.
   Role Principal	Specify the class name (or a comma delimited list of class names) for Principal objects created by the JAAS logon that should be understood as representing security roles for the authenticated user. The value returned by the Principal's getName() method will be the name of the role assigned to the user in iSM.

   For testing, a simple JAAS logon module is provided that wraps the iSM console user database. To try it, you must first create the JAAS configuration file with an application entry pointing to the console module. For example:

   test
   {
   com.ibi.providers.auth.jaas.ConsoleLoginModule REQUIRED;
   };

   Configure the JAAS authentication realm according to the values that are listed in the following table:

   Parameter	Value
   JAAS Config File	The file containing the application entry above.
   Application Entry	For the above example, "test".
   User Principal	The logon module creates a principal for the user of type: com.ibi.providers.auth.jaas.ConsoleUserPrincipal
   Role Principal	The logon module creates a principal for the role of type: com.ibi.providers.auth.jaas.ConsoleRolePrincipal

   It should be possible to configure the JAAS Realm to work with most logon modules.

5. LDAP Realm

   This realm implementation works with a directory server accessed via the Java Naming and Directory Interface (JNDI) APIs. The following table lists and describes the configuration parameters for the LDAP authentication realm:

   Parameter	Description
   LDAP Provider	Name of the directory provider describing the connection to the LDAP server.
   User Base Context	The base of the subtree containing users. Each user that can be authenticated must be represented by an individual entry that corresponds to an element in this directory context. If no value is specified, then the top level element in the directory context will be used.
   User Pattern	A pattern for the distinguished name (DN) of the user's directory entry. Use {0} to substitute the user name. For example, (cn={0}). LDAP OR syntax is also supported. For example, (|(cn={0})(cn={0},o=myorg)). You can use this parameter instead of User Search Filter, Search User Subtree, and User Base Context when the distinguished name contains the user name and is otherwise the same for all users.
   Search User Subtree	The search scope. Set to true if you wish to search the entire subtree rooted at the User Base Context entry. The default value of false requests a single-level search including only the top level.
   User Search Filter	The LDAP filter expression to use when searching for a user's directory entry, with {0} marking where the actual user name should be inserted. Use this parameter (along with the Search User Subtree parameter) instead of the User Pattern parameter to search the directory for the user's entry.
   User Password Attribute	Name of the attribute in the user's entry containing the user's password. If you specify this value, then this realm will retrieve the corresponding attribute for comparison to the value specified by the user being authenticated. If you do not specify this value, then this realm will attempt a simple bind to the directory using the distinguished name (DN) of the user's entry and password specified by the user, with a successful bind being interpreted as an authenticated user.
   Role Base Context	The base directory entry for performing role searches. If no value is specified, then the top level element in the directory context is used.
   Search Role Subtree	Set this parameter to true if you want to search the entire subtree of the element specified by the Role Base Context for role entries associated with the user. The default value of false causes only the top level to be searched.
   Role Search Filter	The LDAP filter expression used for performing role searches. Use {0} to substitute the distinguished name (DN) of the user, and/or {1} to substitute the user name. If no value is specified, then a role search does not take place and roles are taken only from the attribute in the user's entry specified by the User Role Attribute parameter.
   Role Attribute	The name of the attribute that contains role names in the directory entries found by a role search. In addition you can use the User Role Attribute parameter to specify the name of an attribute, in the user's entry, containing additional role names. If no value is specified, then a role search does not take place, and roles are taken only from the user's entry.
   User Role Attribute	The name of an attribute in the user's directory entry containing zero or more values for the names of roles assigned to this user. In addition you can use the Role Attribute parameter to specify the name of an attribute to be retrieved from individual role entries found by searching the directory. If no value is specified, then all the roles for a user derive from the role search.