Context Navigation

Deploying an OTIS Server

This page describes how to deploy an OTIS Server. An OTIS server is a .war file that you must either download or create, deploy, and then configure.

Downloading or Creating a .war File

To obtain a .war file, you must either download it or create your own. These two options are described in the following sections.

Downloading a .war File

The OTIS server is a web application written in Java. It is a .war file that can be downloaded from the OTIS download page. The .war file name is otis-<version>.war (where <version> is the version number). For example: otis-1.0.0.war.

Creating Your Own .war File

While the otis-<version>.war file comes pre-configured (see below) to work on a system where the host name is example.org, and uses an LDAP server on the localhost as the backing data store, you will likely have to make some minor changes to the configuration file after it has been deployed. You can also create your own .war file that has your preferred settings correctly configured out-of-the-box. To do this, you can either check out the otis source (see CodeAndDownloads), or download the [otis tar].

At the root of the project is a file called build.xml. This is used (by Ant) to create various .war files. The .war file targets used by the OTIS project are in an included build file called otis.war.targets.xml. You can also create a file named other.targets.xml. This file and the file's targets are automatically included in build.xml.

Configuration options that tend to change from deployment to deployment are specified as tokens in various configuration files that look like: @TOKEN.NAME@. When a specific war target is built, that target replaces these tokens with values specific for the deployment scenario for that .war file. If you want to create a custom war file, you create a file at the root of the project named other.targets.xml with a target similar to what is shown below, and then run ant mywar.

<target name="samplewar">
   <!-- This creates a properties file which will be used to do the token replacement when -copy.warconfigs gets called -->
   <concat destfile="${out.config.root.dir}/filter.properties">
      # This specifies where the configuration files will be located
      SERVER.CONF.DIR=myotis
      # This configures the LDAP server used by the OTIS server (when the backing CP is org.eclipse.higgins.idas.cp.jndi and it's talking to an LDAP backend)
      LDAP.SERVER.ADDR=ldap://localhost:389
      # These configure security settings for the server
      SESSION.SECRET.BITSIZE=0
      ALLOW.INSECURE.CHANNEL=true
   </concat>
   <fileset id="war.cp.fileset" dir="${lib.dir}/cp-jndi" includes="*.jar" />

   <!-- This sets the name of the war file -->
   <property name="project.war.file" value="myotis.war" />

   <!-- This copies and transforms the config files -->
   <antcall target="-copy.warconfigs" />

   <!-- This builds the war file -->
   <antcall target="-warbuilder" />
</target>

Deploying OTIS

To deploy the OTIS server, follow the steps in "Deploying As a Tomcat Application on Linux". Or, if you want to skip this task, follow the steps in "Quickstart" to quickly deploy a sample OTIS server.

Quickstart

This section is broken into two subsections, both allow you to skip the task configuring the server. In the first, you can find out how to get OTIS up and running with no dependency on having a web app server already installed. It uses an embedded version of Glassfish to host the server. The second section shows you how to deploy an OTIS war file into an existing web app server environment but requires no configuration.

Standalone Glassfish Deployment

To run a sample OTIS server using embedded Glassfish:

Ensure that you have Ant installed.
Download this [otis tar file].
Untar the file by running the following command from the command line:
```
tar -xf otis-1.0.0.tar
```
Run the following command from the command line:
```
ant startOTIS
```

NOTE: The service runs until you kill it.

The OTIS server is now running on the localhost. The OTIS server is backed by an LDAP server (also running on the localhost). To test this, from a new console run:

curl -c cookies.txt -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\
<otis:Authenticate xmlns:otis=\"http://code.bandit-project.org/schemas/2008/otis\"\
                 methodID=\"urn:bandit-project:otis:authmethod:1.0:usernamePassword\">\
   <otis:AuthMaterial materialID=\"urn:bandit-project:otis:authmaterial:1.0:usernamePassword\" mustGatherAllChildren=\"true\">\
      <otis:AuthChildMaterials>\
         <otis:AuthMaterial materialID=\"urn:bandit-project:otis:authmaterial:1.0:username\">\
            <otis:AuthMaterialValue Type=\"string\">otisTest</otis:AuthMaterialValue>\
         </otis:AuthMaterial>\
         <otis:AuthMaterial materialID=\"urn:bandit-project:otis:authmaterial:1.0:password\">\
            <otis:AuthMaterialValue Type=\"string\">otisTest</otis:AuthMaterialValue>\
         </otis:AuthMaterial>\
      </otis:AuthChildMaterials>\
   </otis:AuthMaterial>\
</otis:Authenticate>" http://127.0.0.1:9997/otis-test/AuthenticatedSession

You are now authenticated as the user "otisTest". To read that entity, run the following command:

curl -b cookies.txt http://127.0.0.1:9997/otis-test/Entity/otistest

Simple Pre-configured Deployment

To deploy sample OTIS server into an existing web application server:

Download this [otis war file].
Rename the war file to an appropriate name (we'll assume you name it otis.war)
Deploy into your web app server as you would any other war file
1. See instructions below for help with Tomcat and Apache

A simple way to test the deployment is to run the [HelloWorld] sample application.

Deploying As a Tomcat Application On Linux

To deploy a .war file:

1. Ensure that you have already installed Tomcat on your Linux server.

We are assuming Tomcat5.

2. Access the Tomcat management page by specifying the following URL in your web browser:

http://<yourservername>:8080

For example:

http://wag.bandit-project.org:8080

The Tomcat Administration welcome page is launched.

3. On the left of the page, click Tomcat Manager.

You might be prompted to log in with your Tomcat manager name and password. Tomcat users are defined in a file on the server called $CATALINA_HOME/conf/tomcat-users.xml, where $CATALINA_HOME is the root of the Tomcat installation directory. In this file, look for a user who has the role of 'manager'.

After you are at the management page, there are a couple of options you can use to deploy a .war file. The .war file you want to deploy is the otis-<version>.war file that you either downloaded or created. We recommend deploying it with the the web application name of otis.

4. Use either of the following methods to deploy the .war file:

The simplest method is to upload the .war file from your workstation by using the "Select WAR file to upload" input box in the "WAR file to deploy" section. Rename the .war file to whatever you would like your web application to be named. If you follow the Apache Connector instructions, of course, you need to name the .war file name so that it matches the JkMount directive.
The "Deploy directory or WAR file located on server" method is usable, but you cannot use the "WAR or Directory URL" input box, because it does not automatically unpack the .war file, which is required by the OTIS install. You can, however, use the "XML Configuration file URL" input box to specify deployment instructions that allow the OTIS install to complete successfully. The "unpackWAR" option on your Tomcat Context XML Configuration file should be set to "true". For example, if you are deploying version 1.0.0 of the OTIS server and want your application to be called "otis", your Context XML Configuration file should look something like the following:
```
<?xml version='1.0' encoding='utf-8'?>
<Context docBase="/srv/ftp/otis-1.0.0.war" path="/otis" unpackWAR="true" />
```
This Context Configuration XML file needs to be located on the server, just as the OTIS .war file will. In the "XML Configuration file URL" input box, you must specify the location of your Context Configuration XML file using a "file:/" scheme. For example, if your file is called "otis.xml" and is located in /srv/ftp, you must specify "file:/srv/ftp/otis.xml" in the input box, and then click the "Deploy" button.

Instead of using the Tomcat management page, copy the otis .war file to the appropriate directory on your server where Tomcat applications are deployed. For example: /srv/www/tomcat5/base/webapps. Tomcat automatically detects that you have dropped a new .war file into the webapps directory. It then unpacks it and starts it. The application is given the same name as the .war file, so ensure that you copy it to the otis.war file (if you want the OTIS server application to be called "otis").

Apache Connector

When using Tomcat with Apache, you need to use the mod_jk plug-in. This plug-in handles communication between Tomcat and Apache.

You must add the following directive to the /etc/apache2/conf.d/jk.conf file:

JkMount /otis/* default

The JkMount directive specifies which URI contexts are sent to Tomcat. The mod_jk module supplies the code that enables the different Tomcat workers. In the above example, we specified a context path for otis. If you name your OTIS server something other than otis, then when you deployed it (see above), you must specify that name instead.

For more detailed information about the Tomcat Apache connector and how to set it up, see the Tomcat Apache Connector Website

Java 1.6 or Later

If you are using Java 1.6 or later, you might experience problems; this is because between Java 1.5 and 1.6, changes have been made to this method:

  javax.xml.stream.XMLOutputFactory newInstance( String, ClassLoader);

You can bypass the Java 1.6 implementation of this method by copying the stax-api-1.0.1.jar file from the otis directory to a (possibly new) directory within your Tomcat installation directory called <CATALINA_HOME>/common/endorsed.

Enabling Strong Encryption

On some platforms, the Java JVM might not be set up to allow strong encryption. Some functionality in OTIS requires strong encryption (AES 256 minimum). You should ensure that you have policy .jar files that allow strong encryption. Specifically, look for the following files in the jvm's jre/lib/security directory:

US_export_policy.jar local_policy.jar

The versions of these .jar files that allow strong encryption can be found here.

If you see the following error, then your encryption is not strong enough, and you need to click the link above to update your .jar files.

  Exception org.apache.xml.security.encryption.XMLEncryptionException decrypting token DOM: 
    Illegal key size Original Exception: 
      java.security.InvalidKeyException: Illegal key size

Miscellaneous Issues

Following is a list of miscellaneous issues that have been discovered as people have deployed the OTIS server on various versions of Linux:

Starting Tomcat With -security Option: On some systems, the default Tomcat installation is set up to start Tomcat with a -security option. This means that the security policy found in $CATALINA_BASE/conf/catalina.policy is enforced. However, this causes problems for Tomcat when it loads the servlet class. It gets an error complaining that there is no RuntimePermission for !createClassLoader. In theory, you should be able to edit catalina.policy to grant the needed permission. However, we have not yet had time to figure out how to do this. Our current recommendation is to simply start Tomcat without the -security option. If anyone figures out how to modify catalina.policy correctly, please let us know, or feel free to modify this wiki page.
Jar Files in $CATALINA_BASE/common/endorsed: The .jar files in this directory take precedence over .jar files deployed from the .war file. Sometimes the .jar files in $CATALINA_BASE/common/endorsed are not compatible with the versions we supply in the .war file; sometimes they are older versions. This can cause a problem at run time. If you discover a conflict, you can move the files in $CATALINA_BASE/common/endorsed to $CATALINA_BASE/common/lib. They are then still available to other applications that might be using them, but not as a first resort.

Configuring OTIS

OTIS must be properly configured in order to service requests. OTIS is configured using XML files, beginning with web.xml. On the OTIS Documentation page there is a section called "Configuration Documentation". This section contains general instructions for setting up an XML configuration file, as well as specific instructions for configuring the OTIS web application. It is a rather complex thing to do, so in the .war file we have included three configuration files that you can modify and use. These are described in the following sections:

web.xml

This is the Tomcat configuration file for the OTIS server application. It is found in the WEB-INF subdirectory where the otis application was installed on your server. For example: .../webapps/otis/WEB-INF/web.xml. There are two context parameters that tell OTIS where to find its various configuration files. These are as follows:

org.bandit.otis.server.conf.dir: This parameter's value should be a directory on your server where you will put OTIS configuration files. The directory must already exist, and must be given read/write/execute permissions that allow the OTIS application to access files there.
org.bandit.otis.server.conf.file: This parameter's value is the file name in the configuration directory that is the primary OTIS configuration file. The .war file comes with a pre-configured file called otis-config.server.xml. We recommend using this file and copying it out to the specified configuration directory. You should not need to make any changes to this file.

Below is an example of these parameters in the web.xml file:

   <context-param>
      <param-name>org.bandit.otis.server.conf.dir</param-name>
      <param-value>/usr/share/java/otis-config</param-value>
      <description>
         The OTIS configuration directory
      </description>
   </context-param>
   <context-param>
      <param-name>org.bandit.otis.server.conf.file</param-name>
      <param-value>otis-config.server.xml</param-value>
      <description>
         The OTIS configuration file.
      </description>
   </context-param>

otis-config.server.xml

This is the primary configuration file for OTIS. It should be placed in the directory specified by the org.bandit.otis.server.conf.dir context parameter in the web.xml file (see above). Make sure that it has read permission for the OTIS server to read it. If desired, you can change the name of the file by changing the value of the org.bandit.otis.server.config.file context parameter in the web.xml file (see above). The OTIS .war file contains a preconfigured otis-config.server.xml file that you do not need to modify in order to use. Of course, you are free to create your own, but this is not recommended.

otis-config.client.local.xml

This is the secondary configuration file for OTIS. It should be placed in the directory specified by the org.bandit.otis.server.conf.dir context parameter in the web.xml file (see above). ensure that it has read permission for the OTIS server to read it. The name of this file is specified in the LocalAuthSession setting in the otis-config.server.xml file. For more information on the LocalAuthSession setting, see LocalAuthSessionSetting.

This file requires you to make some changes. It contains settings for the identity store backend, authentication method configuration, role configuration, attribute mappings, and so forth. It comes preconfigured to work with an LDAP directory with some fairly decent default settings. If you have an LDAP directory, you can make some minor changes to point it to your LDAP directory, and be ready to try some things in only a few minutes (see the documentation on A Simple LDAP Deployment below).

For detailed information on the settings in this file, start with the documentation on the LocalAuthSession Setting in the otis-config.server.xml file and follow its links.

A Simple LDAP Deployment

The OTIS server .war file comes preconfigured to use an LDAP directory as its back-end identity store. It assumes that most user objects of interest are in a single container in the directory. Note that this is just one simple configuration option; it is in no way meant to be limited to that type of setup.

You can make a few minor modifications to the otis-config.client.local.xml file to have it point to your LDAP server and be up and running in only a few minutes. The changes that need to be made are in the configuration settings for the JNDI context provider, which is found inside the settings for the IdAS registry, which is one of the components inside the ComponentSettings element, illustrated below:

 1)   <Setting Name="ComponentSettings" Type="htf:map">
 2)      ...
 3)      <Setting Name="IdASRegistry" Type="htf:map">
 4)         ...
 5)         <Setting Name="ContextIdsList" Type="htf:list">
 6)            ...
 7)            <Setting Name="urn:Corporate-LDAP-Server" Type="htf:map">
 8)               ...
 9)               <Setting Name="Connection" Type="htf:map">
10)                  ...
11)                  <Setting Name="AddressList" Type="htf:list">
12)                     <Setting Name="Address" Type="xsd:string">ldap://localhost:50389</Setting>
13)                  </Setting>
14)                  <Setting Name="jndiProvider" Type="xsd:string">com.sun.jndi.ldap.LdapCtxFactory</Setting>
15)                  <Setting Name="searchBase" Type="xsd:string">ou=people,o=bandit</Setting>
16)               </Setting>
17)               ...
18)               <Setting Name="env" Type="htf:map">
19)                  <Setting Name="java.naming.security.authentication" Type="xsd:string">simple</Setting>
20)                  <Setting Name="java.naming.security.principal" Type="xsd:string">cn=admin,o=bandit</Setting>
21)                  <Setting Name="java.naming.security.credentials" Type="xsd:string">admin</Setting>
22)               </Setting>
23)               ...
24)               <Setting Name="JSPolicyAction" Type="htf:map>
25)                  <Setting Name="JSSharedScope" Type="htf:jscriptscope">
26)                     <!-- Javascript goes here -->
27)                  </Setting>
28)                  <Setting Name="consumerEntityIDToProvider" Type="htf:jscriptexec">
29)                     <!-- Javascript goes here -->
30)                  </Setting>
31)                  <Setting Name="providerEntityIDToConsumer" Type="htf:jscriptexec">
32)                     <!-- Javascript goes here -->
33)                  </Setting>
34)                  <Setting Name="consumerEntityTypeToProvider" Type="htf:jscriptexec">
35)                     <!-- Javascript goes here -->
36)                  </Setting>
37)                  <Setting Name="providerEntityTypeToConsumer" Type="htf:jscriptexec">
38)                     <!-- Javascript goes here -->
39)                  </Setting>
40)                  <Setting Name="consumerAIDToProvider" Type="htf:jscriptexec">
41)                     <!-- Javascript goes here -->
42)                  </Setting>
43)                  <Setting Name="providerAIDToConsumer" Type="htf:jscriptexec">
44)                     <!-- Javascript goes here -->
45)                  </Setting>
46)                  <Setting Name="consumerAValueToProvider" Type="htf:jscriptexec">
47)                     <!-- Javascript goes here -->
48)                  </Setting>
49)                  <Setting Name="providerAValueToConsumer" Type="htf:jscriptexec">
50)                     <!-- Javascript goes here -->
51)                  </Setting>
52)               </Setting>
53)               ...
54)            </Setting>
55)            ...
56)         </Setting>
57)         ...
58)      </Setting
59)      ...
60)   </Setting>

The first change to the above settings is to modify the LDAP address setting to point to your LDAP server. In the example above, it is line #12 that needs to be modified:

12)                     <Setting Name="Address" Type="xsd:string">ldap://localhost:50389</Setting>

The ldap://localhost:50389 value should be changed to point to your LDAP server.

The next change is to line 15:

15)                  <Setting Name="searchBase" Type="xsd:string">ou=people,o=bandit</Setting>

This setting holds the DN of a container where your user objects are stored. Change the value ou=people,o=bandit to specify the DN of your container.

The next change is to lines 20 & 21:

20)                  <Setting Name="java.naming.security.principal" Type="xsd:string">cn=admin,o=bandit</Setting>
21)                  <Setting Name="java.naming.security.credentials" Type="xsd:string">admin</Setting>

These two lines are basically a user ID (the "java.naming.security.principal" setting) and password (the "java.naming.security.credentials" setting) that identify a least-privileged user. This information is only used when or if OTIS needs to use a least-privileged user to access the directory. A least-privileged user is one that has the minimal set of rights needed to read your user objects. It does this for some kinds of authentication.

In addition to these changes, you might want to make changes to the settings that control attribute name mappings between IdAS and LDAP, as well as mapping between IdAS user IDs to DNs. These are explained and illustrated in the following sections. Note that all of these settings are children of the JSPolicyAction setting (line 24 above).

Username to DN Mapping

There are two settings that control mapping of usernames to DNs (the consumerEntityIDToProvider setting, as shown in line 28 above) and DNs to usernames (the providerEntityIDToConsumer setting, as shown in line 31 above). These settings contain javascript that does the mapping. With javascript it is possible to do many sophisticated kinds of mappings. For an in-depth explanation of the consumerEntityIDToProvider setting and how to use it, see here. For an in-depth explanation of the providerEntityIDToConsumer setting and how to use it, see here.

The default configuration operates on a very simple assumption: that all of the user objects you care about reside in a single container in your LDAP directory. Note that this is NOT a limitation, it's simply the way the default LDAP configuration is set up. You can change it however you like, but to get started, the simplest change is to change the LDAP container name. The default configuration shown below assumes an LDAP container name of ou=people,o=bandit.

 1)   <Setting Name="consumerEntityIDToProvider" Type="htf:jscriptexec">
 2)      <![CDATA[
 3)      if ((consumerID.length >= 3 && consumerID.slice( 0, 3) == "cn=") ||
 4)          (consumerID.length >= 3 && consumerID.slice( 0, 3) == "CN=") ||
 5)          (consumerID.length >= 3 && consumerID.slice( 0, 3) == "dc=") ||
 6)          (consumerID.length >= 3 && consumerID.slice( 0, 3) == "DC=") ||
 7)          (consumerID.length >= 3 && consumerID.slice( 0, 3) == "ou=") ||
 8)          (consumerID.length >= 3 && consumerID.slice( 0, 3) == "OU=") ||
 9)          (consumerID.length >= 4 && consumerID.slice( 0, 4) == "uid=") ||
10)          (consumerID.length >= 4 && consumerID.slice( 0, 4) == "UID="))
11)      {
12)         /* Application passed in a DN probably - don't change it */
13)         map = consumerID;
14)      }
15)      else
16)      {
17)         /* Tack on the right stuff to make a DN in the ou=people,o=bandit container */
18)         map = "cn=" + consumerID + ",ou=people,o=bandit";                              // CHANGE THIS LINE
19)      }
20)      RESULT = map;
21)      ]]>
22)   </Setting>
23)   ...
24)   <Setting Name="providerEntityIDToConsumer" Type="htf:jscriptexec">
25)      <![CDATA[
26)      var re = new RegExp("^cn=(.*),ou=people,o=bandit$", "i");                        // CHANGE THIS LINE
27)      RESULT = String(providerID.toString()).replace(re, "$1");
28)      ]]>
29)   </Setting>

You need to change the ou=people,o=bandit to your actual LDAP container name. (Lines 18 and 26 in the above example.)

The JSSharedScope Setting

The JSSharedScope setting is somewhat unique in that it is shared with the other javascript settings that follow it.(consumerEntityTypeToProvider, providerEntityIDToConsumer, and so forth. See lines 28 to 51 in the overall example above.) For an in-depth explanation of the JSSharedScope setting and how it is used in conjunction with these other settings, see documentation here. In the default configuration, the JSSharedScope setting is used to define a multimap variable that is used as a lookup table for two kinds of mappings:

Entity type to object class mappings (and vice versa)
Attribute name to LDAP attribute name mappings (and vice versa)

You will see how the multimap table is used to do this in later sections. The JSSharedScope javascript that sets up the multimap variable is shown below:

 1)   <Setting Name="JSSharedScope" Type="htf:jscriptscope">
 2)      <![CDATA[
 3)      var multimap = {
 4)                      consumer: [],
 5)                      provider: []
 6)                     };
 7)
 8)      /* Map standard information card claim names */
 9)
10)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"] =
11)         ["givenName"];
12)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"] =
13)         ["sn"];
14)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"] =
15)         ["mail"];
16)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress"] =
17)         ["street"];
18)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/locality"] =
19)         ["localityName"];
20)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/stateorprovince"] =
21)         ["st"];
22)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/postalcode"] =
23)         ["postalcode"];
24)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country"] =
25)         ["countryname"];
26)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/homephone"] =
27)         ["homephone"];
28)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/otherphone"] =
29)         ["otherphone"];
30)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone"] =
31)         ["mobilephone"];
32)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth"] =
33)         ["dateofbirth"];
34)      multimap.consumer["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender"] =
35)         ["gender"];
36)
37)      /* Map some standard Higgins entity types and attribute names to LDAP names */
38)
39)      multimap.consumer["http://www.eclipse.org/higgins/ontologies/2006/higgins#Person"] =
40)         ["inetOrgPerson"];
41)      multimap.consumer["http://www.eclipse.org/higgins/ontologies/2006/higgins#password"] =
42)         ["userPassword"];
43)      multimap.consumer["http://www.eclipse.org/higgins/ontologies/2006/higgins#cardKeyHash"] =
44)         ["cardKeyHash"];
45)      multimap.consumer["http://www.eclipse.org/higgins/ontologies/2006/higgins#cardKeyHashInfo"] =
46)         ["cardKeyHashInfo"];
47)
48)      /* Produce the reverse mapping: LDAP name -> standard information card or Higgins name */
49)
50)      for (elem in multimap.consumer)
51)      {
52)         for (provider in multimap.consumer[elem])
53)            multimap.provider[multimap.consumer[elem][provider]] = elem;
54)      }
55)      ]]>
56)   </Setting>

To add a new mapping, simply add an appropriate entry to the multimap table. It is self-evident how this is done. To remove a mapping, remove the appropriate lines from the table. For example, lines 12 and 13 provide a mapping between the IdAS attribute name of "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" and the LDAP attribute name of sn. To delete this mapping, simply delete lines 12 and 13. To modify a mapping, simply change the desired lines.

Entity Type to Object Class Name Mapping

The setting that controls mapping of IdAS entity types to LDAP object classes is the consumerEntityTypeToProvider setting (see line 34 in the overall example above). The setting that controls mapping of object classes to IdAS entity types is the providerEntityTypeToConsumer setting (see line 37 in the overall example above). These settings contain javascript that does the mapping. With javascript it is possible to do all kinds of sophisticated kinds of mappings. For an in-depth explanation of the consumerEntityTypeToProvider setting and how to use it, see here. For an in-depth explanation of the providerEntityTypeToConsumer setting and how to use it, see here.

The reason to have a entity type mapping functions is that an application wants to use consistent, standard IdAS entity types. These need to be mapped to appropriate LDAP object classes. In the javascript given below, a keyed array called multimap.consumer (see line 3) is used to lookup the IdAS entity type and produce an object class, and a keyed array called multimap.provider (see line 15) is used to lookup object class and produce the IdAS entity type. In essence, the multimap variable (see here for an explanation of how this variable is set up) allows for setting of specific mappings between IdAS entity type and LDAP object class. Anything not specifically mapped is simply transformed with a rule (see lines 6 & 7 and 17 below).

 1)   <Setting Name="consumerEntityTypeToProvider" Type="htf:jscriptexec">
 2)      <![CDATA[
 3)      map = multimap.consumer[String(consumerType.toString())];
 4)      if (!map)
 5)      {
 6)         var re = new RegExp("^http://www.eclipse.org/higgins/ontologies/2006/higgins/ldap#class_", "i");
 7)         map = String(consumerType.toString()).replace(re, "");
 8)      }
 9)      RESULT = map;
10)      ]]>
11)   </Setting>
12)   ...
13)   <Setting Name="providerEntityTypeToConsumer" Type="htf:jscriptexec">
14)      <![CDATA[
15)      map = multimap.provider[String(providerType.toString())];
16)      if (!map)
17)         map = "http://www.eclipse.org/higgins/ontologies/2006/higgins/ldap#class_" + String(providerType.toString());
18)      RESULT = map;
19)      ]]>
20)   </Setting>

Attribute Name Mapping

The setting that controls mapping of IdAS attribute names to LDAP attribute names is the consumerAIDToProvider setting (see line 40 in the overall example above). The setting that controls mapping of LDAP attribute names to IdAS attribute names is the providerAIDToConsumer setting (see line 43 in the overall example above). These settings contain javascript that does the mapping. With javascript it is possible to do all kinds of sophisticated kinds of mappings. For an in-depth explanation of the consumerAIDToProvider setting and how to use it, see here. For an in-depth explanation of the providerAIDToConsumer setting and how to use it, see here.

The reason to have a attribute name mapping functions is that an application wants to use consistent, standard IdAS attribute names. These need to be mapped to appropriate LDAP attribute names. In the javascript given below, a keyed array called multimap.consumer (see line 3) is used to lookup the IdAS attribute name and produce an LDAP attribute name, and a keyed array called multimap.provider (see line 15) is used to lookup an LDAP attribute name and produce the IdAS attribute name. In essence, the multimap variable (see here for an explanation of how this variable is set up) allows for setting of specific mappings between IdAS attribute name and LDAP attribute name. Anything not specifically mapped is simply transformed with a rule (see lines 6 & 7 and 17 below).

 1)   <Setting Name="consumerAIDToProvider" Type="htf:jscriptexec">
 2)      <![CDATA[
 3)      map = multimap.consumer[String(consumerID.toString())];
 4)      if (!map)
 5)      {
 6)         var re = new RegExp("^http://www.eclipse.org/higgins/ontologies/2006/higgins/ldap#attr_", "i");
 7)         map = String(consumerID.toString()).replace(re, "");
 8)      }
 9)      RESULT = map;
10)      ]]>
11)   </Setting>
12)   ...
13)   <Setting Name="providerAIDToConsumer" Type="htf:jscriptexec">
14)      <![CDATA[
15)      map = multimap.provider[String(providerID.toString())];
16)      if (!map)
17)         map = "http://www.eclipse.org/higgins/ontologies/2006/higgins/ldap#attr_" + providerID.toString();
18)      RESULT = map;
19)      ]]>
20)   </Setting>

Attribute Value Mapping

The setting that controls mapping of IdAS attribute values to LDAP attribute values is the consumerAValueToProvider setting (see line 46 in the overall example above). The setting that controls mapping of LDAP attribute values to IdAS attribute values is the providerAValueToConsumer setting (see line 49 in the overall example above). These settings contain javascript that does the mapping. With javascript it is possible to do all kinds of sophisticated kinds of mappings. For an in-depth explanation of the consumerAValueToProvider setting and how to use it, see here. For an in-depth explanation of the providerAValueToConsumer setting and how to use it, see here.

The reason to have attribute value mapping functions is that an application may want to standardize attribute values somehow for consumption by other policies that are configured in the OTIS server. This is NOT a common need. The javascript below does some special mapping of values in the LDAP role attribute to ensure that they look like full DNs. This is based on two assumptions:

that your directory actually represents roles as role objects in the directory
the OTIS server which has role policy rules that are based on full DN names for role objects. In the javascripts below, it assumes they come from a container called ou=people,o=bandit (see lines 9 and 26).

If neither of these apply to your directory, you can either ignore these settings altogether or you can remove them from the otis-config.client.local.xml file. If, on the other hand, your directory has role policy objects, and they are located in a particular container, you may want to change the javascript below (lines 9 and 26). You may also want to examine the role policy settings in the otis-config.client.local.xml file (see documentation on the Roles setting) and make appropriate corresponding changes. NOTE: The default role policy currently has no rules that would be affected by this, so you would probably be safe to simply delete these settings or leave them alone altogether until there is a need to pay attention to them.

 1)   <Setting Name="consumerAValueToProvider" Type="htf:jscriptexec">
 2)      <![CDATA[
 3)      importPackage(Packages.org.eclipse.higgins.idas);
 4)      importPackage(Packages.org.eclipse.higgins.idas.spi);
 5)
 6)      if (providerID == "role")
 7)      {
 8)         RESULT = new Packages.org.eclipse.higgins.idas.spi.BasicValueString(
 9)         "cn=" + PARAM.getLexical() + ",ou=people,o=bandit", null);              // CHANGE THIS LINE
10)      }
11)      else
12)      {
13)         RESULT = PARAM;
14)      }
15)      ]]>
16)   </Setting>
17)   ...
18)   <Setting Name="providerAValueToConsumer" Type="htf:jscriptexec">
19)      <![CDATA[
20)      importPackage(Packages.org.eclipse.higgins.idas);
21)      importPackage(Packages.org.eclipse.higgins.idas.spi);
22)
23)      if (providerID == "role")
24)      {
25)         //TODO how do we detect java types for the correct casts?
26)         var re = new RegExp("^cn=(.*),ou=people,o=bandit$", "i");              // CHANGE THIS LINE
27)         RESULT = new Packages.org.eclipse.higgins.idas.spi.BasicValueString(
28)         String(PARAM.getData()).replace(re, "$1"), null);
29)      }
30)      else
31)      {
32)         RESULT = PARAM;
33)      }
34)      ]]>
35)   </Setting>

Download in other formats:

Plain Text