Context Navigation

Configuration Settings for OTIS Client

This page defines the entries in the java.util.Map object that OTIS client Java objects expect. We have chosen to define these settings using the XML settings syntax described here, as the XML format is a very simple and easy-to-use method to specify configuration for these objects. Furthermore, the code to generate the java.util.Map object that is passed to the objects' configure method is very simple (see here for instructions on how to do this.) However, since it is ultimately a java.util.Map object that is passed into the configure method of these objects, it is up to the application developer how these Map objects get generated. Map objects can be created in whatever way suits the application developer, including possibly reading the settings from other file formats like JSON, name-value pairs, etc.

The top-level java.util.Map settings object is passed into both the AuthSessionManager object and the IAuthSession object, and sub-parts of those settings may be passed to other OTIS client objects. Which sub-parts get passed to what objects is called out as we go along.

Below are the major settings that must be present in the configuration map for the AuthSessionManager and IAuthSession objects:

defaultContextId Setting

The Type for this Setting element is "xsd:string" (Java String object). This setting contains the default context ID that is to be used for IdAS operations. Most of the default authentication methods use this IdAS context to authenticate, unless it is overridden by the application.

   <Setting Name="defaultContextId" Type="xsd:string">urn:Corporate-LDAP-Server</Setting>

lenientReauth Setting

The Type for this Setting element is "xsd:boolean" (Java Boolean object). This setting contains a flag ("true" or "false") which specifies whether lenient reauthentication is allowed. When re-authenticating an authentication method, the method is supposed to revalidate the authentication material it has received (for example, username and password). Depending on the implementation, this might involve submitting the material to the backend identity provider (if any) for re-validation. This is "strict reauthentication." However, it is possible that an authentication method may not be able to do strict reauthentication. In that case, this flag specifies whether "lenient reauthentication" is acceptable. Lenient reauthentication is simply a normal authentication request. For authentication methods that use IdAS context providers, the authentication method attempts to do a strict reauthenticate call to the context provider. If that fails because the context provider does not support strict reauthentication, the authentication method may check this flag to see if lenient reauthentication is allowed. If allowed, the authentication method may revert to a normal authenticate request. Authentication methods that do not use IdAS context providers might want to implement similar reauthentication logic, unless the distinction between lenient and strict reauthentication is meaningless.

   <Setting Name="defaultContextId" Type="xsd:string">urn:Corporate-LDAP-Server</Setting>

AuditRecordClass Setting

The Type of this setting is "xsd:string" (Java String). It is optional. If present, it is ONLY used if there is no otisEndpoint setting. If there is an otisEndpoint setting, audit logging happens in the OTIS server, not on the client side. This setting contains the name of the class that implements the org.eclipse.higgins.audit.api.AuditRecord interface. Objects of this class will be used to log audit events (provided there is no otisEndpoint setting). If this setting is missing, audit events will not be logged. The OTIS SDK provides a class that implements this interface - org.bandit.otis.impl.OtisAuditRecord. This particular implementation formats audit records according to the XDAS record format. Specifying this class as the audit record class is illustrated below:

   <Setting Name="AuditRecordClass" Type="xsd:string">org.bandit.otis.impl.OtisAuditRecord</Setting>

IMPORTANT NOTE: Whatever audit record class is specified here should also be specified for the IdAS context providers so that all audit logging is done the same. See the settings documentation for the JNDI Context Provider and the XML File Context Provider for instructions on how to do this.

Note that audit event records are logged to a logger named higgins.audit.events. If you are using log4j to do logging, the OTIS SDK also provides a log4j appender that will log the audit records to the XDAS Daemon. The appender class is org.bandit.otis.impl.OtisAuditAppender. This appender can be included in your log4j.properties file to cause audit events to be sent to the XDAS Daemon. The log4j settings to do this are illustrated below:

# Specify an appender for audit events.  All audit events are sent to the higgins.audit.events logger.
# We therefore create an appender for that logger.  We also set the additivity property of the
# logger to false, so that audit events will ONLY go to that appender.

log4j.logger.higgins.audit.events=trace, auditappender
log4j.additivity.higgins.audit.events=false
log4j.appender.auditappender=org.bandit.otis.impl.OtisAuditAppender

Audit Originator Settings

The originator of an audit record is the service that is detecting the audit-worthy event, and requesting the recording of the event. In the context of submitting events from within an instrumented application, the originator then is the identity under which the submitting application is acting, relative to the authority or security realm from which that identity is obtained. There are six settings that specify an audit event originator. All are of Type "xsd:string":

auditOrigLocationName. This setting contains the name of the host or service that is reporting the event. It may be as simple as host/service, for example: "waldo/apache".
auditOrigLocationAddress. This setting contains a communication service end point address, which may be a URL, or other type of address that fully specifies a connection point, for example: "http://waldo.mycorp.com".
auditOrigServiceType. This setting contains the protocol used by the originator location address (the auditOrigLocationName setting), for example: "http". One should, under ideal circumstances, be able to establish a communication channel to the originator using the combined data in this component and the originator location address.
auditOrigAuthAuthority. This setting contains the name of a server, or domain and realm that provides the identities involved in the associated events. A Unix host name is a good example of an authentication authority. Any service that manages an identity database with authoritative control of a security domain is a valid authentication authority, for example: "waldo".
auditOrigPrincipalName. This setting contains the user name relative to the originator authentication authority (the auditOrigAuthAuthority setting). For example, if the application is the Apache web server, then the originator principal name might be the name of the Unix user account under which Apache is running, or simply “root” if the Apache server is not running under any specific user account. This setting is optional.
auditOrigPrincipalIdentity. This setting contains the user id of the principal, relative to the authentication authority. In the example above using Apache, the root user ID might just be 0. On Win32 systems, this might be the GUID of the user under which IIS is running.

Below is an example of these settings. NOTE: these are the default settings that are shipped with the OTIS client, so it would be a good idea to change them to values appropriate for your system:

   <Setting Name="auditOrigLocationName" Type="xsd:string">localhost/otis</Setting>
   <Setting Name="auditOrigLocationAddress" Type="xsd:string">http://localhost</Setting>
   <Setting Name="auditOrigServiceType" Type="xsd:string">http</Setting>
   <Setting Name="auditOrigAuthAuthority" Type="xsd:string">localhost</Setting>
   <Setting Name="auditOrigPrincipalName" Type="xsd:string">otis</Setting>
   <Setting Name="auditOrigPrincipalIdentity" Type="xsd:string">otis</Setting>

otisEndpoint Setting

The Type for this Setting element is "htf:remoteEndPointHandler" (org.bandit.otis.impl.RemoteEndPointClient object). If specified, this contains the URL of the OTIS server the OTIS client is to connect to. For example:

   <Setting Name="otisEndpoint" Type="htf:remoteEndPointHandler">https://wag.bandit-project.org/otis</Setting>

NOTE: Even when connecting to an OTIS server, it is still necessary to specify a defaultContextId setting, because there is still a client-side IdAS component that must be configured.

Authentication Policy Settings

The the combination of the doAllAuthMethods setting and the authMethods setting define the authentication policy for OTIS. Authentication policy determines what authentication methods must be used for authentication. Policy may specify that various combinations of multiple authentication methods be used, including the order in which they must be used. This is sometimes referred to as multi-factor authentication. Multiple authentication methods may be essentially ANDed or ORed together. Standard boolean logic determines which methods must be executed. Below are some examples:

A and B and C. This states that ALL of three methods must be executed - A first, B second, and C third.
A or B or C. This states that ANY ONE of the three methods may be executed. If the client did not specify which one, OTIS will try A first, B second, and C third. It will stop when one of the methods works.
(A or B) and (C or D). This states that either method A or B must be executed, followed by either method C or D.
(A and B) or (C and D). This states that either A and B must be executed or C and D.

Multi-factor policy may be as complex as needed. Note that an AND may be thought of as ALL - all methods or method lists must be executed. An OR may be thought of as ANY - any one of the methods or method lists may be be executed.

authMethods Setting

The authMethods setting is of Type "htf:list". Each item in the list is an "htf:map" type which defines either an authentication method, or a nested child list. Note that the order of items in the list is important as it determines the sequence in which methods and child lists are tried.

If the list item is an authentication method, its Map will have the following sub-settings:

authMethodID. The Type for this Setting element is "xsd:string" (String). It is a URI that specifies the unique name of the authentication method.
authMethodClass. The Type for this Setting element is "xsd:string" (String). It is the name of the Java class that implements the IAuthMethod interface for the authentication method. Note that the "htf:instance" and "htf:classinstance" types are deliberately NOT used here, because we don't actually want an instance of the object instantiated in the settings map. Instances of the object are generated as needed when an authentication method is invoked.

If the list item is a child list, its Map will have the following sub-settings (note the nested use of the doAllAuthMethods and authMethods settings):

authMethods. This recursively defines a nested child list as specified in this section. Nesting of child lists may go to any depth.
doAllAuthMethods. This defines whether items in the child list should be ANDed or ORed (see below).

doAllAuthMethods Setting

The doAllAuthMethods Setting is of Type "xsd:boolean". It is always a sibling to the the authMethods setting setting. It specifies whether the list of items inside the authMethods setting should be ANDed (ALL) or ORed (ANY). A value of true means they are to be ANDed. A value of false means they are to be ORed. If the doAllAuthMethods setting is missing, the default value is false - which means that the items inside the authMethods setting will be ORed.

Example Authentication Policies

The following illustrates an authentication policy which is basically a selection of ANY ONE of four authentication methods (which happen to be the four that ship with OTIS). The items in this list are ORed together because there is no doAllAuthMethods setting that is a sibling to the authMethods setting:

   <!-- Define the default authentication methods that ship with OTIS -->

   <Setting Name="authMethods" Type="htf:list">
      <Setting Type="htf:map">
         <Setting Name="authMethodID" Type="xsd:string">urn:bandit-project:otis:authmethod:1.0:usernamePassword</Setting>
         <Setting Name="authMethodClass" Type="xsd:string">org.bandit.otis.impl.UsernamePasswordAuthMethod</Setting>
      </Setting>
      <Setting Type="htf:map">
         <Setting Name="authMethodID" Type="xsd:string">urn:bandit-project:otis:authmethod:1.0:anonymous</Setting>
         <Setting Name="authMethodClass" Type="xsd:string">org.bandit.otis.impl.AnonymousAuthMethod</Setting>
      </Setting>
      <Setting Type="htf:map">
         <Setting Name="authMethodID" Type="xsd:string">urn:bandit-project:otis:authmethod:1.0:infocard</Setting>
         <Setting Name="authMethodClass" Type="xsd:string">org.bandit.otis.impl.InfocardAuthMethod</Setting>
      </Setting>
      <Setting Type="htf:map">
         <Setting Name="authMethodID" Type="xsd:string">urn:bandit-project:otis:authmethod:1.0:samlpolicy</Setting>
         <Setting Name="authMethodClass" Type="xsd:string">org.bandit.otis.impl.SAMLPolicyAuthMethod</Setting>

         <!-- There are other settings for this particular authentication method, which would be specified here -->

      </Setting>
   </Setting>

Here is an example of policy (methodA and methodB) or methodC:

   <!-- The doAllAuthMethods setting of false is the OR between the items in the authMethods list.  This could
        be omitted since false is the default. -->

   <Setting Name="doAllAuthMethods" Type="xsd:boolean">false</Setting>

   <!-- This authMethods list has two items:
        1. (methodA and methodB)
        2. methodC
   -->

   <Setting Name="authMethods" Type="htf:list">

      <!-- (methodA and methodB) item -->

      <Setting Type="htf:map">

         <!-- the doAllAuthMethods setting of true defines the AND between methodA and methodB -->

         <Setting Name="doAllAuthMethods" Type="xsd:boolean">true</Setting>
         <Setting Name="authMethods" Type="htf:list">
            <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodA</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodA</Setting>
            </Setting>
            <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodB</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodB</Setting>
            </Setting>
         </Setting>
      </Setting>

      <!-- methodC item -->

      <Setting Type="htf:map">
         <Setting Name="authMethodID" Type="xsd:string">methodC</Setting>
         <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodC</Setting>
      </Setting>

   </Setting>

Here is an example of multi-factor policy (methodA and methodB) or (methodC and methodD):

   <!-- The doAllAuthMethods setting of false is the OR between the items in the authMethods list.  This could
        be omitted since false is the default. -->

   <Setting Name="doAllAuthMethods" Type="xsd:boolean">false</Setting>
   <Setting Name="authMethods" Type="htf:list">

      <-- (methodA and methodB) list -->

      <Setting Type="htf:map">

         <!-- The doAllAuthMethods of true is the AND between items in the authMethods list. -->

         <Setting Name="doAllAuthMethods" Type="xsd:boolean">true</Setting>
         <Setting Name="authMethods" Type="htf:list">

           <!-- methodA -->

           <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodA</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodA</Setting>
            </Setting>

            <!-- methodB -->

            <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodB</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodB</Setting>
            </Setting>

         </Setting>
      </Setting>

      <!-- (methodC and methodD) list -->

      <Setting Type="htf:map">

         <!-- The doAllAuthMethods of true is the AND between items in the authMethods list. -->

         <Setting Name="doAllAuthMethods" Type="xsd:boolean">true</Setting>
         <Setting Name="authMethods" Type="htf:list">

           <!-- methodC -->

           <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodC</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodC</Setting>
            </Setting>

            <!-- methodD -->

            <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodD</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodD</Setting>
            </Setting>

         </Setting>
      </Setting>

   </Setting>

Here is an example of multi-factor policy (methodA or methodB) and (methodC or methodD):

   <!-- The doAllAuthMethods setting of true is the AND between the items in the authMethods list. -->

   <Setting Name="doAllAuthMethods" Type="xsd:boolean">true</Setting>
   <Setting Name="authMethods" Type="htf:list">

      <!-- (methodA or methodB) list -->

      <Setting Type="htf:map">

         <!-- The doAllAuthMethods of false is the OR between items in the authMethods list.  It could
              be omitted, as false is the default. -->

         <Setting Name="doAllAuthMethods" Type="xsd:boolean">false</Setting>
         <Setting Name="authMethods" Type="htf:list">

            <!-- methodA -->

            <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodA</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodA</Setting>
            </Setting>

            <!-- methodB -->

            <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodB</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodB</Setting>
            </Setting>
         </Setting>

      </Setting>

      <!-- (methodC or methodD list -->

      <Setting Type="htf:map">

         <!-- The doAllAuthMethods of false is the OR between items in the authMethods list.  It could
              be omitted, as false is the default. -->

         <Setting Name="doAllAuthMethods" Type="xsd:boolean">false</Setting>
         <Setting Name="authMethods" Type="htf:list">

            <!-- methodC -->

            <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodC</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodC</Setting>
            </Setting>

            <!-- methodD -->

            <Setting Type="htf:map">
               <Setting Name="authMethodID" Type="xsd:string">methodD</Setting>
               <Setting Name="authMethodClass" Type="xsd:string">somepackage.AuthMethodD</Setting>
            </Setting>

         </Setting>
      </Setting>

   </Setting>

authMethodGatherers Setting

The authMethodGatherers setting is of Type "htf:map". It is used to specify Java classes which can handle gathering of authentication materials for authentication methods. Each entry in the Map is also a Map. The name of the setting must be an authentication method id which corresponds to the value of the authMethodID setting for an authentication method (see authMethods settings above).

Each Map must have at least a authMethodGathererClass setting. The Type for this Setting element is "xsd:string" (String). It is the name of the Java class that implements the IGatherAuthMaterial interface. Note that the "htf:instance" and "htf:classinstance" types are deliberately NOT used here, because we don't actually want an instance of the object instantiated in the settings map. Instances of the object are generated as needed when an gatherer method is invoked. Other settings may be included in the Map which are specific to the particular gatherer implementation. They will be passed to the instantiated gatherer object via a call to its configure method.

During authentication, when the OTIS client needs to gather authentication material for a particular authentication method, it will see if a gatherer class has been defined for the method. If no gatherer class is defined, the authentication will fail. NOTE: The OTIS client SDK allows an application to register gatherer classes for authentication methods at run-time. Thus, it is not necessary to define them in the configuration settings, although it is certainly convenient to do so. If an application registers a gatherer class at run-time for an authentication method, the run-time registered class takes precedence over any class that may have been defined in the configuration settings.

The following settings show how one might define gatherer classes for the username/password authentication method and the infocard authentication method. The gatherer class for the username/password method would presumably know how to collect a username and password as the authentication material. The gatherer class for the infocard method would presumably know how to collect an information card security token as the authentication material.

   <Setting Name="authMethodGatherers" Type="htf:map">

      <!-- Gatherer for the username/password authentication method. -->

      <Setting Name="urn:bandit-project:otis:authmethod:1.0:usernamePassword" Type="htf:map">
         <Setting Name="authMethodGathererClass" Type="xsd:string">somepackage.UsernamePasswordGatherer</Setting>

         <!-- Other settings for the UsernamePasswordGatherer class would go here -->

      </Setting>

      <!-- Gatherer for the infocard authentication method -->

      <Setting Name="urn:bandit-project:otis:authmethod:1.0:infocard" Type="htf:map">
         <Setting Name="authMethodGathererClass" Type="xsd:string">somepackage.InfocardTokenGatherer</Setting>

         <!-- Other settings for the InfocardTokenGatherer class would go here -->

      </Setting>

   </Setting>

ComponentSettings Setting

The Type for this Setting element is "htf:map" (java.util.Map). This contains a setting for each sub-component of OTIS that needs configuration. Each entry in the ComponentSettings map is itself a map, one per sub-component. Currently, the only sub-component is a component called "IdASRegistry". For example:

   <Setting Name="ComponentSettings" Type="htf:map">
      <Setting Name="IdASRegistry" Type="htf:map">
         <!-- Settings for the IdASRegistry would go here -->
      </Setting
   </Setting

IdASRegistry Setting

The Type for this Setting element is "htf:classsingleton". This setting MUST contain the name of the Java class which implements the IdASRegistry, which is org.eclipse.higgins.idas.registry.IdASRegistry. Settings for the IdASRegistry object are found in the IdASRegistry setting under the ComponentSettings setting (see above). In XML, the IdASRegistry Setting element MUST be specified AFTER the ComponentSettings Setting element, as follows:

   <Setting Name="IdASRegistry" Type="htf:classsingleton">org.eclipse.higgins.idas.registry.IdASRegistry</Setting>

More information on IdASRegistry settings:

Configuration Settings for IdAS Registry

Roles Setting

The Type for this Setting element is "htf:map" (java.util.Map). This setting contains role policy which is used to calculate active roles, assumable roles, and so forth. It is defined in more detail here. The following demonstrates what it looks like in XML code:

   <Setting Name="Roles" Type="htf:map">

      <!-- Role policy settings go here -->

   </Setting>

Download in other formats:

Plain Text