Realm Based Authentication

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.

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

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.

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.

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.
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”.

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 via 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.

Parameter	Description
JNDI Factory Name	Initial Context Factory class to access the data source via 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 = ?

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.

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.

iWay Software