1. General OTIS Configuration
  2. Security Administrator's Guide
    1. Java Client Security
    2. Outward Facing Server Security
      1. Inactive Session Cleanup
      2. Preventing URL Injection Attacks
      3. Enhanced Client-to-Server Session Security
      4. Enabling/Disabling Anonymous Reads
      5. LDAP Injection Attacks
      6. White List of Attributes
      7. Cross-Site Scripting Attacks
      8. HTTPS versus HTTP
    3. Inward Facing Server Security
  3. XML File Configuration Format
    1. Setting Handlers
    2. Setting Elements
  4. Configuring OTIS Client in Java
  5. Configuration Settings for OTIS Client
    1. defaultContextId Setting
    2. lenientReauth Setting
    3. AuditRecordClass Setting
    4. Audit Originator Settings
    5. otisEndpoint Setting
    6. Authentication Policy Settings
      1. authMethods Setting
      2. doAllAuthMethods Setting
      3. Example Authentication Policies
    7. authMethodGatherers Setting
    8. ComponentSettings Setting
    9. IdASRegistry Setting
    10. Roles Setting
  6. Configuration Settings for OTIS Server
    1. LocalAuthSession Setting
    2. AllowInsecureChannel Setting
    3. SanitizeStrings Setting
    4. AttributeList Setting
    5. NounHandlers Setting
      1. GET_TemplateFile Setting
      2. GET_PropertiesTemplateFile Setting
      3. GET_ContextTemplateFile Setting
      4. GET_EntityTemplateFile Setting
      5. GET_AttributeTemplateFile Setting
      6. POST_TemplateFile Setting
      7. PUT_TemplateFile Setting
      8. EntityIDPolicy Setting
      9. SessionSecretBitSize Setting
      10. AuthSessionTimeout Setting
      11. AnonymousRead Setting
    6. Miscellaneous Noun Handler Information
      1. Resolving URLs to Noun Handlers
      2. Cookies and Nouns
      3. Session Secret
    7. AcceptMedia Setting
  7. Configuration Settings for Specific Authentication Methods
    1. SAML Policy Authentication Method Settings
      1. UseForOpen
      2. ValidateSAML
      3. JSSharedScope
      4. AuthMaterials
      5. AuthEntityId
      6. InjectEntity
      7. InjectEntityAttrMap
      8. ClearEntity

XML File Configuration Format

An XML file can be used to specify settings for both the OTIS client and an OTIS server. This page documents the format of an XML configuration file.

The XML file configuration format consists of a root element, where the XML namespaces are normally defined: 

<Configuration xmlns="http://higgins.eclipse.org/sts/Configuration"
	xmlns:htf="http://higgins.eclipse.org/sts/Configuration"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xsd:schemaLocation="http://higgins.eclipse.org/sts/Configuration Configuration.xsd ">

Note that the namespace for configuration elements is http://higgins.eclipse.org/sts/Configuration. In the example above, the namespace is defined as the default namespace for the document that follows. In addition, it is defined by using the "htf" prefix. In all of the examples below, elements are not prefixed - it should be assumed that the default namespace is as defined here.

There are two main child elements of the Configuration element: 

<Configuration...>
   <SettingHandlers>
      ...
   </SettingHandlers>

   <Setting ...>
   </Setting>
</Configuration>

Setting Handlers

The SettingHandlers element defines a set of Java classes that know how to convert setting values into Java objects. Child elements of the SettingHandlers element consist of SettingHandler elements, as illustrated below: 

   <SettingHandlers>
      <SettingHandler Type="htf:map" Class="java.util.Map" Handler="org.eclipse.higgins.configuration.xml.MapHandler"/>
      <SettingHandler Type="htf:list" Class="java.util.List" Handler="org.eclipse.higgins.configuration.xml.ListHandler"/>
      <SettingHandler Type="xsd:string" Class="java.lang.String" Handler="org.eclipse.higgins.configuration.xml.StringHandler"/>
      <SettingHandler Type="xsd:boolean" Class="java.lang.Boolean" Handler="org.eclipse.higgins.configuration.xml.BooleanHandler"/>
      <SettingHandler Type="xsd:int" Class="java.lang.Integer" Handler="org.eclipse.higgins.configuration.xml.IntegerHandler"/>
      <SettingHandler Type="xsd:anyURI" Class="java.net.URI" Handler="org.eclipse.higgins.configuration.xml.URIHandler"/>
      <SettingHandler Type="htf:file" Class="java.io.FileInputStream" Handler="org.eclipse.higgins.configuration.xml.FileHandler"/>
      <SettingHandler Type="htf:keystore" Class="java.security.KeyStore" Handler="org.eclipse.higgins.configuration.xml.KeyStoreHandler"/>
      <SettingHandler Type="htf:certificate" Class="java.lang.String" Handler="org.eclipse.higgins.configuration.xml.CertificateHandler"/>
      <SettingHandler Type="htf:privatekey" Class="java.security.PrivateKey" Handler="org.eclipse.higgins.configuration.xml.PrivateKeyHandler"/>
      <SettingHandler Type="htf:singleton" Class="java.lang.Object" Handler="org.eclipse.higgins.configuration.xml.SingletonHandler"/>
      <SettingHandler Type="htf:instance" Class="java.lang.Object" Handler="org.eclipse.higgins.configuration.xml.InstanceHandler"/>
      <SettingHandler Type="htf:classinstance" Class="java.lang.Object" Handler="org.eclipse.higgins.configuration.xml.ClassInstanceHandler"/>
      <SettingHandler Type="htf:classsingleton" Class="java.lang.Object" Handler="org.eclipse.higgins.configuration.xml.ClassSingletonHandler"/>
      <SettingHandler Type="htf:jscriptexec" Class="org.eclipse.higgins.util.jscript.JScriptExec" Handler="org.eclipse.higgins.util.idas.cp.jscript.JScriptExecSettingHandler"/>
      <SettingHandler Type="htf:jscriptscope" Class="org.eclipse.higgins.util.jscript.JScriptScope" Handler="org.eclipse.higgins.util.idas.cp.jscript.JScriptScopeSettingHandler"/>
      <SettingHandler Type="htf:include" Class="java.util.Map" Handler="org.eclipse.higgins.configuration.xml.IncludeHandler"/>
      <SettingHandler Type="htf:remoteEndPointHandler" Class="org.bandit.otis.impl.RemoteEndPointClient" Handler="org.bandit.otis.impl.RemoteEndPointClientHandler"/>
      <SettingHandler Type="htf:ref" Class="Object" Handler="org.eclipse.higgins.configuration.xml.ReferenceHandler"/>
   </SettingHandlers>

Each SettingHandler element has the following two attributes, a type and a handler class:

  • Type: This specifies a setting type that the handler class knows how to parse. When parsing a Setting element of this type (i.e., a Setting element with a matching Type attribute), the specified handler class is invoked to convert the Setting element's value into a Java object.
  • Class: This is the handler class that knows how to parse values of the specified type.

Most of the setting handlers shown above are the default set of handlers that are provided by the Higgins project. Handlers may be created as needed. The htf:remoteEndPointHandler setting handler is unique to OTIS. The default Higgins setting handlers are briefly described below:

  • htf:map: A Setting element of this type produces a java.util.Map object. The contents of this element is expected to be a list of child Setting elements. Each child Setting element becomes an entry in the produced Java Map object. The key value for the entry is Name attribute of the child Setting element, and the value is a Java object of the specified Type attribute of the child Setting element. This type, along with the "htf:list" type, allows settings to be nested.
  • htf:list: A Setting element of this type produces a java.util.List object. The contents of this element is expected to be a list of child Setting elements. Each child Setting element becomes an entry in the produced Java List object. The Name attribute of child Setting elements is ignored, but the value is a Java object of the specified Type attribute of the child Setting element. Note that entries in the produced List object are in the order of child Setting elements. This type, along with the "htf:map" type allow settings to be nested.
  • xsd:string: A Setting element of this type produces a String object. The contents of this element is expected to be a string.
  • xsd:boolean: A Setting element of this type produces a Boolean object. The contents of this element should be a "true" or "false" value.
  • xsd:int: A Setting element of this type produces an Integer object. The contents of this element should be an integer whose range of values is the Java int scalar type.
  • xsd:anyURI: A Setting element of this type produces a java.net.URI object. The contents of this element is expected to be a string that conforms to the syntax of a URI.
  • htf:file: A Setting element of this type produces a java.io.FileInputStream object. The contents of this element is expected to be a string containing a valid file name.
  • htf:keystore: A Setting element of this type produces a java.security.Keystore object. The contents of this element is expected to be child Setting elements with the following names and types:
    • Type: This child Setting element specifies the type of keystore. Its Type attribute must be "xsd:string". Currently, the only allowed value is "JKS".
    • File: This is the name of the file that contains the keystore. Its Type attribute must be "htf:file".
    • Password: This is the password for the keystore. Its Type attribute must be "xsd:string".
  • htf:certificate: A Setting element of this type produces a String object that contains a certificate. The contents of this element is expected to be child Setting elements with the following names and types:
    • KeyStoreName: This child Setting element specifies the name of a keystore this certificate comes from. Its Type attribute must be "xsd:string". The string value should reference a previously defined Setting element whose Type is "htf:keystore".
    • Alias: This is the alias for the certificate within the specified keystore. Its Type attribute must be "xsd:string".
  • htf:privatekey: A Setting element of this type produces a java.security.PrivateKey object. The contents of this element is expected to be child Setting elements with the following names and types:
    • KeyStoreName: This child Setting element specifies the name of a keystore this private key comes from. Its Type attribute must be "xsd:string". The string value should reference a previously defined Setting element whose Type is "htf:keystore".
    • Alias: This is the alias for the private key within the specified keystore. Its Type attribute must be "xsd:string".
    • Password: This is the password for the private key within the specified keystore. Its Type attribute must be "xsd:string".
  • htf:singleton: A Setting element of this type produces a singleton Java Object. The contents of this element is expected to be the name of a Java class factory that produces a Java singleton object. The class factory must implement the org.eclipse.higgins.configuration.api.IConfigurableComponentFactory interface and the org.eclipse.higgins.configuration.api.IConfigurableComponent interface. The Java object it produces must implement the org.eclipse.higgins.configuration.api.IConfigurableComponent interface. The class factory's getSingletonInstance method is called to produce the Java object. The Java object's configure method is then called to pass in settings to the object. The settings for the object are obtained by looking for a previously defined sibling Setting element whose Name attribute is ComponentSettings, and then looking for a Setting element that is a child to the ComponentSettings element whose name matches this Setting element. The child Setting element is expected to be of the type "htf:map". This relationship is illustrated below: 
   <Setting Name="ComponentSettings" Type="htf:map">
      <Setting Name="MySingletonObject" Type="htf:map">
         <!-- This should contain settings for the "MySingletonObject" defined below -->
      </Setting>
   </Setting>
   <Setting Name="MySingletonObject" Type="htf:singleton">org.mycorp.MySingletonObjectFactory</Setting>
  • htf:instance: A Setting element of this type produces a Java Object. The contents of this element is expected to be the name of a Java class factory that produces a Java Object. The class factory must implement the org.eclipse.higgins.configuration.api.IConfigurableComponentFactory interface and the org.eclipse.higgins.configuration.api.IConfigurableComponent interface. The Java object it produces must implement the org.eclipse.higgins.configuration.api.IConfigurableComponent interface. The class factory's getNewInstance method is called to produce the Java object. The Java object's configure method is then called to pass in settings to the object. The settings for the object are obtained by looking for a previously defined sibling Setting element whose Name attribute is ComponentSettings, and then looking for a Setting element that is a child to the ComponentSettings element whose name matches this Setting element. The child Setting element is expected to be of the type "htf:map". This relationship is illustrated below: 
   <Setting Name="ComponentSettings" Type="htf:map">
      <Setting Name="MyInstanceObject" Type="htf:map">
         <!-- This should contain settings for the "MyInstanceObject" defined below -->
      </Setting>
   </Setting>
   <Setting Name="MyInstanceObject" Type="htf:singleton">org.mycorp.MyInstanceObjectFactory</Setting>
  • htf:classsingleton. A Setting element of this type produces a singleton Java Object. The contents of this element is expected to be the name of the Java class to be instantiated. This type is very similar to the htf:singleton type, except that no class factory is used. Instead, a singleton for the target class is instantiated by calling the getInstance method of the class (which is expected to be a static method that returns a singleton instance of the class). The class is also expected to implement the org.eclipse.higgins.configuration.api.IConfigurableComponent interface so that it has a configure method. Once instantiated, the Java object's configure method is then called to pass in settings to the object. The settings for the object are obtained by looking for a previously defined sibling Setting element whose Name attribute is ComponentSettings, and then looking for a Setting element that is a child to the ComponentSettings element whose name matches this Setting element. The child Setting element is expected to be of the type "htf:map". This relationship is illustrated below: 
   <Setting Name="ComponentSettings" Type="htf:map">
      <Setting Name="MySingletonObject" Type="htf:map">
         <!-- This should contain settings for the "MySingletonObject" defined below -->
      </Setting>
   </Setting>
   <Setting Name="MySingletonObject" Type="htf:singleton">org.mycorp.MySingletonObject</Setting>
  • htf:classinstance. A Setting element of this type produces a Java Object. The contents of this element is expected to be the name of the Java class to be instantiated. This type is very similar to the htf:instance type, except that no class factory is used. Instead, an instance for the target class is instantiated by calling the newInstance method of the class. The class is also expected to implement the org.eclipse.higgins.configuration.api.IConfigurableComponent interface so that it has a configure method. Once instantiated, the Java object's configure method is then called to pass in settings to the object. The settings for the object are obtained by looking for a previously defined sibling Setting element whose Name attribute is ComponentSettings, and then looking for a Setting element that is a child to the ComponentSettings element whose name matches this Setting element. The child Setting element is expected to be of the type "htf:map". This relationship is illustrated below: 
   <Setting Name="ComponentSettings" Type="htf:map">
      <Setting Name="MyInstanceObject" Type="htf:map">
         <!-- This should contain settings for the "MyInstanceObject" defined below -->
      </Setting>
   </Setting>
   <Setting Name="MyInstanceObject" Type="htf:singleton">org.mycorp.MyInstanceObject</Setting>
  • htf:jscriptexec. A Setting element of this type produces a org.eclipse.higgins.util.jscript.JScriptExec object. The contents of this element is expected to be Javascript. The purpose of the Javascript is specific to the Setting, as are the names and types of parameters passed into the script.
  • htf:jscriptscope. A Setting element of this type produces a org.eclipse.higgins.util.jscript.JScriptScope object. The contents of this element is expected to be Javascript. The purpose of the Javascript is specific to the Setting, as are the names and types of parameters passed into the script. The primary difference between an htf:jscriptexec Setting element and an htf:jscriptscope Setting element is that anything defined in an htf:jscriptscope Setting element is shared with any htf:jscriptexec Setting elements that are defined later. A htf:jscriptscope Setting element is NOT visible to previously defined htf:jscriptexec Setting elements, only later ones.
  • htf:include. A Setting element of this type produces a java.util.Map object. The contents of this element is expected to be a file name that is another XML configuration file. The settings map produced by that file becomes the value of this setting. The file specified must be in the same directory as the XML configuration file that contains this Setting element.
  • htf:ref. The contents of this element is expected to be a simple path to another setting element. The element produced by de-referencing that value becomes the value of this setting. This setting also has the same type as the referenced element.
    • Sample <Setting Name="JSSharedScope" Type="htf:ref">/JSSharedScope</Setting> results in an element named JSSharedScope, with the element named JSSharedScope being read from the root of the configuration tree.

Setting Elements

The XML configuration file is expected to have one Setting element that is a child to the root Configuration element. That Setting element can have one or many child Setting elements. Each Setting element contains three things:

  • Type attribute. The Type attribute specifies the type of data expected in the setting. It should correspond to one of the SettingHandler elements specified under the SettingHandlers element. That is, its value should match the value of the Type attribute of one of the SettingHandler elements. This tells the parser what kind of Java object should be produced from the setting's content.
  • Name attribute. The Name attribute gives the setting a name. This is only used if the Setting element is a child element of a Setting element whose Type attribute is "htf:map". This is the key for looking up the setting within the parent Setting element. If the parent Setting element is an "htf:map" type, this name must be unique within the set of the parent's child Setting elements.
  • Element content. The content is converted to a java object as specified by the Type attribute.

An XML configuration file produces a single java.util.Map object. It is built from the first Setting element it encounters, which is expected to have a Type attribute of "htf:map". Nesting of settings is accomplished using Setting elements whose Type attribute is either "htf:map" or "htf:list". Below is an illustration of a complete XML settings document: 

<Configuration...>
   <SettingHandlers>
      <SettingHandler Type="htf:map" Class="java.util.Map" Handler="org.eclipse.higgins.configuration.xml.MapHandler"/>
      <SettingHandler Type="htf:list" Class="java.util.List" Handler="org.eclipse.higgins.configuration.xml.ListHandler"/>
      <SettingHandler Type="xsd:string" Class="java.lang.String" Handler="org.eclipse.higgins.configuration.xml.StringHandler"/>
      <SettingHandler Type="xsd:boolean" Class="java.lang.Boolean" Handler="org.eclipse.higgins.configuration.xml.BooleanHandler"/>
      <SettingHandler Type="xsd:anyURI" Class="java.net.URI" Handler="org.eclipse.higgins.configuration.xml.URIHandler"/>
   </SettingHandlers>

   <!-- This is the main Setting element for the file.  Note that it's Name attribute really doesn't matter.  It's Type attribute is required to be "htf:map" -->

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

      <!-- This illustrates a nested Setting that produces a java.util.Map object.  Note that each child Setting element must have a unique name.  Note also that
           the child Setting elements do NOT all need to be the same type of object. -->

      <Setting Name="NestedSetting" Type="htf:map:>
         <Setting Name="UniqueName1" Type="xsd:string">some value for this setting</Setting>
         <Setting Name="UniqueName2" Type="xsd:boolean">true</Setting>
         <Setting Name="UniqueName3" Type="xsd:anyURI">http://mycorp.org/stuff</Setting>
      </Setting>

      <!-- This illustrates a nested Setting that produces a java.util.List object.  The names of child Setting elements here are ignored, so they don't
           need to be unique.  Note how each object in the list is a Map that contains an address consisting of a City and State setting.  One of the
           objects is simply a string - which illustrates that all of the objects in a List do NOT need to be the same type. -->

      <Setting Name="ListOfAddresses" Type="htf:list">
         <Setting Name="Address" Type="htf:map">
            <Setting Name="City" Type="xsd:string">San Francisco</Setting>
            <Setting Name="State" Type="xsd:string">California</Setting>
         </Setting>
         <Setting Name="Address" Type="htf:map">
            <Setting Name="City" Type="xsd:string">Cheyenne</Setting>
            <Setting Name="State" Type="xsd:string">Wyoming</Setting>
         </Setting>
         <Setting Name="Address" Type="xsd:string>Portland, Oregon</Setting>
      </Setting>
   </Setting>
</Configuration>