1. Introduction

Welcome to the iKnowBase Installation Guide. Note that this installation guide only covers upgrades from iKnowBase 5.7.2 and newer.

Note
If you are upgrading from an older version, you must first upgrade to iKnowBase 5.7.2 using the old upgrade instructions, and then use these upgrade instructions to upgrade to the latest version.

Overview

2. Installation topologies

2.1. iKnowBase components

iKnowBase Conceptual Topology
Figure 1. iKnowBase Conceptual Topology

The diagram shows the various components of an iKnowBase installation:

  • The database ("iKnowBase repository") contains configuration, metadata and content. This is deployed to an Oracle Database.

  • The iKnowBase application containing all server side components.

The iKnowBase application is modularized. Modules may be activated/deactivated as needed. You can run several instances of the iKnowbase application, each with its own configuration.

See the Java Applications section for details about modules and deployment. See the Configuration section for details about how the modules can be enabled/disabled and configured.

2.2. Deployment options

2.2.1. The iKnowBase repository

The iKnowBase repository is installed onto an Oracle database. For production use, we recommend that you always install at least three repositories: development (where you build new functionality), test (where you verify that the functionality works) and production (where live data lives).

For smaller installations, use a single database and create schemas (database users) for the required repositories. This is extremely easy to set up, but provides limited isolation between the environments. Some applications are built using hard coded schema names, and thus require a different database instance for each repository. These instances may all reside on the same Oracle database server, using the same database license.

Advanced installations (typically with large data volumes or stricter security requirements) will want to install the production repository on its own server; the development and test repositories may still be co-located if that is desired.

2.2.2. The web tier

The web tier can also be installed in a large variety of ways:

For most installations, use the iKnowBase web server to host the web applications. This server is customized for running iKnowBase, containing all required functionality in a small, easy-to-manage installation.

  • For small installations, run a single iKnowBase web server on the same server as the database.

  • For larger installations, run multiple iKnowBase web servers, on one or more physical machines.

  • For higher security requirements, install separate instances for internal and public use. Run development and similar services only on the internal server.

Customers that already have an established and managed infrastructure using a supported third party application server may also chose to run the web tier on that server. Note that we recommend setting up the iKnowBase web server even then, since the iKnowBase program is also used for repository installation and upgrades, and is a useful management and troubleshooting tool.

We generally recommend installing an Apache (or similar) proxy server in front of the iKnowBase web server. This is useful for things like SSL-termination, serving static content, redirect rules, virtual hosts, etc.

2.3. Supported infrastructure

See "Supported platforms" in iKnowBase Release Notes.

3. Quick installation and upgrade overview

This chapter gives a brief overview of the installation or upgrade of an iKnowBase instance.

The process typically have the following steps:

  • Download and install the software onto your application server.

  • Prepare the instance-specific installation directory.

  • Use the iKnowBase program to install or upgrade the database repository.

  • Run the iKnowBase web server to verify the installation.

  • Optional: Extend and deploy the iKnowBase web application with plugins and patches.

We recommend that you use the procedure above even if you intend to install the web application into a third party application server, proceeding with the third party server only when the iKnowBase web server has been verified.

We recommend that you choose a server for storing the iKnowBase software and running the installation. In most scenarios this server would be a server where the web applications will run. Here, install into a directory structure similar to the one below, with one directory for each version the actual distribution (named after the distribution version) and one directory for each iKnowBase installation (each database repository):

Directory Purpose

/opt/iknowbase

Root for all iKnowBase software.

…​/distributions

Collection of all distribution files, packed.

…​/iknowbase-6.4

Version specific directory for the unpacked software (old version).

…​/iknowbase-7.5.1

Version specific directory for the unpacked software (current version).

…​/development

Directory for a given instance (example: "development").

…​/development/plugins

Directory containing all plugins (.jar files only).

…​/production

Directory for a given instance (example: "production").

…​/production/plugins

Directory containing all plugins (.jar files only).

3.2. Download and install the iKnowBase software

Using the recommended directory structure above, install the iKnowBase software into the proper location. The assumption here is that the distribution file has been downloaded to /tmp.

sudo mkdir /opt/iknowbase
sudo chown iknowbase /opt/iknowbase
mkdir /opt/iknowbase/distributions
cp /tmp/iknowbase-7.5.1-bin.zip /opt/iknowbase/distributions/

# Note: the .zip-file contains top level directory "iknowbase-7.5.1"
cd /opt/iknowbase
unzip distributions/iknowbase-7.5.1-bin.zip

3.3. Prepare the instance-specific home directory and configuration

You will typically have multiple iKnowBase repositories, to handle different phases in the life cycle, such as development, testing and production. We recommend that you set up a directory for each such repository, where you store configuration files, log files, etc. This chapter describes setting up only one such instance, so you should repeat this for e.g. development, test and production.

mkdir /opt/iknowbase/production

For simplicity, and to avoid accidentally using the wrong version of the iKnowBase program, we also recommend creating a "iknowbase.sh" script that forwards to the proper version. Run the script below from each of the instance-specific directories:

cd /opt/iknowbase/production
cat > iknowbase.sh << 'EOF'
#!/bin/bash
../iknowbase-7.5.1/iknowbase.sh $*
EOF

chmod +x iknowbase.sh

For each repository, create a property file application.properties with all the required settings for connecting to the database and running the iKnowBase web server. A sample is provided in etc/application.properties.SAMPLE in the distribution. Copy the sample as application.properties, edit the new file and set proper values for options prefixed with spring.datasource and com.iknowbase.setup.

cd /opt/iknowbase/production
cp ../iknowbase-7.5.1/etc/application.properties.SAMPLE application.properties
  • spring.datasource.url is the jdbc url to the database, see example below and i SAMPLE.properties.

  • spring.datasource.username is the name of the database user that contains the iKnowBase repository that will be upgraded.

  • spring.datasource.password is the password for the iKnowBase database user.

  • com.iknowbase.setup.database.sysUser is the name of a user with SYSDBA privilege in the database, typically "SYS"

  • com.iknowbase.setup.database.sysPassword is the password for the SYS-user in the database.

Note that the com.iknowbase.setup.database.sysUser and com.iknowbase.setup.database.sysPassword is only required during installation and upgrade, and may be removed during normal execution, if that is required.

Note that the name application.properties is the default and recommended name. Changing this name requires extra environment or JVM options. See Spring Boot’s documentation for details.

3.4. Install a new database repository

Use this chapter if you are installing a new iKnowBase repository. If you are upgrading an existing repository, follow the steps in the next chapter.

  1. Create user and import schema content:

    cd /opt/iknowbase/production
    ./iknowbase.sh createUser
    ./iknowbase.sh uploadFile ../iknowbase-7.5.1/etc/IKB_MASTER_75.dmp
    ./iknowbase.sh importFile IKB_MASTER_75.dmp IKB_MASTER_75
  2. Optionally download and display import log:

    ./iknowbase.sh downloadFile IKB_MASTER_75.log .
    cat IKB_MASTER_75.log
  3. Run upgrade scripts on the newly created installation:

    ./iknowbase.sh upgradeAll
  4. Set password for ORCLADMIN, so that you may log in with the default security setup on the iKnowBase web server (replace the example password "changeMe" with one of your own choosing):

    ./iknowbase.sh setIkbPassword orcladmin changeMe

3.5. Upgrade an existing database repository

Use this chapter if you are upgrading an existing repository. If you are installing a new iKnowBase repository, follow the steps in the previous chapter.

./iknowbase.sh exportSource source.zip
./iknowbase.sh configureUser
./iknowbase.sh upgradeAll

If you have any custom scripts that need to run, for example to grant permissions to custom code, run these now.

3.6. Configure and start the iKnowBase Web Application

With the database repository in place, you can run the iKnowBase web applications. There are two main alternatives: Either use the iKnowBase web server, or deploy to one of the supported application servers. This chapter describes how to configure and run the iKnowBase Web Server.

3.6.1. Plugins

If you have any plugins that you want to use, create a "./plugins" directory and install them there. Note that the server can only load .jar files. Check the chapter on Java-applications for more information.

Note
iKnowBase Content Studio, iKnowBase Process Studio and iKnowBase REST User Repository applications are distributed as plugins. If you want to use these applications, add them in this step (see the iKnowBase Process Studio section.
mkdir /opt/iknowbase/production/plugins

. Copy plugins, e.g. from /where/i/keep/my/plugins/*
. cp /where/i/keep/my/plugins/*.jar /opt/iknowbase/production/plugins/
iKnowBase REST User Repository plugin

The iKnowBase REST User Repository is deployed as a regular plugin and adds user repository resources to the /ikb$rest endpoint. These resources are by default protected by ACL with external key IKB_REST_REPOSITORY.

When deployed, see /ressurs/iknowbase/doc/html/rest/ikb/index.html for details and configuration options.

3.6.2. Start the iKnowBase application

To run the iKnowBase web server, use:

cd /opt/iknowbase/production
./iknowbase.sh webServer

3.7. Next steps

Generic Java applications chapter:

Application server specific chapters:

4. Configuration

The iKnowBase web application can be configured to adapt to different needs using configuration properties.

4.1. Overview

First, modules in iKnowBase expose a number of Configuration objects that control the workings of the module. Each configuration object has one or more named configuration properties that can be set by the user. If the user does not set a given configuration property, a default value will be used.

When the iKnowBase web application starts, it populates the configuration objects with property values set by the user, and then uses the configuration objects to adapt the module. Note that this implies that making changes to properties will require a restart of the application server.

At run time, the actual property values can be inspected in the management console, e.g. at /ikb$console.

4.2. Property sources

Configuration properties are available from many different sources. When an application requires a property value, it will check these sources in order, and the first one that can supply the required property will be used:

  • The property source "IKB_INSTALLATION_PROPERTIES" represents values loaded from the database table ikb_installation_properties.

  • The property source "servletConfigInitParams" is typically not used, but is provided as a standard source by the underlying technology.

  • The property source "servletContextInitParams" is typically not used, but is provided as a standard source by the underlying technology.

  • The property source "jndiProperties" is typically not used, but is provided as a standard source by the underlying technology.

  • The property source "systemProperties" gets values from the command line used to start the java virtual machine, so that you can directly specify property values when starting the server.

  • The property source "systemEnvironment" gets values from the operating system environment (where you find e.g. the PATH environment variable).

In practice, you will probably use either java system properties or the ikb_installation_properties tables:

  • Java system properties are easy to set, in particular in an installation with a single application server instance.

  • The ikb_installation_properties database table is more easily managed, and allows you to set values that apply to multiple application server instances.

4.2.1. System properties

System properties is the "standard" java mechanism for configuring an application. They may be set in various ways:

  • Using "-Dname=value" as a command-line option to the java program.

  • Using "System.name=value" in an iKnowBase property file.

Thus, to enable the activiti process engine inside iKnowBase, you could use the following iKnowBase property file:

db.URL = jdbc:oracle:thin:@//localhost:1521/orcl
db.ikbUser = ikb_prod
db.ikbPassword = SECRETPASSWORD

System.com.iknowbase.process.activiti.enabled=true

4.2.2. The ikb_installation_properties database table

Using the IKB_INSTALLATION_PROPERTY table is the most common option. Since this table is shared between all applications and all application server instances, it is possible to add expressions that are checked at runtime in order to select the proper property. This is done using the "instance_qualifier" table column.

At startup, each iKnowBase java web application loads properties from the ikb_installation_table. For each row, it will evaluate the "instance_qualifier" value to decide if this particular property is valid for this particular application instance. The qualifier is interpreted using the Spring Expression Language, which allows for combining various types of tests.

The available variables and methods for the expression is limited to the following logical interface definition:

Variable Description

hostname

Name of server

directory

Startup directory; same as the java property "user.dir"

contextPath

Root context path of web application (e.g. "" or "/CustomContextRoot")

getSystemProperty(name)

Value of system property

These can be combined in several ways, to achieve various effects:

Qualifier Description

*

Used by any application, anytime

true

Used by any application, anytime

hostname == 'tango'

Used by any application running on a host named "tango"

directory == '/opt/iknowbase/sso'

Used by applications running from the "/opt/iknowbase/sso"-directory

hostname == 'tango' && contextPath == '/CustomContextRoot'

Used by an application deployed to /CustomContextRoot, when running on a host named "tango"

hostname == 'tango' && contextPath matches '/Custom.*'

Used by all "/Custom" prefixed applications, when running on a host named "tango" (/CustomContextRoot, /CustomOtherContextRoot, …​)

4.2.3. Language settings (NLS)

In order to set the session language for the JDBC Oracle connection to a different language than the instance- or database language, you need to add an instruction in the property file.

e.g. to set the language to Norwegian, add the following :

JAVA_OPTIONS=-Duser.language=no -Duser.region=NO

Setup details

5. Database repository

iKnowBase uses an Oracle Database for storing both data, metadata and applications. Inside the database, iKnowBase also stores a lot of system code, as well as public APIs for manipulating the data.

5.1. Fresh install

A fresh install of the Oracle repository is pretty simple, and consists of only a few steps:

  • The database schema where iKnowBase is installed must be created, and it must be given the proper permissions. Also, an instance specific database package must be created.

  • The database schema must be populated with startup data. These data can be loaded from an existing instance (for example, when doing a fresh install of a test environment, where the startup data comes from an existing production environment), or they can be loaded from the iKnowBase distribution.

A full set of typical commands is shown below, and further described in the following chapters.

$ cd /opt/iknowbase/production
$ ./iknowbase.sh createUser
$ ./iknowbase.sh uploadFile  IKB_MASTER_75.dmp
$ ./iknowbase.sh importFile IKB_MASTER_75.dmp IKB_MASTER_75
$ # Optionally download and display import log
$ ./iknowbase.sh downloadFile IKB_MASTER_75.log .
$ cat IKB_MASTER_75.log

5.1.1. Prepare the database schema

Installing the database schema is most easily done using the iKnowBase program. Assuming that you have created a file "production.properties" with the proper information, use the following command:

$ iknowbase.sh createUser

This command will perform three actions:

  • First, as user SYS, it will create the user specified in the property file, with the password also specified there.

  • Next, as user SYS, it will grant required permissions to that user. A full list of permissions can be seen in the log file after executing the command.

  • Finally, as the newly created user, it will create the database package IKB_GLOBAL_PREFS with default variables.

5.1.2. Custom step for Oracle 12c database with Pluggable databases (PDB)

If installing on a Oracle 12c database with Pluggable databases (PDB), DATA_PUMP_DIR does not work with PDBs. You must define an explicit Directory object within the PDB after you have created the new schema. Create a new directory and configure iKnowBase to use it:

  • Create directory <DIRECTORY_NAME> as '<OS path to where datapump files should be stored>';

  • Grant read, write on directory <DIRECTORY_NAME> to <schema name>;

  • Add a property to the iKnowBase configuration file e.g. db.dataPumpDirectory=<DIRECTORY_NAME>

5.1.3. Import startup data based on a export file

You can import startup data with any mechanims you choose, but once again the iKnowBase program is the preferred and supported mechanism. Using the iKnowBase program has two steps: First you upload the startup data to the oracle database server, and then you import them into the oracle database schema:

$ ./iknowbase.sh uploadFile IKB_MASTER_75.dmp
$ ./iknowbase.sh importFile IKB_MASTER_75.dmp `IKB_MASTER_75`

The first command will upload the file IKB_MASTER_75.dmp from the local directory, and store in an Oracle Directory on the server. The default (and recommended) directory is called DATA_PUMP_DIR, and is often available under /app/oracle/admin/INSTANCE/dpdump. Note that if you import data from another existing database, the file may have any other name. This command will run as the iKnowBase-user.

The second command will import the file IKB_MASTER_75.dmp from the Oracle Directory into the iKnowBase schema. The iKnowBase program will in fact use Oracle Datapump to perform this import. For the datapump import to succeed, the name of the database user that exported the schema must be specified. In the distribution, and by convention, the name of the datafile reflects the name of the exporting user; here, it is IKB_MASTER_75.

If something fails during import, Oracle Datapump will store log messages in a log file in the Oracle Directory on the database server. When using the importFile command, the name of the logfile is always the same as the name of the datafile, with a .log-suffix.

Since the file already exist on the database server, you may view it there (i.e. typically /app/oracle/admin/INSTANCE/dpdump/IKB_MASTER_75.log). You can also use the following command to download the logfile to your local directory:

$ ./iknowbase.sh downloadFile IKB_MASTER_75.log .

Note that it is often useful to store a copy of the logfile even when there are no appearent failures, in case you need it later.

5.2. Upgrade

Upgrading an iKnowBase-installation is technically more complex than a fresh install, mostly because there are already existing data that must not be deleted. An upgrade therefore have the following steps:

  • If you want, take a copy of existing database object definitions for post-upgrade troubleshooting.

  • Next, update and verify the user/schema settings.

  • Run through schema upgrade scripts for all required versions, and install the latest code (types, packages, functions and procedures).

  • Recompile any invalid packages.

$ cd /opt/iknowbase/production
$ iknowbase.sh exportSource scripts.zip
$ iknowbase.sh configureUser
$ iknowbase.sh upgradeAll
$ iknowbase.sh compileInvalid

5.2.1. Export existing scripts

Export existing scripts is entirely optional, but we recommend this for easier post-upgrade troubleshooting. You may use any available tool for this process, but once again the iKnowBase program has an easy-to-use mechanism:

$ iknowbase.sh exportSource scripts.zip

The above command will use DBMS_METADATA to recreate scripts for all TYPEs, PACKAGEs, PROCEDUREs and FUNCTIONs in the iKnowBase schema, and store it in a zip file. The zip-file will also contain compile-scripts for each of the object types, as well as a compile script that compiles everything.

5.2.2. Prepare the database schema

Various versions of iKnowBase require different permissions, and have different information in the IKB_GLOBAL_PREFS-package. It is therefore necessary to configure the database schema to the new requirements:

$ iknowbase.sh configureUser

This command will perform two actions:

  • First, as user SYS, it will grant required permissions to that user. A full list of permissions can be seen in the log file after executing the command.

  • Then, as the iKnowBase user, it will recreate the database package IKB_GLOBAL_PREFS with default values.

5.2.3. Upgrade schema and install latest code

The most complex step in the upgrade process is to upgrade the schema and install the latest code. For convenience, use the iKnowBase program’s upgradeAll feature:

$ iknowbase.sh upgradeAll

This command does in fact comprise a number of schema upgrade steps (one for each schema version), and then a single code installation step.

Note that after installing the latest code, open database connections and open cursors may cache database type information that is no longer correct. It is therefore recommended to restart all application servers, email readers, search crawlers, etc. that might have open database connections.

5.2.4. Recompile invalid packages

After the upgrade step, it may be required to recompile invalid packages in the Oracle schema:

$ iknowbase.sh compileInvalid

This command utilizes DBMS_UTILITY.RECOMPILE_SCHEMA for recompiling only invalid packages.

5.3. De-installation

De-installation of the iKnowBase installation is pretty simple: Remove the user and all it’s data:

$ iknowbase.sh dropUserCascade

Note that you may have to set the value "allowDropUserCascade=true" in the property file before this command will work.

Note also that while a simple "drop user cascade" from sql*plus may work, it also may not: When a schema has Oracle AQ-tables (Advanced Queing), it is sometimes required to manually drop these queues first. The iKnowBase program handles this, and is therefore the recommended way of deleting a user.

And finally, a word of warning: The dropUserCascade command is utterly unrecoverable, and if you drop a user by accident, you will have to reload data from a backup. Take care!

5.4. Advanced topics

5.4.1. Global runtime preferences

iKnowBase uses a database package header, IKB_GLOBAL_PREFS, to determine methods and options on certain functionality. To modify the package header you need access to the database with a proper tool e.g. SqlDeveloper or Toad.

Property name Default Value _Description

has_oracle_workflow

FALSE

Set to TRUE if Oracle Workflow is a integrated part of solution.

has_oracle_oid

FALSE

Set to TRUE if users are maintained and integrated from a LDAP directory. When FALSE, the user is maintained fully in iKnowBase.

has_oracle_ordsys

FALSE

When FALSE, use a Java based image scaling which is the preferred way of scaling images. Oracle Imtermedia uses internal Oracle functions and the may not be available on all versions of the Oracle Database.

has_oracle_smtp

FALSE

When FALSE, use a Java based mail sender which is the preferred method when sending email. Oracle SMTP uses internal Oracle functions and they may not be available on all versions of the Oracle Database.

has_oracle_http

TRUE

Oracle HTTP may not be available on all versions of the Oracle Database.

log_level

ERROR

Defines the log level for iKnowBase when catching errors and debug messages. Valid values are ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL or OFF.

has_custom_access_control

FALSE

If the instance is running wihout a custom access control, the value should be set to FALSE. Will improve performance.

attribute_security_function

blank string

Defines the name of the custom function used for attribute security. Set to NULL if no such function exists. It the function exists within a package, use the notation package.function

oracleTextSearchParser

blank string

Defines the name of the custom oracle text search parser. Set to NULL if no such function exists. It the function exists within a package, use the notation package.function

ignore_illegal_attrib_on_save

FALSE

Used for backward compability.

use_native_plsql_compiler

TRUE

For Oracle Database 11g and up: use native compilation for PL/SQL code.

index_binary_using_oratext

TRUE

Defines whether the oracle text index should contain binary content. Set to FALSE to index only metadata and text content, or leave as TRUE to index both metadata, text content and binary content.

index_metadata_using_oratext

TRUE

Defines whether the oracle text index should contain metadata values. Set to FALSE to index disable metadata aggragation and indexing, or leave as TRUE to index the metadata.

5.4.2. Duplicate an existing installation

Often, you will want to duplicate an existing installation. For example, you may have a development, test and production instance, and you may need to copy from production to test. Doing so is very simple:

$ cd IKB_PROD
$ iknowbase.sh exportFile IKB_PROD.dmp
$ cd ../IKB_TEST
$ iknowbase.sh importFile IKB_PROD.dmp IKB_PROD

In the example above, there are two instance directories containing start script and application.properties. IKB_PROD/application.properties contains information about the production schema, while IKB_TEST/application.properties contains information about the test schema. Data is first exported from the production schema, then imported into the test schema.

Note that the first time you do this, you will also need to run the createUser-command. Of course, if the IKB_PROD and IKB_TEST schemas reside on different Oracle-instances, you will also need to move the dump file between the instances, either using a combination of downloadFile and uploadFile, or by using some other file transfer mechanism.

5.4.3. Running iKnowBase in a Oracle Enterprise Edition database

By default, an iKnowBase installation is prepared for running in a Oracle Standard Edition database. It you are licensed for running Oracle Database Enterprise Edition then run the following command to speed up queries displaying (or sorting) document popularity.

$ iknowbase.sh dbscript common/mv_log_document.sql logfile

To switch back to the standard edition version do:

$ iknowbase.sh dbscript common/view_log_document.sql logfile

5.4.4. Recreating Oracle Text index

In former distributions, the Oracle Text index would index title, metadata, description, binary- and text content. With SOLR, a text index with Oracle Text should be obsolete, but for some reasons it is still useful for compability reasons, but the overall goal is to convert all search functionality to SOLR. Meanwhile, you can create a lightweigh Oracle Text index without the binary content which will reduce the index size dramatically and still be able to search. To do this you need to run the following two steps:

$ Change ikb_global_prefs.index_binary_using_oratext to FALSE
$ iknowbase.sh dbscript common/create_ikb_freetext.sql

To switch back to a full index with also binary content indexed do:

$ Change ikb_global_prefs.index_binary_using_oratext to TRUE
$ iknowbase.sh dbscript common/create_ikb_freetext.sql

6. Java applications

6.1. Overview

The server side components of iKnowBase are assembled as a single file.

  • iknowbase-boot-embedded-7.5.1-app.jar for running with the embedded iKnowBase Web Server.

  • iknowbase-boot-weblogic-7.5.1.war for deployment to Oracle WebLogic.

The main iKnowBase Java web modules, which may be enabled or disabled in the configuration, are:

  • Batch: module is the batch processing server.

  • Instant: module is the real time asynchronous messaging server for web clients.

  • Studio: module adds content administration, user administration and development capabilities to the Administration Console.

  • Viewer: module is the core runtime environment, serving web pages to end users.

  • WebServices: module is the Web Services-server, typically to programs and integration engines.

  • WebDAV: module is the WebDAV content server, enabling easy editing of Office documents stored in iKnowBase.

See the module’s own chapter for details.

6.2. Special requirements

  • We strongly recommend deploying iKnowBase with context root set to "/".

  • If you intend to use WebDAV, the iKnowBase web application must be deployed with context root set to "/".

6.3. Installing plugins and patches

6.3.1. iKnowBase Web Server (embedded)

Jar plugins in the ./plugins directory (subdirectories are not scanned) are automatically included in the application.

If you want to change or add more directories containing jar plugins, you may configure this using

  • Linux: Set loader.path in application.properties (recommended) or JVM option, or set LOADER_PATH environment variable (use only one method).

  • Windows: Set loader.path JVM option or set LOADER_PATH environment variable.

The loader.path / LOADER_PATH is a comma delimited list of jar files or directories containing jar files. Note that it does not support relative parent directory "../".

6.3.2. Oracle WebLogic

First create the required directories, "plugins" to store the plugins, and "wars" to store the custom application (the output). Add all plugins and patches to the plugins directory:

mkdir /opt/iknowbase/production/plugins
mkdir /opt/iknowbase/production/wars

# Copy plugins, e.g. from /opt/my-plugins
cp /my-plugins/*.jar /opt/iknowbase/production/plugins/

Next, create an instance-specific web application based on the original iKnowBase web application + all plugins. Always patch from the original application, as this ensures you know which plugins you’ve added at all times:

cd /opt/iknowbase/production
./iknowbase.sh assembleWar \
               /opt/iknowbase/iknowbase-7.5.1/libs/iknowbase-boot-weblogic-7.5.1.war \
               /opt/iknowbase/production/wars/iknowbase-boot-weblogic-7.5.1-custom.war \
               /opt/iknowbase/production/plugins/*

Finally, deploy the newly created iKnowBase web application instead of the original web application.

6.4. Install/upgrade

For the iKnowBase web server, installation is quick and mostly automatic:

  • Install and configure the iknowbase instance (software + property file). This is a required step to install the database, so it is probably done.

  • If this is your first installation (not an upgrade), you may want to enable a web password for the default ORCLADMIN admin user.

  • Start the webServer.

$ cd /opt/iknowbase/production
$ ./iknowbase.sh setIkbPassword orcladmin secretpassword
$ ./iknowbase.sh webServer

When the server has started, you should be able to navigate to a few interesting links:

For further configuration options, or if you want to install on an alternative application server, see the details for each of them:

6.5. Web application security

During or after deployment, you need to configure security for the application (NOT the same as content security). Again, the configuration method will vary from application server to application server.

See Installation Guide > Web Application Security for details and examples.

6.6. Advanced topics

6.6.1. Deploy with alternative context root (/ikbViewer)

In the default and recommended installation, the iKnowBase web application is deployed to "/", so that you can access pages and components without an application-specific prefix. For compatibility reasons, the server will automatically also handle all requests to "/ikbViewer/", and redirect them to "/".

While it is technically possible to deploy to a different root (e.g. "/ikbViewer"), we do not recommend this. It brings no apparent benefit, but the user experience is negatively impacted. That said, should you choose to do so:

  • Deploy to any chosen path.

  • Update paths specified in the "Domains" definitions in Development Studio.

  • Ensure the infrastructure (reverse proxy) maps the default static resource paths to the updated paths.

    • /ressurs ⇒ /NEW_PATH/ressurs

    • /plugin-resources ⇒ /NEW_PATH/plugin-resources

Note that the WebDAV service will not work when deployed to a context root other than "/".

6.6.2. Clustering

The iKnowBase application itself supports clustered deployment, but the "Instant" module does not. If you intend to use this modules in an otherwise clustered environment, it must be deployed to a standalone server instance with no clustering.

By default, iKnowBase runs with database persisted sessions. This means that session persistence / sticky sessions are not required. If you change the session configuration to memory sessions (Spring Session or native), you must use session persistence / sticky sessions.

6.6.3. Add custom locations for additional static resources

You may configure the iKnowBase application to serve additional static resource locations, typically used for customer specific files (css, js, images).

Note
This was previously only available for the iKnowBase Web Server, but has now been extended to iKnowBase application regardless of deployment platform.

See options prefixed with com.iknowbase.server.resource.custom in application.properies.SAMPLE for configuration details.

6.6.4. Limit file upload size

iKnowBase does not by default limit the size of files you may upload. If you want to set a max limit, use Spring Boot’s multipart.*` configuration options.

# Max file size (-1 = unlimited)
#multipart.max-file-size=-1
multipart.max-file-size=50MB

# Max total request size (-1 = unlimited)
#multipart.max-request-size=-1
multipart.max-request-size=100MB

6.6.5. Session configuration

iKnowBase uses Spring Session with database persistence by default. This means that the application itself handles all things related to sessions and does not use the session features provided by the server platform.

All requests use this session setup, except requests for public static resources in /ressurs, /plugin-resources, or any custom-resources you have defined.

The advantages with this setup are:

  • The session is still valid after server restart.

    • The users can continue without login interruption.

  • No session replication setup is required for seamless failover in a clustered environment.

  • Sticky sessions are not required and you may load balance the application using any algorithm you want.

    • NOTE: The Instant module does not support clustering.

  • No overhead for static resources.

  • Possible to force logout a user by deleting the persisted session.

The disadvantages are:

  • A couple of milliseconds overhead for each request to non-static content.

  • Minor extra load on database.

See the sub sections below for configuration details.

Use native sessions

If for some reason you need to use native sessions provided by the application server, you may disable Spring Session by setting

com.iknowbase.spring.session.enabled=false

In native session mode, refer to documentation for Spring Boot and the application server for configuration options for sessions. All other sections in this document regarding sessions describe configurations applicable for Spring Session.

By default, the iKnowBase separates session between different domains, so that a user that opens both http://www.example.com and http://intranet.example.com will have to log on to each of these sites. Technically, this is done by using different "session cookie domains" for the session cookie for each of these hosts.

Sometimes, it is desirable to share the session information between sites. To do that, configure the session cookie domain to be used by the server. It is important that this domain is the parent domain of the various hosts used, for example, to share the login session between http://www.example.com and http://intranett.example.com you must specify "example.com"; to share the login session between http://www.iknowbase.com and http://customers.iknowbase.com you must specify "iknowbase.com".

com.iknowbase.spring.session.domainName=example.com

If you want to support more than one domain name at the same time, you can use a domain name expression instead of the static domainName value.

Example:

  • http://www.example.com, http://intranett.example.com with shared cookie for example.com

  • http://www.iknowbase.com (separate domain)

  • http://localhost:8080 (for testing)

# Will match example.com for requests to www.example.com and intranett.example.com.
# Will match iknowbase.com for requests to www.iknowbase.com
# Will not match localhost and for localhost it will not override the cookie domain name either.
# Note: Double backslash is used in this regular expression configuration
com.iknowbase.spring.session.domainNamePattern=^.+?\\.(\\w+\\.[a-z]+)$

You must choose between com.iknowbase.spring.session.domainName and com.iknowbase.spring.session.domainNamePattern. Configuring both will result in startup error.

The iKnowBase application will use session cookie name IKBSESSION. In case of session name collision you may change the session cookie name. Session cookie name can be set using:

...
com.iknowbase.spring.session.cookieName=JSESSIONID_CUSTOM_NAME
...

Default max session idle time is set to 2100 seconds / 35 minutes. This can be changed by setting:

com.iknowbase.spring.session.maxInactiveInterval=<NUMBER IF SECONDS>

You may encounter a session cookie collision if you deploy two iKnowBase applications on the same host on different ports or otherwise have additional applications with the same cookie name running behind a load balancer.

As the host name is the same for both requests, the session cookie name will by default be valid for both requests. The session cookie is only valid on one server, which will result in a replaced session cookie and effective log out the authenticated user.

Resolve the issue by changing the session cookie name for one of the applications or use different hostnames for accessing the applications.

Web Application Modules

7. The web application runtime module

The web application runtime module is the infrastructure upon which all modules rely. This module is mostly "invisible" to users and administratiors alike, but it is possible to configure certain aspects of it.

7.1. The in-memory cache manager

The iKnowBase system provides a cache system based on Ehcache (http://www.ehcache.org). This cache helps in maintaining the performance of the system, by storing both metadata and content in memory, saving costly disk and database access.

The caches in iKnowBase are replicated betweeen servers, ensuring that all applications connected to the same repository see the same data. The mechanism used to communicate between the caches is specific to EHCache, and can be configured using the properties shown below.

For information on the meaning of these properties, see the EHCache Product Documentation.

The CacheManagerConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.cache.EHCache.enableReplication

Enable or disable cache replication.

com.iknowbase.cache.EHCache.peerDiscovery

Sets the properties used by Ehcache to discover other nodes.

com.iknowbase.cache.EHCache.listenerProperties

Sets the properties used by Ehcache node for cache replication.

7.2. The SecureToken engine

For most security purposes, iKnowBase uses the secure session mechanisms supported by the underlying application server. However, there are situations when this session is not available to all clients, and iKnowBase then needs an alternative, secure way of passing identity information. This token is generated using the HMAC_SHA1 message authentication algorithm, based on a secret key along with user identity and time information.

iKnowBase needs to generate a secure token for login information in the following scenarios:

  • Client authentication integration between iKnowBase Viewer and iKnowBase Instant.

  • Identity-forwarding to the Solr search engine.

By default, a suitable key is automatically generated when the application server starts up. However, for load balanced scenarios with multiple application servers, this would result in different keys and spurious failures during data load. You may then manually specifiy a secret key in the configuration. For optimum security, please use a long phrase with multiple words, numbers and special characters.

The SecureTokenEngineConfiguration_ accepts these configuration properties:

Property name Description

com.iknowbase.secureTokenEngine.secureKey

Key value used for generating tokens, when required.

8. Batch module

iKnowBase comes with a batch module used for processing certain off-line and near-line tasks, such as email processing and file format conversion.

Currently, the Batch Server handles these services:

  • The ContentIndexer service submits documents to a Solr search index for indexing.

  • The EmailReader service fetches email from an email account, and submits to iKnowBase for processing.

  • The EmailSender service sends emails.

  • The PageEngine service runs a specific iKnowBase Page and returns the HTML result. Used by the newsletter module.

  • The Transformation service supports various transformation operations on binary data through a set of providers.

The batch server is enabled by default, but may be disabled as needed. In particular, a larger site with multiple servers might want to disable batch processing on the servers handling public traffic. Disabling the batch module will implicitly also disable all services described below.

The BatchServerConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.batch.enabled

Toggles whether the batch server modules are available.

8.1. ContentIndexer

When using the Solr search engine for content search, the iKnowBase database repository will send indexing requests to the batch server, which will then submit content to the Solr server for actual indexing.

The ContentIndexerConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.batch.contentIndexer.enabled

Toggles whether to start the contentIndexer. The legal values are either "true" or "false".

com.iknowbase.batch.contentIndexer.dequeTimeoutSeconds

Number of seconds each dequeue() shall wait before recycling.

com.iknowbase.batch.contentIndexer.spawnPolicy

Decides when the pageEngine starts listening for a new message. Use "immediate" for parallel processing, or "delayed" for serial processing.

iKnowBase is capable of submitting content to multiple search engines for indexing. The administrative interface uses a logical "search engine name" when mapping content for searching; for each such there is a corresponding SearchEngineConfiguration accepting these configuration properties:

com.iknowbase.searchEngine.<searchEngineName>.index.type Type of index server. Currently "SOLR" is the only supported value.

com.iknowbase.searchEngine.<searchEngineName>.index.URL

URL to index server, e.g. http://solr.example.com/solr/CoreName.

com.iknowbase.searchEngine.<searchEngineName>.index.connectionTimeoutMillis

Max number of milliseconds to wait for the connection.

com.iknowbase.searchEngine.<searchEngineName>.index.operationTimeoutMillis

Max number of milliseconds to wait for the operation.

com.iknowbase.searchEngine.<searchEngineName>.index.commitWithinSeconds

Max number of seconds before the index server commits an update to the search index.

8.2. EmailReader

Most of the EmailReader configuration is performed in the Development Studio, where you define the various email accounts that you want to process, along with the pl/sql packages you want to use for processing the actual messages.

By default, any running iKnowBase batch server will process email messages. This is nice, unless you happen to have multiple BatchServers installed and running in parallel, which might lead to multiple batch servers accessing the same email account at the same time. This is a potential source of trouble, so we recommend that you configure the EmailReader so that only one instance is active at any time.

The EmailReaderConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.batch.emailReader.enabled

Toggles whether the emailReader is enabled or not.

8.2.1. Support non-standard character sets

UTF-7 character set is not included in Java by default. If you receive emails using this character set, or any other non-included character sets, you must add this character set to your JDK’s jre/lib/ext directory.

Example: To support UTF-7, use the jutf7 library from http://jutf7.sourceforge.net/. Add the jutf7-VERSION.jar to $JAVA_HOME/jre/lib/ext and restart the application.

8.3. EmailSender

EmailSender is the preferred method for sending emails and is set as default for new installations. An alternative method is available through the iKnowBase repository, see IKB_GLOBAL_PREFS.

The EmailSender configuration is performed using configuration properties, where you define profiles and settings used for sending emails. Whether emails are sent using this service or sent using iKnowBase Repository is controlled by iKnowBase Global Preferences in the iKnowBase Repository.

The EmailSenderConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.batch.emailSender.enabled

Toggles whether to start the fileConverter. The legal values are either "true" or "false".

com.iknowbase.batch.emailSender.dequeTimeoutSeconds

Number of seconds each dequeue() shall wait before recycling.

com.iknowbase.batch.emailSender.spawnPolicy

Decides when the pageEngine starts listening for a new message. Use "immediate" for parallel processing, or "delayed" for serial processing.

8.4. Transformation Server

The Transformation Server provides a database accessible entry point to the Content Transformation Service.

The TransformationServer is reachable through the database package IKB_TRANSFORMATION_API.

See Content Transformation Providers for provider specific installation instructions.

The TransformationConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.batch.transformation.enabled

Toggles whether to start the server. The legal values are either "true" or "false".

com.iknowbase.batch.transformation.dequeTimeoutSeconds

Number of seconds each dequeue() shall wait before recycling.

com.iknowbase.batch.transformation.spawnPolicy

Decides when the server starts listening for a new message. Use "immediate" for parallel processing, or "delayed" for serial processing.

com.iknowbase.batch.transformation.replyMessageExpirationSeconds

Number of seconds each reply message shall be valid, before expiring.

8.5. PageEngine

The ikbBatch module contains a page engine server, which can be configured to listen for page rendering requests. This is used by for example the newsletter module, which asks the batch module to render a page to be used as the content.

The BatchPageEngineConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.batch.pageEngine.enabled

Toggles whether to start the fileConverter. The legal values are either "true" or "false".

com.iknowbase.batch.pageEngine.dequeTimeoutSeconds

Number of seconds each dequeue() shall wait before recycling.

com.iknowbase.batch.pageEngine.spawnPolicy

Decides when the pageEngine starts listening for a new message. Use "immediate" for parallel processing, or "delayed" for serial processing.

com.iknowbase.batch.pageEngine.replyMessageExpirationSeconds

Number of seconds each reply message shall be valid, before expiring.

9. Development Studio module

iKnowBase comes with a Development Studio used to develop and maintain applications. This module is enabled by default, but may be disabled as needed. In particular, a larger site with multiple servers might want to disable Development Studio on the servers handling public traffic.

The StudioConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.studio.enabled

Toggles whether the development studio administration options are available in the Administration Console.

10. Instant module

iKnowBase comes with client and server side support for creating applications with real time asynchronous messaging support.

See the iKnowBase Development Guide > Using iKnowBase Instant for concept and examples.

10.1. Installation

The Instant Server is disabled by default, but can be enabled and configured using configuration properties.

Make sure that CORS is enabled in configuration id the clients use Instant on a different name or port than what is used for fetching content from iKnowBase Viewer.

Make sure you also configure The SecureToken engine to enable web client single sign on between iKnowBase Viewer and Instant. An alternative without single sign on between iKnowBase Viewer and Instant is to use explicit login - see the Authenticating with direct application container authentication section of iKnowBase Development Guide > Using iKnowBase Instant.

10.1.1. Special requirements

The connected web-clients will be "always connected" using asycnchronous HTTP transport mechanisms and will, compared to traditional HTTP clients, need infrastructure with support for non-blocking I/O or a sufficient high number of supported concurrent connections. One Instant client subscription means one network connection. ikbInstant may be deployed on an application server separate from where the other iKnowBase applications are deployed, as long as it’s connected to the same iKnowBase database repository.

If Cross Origin Resource Sharing (CORS) is in use, the CORS address MUST use the same protocol as the webpage containing the JavaScript client. If the web page uses HTTPS, then the CORS address must also be HTTPS.

10.2. Configuring the Instant module

The Instant Server is disabled by default and must be explicitly enabled using configuration properties. The InstantServerConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.instant.enabled

Toggles whether the instant module is enabled.

com.iknowbase.instant.suspendTimeoutLP

How long in miliseconds a Long Polling connection is suspended before the server resumes the connection. This will trigger a reconnect by the client.

com.iknowbase.instant.enableCORSFilter

Server side support for Cross Origin Resource Sharing (CORS). The legal values are either "true" or "false".

com.iknowbase.instant.cleanupTopicThreshold

How often the disconnect cleanup maintenance thread looks for disconnected clients.

com.iknowbase.instant.cleanupDisconnectedConnectionsThreshold

How long a connection needs to be in disconnect inactivity queue before it is examined and validated.

com.iknowbase.instant.broadcastDelayUserListUsers

Delay between a client subscribe and the issued broadcast for userList is. Must be large enough to allow the client to complete the handshake and enter suspend mode.

com.iknowbase.instant.broadcastDelayUserListJoin

Optional delay between a detected join and the issued broadcast. Default no delay.

com.iknowbase.instant.broadcastDelayServerRequest

Optional delay between a serverRequest and the issued broadcast. Default no delay.

Note
Make sure you also configure the SecureTokenEngine to enable authentication for web clients

10.2.1. InstantQueueServerConfiguration

The Instant Queue Server is the unit responsible for consuming messages published using Instant’s PL/SQL API and delivering them to the specified topic where all web clients are connected. This queue listener can of course be configured through The InstantQueueServerConfiguration which accepts these configuration properties:

Property name Description

com.iknowbase.instant.aq.enabled

Toggles whether AQ messages is processed by this instance at all. The legal values are either "true" or "false".

com.iknowbase.instant.aq.dequeTimeoutSeconds

Number of seconds each dequeue() shall wait before recycyling.

com.iknowbase.instant.aq.spawnPolicy

Decides when the AQ server starts listening for a new message. Use "immediate" for parallel processing, or "delayed" for serial processing.

10.3. Testing and troubleshooting

10.3.1. Administration console

For developers, the Administration Console provides monitoring and testing details for Instant.

  • instant > topics: A list of all topics.

  • instant > topics > [topicName]: Detailed information about the specific topic, including all connected clients.

  • instant > test: Test page for Instant Server.

You may encounter a session cookie collision if you

  • Deploy iKnowBase with Viewer module to an iKnowBase Quickstart server (e.g. host1:443).

  • Deploy iKnowBase with Instant module to a separate iKnowBase Quickstart server on the same host (same hostname seen by web client) and a different port (e.g. host1:8443).

  • Use CORS from javascript client.

As the host name is the same for both requests, the session cookie name will by default be valid for both requests. The session cookie is only valid on one server, which will result in a replaced session cookie and effective log out of the authenticated user.

Resolve the issue by changing the session cookie name for one of the applications or use different hostnames for accessing the applications.

10.3.3. WebLogic: WARN AtmosphereFrameworkInitializer - WebLogic 12c unable to retrieve Servlet. Please make sure your servlet-name is 'AtmosphereServlet' or set org.atmosphere.servlet to the current value

This warning can safely be ignored.

The current Atmosphere library incorrectly switches to BlockingIO if JSR356AsyncSupport is not available.

ERROR   DefaultAsyncSupportResolver - Failed to create comet support class: class org.atmosphere.container.JSR356AsyncSupport, error: java.lang.reflect.InvocationTargetException
ERROR   DefaultAsyncSupportResolver - Switching to BlockingIO

This has been registered as Atmosphere Issue 2018 and fixed for future versions. iKnowBase ships with a workaround to avoid BlockingIO and you should see the previous ERROR messages immediately followed by:

WARN    IKBAsyncSupportResolver - Atmosphere issue 2018 detected. Overriding asyncSupport class from BlockingIOCometSupport to Servlet30CometSupport to avoid Blocking IO

11. Viewer module

The viewer module is the main runtime component of iKnowBase, responsible for serving content (pages and documents) to end users over a web interface. The module is almost always enabled, and we rarely recommend that it be disabled.

The ViewerConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.viewer.enabled

Toggles whether the viewer server modules are available.

11.1. ContentServer

The Content Server is the unit responsible for serving file content, such as word documents or PDFs. The ContentServerConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.contentServer.contentCacheHeader

Controls cache-related http headers generated by default (when no cache-control is specified in the url). When set to "" (blank), none of the headers Cache-control, Last-Modified or ETag are generated. When set to a non-blank value, the specified value is used for Cache-control, while Last-Modified and ETag are set based on the timestamp of the document.

The default value of max-age=0 will make browsers cache the received documents, but re-validate the content before use (re-validation will typically be much faster than a new download). Any proxy server will also cache the content, and use re-validation to verify the cache status.

com.iknowbase.contentServer.defaultContentDisposition

Set to "inline" to have the browser try to open documents in-line, or to start Office for viewing. Set to "attachment" to have "save as" as the default browser behaviour.

com.iknowbase.contentServer.createResponseHeaders

Toggles whether to include HTML-headers for document information. Normally left unchanged.

11.2. PageEngine

The Page Engine is the unit responsible for composing portlets and data, and rendering information to web clients.

The PageEngineConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.pageEngine.contentCacheEnabled

Toggles whether content caching is used at all. The legal values are either "true" or "false".

11.3. ContentViewerConfiguration

The ContentViewerConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.contentViewer

Decides if and how clueTip scripts are rendered. The legal values are none (default), delayed (load scripts only if tooltip information is found in the page), traditional (always load clueTip scripts).

11.4. SearchClientConfiguration

The Search Client, using SOLR, handles connections to a SOLR search server. iKnowBase is capable of using multiple search engines for searching. The administrative interface uses a logical "search engine name" when mapping content for searching; for each such there is a corresponding SearchEngineConfiguration accepting these configuration properties:

Property name Description

com.iknowbase.searchEngine.<searchEngineName>.search.URL

URL to index server, e.g. http://solr.example.com/solr.

com.iknowbase.searchEngine.<searchEngineName>.search.connectionTimeoutMillis

Max number of milliseconds to wait for the connection.

com.iknowbase.searchEngine.<searchEngineName>.search.operationTimeoutMillis

Max number of milliseconds to wait for the operation.

Note that you may also configure search engines using the iKnowBase Java Development Toolkit. Any managed bean of type "org.apache.solr.client.solrj.SolrClient" will be discovered, and a corresponding search client will be created. Using this mechanism provides the ultimate control of the SolrServer connection parameters.

11.5. Activiti BPM Platform

iKnowBase comes with an embedded process engine based on the Activiti BPM Platform. This engine must be explicitly enabled if you want to use it.

You should consider deploying the iKnowBase Process Studio which is available as a plugin extension.

The ActivitiProcessEngineConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.process.activiti.enabled

Toggles whether the activiti engine is enabled.

com.iknowbase.process.activiti.jobExecutorEnabled

Toggles whether the activiti engine will pick up jobs from the database, or only respond to online requests.

com.iknowbase.process.activiti.processEngineName

Sets the name of the process engine. Should normally not be changed.

com.iknowbase.process.activiti.mailServerDefaultFrom

Sets default "from" address for email sent from activiti.

com.iknowbase.process.activiti.mailServerHost

Hostname for smtp server used when sending email.

com.iknowbase.process.activiti.mailServerPort

Port number for smtp server.

com.iknowbase.process.activiti.mailServerUsername

Username used for logging in to email server when sending email.

com.iknowbase.process.activiti.mailServerPassword

Password used for logging in to email server when sending email.

12. WebDAV module

iKnowBase comes with a WebDAV server serving iKnowBase documents to WebDAV Clients. This enables direct editing of Microsoft Office documents with a Microsoft Office client. It also provides development support for WebDAV file system extensions (see Development Guide).

12.1. Special requirements

12.1.1. License from Milton.io

The WebDAV server is built with Java WebDAV Server Library from Milton.io. A valid commercial license is required and can be purchased from Milton.io. The WebDAV server must be configured with path to a directory containing the license file.

12.1.2. WebDAV traffic is served from /

Due to client requirements, the WebDAV Server must be available at context root / (the root). Collision with the iKnowBase Viewer module (also deployed to /) is avoided using either User-Agent detection or a separate virtual host for WebDAV traffic.

By default, all known Microsoft Office User-Agents will be served by the WebDAV server (the expression is configurable). This detection mechanism is default and recommended.

For special requirements, you may also use a separate virtual host for the WebDAV traffic (e.g. using webdav.example.com, while other applications are deployed on intranet.example.com). When enabled together with the Viewer module, use the hostnames WebDAV configuration option.

12.1.3. SSL

SSL is strongly recommended and Microsoft Office will require SSL for some authentication types.

12.1.4. Clustering

The WebDAV module supports clustering from iKnowBase 7.1.1.

12.1.5. Failover on expired session

Failover for an expired editing session works seamlessly with Basic and Spnego authentication, but forms based authentication and SAML2 authentication will prompt the user to save a copy and then trigger reauthentication.

12.2. Installation

Review WebDAV Special Requirements and configure the WebDAV Server module accordingly.

The WebdavConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.webdav.enabled

Toggles whether the WebDAV server modules are available.

com.iknowbase.webdav.userAgentExpr

Regular expression matching the User-Agent headers the WebDAV server will respond to. Defaults to all known Microsoft Office User-Agents.

com.iknowbase.webdav.pathExpr

Regular expression matching the non root paths the WebDAV server will respond to. Defaults to iKnowBase WebDAV Content path only.

com.iknowbase.webdav.hostnames

Hostnames the WebDAV server will respond to. Comma delimited.

com.iknowbase.webdav.lockTimeoutSeconds

Default lock timeout in seconds.

milton.license.dir

File system directory containing the license files for Milton WebDAV.

See Web Application Security for configuration options for form based authentication for WebDAV.

12.2.1. Authentication

The WebDAV module supports these authentication options in prioritized order (first enabled module wins):

  • Header

  • Spnego

  • Form based (MS-OFBA protocol)

  • Basic

  • Container (Oracle WebLogic only)

For the iKnowBase web server, the default authentication option is "Form". For Oracle WebLogic, the default is "Container".

12.3. Presentation configuration

To set up direct editing of Microsoft Office documents, do the following:

  • Using the iKnowBase Administration Console, configure the "WebDAV Path" in the relevant Domain configuration with the proper value, e.g. "https://webdav.example.com/".

  • In relevant content viewers, configure an "Edit using WebDAV" action.

  • From a supported web browser, click the "Edit using WebDAV" icon.

12.3.1. Launching applications for editing

From iKnowBase 7.0, applications are launched using browser protocol extensions and Microsoft Office URI schemes.

If the document type has been registered as a WebDAV type and presentation has been configured to display "Edit using WebDAV", the registered application will launch when the link is clicked. The link includes information regarding which application to launch.

Before iKnowBase 7.0, applications were launched using the Microsoft SharePoint NPAPI plugin (SharePoint.OpenDocuments and ffSharepointPlugin). Support for this plugin has been removed in favor of browser protocol extensions.

12.3.2. WebDAV registration for file types

WebDAV registration for each type file type is managed in iKnowBase administration console under Mimetypes. "Edit using WebDAV" will only be available for types enabled for WebDAV. The associated WebDAV script must match the Microsoft Office URI Scheme for the application that should be used for editing the file.

12.4. Troubleshooting

For troubleshooting, do this:

  • Find a suitable document in your iKnowBase installation, making note of the document ID. For this example, we assume a document ID of "2804".

  • Using a web browser, go to the url "https://webdav.example.com/ikb$content/2804/document.docx" (using the proper hostname and a suitable extension). Open (or save + open) this document, and verify that it opens properly in e.g. Microsoft Word.

  • Using Microsoft Word directly, go to the "Open Document" dialog (Ctrl+F12 will often do the trick). Here, enter the same full URL, including the https-prototcol and all ("https://webdav.example.com/ikb$content/2804/document.docx") and click "Open". Verify that it opens properly.

  • Make sure that the plugin is not blocked by the browser (in such case you will be prompted).

12.4.1. Microsoft Office 2011 for Mac requires SSLv3 protocol support

Microsoft Office 2011 for Mac requires that the old SSLv3 protocol is enabled. Web sites will typically want to remove support for SSLv3 due to the SSLv3 vulnerability "POODLE", but this will result in the message "No connectivity with the server" when opening a document using WebDAV.

The WebDAV web site must support SSLv3 until this issue is resolved.

iKnowBase reference: IKB-2867

12.4.2. Microsoft Office 2016 for Mac and MS-OFBA

There are unresolved authentication issues regarding Office 2016 for Mac clients when using forms based authentication (MS-OFBA).

iKnowBase reference: IKB-3060

12.4.3. Re-authentication problems with form based login

Form based authentication for WebDAV uses persistent session cookies. The session is valid until server restart or idle timeout.

When a presented session cookie is invalid, Microsoft Office will say that there is a permission problem and offer to save a copy. If you continue with the save copy dialog, you will be able to re-authenticate and save your document.

Note
Microsoft Office also offers the sign in option when a permission error occurs. However, this option will not try to re-authenticate when you still have a persistent cookie.
Note
A restart of the Microsoft Office application will prompt for new authentication.

12.4.4. Word did not save the document (0x80004005)

When a form based authentication is invalid and you re-authenticate (see previous section), this error message may occur if you cancel the re-authentication dialog: "Word did not save the document" with the error code 0x80004005 in event viewer. A hotfix is available at http://support2.microsoft.com/kb/2479169.

12.4.5. Browser warning when launching application for direct editing

By default, all browsers will display a warning when clicking the "Edit using WebDAV" (or similar) link.

Chrome displays an option to remember the decision and further warnings can then easily be avoided.

The warning in Firefox and Internet Explorer can be avoided by adding the WebDAV hostname to Internet Explorer’s Trusted Zone. Note that if you run WebDAV on a separate hostname, then only that hostname is required to be in the Trusted Zone.

Warning
While Intranet Zone will have Compatibility View and Automatic Windows login enabled by default, the Trusted Zone will not. You may add the site to Compatibility View manually (if required) and enable Automatic Windows login by setting Trusted Zone custom level to "Automatic login with current user name and password".

13. WebServices module

iKnowBase comes with a WebServices server that provides SOAP-access to the Service API. This is disabled by default, but can be enabled when needed.

The WebServicesConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.ws.enabled

Toggles whether the webservices module is enabled.

com.iknowbase.ws.mtomEnabled

Toggles whether MTOM is enabled for the SOAP endpoints.

com.iknowbase.ws.security.requireAuthentication

Toggles whether WS-SECURITY based authentication is required to connect to the SOAP server.

com.iknowbase.ws.security.loginModuleName

Name of login module to handle login requests. Use default value.

com.iknowbase.ws.security.trustedPrincipal

Name of trusted principal (user or group) if only some users are to be given access.

14. Content Transformation Providers

See Content Transformation Service in the Development Guide for concept and usage details.

These providers are automatically enabled

  • ImageEditor

  • Oracle Multimedia (provided ordsys.ordimage is available in the database)

  • Oracle Text

These providers have specific installation requirements detailed below

  • FileConverter

  • CloudConvert

14.1. FileConverter

The FileConverter is a content transformation provider that converts documents from a number of file formats, to PDF, HTML or a number of image formats.

Note that the FileConverter is licensed separately from the core iKnowBase product. Note that the FileConverter requires 64-bit Linux "x86_64" architecture.

14.1.1. Understanding the FileConverter

Usage of the FileConverter works like this:

  • In the database, a file (Word document, PowerPoint, etc.) is put onto a Queue through the use of the database package BATCH_FILECONVERT_CLIENT.

  • The FileConverter, running in the batch server, will receive this document from the Queue via TransformationServer.

  • The FileConverter will write the file to disk, and use Oracle’s Outside In technology to convert it to a new format.

  • The FileConverter will receive the new, converted file, and put on the queue again, using a correlation ID that lets the client find it

  • In the database, the client will receive the document.

The process above implies that for the FileConverter to work, you also need to install a separate Outside In program to the server.

14.1.2. Installing Outside In technology

The Outside In programs are delivered separately from iKnowBase, in a zip-file that will typically be named something like fileConverter-linux-x86-64-outsidein-835.zip. Install this file using the following steps:

  • Create a directory on the server, where you want to install the fileConverter

  • Unzip the file, which should create a subdirectory fileConverter

  • Configure the FileConverter with the proper location

$ cd /opt/iknowbase
$ unzip fileConverter-linux-x86-64-outsidein-835.zip

14.1.3. Configuration properties

After installing the outside in technology, you must configure the file converter. The FileConverterConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.batch.fileConverter.outsideInDirectory

Location of outside in installation. File Converter is disabled when this is not set.

14.1.4. Testing and troubleshooting

Running tests

The first step is to verify that the converstion program itself runs. Go to the installation directory, and verify that you may run document conversion from the command line:

$ ./exsimple Test.docx Test.pdf pdf.cfg
EX_CALLBACK_ID_PAGECOUNT: The File had 5 pages.
Export successful: 1 output file(s) created.

The second step is to run a "local" conversion from the web-application. Using a browser, open the "/ikbBatch" application. In the tab named "fileconverter", you will find a number of links for test conversions. They will convert from a Microsoft Word document and a Microsoft PowerPoint presentation, to a number of export formats. Clicking on these will run the server-side conversion, and return the converted document. Using the tests named "Test.docx (local)" and "Test.pptx (local)" will run the test locally, without any database involvment.

The third step is to run a "queue based" conversion. The procedure is the same as above. Using the tests named "Test.docx (queue)" and "Test.pptx (queue)" will send the document through the database for conversion, the same way as most production usage will work.

Missing libraries

A common problem is for conversion to image formats to fail under Linux, due to missing libraries:

$ ./exsimple Test.docx Test.pdf pdf.cfg
./exsimple: error while loading shared libraries: libstdc++.so.5: cannot open shared object file: No such file or directory
./exsimple: error while loading shared libraries: libXm.so.3: cannot open shared object file: No such file or directory

Search for the missing file using the "locate"-command, as shown below. If the file is missing, or only available as a stub, the proper library must be installed.

  • If the library libXm.so.3 is missing, this is often due to missing openmotif22. Try the command up2date openmotif22.

  • For libstdc.so.5, try using `yum install compat-libstdc-33.x86_64`.

  • Or, search the web for similar problems, and follow instructions.

Fonts not found

If font path is not set you get the following message:

[root@build fileConverter]# ./exsimple test.docx test.tiff tiff.cfg
        EX_CALLBACK_ID_PAGECOUNT: The File had 0 pages.
EXRunExport() failed: No valid fonts found (0x0B03)

This can be fixed by setting the environment variable GDFONTPATH to a true type font directory.

One way of doing this is to add a file named "fonts.sh", with the following content, to the /etc/profile.d directory:

export GDFONTPATH=/usr/share/fonts/liberation/
Missing fonts

Another common problem is missing fonts:

[root@ip-10-53-107-93 fileConverter]# ./exsimple Test.docx Test.pdf pdf.cfg
EX_CALLBACK_ID_PAGECOUNT: The File had 1 page.
EXRunExport() failed: The font directory does not contain any font files or the directory is invalid (0x0B02)

This can often be fixed by installing the liberation fonts:

$ yum install liberation-fonts-common liberation-mono-fonts liberation-sans-fonts liberation-serif-fonts libreoffice-opensymbol-fonts

14.2. CloudConvert

The CloudConvert content transformation provider supports a large set of transformations via www.cloudconvert.com, including among other things format transformation and image manipulation.

It requires a valid account with www.cloudconvert.com as well as HTTPS network access to www.cloudconvert.com.

14.2.1. Understanding the CloudConvert provider

Concept and transformation instructions are covered in detail in the Development Guide.

14.2.2. Installation

Create an account with www.cloudconvert.com and configure iKnowBase with the API Token from the user account.

The provider is now ready for use through the Content Server or the PLSQL API.

14.2.3. Configuration properties

You may add new or reconfigure transformation types to use the "cloudconvert" provider where applicable.

The CloudConvertConfiguration accepts these configuration properties:

Property name Description

com.iknowbase.content.transformation.cloudconvert.apiToken

Subscription token for accessing the www.cloudconvert.com account.

com.iknowbase.content.transformation.cloudconvert.supportedFormats

List of supported formats for input or output.

com.iknowbase.content.transformation.cloudconvert.http.connectTimeout

Optional: www.cloudconvert.com HTTP client connect timeout (ms).

com.iknowbase.content.transformation.cloudconvert.http.readTimeout

Optional: www.cloudconvert.com HTTP client read timeout (ms) if no data has been received.

com.iknowbase.content.transformation.cloudconvert.http.proxy.type

Optional: www.cloudconvert.com HTTP client outgoing proxy (<null>, HTTP or SOCKS).

com.iknowbase.content.transformation.cloudconvert.http.proxy.hostname

Optional: www.cloudconvert.com HTTP client outgoing proxy hostname.

com.iknowbase.content.transformation.cloudconvert.http.proxy.port

Optional: www.cloudconvert.com HTTP client outgoing proxy port.

14.2.4. Testing and troubleshooting

The CloudConvert content transformation provider is available through the Content Transformation Service, which is enabled in both the Content Server (Viewer) and Batch server.

See www.cloudconvert.com API description and console for valid input to output formats and applicable configuration options.

Test using Content Server (Viewer) by accessing the URLs (examples):

  • To HTML: /Content/<DOCUMENT_ID>/transformation=cloudconvert:html/<FILENAME>.html

  • To PDF: /Content/<DOCUMENT_ID>/transformation=cloudconvert:pdf/<FILENAME>.pdf

Transformation fails with HTTP status 40x

Verify that the transformation (all options) is valid using www.cloudconvert.com API description and console.

Enable TRACE logging to get more information about the content transformation process.

Transformation times out

You may need to increase the various timeout settings for the transformation, see Development Guide for details.

15. Plugins

You can install and activate custom plugins and plugins distributed with iKnowBase. iKnowBase is distributed with two plugins: Content Studio and Process Studio.

Note
Neither of the iKnowBase plugins is installed by default.

For installation instructions, see the Installing plugins and patches section.

15.1. Content Studio plugin

iKnowBase Content Studio is a suite of web-based tools for publishers. It includes document and image picklists.

The Content Studio plugin accepts these configuration properties:

Property name Description

com.iknowbase.plugin.ikbcontentstudio.changeDocumentTypeQuickLinkGuid

The guid of the quicklink used for chaning document types. Default value 19E06AFF1BD92038E050000A18006129, ie quicklink "CS Publish links".

com.iknowbase.plugin.ikbcontentstudio.completeStatusValueExternalKey

The external key of the status value used for completed documents (IKB$STATUS), used as filter on the approval page (/cs/approva). Default value IKB_COMPLETE.

com.iknowbase.plugin.ikbcontentstudio.imageDefaultAclExternalKey

The external key of the acl to be used as default acl for images, both in the image form and when uploading an image using drag and drop. No default value.

com.iknowbase.plugin.ikbcontentstudio.imageDefaultFolderExternalKey

The external key of the dimension to be used as default folder for images in the image form. No default value.

com.iknowbase.plugin.ikbcontentstudio.imageDoctypeExternalKey

The external key used for image documents, used both by image form and content queries. Default value IKB_DOCTYPE_IMAGE.

com.iknowbase.plugin.ikbcontentstudio.subtypeAttributeExternalKey

The external key of the subtype attribute, used as filter in the document archive/picklist. Default value IKB_COMMON_SUBLIST.

15.2. Process Studio plugin

iKnowBase Process Studio is a web-based tool for managing Activiti process definitions, starting and monitoring processes and completing user tasks. It requires that the Activiti Process Engine is enabled, see Activiti BPM Platform.

15.2.1. Troubleshooting

java.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment

If you get the exception java.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment, you should add the following to your application.properties file:

JAVA_OPTIONS=-Djava.awt.headless=true

Web Application Security

16. Quick install

For the iKnowBase web server, the default configuration will be

  • Form based username and password authentication against the iKnowBase User Repository.

  • RememberMe functionality.

If you are installing on Oracle WebLogic, the default will be

  • HTTP basic username and password authentication against the internal WebLogic user repository.

If you need to customize authentication, the basic steps are

  • Configure and set a default authentication module.

  • Optional: Configure any extra authentication modules you need.

17. Overview

The iKnowBase web application security implementation is based on the Spring Security framework and takes care of user authentication and authorization to specific web application protected areas.

An authentication module combines authentication methods with authentication providers.

Authentication Module
Figure 2. Authentication Module

Whereas an authentication mechanism defines how the client interacts with the system to provide the necessary credentials for authentication, the authentication provider verifies the credentials and, if verified, creates the authentication object for the application. The authentication object are then evaluated by the authorization rules associated with the requested resource.

The authentication process follows this flow:

Authentication Process
Figure 3. Authentication Process

The authentication modules may authenticate the user based on the incoming web request or start a authentication challenge flow.

ALL authentications will ultimately be verified by loading and verifying the user from the iKnowBase User Repository.

Multiple authentication modules (mechanisms and providers) are supported and can be activated at the same time. One is set as the default and the other active modules may be explicitly triggered. This image provides an overview of the possible combinations:

Supported Authentication Modules
Figure 4. Supported Authentication Modules
  • The Saml module may be triggered from the form based login module.

  • The Social module is triggered from the form based login module.

  • The Secure Token module is intended for application to application authentication.

  • The Container Specific module delegates to the application server.

  • The Public module triggers if none of the other modules have authenticated the user.

18. Configuration

Web Application Security is configured using configuration properties.

See SpringSecurityConfiguration for detailed configuration options.

19. Authentication

19.1. Default authentication module

When the users enters a protected area, the default authentication module will be triggered and as part of the authentication process challenge the user for user credentials.

When no explicit default module has been set, the following defaults apply:

Application Server Modules Authentication module Authentication method Authentication provider Comment

iKnowBase web server

*

Form

Form

iKnowBase User repository

iKnowBase web server

Instant

Basic

Basic

iKnowBase User repository

Due to client compatibility.

Oracle WebLogic

*

Container

Container dependant

Container dependant

19.1.1. Instant

"simple authentication" in this section refers to the following authentication mechanisms in prioritized order (first enabled wins)

  • Header

  • Spnego

  • Basic

iKnowBase Instant requires "simple authentication" if you want to use the /private Instant endpoint and this is therefore set as the default. If not, you may reconfigure and use other modules such as Form based authentication.

19.1.2. WebDAV

Form based authentication for WebDAV uses the MS-OFBA protocol. See WebDAV specific configuration options for form based authentication.

19.2. Force a specific authentication mechanism

A client may trigger a specific type of authentication other than the configured default. iKnowBase supports triggering a specific mechanism using the either path /ikb$auth/<authentication mechanism>/authenticate or HTTP request header X-IKB-AUTH.

As an example, while the default authentication is form based, a client may trigger the HTTP Basic mechanism by accessing /ikb$auth/basic/authenticate or by issuing the HTTP request header X-IKB-AUTH: Basic.

Note
Path trigger has lower case "basic", but header and default module setting has the initial letter in uppercase "Basic".

19.3. Available authentication modules

Available authentication mechanisms:

Authentication mechanism Path trigger Header trigger Can be used as default Authentication provider Description

Basic

/ikb$auth/basic/authenticate

X-IKB-AUTH: Basic

YES

UsernamePassword

Basic authentication for username and password.

Container

/ikb$auth/container/authenticate

X-IKB-AUTH: Container

YES (WebLogic only)

Container

Container based authentication (depends on security setup in the application server).

Form

/ikb$auth/form/authenticate

X-IKB-AUTH: Form

YES

UsernamePassword, Social, Saml

Form based authentication.

FormWebdav

/ikb$auth/formWebdav/authenticate

X-IKB-AUTH: FormWebdav

YES (WebDAV only)

UsernamePassword, Social, Saml

Form based authentication for WebDAV (MS-OFBA protocol authentication page traffic).

Msofba

/ikb$auth/msofba/authenticate

X-IKB-AUTH: Msofba

YES (WebDAV only)

UsernamePassword, Social, Saml

Form based authentication for WebDAV (MS-OFBA protocol WebDAV traffic).

Header

/ikb$auth/header/authenticate

X-IKB-AUTH: Header

YES

Header validation

Request header based authentication.

Spnego

/ikb$auth/spnego/authenticate

X-IKB-AUTH: Spnego

YES

Kerberos realm and LDAP

SPNEGO based authentication for Kerberos single sign on (i.e. Microsoft Windows domain single sign on).

Saml

/ikb$auth/saml/authenticate

X-IKB-AUTH: Saml

YES

SAML2 identity provider

SAML2 based authentication with SAML2 compatible identity providers (i.e. ADFS, Feide, Salesforce).

Google

/ikb$auth/google

N/A

NO

Social connection

Uses form based module. Will verify a preexisting social connection (created using account activation link).

Twitter

/ikb$auth/twitter

N/A

NO

Social connection

Uses form based module. Will verify a preexisting social connection (created using account activation link).

Facebook

/ikb$auth/facebook

N/A

NO

Social connection

Uses form based module. Will verify a preexisting social connection (created using account activation link).

LinkedIn

/ikb$auth/linkedin

N/A

NO

Social connection

Uses form based module. Will verify a preexisting social connection (created using account activation link).

Microsoft Live

/ikb$auth/live

N/A

NO

Social connection

Uses form based module. Will verify a preexisting social connection (created using account activation link).

iKB Secure Token

N/A

N/A

NO

Secure token validation

iKnowBase secure token based authentication.

iKB Auth Token

N/A

N/A

NO

Auth token validation

iKnowBase Auth token based authentication.

RememberMe

N/A

N/A

NO

RememberMe

Uses form based module. Will verify RememberMe cookies (created during form based login if checked).

The authentication provider token "UsernamePassword" must be processed by an authentication provider capable of validating username and password.

All modules must ultimately validate the user against the iKnowBase User Repository using username lookup for an authentication to be considered successful.

19.3.1. Username and password capable Providers

iKnowBase supports multiple UsernamePassword providers for verifying the submitted username and password.

Available authentication providers for UsernamePassword:

Provider Default enabled Order Description

LDAP

NO

1

LDAP user repository.

iKnowBase

YES(if non-container mode)

2

iKnowBase User repository.

Both modules may be enabled at once and will be tried in the specified order.

19.3.2. SAML capable Providers

An external account hosted by a SAML2 identity provider can be linked to an existing iKnowBase user account and used for authentication.

In the SAML module, iKnowBase acts as a service provider that authenticates the user with an identity provider.

Basic steps to enable iKnowBase as a service provider:

  • Setup HTTPS for the iKnowBase web site (may be terminated in front of iKnowBase).

  • Create / reuse a Java Keystore with a private key and certificate for signing, encryption and validation of SAML metadata and messages.

  • Configure iKnowBase: Enable Social (social infrastructure is required by the SAML module).

  • Configure iKnowBase: Enable SAML.

  • Configure iKnowBase: Use the keystore with the specified private key(s).

  • Start iKnowBase and use the SAML metadata generator to generate the metadata along with configuration settings.

  • Store the metadata XML file to the application server’s file system.

  • Configure iKnowBase: According to the generator’s configuration settings.

Basic steps to enable authentication with an identity provider:

  • Configure iKnowBase: Add the identity provider.

  • Configure identity provider: Add the iKnowBase service provider and map exchanged SAML attributes for the authenticated user.

SAML support is implemented using "spring-security-saml" (Spring Security SAML documentation).

SAML account connection

A SAML account can be mapped to an iKnowBase account using either iKnowBase Auth Token or the auto connect feature.

iKnowBase auth token "ACTIVATION" is a one time token that can be issued to a pre-existing iKnowBase user. When such as token is used, the user can choose authentication method. After successful authentication with an external identity provider, the token is used to map the accounts.

The SAML auto connect feature can be used if the identity provider knows the iKnowBase user name and can issue this username attribute in the SAML response. iKnowBase will connect the accounts if a user was found with the specified username.

Note
Account connections leverage the social connection infrastructure. Existing connections per user can be viewed in administration console.
SAML and multiple identity providers

iKnowBase supports multiple identity providers. The user may choose identity provider using either the login form or SAML identity provider discovery mode.

The login form provided with iKnowBase will add login buttons for each configured identity provider. The login form may be fully custom implemented.

The discovery mode redirects the user to a discovery area where the default provided implementation displays a list of valid identity providers. The user may choose a provider and start the authentication process. The discovery area also takes an optional parameter that specifies which identity provider to use and will, if specified, start the authentication process automatically. The discovery area can be fully customized and allow custom automatic detection of the correct identity provider.

SAML and multiple service providers

Multiple service providers may be specified and the default strategy for selecting a service provider is configured using the "spSelectionStrategy" option. The default strategy is to resolve using the request’s serverName, which normally will be the value of the HTTP Host header. An alternative is to use the alias path strategy where the Service Provider Entity ID must be present on the login path on the form …​/alias/@localEntityId@.

SAML services and endpoints

SAML administration services:

Path Description

/ikb$auth/saml/display

Metadata web display (for iKnowBase service provider metadata).

/ikb$auth/saml/generate

Metadata generator (for iKnowBase service provider metadata).

/ikb$auth/saml/metadata

Metadata download URL (for iKnowBase service provider metadata). Supports additional alias=entityId path parameter if multiple SPs are present.

SAML endpoints:

Path Description

/ikb$auth/saml/authenticate

Explicit SAML authentication trigger. Common iKnowBase auth trigger.

/ikb$auth/saml/discovery

IdP discovery service.

/ikb$auth/saml/login

Explicit SAML authentication trigger. Supports multiple SPs using "alias" path parameter.

/ikb$auth/saml/logout

Global logout. Use common /ikb$auth/logout for local logout.

/ikb$auth/saml/SingleLogout

Single Logout processing. (Called during global logout)

/ikb$auth/saml/SSO

Web Single Sign-on processing. (Called during single sign-on)

/ikb$auth/saml/HoKSSO

Web Single Sign-on Holder of Key processing. (Called during single sign-on)

SAML verified identity providers

iKnowBase has been verified against these providers:

  • Microsoft ADFS 2.0 and 3.0 using HTTP POST binding

  • Feide OpenIdP using HTTP POST binding

  • Salesforce using HTTP POST binding

  • OpenAM using HTTP POST binding

19.3.3. Social capable Providers

An external social account can be linked to an existing iKnowBase user account and used for authentication. iKnowBase supports multiple social providers.

The social authentication module requires that "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" are installed. Download and install "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" from http://www.oracle.com/technetwork/java/javase/downloads/index.html.

When enabling social authentication, you are required to set password and salt used for encrypting the secret user tokens received from the social provider.

Each social provider is configured and enabled separately and require that you configure them with the registered application id and secret. Refer to the social provider’s documentation for application registration.

Some social providers require that you specify the OAuth 2.0 Redirect URL(s). Use <absolute url to site><iknowbase contextPath>/ikb$auth/<providerid>. Example: https://www.example.com/ikb$auth/google or https://www.example.com/ikb$auth/google.

19.3.4. Trusted HTTP request header as authentication

The iKnowBase Header authentication module supports authentication based on a trusted HTTP request header. This means that if you have a reverse proxy in front of iKnowBase that handles the authentication and is able provide the user name in a guaranteed and trusted HTTP request header, the user will be logged in to iKnowBase as well.

It is extremely important that the reverse proxy guarantees the header, meaning that if an end client (user) sends the trusted header it is to be discarded from the HTTP request and not be allowed to reach the iKnowBase web applications.

You may configure the header module with restrictions that must be satisfied before a header is trusted, like server name, ip-address and secret header sent by the reverse proxy.

19.3.5. iKnowBase Auth Token

iKnowBase supports a token called "ikbAuthToken" that can be used if the end user does not know the password associated with the account. The following types and privileges are supported:

TokenType Consumed after use Privilege description

LOGIN

NO

Valid non expired token allows automatic login.

ACTIVATION

YES (successful only)

Valid non expired token allows the end user to choose between multiple authentication activation options.

Tokens are generated using IKB_AUTH_API, see iKnowBase PL/SQL ContentServices API, and used as eith URL parameter ikbAuthToken or HTTP header X-IKB-AUTH-TOKEN.

Example with URL parameter: http://www.example.com?ikbAuthToken=the-generated-token

iKnowBase Auth Token: LOGIN

Enables authentication with only a web link (no username, no password) as long as the has not expired.

Warning
Anyone with a valid non expired trusted login token will be automatically logged in as the user associated with the token!
iKnowBase Auth Token: ACTIVATION

The available activation options are:

  • Set password for the account in the iKnowBase User Repository and proceed with username and password login to iKnowBase.

  • Connect a external (social or saml) account from one of the installed providers to the newly created iKnowBase account and authenticate using external (social or saml) authentication.

Warning
Anyone with a valid non-expired trusted activation token will be allowed to set password / connect using ANY external (social or saml) account!

Requests containing an activation token will be intercepted and will redirect the user to the link without the activation token after successful activation.

19.3.6. Authentication token processing

Before an authenticated user has been established all enabled modules will examine the request for authentication information in the order they are defined. Some modules will only do so on specific paths (path scoped), while other modules will look no matter where the request is sent. A disabled module will skip processing.

If all modules are enabled, they will be called in the following order:

Module Authentication token Path scoped

ikbAuthToken

ikbAuthToken URL param

NO

ikbAuthToken

X-IKB-AUTH-TOKEN Header

NO

Social Login

HTTP request for social login

/ikb$auth/<socialProvider>

Secure Token

_ikbUserToken HTTP header or URL param

NO

Header

HTTP header: [Configurable]

NO

Spnego

HTTP header: Authorization: Negotiate

NO

Container

Container dependant

Container dependant

Form

HTTP POST j_username, j_password

/j_spring_security_check

Basic

HTTP header: Authorization: Basic

NO

Saml

SAML2 messages

/ikb$auth/saml/*

RememberMe

HTTP RememberMe Cookie

NO

Public

NO

Public authentication specific for iKnowBase will be used if no other authentication has been established and public access is allowed.

20. Authorization

A client may have one of three privilege levels:

  1. Public

  2. Normal

  3. Administrator

If a client uses the Public level and tries to access a web area that requires Normal authentication or higher, the user will be asked to authenticate.

The iKnowBase modules have the following access requirements:

Module Area Required level

iKnowBase Viewer

Default (NO ACL)

1

iKnowBase Viewer

ACL with public user

1

iKnowBase Authentication area

/ikb$auth

2

iKnowBase Viewer

ACL without public user

2

iKnowBase Viewer

/private

2

iKnowBase WebDAV

Default

2

iKnowBase WebServices

Default

2 and TRUSTED

iKnowBase Administration console

/ikb$console

3

iKnowBase WebServices requires that the user is registered as a trusted principal through membership in the trusted principal ACL. See the WebServices module section for configuration details.

In addition content (web modules or documents) may also be protected by iKnowBase ACLs as discussed in iKnowBase Development Guide > Security Administration and iKnowBase User Administration Reference > Access Control Lists.

20.1. Administrator

A user receives administrator privileges if the user is flagged as an administrator in the iKnowBase User Repository, see iKnowBase User Administration Reference > Users.

20.2. Development toolkit

Restricting access in development toolkit is discussed in the Security section of the iKnowBase Development Guide > Development Toolkit.

20.3. iKnowBase 6.5 and earlier versions

iKnowBase 6.5 and earlier versions required various roles for allowing access to the application, such as IKB_USERS, IKB_DEVELOPERS and IKB_SYSADMINS. These roles are no longer in use.

From iKnowBase 6.6 the security privileges are:

Privilege Previous applicable role Current requirement

Normal (2)

IKB_USERS

Any user that has authenticated and been verified as enabled in iKnowBase User Repository.

Administrator (3)

IKB_DEVELOPERS, IKB_SYSADMINS

User marked as Admin in iKnowBase User Repository.

21. Switch user

An authorized user may switch to a different identity. This can be used to greatly speed up troubleshooting as a administrator/developer can be granted permission to act as the user that reported the issue.

Warning
Enabling switch user functionality can have severe security implications. Make sure these are understood and approved before activating this module.

Switch user support is enabled with (See configuration reference):

  • configuration enable flag

  • access check procedure

  • an optional audit procedure

21.1. Switch user access check procedure

The access check procedure is mandatory and must have the following signature:

procedure [procedure_name] (
    p_switch_user       ot_switch_user,
    p_return_code       out number,     // 0=PERMIT, others are user defined error codes
    p_return_message    out varchar2    // User defined error message
);

The input object ot_switch user is described below. A return code of 0 will allow access. Any other will deny access and both return code and return message will be logged.

21.2. Switch user audit procedure

Whenever a user switches to or exits from a user happens an INFO message will be logged and the optionally defined audit procedure will be called.

procedure [procedure_name] (
    p_switch_user       ot_switch_user
);

21.3. Switch user database object ot_switch_user

The ot_switch_user object has the following properties:

Property name Value

authenticated_username

Username of the real authenticated user.

switch_to_username

Username of the user that is being switched to-

switch_type

1=SWITCH, 2=EXIT (Only applicable for audit function).

21.4. Trigger switch user

When switch user has been enabled and configured, a user can switch by accessing the path /j_spring_security_switch_user?j_username=[USERNAME TO SWITCH TO] and exit with path /j_spring_security_exit_user. Both services supports an optional redirect URL parameter that defaults to "/".

A user may switch to different users provided access is granted for the switch. The maximum switch depth is 1, i.e. if USER1 has switched to USER2, the user may switch to USER3 provided USER1 is granted the switch. An implicit exit from USER2 is executed before the switch to USER3.

22. Logout

Logout service is available at /ikb$auth/logout with an optional redirect URL param, which supports both relative and absolute URLs.

Note that you are specifically authenticated for each deployed application. If you deploy iKnowBase multiple times, then each will have a [Application context path]/ikb$auth/logout service.

If you use Basic authentication, you may still logout, but the browser will automatically log in again if needed until the browser is closed.

If you use Spnego authentication, you may still logout, but the browser will automatically log in again if needed.

23. Custom security implementation

You may provide your own security implementation. Contact the iKnowBase Product Development team for implementation requirements.

24. Examples

This section covers common setup scenarios and explains the necessary setup.

WebLogic: Note that container mode for WebLogic is supported and you may also as an alternative accomplish the required authentication using WebLogic’s own security modules. These examples does not cover detailed WebLogic container configuration.

24.1. Set password for users in iKnowBase User Repository

This is most often done from inside ikbStudio, but for the first user you will have to do it using the command line:

cd /opt/iknowbase/production
./iknowbase.sh setIkbPassword orcladmin SECRETPASSWORD

You can now log in using the orcladmin user, with the password SECRETPASSWORD.

24.2. Form based authentication against iKnowBase User Repository

For the iKnowBase web server, this is the default. There is no need to change anything.

WebLogic only:

  • Change the default authentication module to: Form

24.3. Custom login form

To use a custom login form instead of the default provided with iKnowBase, adjust the form module configuration with

  • Where the login form is located.

  • Where the error page is located.

Login form requirements for username and password:

  • Username input MUST be named "j_username"

  • Password input MUST be named "j_password"

  • Form action must be [contextPath]/j_spring_security_check

Login form Social requirements:

  • Form action must be [contextPathForIKnowBaseWebApp]/ikb$auth/<social_provider>

  • MUST have a input named "scope" for specifying social provider permissions.

Login form RememberMe requirements:

  • RememberMe input MUST be named "_spring_security_remember_me"

With database persisted sessions (default), sessions are valid for all applications using the same database repository and you may deploy multiple iKnowBase applications and reuse the sessions. If you have changed session persistence (non-default) to memory sessions please note that an authenticated session is valid for one web application only. If you deploy multiple applications, e.g. iknowbase-1, iknowbase-2, etc., the login form needs to POST to /j_spring_security_check relative to the Web Application you want to log in to.

  • /j_spring_security_check (if deployed to the default /)

  • /custom1/j_spring_security_check (if iknowbase is deployed to /custom1)

RememberMe functionality can be used to cross application borders.

The Form login module will remember the original path that triggered authentication and redirect after successful login.

If you submit directly to j_spring_security_check without being redirected to a login form first, i.e. you have implemented login functionality on a public page, you will be redirected to /. You may use an additional parameter "redirect" to explicitly set the redirect location after successful login.

24.4. Basic authentication against iKnowBase User Repository

  • Change the default authentication module to: Basic

24.5. Username and password authentication against LDAP User Repository

  • Change the default authentication module to a username and password capable authentication: Form or Basic (if required, see previous examples)

  • Enable and configure the "LDAP UsernamePassword authentication provider"

If you don’t want fallback to iKnowBase User Repository

  • Disable the "iKnowBase UsernamePassword authentication provider"

24.6. Authentication against LDAP User Repository with mapping for the iKnowBase username

The username mapped to iKnowBase user may also be set to any attribute name.

Given the user

DN:                     CN=My Name,CN=Users,DC=ad,DC=example,DC=com
sAMAccountName:         MYNAME1234
someCustomAttribute:    ORCLADMIN

You will be logged in to iKnowBase as "ORCLADMIN" when authenticating as "MYNAME1234".

24.7. Windows single sign on

It is possible to configure iKnowBase to provide single sign-on authentication on Windows workstations that are already logged into Active Directory using the SPNEGO protocol. There are several steps to this process:

These main steps will be discussed in the following section

  • Change the default authentication module to: Spnego

  • Enable and configure the "Spnego module"

  • Enable and configure the "LDAP UsernamePassword authentication provider"

    • Optionally enable and configure the user sync feature

If you don’t want fallback to iKnowBase User Repository

  1. Disable the "iKnowBase UsernamePassword authentication provider"

24.7.1. Prerequisites

Certain things needs to be known for SPNEGO to work. Let us assume the following configuration:

  • We have windows active directory running on a server called "ad-server.example.com", serving an active directory domain called "ad.example.com".

  • We will install on a server known as "webserver-01.example.com", with the IP-address 10.10.10.10, where it will serve requests to "www.example.com" and "intranett.example.com".

First, we need to make sure that the DNS (domain name system) is set up properly:

  • There must be a single A(Address)-record for the webserver, with the proper IP-address. In the example, this would be a A-record for "webserver-01.example.com", pointing to the IP-address 10.10.10.10.

  • All other names must be aliases, or CNAME-records, pointing to the real server. In the example, this would be two CNAME-records for "www.example.com" and "intranett.example.com", both pointing to "webserver-01.example.com".

The reason for this requirement is that the web browser will use the canonical name when creating its secret "ticket", which the server will then decode. It is therefore important that the client uses the name expected by the server. The configuration can be verified using the "ping" command on a client:

C:\>ping www.example.com
Pinging webserver-01.example.com [10.10.10.10] with 32 bytes of data:
Reply from 10.0.0.24: bytes=32 time=10ms TTL=63
...
C:\>ping intranett.example.com
Pinging webserver-01.example.com [10.10.10.10] with 32 bytes of data:
Reply from 10.0.0.24: bytes=32 time=10ms TTL=63
...

Internet Explorer will, by default, only attempt SPNEGO logins if the client uses a hostname without any dots. Thus, for maximum interoperatibiliy, make sure that it can reach the hosts "www" and "intranett":

C:\>ping www
Pinging webserver-01.example.com [10.10.10.10] with 32 bytes of data:
Reply from 10.0.0.24: bytes=32 time=10ms TTL=63
...
C:\>ping intranett
Pinging webserver-01.example.com [10.10.10.10] with 32 bytes of data:
Reply from 10.0.0.24: bytes=32 time=10ms TTL=63
...

To enable SPNEGO for hostnames with dots, they must be added to IE’s Local Intranet Sites.

For the web server to be able to verify login requests, it will need to communicate with the active directory server. For that, it will need a dedicated user in active directory. The name of that user is arbitrary, but we recommend a name that matches the name of the webserver:

  • The user should be named "iknowbase.webserver-01"

24.7.2. Configure Active Directory (Windows Server 2008 R2)

In active directory, create a user with the following properties:

  • Set username to "iknowbase.webserver-01"

  • Set a secret password. Use a long password with multiple words, such as "SecretPassword!GlobalMilk"

  • Set "User cannot change password"

  • Set "Other encryption options", "This account supports kerberos AES 128" and "…​ AES 256"

    • NOTE: AES encryption is recommended, but the iKnowBase web server supports other encryption types as well through Java GSS-API.

    • NOTE: AES 256 requires that Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files are added to the JVM.

On the active directory server, generate a keytab file for the user. The keytab file contains a username and password in encrypted format, and is used so that the web server can log in without specifying a password in a property file. The parameter to "-princ" is very important, and must follow this presice syntax: First the string "HTTP/", then the canonical name of the web server, as seen by clients, and finally an at-sign followed by the active directory domain name.

C:\>ktpass -out iknowbase.webserver-01.example.com.krb5.keytab -princ HTTP/webserver-01.example.com@AD.EXAMPLE.COM -pass SecretPassword!GlobalMilk -mapUser iknowbase.webserver-01@AD.EXAMPLE.COM -pType KRB5_NT_PRINCIPAL -crypto ALL /kvno 0
Targeting domain controller: ad-server.example.com
Using legacy password setting method
Successfully mapped HTTP/webserver-01.example.com to webserver-01.example.com.
Key created.
Key created.
Key created.
Key created.
Key created.
Output keytab to webserver-01.example.com.krb5.keytab:
Keytab version: 0x502
keysize 68 HTTP/webserver-01.example.com@AD.IKNOWBASE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x1 (DES-CBC-CRC) keylength 8 (0x80b685bf1f52ec5b)
keysize 68 HTTP/webserver-01.example.com@AD.IKNOWBASE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x3 (DES-CBC-MD5) keylength 8 (0x80b685bf1f52ec5b)
keysize 76 HTTP/webserver-01.example.com@AD.IKNOWBASE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x17 (RC4-HMAC) keylength 16 (0x8d32128c7d08747ccc61c3b343c93c47)
keysize 92 HTTP/webserver-01.example.com@AD.IKNOWBASE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x12 (AES256-SHA1) keylength 32 (0xdd23498cd95fdb4b7ae7355b81c7999712bb4d590137af137922af97482ee45d)
keysize 76 HTTP/webserver-01.example.com@AD.IKNOWBASE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 0 etype 0x11 (AES128-SHA1) keylength 16 (0x4296070ee7889d4b26d15986f8190df4)

24.7.3. Configure Web Application Security (SPNEGO and LDAP)

Move the keytab file you generated on the AD-server to the web server. Note that this is a sensitive file, since it can be used to log in on the AD-server: Use a secure transferring mechanism, and keep the file protected while on the web server.

Configure the Spnego module with the following settings: (More options are available)

Property name Value

com.iknowbase.spring.security.spnego.enabled

true

com.iknowbase.spring.security.spnego.keytab

[PATH_TO]/iknowbase.webserver-01.example.com.krb5.keytab

com.iknowbase.spring.security.spnego.targetName

HTTP/webserver-01.example.com@AD.EXAMPLE.COM

com.iknowbase.spring.security.spnego.enabled

true

com.iknowbase.spring.security.spnego.debug

true (optional)

Configure the LDAP UsernamePassword authentication provider: (More options are available)

Property name Value

com.iknowbase.spring.security.ldap.enabled

true

com.iknowbase.spring.security.ldap.serverUrl

ldap://ad-server.example.com:389/DC=ad,DC=example,DC=com

com.iknowbase.spring.security.ldap.clientUserDn

CN=iknowbase.webserver-01.example.com,CN=Users,DC=ad,DC=example,DC=com

com.iknowbase.spring.security.ldap.clientUserPassword

SecretPassword!GlobalMilk

com.iknowbase.spring.security.ldap.userSearchBase.1

CN=Users

com.iknowbase.spring.security.ikbauth.enabled

false (optional if you don’w want fallback to iKnowBase User Repository)

Optionally, specify the LDAP sync profile. If this is specified, user synchronization will happend during login to add new users automatically. If it is ommited, a user who tries to log on must already exist in iKnowBase (typically through a scheduled LDAP Synch). The property "profile" is the externalKey of the "LDAP Sync" profile as specified in ikbStudio: (More options are available)

Property name Value

com.iknowbase.spring.security.ldap.sync.enabled

true

com.iknowbase.spring.security.ldap.sync.profileExternalKey

ADSYNC_PROFILE_EXTERNALKEY

Next, startup iKnowBase. The Spnego module will verify the settings when starting up. The results are logged to the configured log files.

24.7.4. Configure Active Directory for end users

Out of the box, all iknowbase objects are owned by a user called "orcladmin". We recommend that you create a corresponding user in Active Directory, but you may also skip this step if you have enabled fallback authentication to iKnowBase User Repository:

  • Create an AD-user called "orcladmin". No group memberships are required.

24.7.5. Configure user synchronization for Active Directory users

For a user to be allowed access to iKnowBase, the user must exist in the iKnowBase user directory. This is done through a directory synchronization. Use the "LDAP Profile" to configure a profile, and "LDAP Sync" to configure synchronization frequency.

24.7.6. Using an alternative username

By default, logging in using Active Directory will expose the "sAMAccountName" attribute (the windows domain user account name) as the username in iKnowBase. This is the default behaviour, and most often the correct one.

In some scenarios, however, you may want to expose a different username to the iKnowBase application. For example, a new corporate directory may specify account names (login names) based on employee numbers (emp10523), while you want the iKnowBase application to use the historical usernames (which could be based on first initial and last name, e.g. "EPresley"). This is easily solvable, using the following steps:

  • Designate an attribute in the Active Directory to store the username you want to expose to iKnowBase. You may create a new attribute, or you may choose to reuse an existing (but unused) attribute for this purpose. Creating a new attribute is often more work and requires some effort on the Active Directory side, while reusing an existing attribute is easy but creates a mismatch between attribute purpose and actual value (some customer have chosen to use the "ipPhone" attribute, since it is most often not used for anything else).

  • Update Active Directory with the proper information (e.g. for windows logon account "53310761" insert the value "EPresley" into the designated attribute).

  • Update the LDAP UsernamePassword authentication provider with a username mapping as shown below:

Property name Value

com.iknowbase.spring.security.ldap.ikbUsernameAttribute

ipPhone

With this setup, a user logging in with the windows login "53310761" will be known as "EPresley" to iKnowBase.

24.7.7. Configuring multiple and separate user dn patterns

The most frequently used setup is to have all users located in the same Active Directory subtree (in the examples at the beginning of this chapter, this is "CN=Users,DC=ad,DC=example,DC=com"). However, the iKnowBase security framework allows multiple user bases. The application uses the following logic when looking for these values:

  • Always look for com.iknowbase.spring.security.ldap.userSearchBase.1.

  • Keep looking for incremented numbers as long as they exist (e.g. ".2", ".3", etc., but if ".3" is missing, don’t look further).

  • The default value of "CN=Users" is set if no configuration was found.

This is the simplest possible configuration (also the default), with a single userbase. For users in CN=Users,DC=ad,DC=example,DC=com (DC=ad,DC=example,DC=com is set as base in the LDAP server url)

Property name Value

com.iknowbase.spring.security.ldap.userSearchBase.1

CN=Users

This a more complex configuration, with three userbases

Property name Value

com.iknowbase.spring.security.ldap.userSearchBase.1

CN=Employees

com.iknowbase.spring.security.ldap.userSearchBase.2

CN=Premium Members

com.iknowbase.spring.security.ldap.userSearchBase.3

CN=Basic Members

24.7.8. Combined Windows single sign on and iKnowBase User Repository

You may use a combination of Active Directory and iKnowBase login. This is by default enabled. When enabled, the server and client will first attempt to do a single sign on using the Active Directory. If this fails, the client will ask for user information which will be used to first try LDAP authentication against the Active Directory and then authenticate against the internal iKnowBase user repository. This is useful for scenarios where certain administrative users (such as the "orcladmin" user) should not exist in Active Directory.

Building on the previous example, this mode is by default enabled, but you may disable the iKnowBase User Repository by setting

Property name Value

com.iknowbase.spring.security.ikbauth.enabled

false

24.7.9. Conditional SPNEGO support

You may add restrictions for which requests should trigger authentication negotiation. If negotiation is disabled due to a restriction, this module will fallback to a username and password based authentication.

To restrict the negotiation to a set of specific hosts:

Property name Value

com.iknowbase.spring.security.spnego.serverNameExpr

webserver-01.example.com (server name from http request)

To restrict the negotiation to a set of specific IP addresses (X-Forwarded-For IPs are supported):

Property name Value

com.iknowbase.spring.security.spnego.remoteAddrExpr

^10\..*

iKnowBase web server only: To restrict the negotiation to the real immediate client IP (typically a reverse proxy):

Property name Value

com.iknowbase.spring.security.spnego.realRemoteAddrExpr

^192\.168\..*

To restrict the negotiation to a specific request header (any request header):

Property name Value

com.iknowbase.spring.security.spnego.requestHeaderName

User-Agent

com.iknowbase.spring.security.spnego.requestHeaderExpr

.*Firefox/25.*

24.7.10. SPNEGO fallback

The default fallback mode if SPNEGO fails is using redirect to form based login where the user can provide username and password to be validated against the enabled UsernamePassword providers (LDAP, iKnowBase).

If you want fallback to Basic authentication instead, set

Property name Value

com.iknowbase.spring.security.spnego.sendAdditionalHttpBasicChallenge

true

com.iknowbase.spring.security.spnego.fallbackRedirectEnabled

false

This will first send both a Negotiate and a Basic challenge. The client will normally try Negotiate if it supports SPNEGO. If SPNEGO fails, the next challenge will be Basic only.

24.8. Explicit authentication trigger with redirect

The explicit authentication trigger /ikb$auth/<authentication module>/authenticate supports the URL parameter redirect. If the default module is Form based and you want to use the Basic trigger and be redirected to a specific URL afterwards, you would use /ikb$auth/<authentication module>/authenticate?redirect=[Absolute_or_relative_url].

24.9. Integrating with Oracle SSO 10g

The Header authentication module can be used if you want to integrate with the Oracle SSO 10g platform. When using the Header authentication module it is extremely important that the trusted HTTP header is guaranteed by the reverse proxy in front of the iKnowBase web applications.

24.9.1. Guarantee integrity of HTTP server Osso-User-Dn

The header Osso-User-Dn must be guaranteed by the reverse proxyies in front of iKnowBase. The Oracle HTTP Server 10g does not have the capabilities to guarantee that the client cannot send this header, so you must have an additional reverse proxy in front of the Oracle HTTP Server 10g that removes the HTTP header Osso-User-Dn from all incoming requests.

24.9.2. Rely on Oracle HTTP Server OSSO plugin

The iKnowBase Web Application must be deployed to a server behind the Oracle HTTP Server with OSSO plugin and the following paths must be protected and require valid-user.

  • /private

  • /ikbInstant/private

  • /ikb$console

  • /ikb$content

  • /ikb$runner

  • /ikbWebServices

An example Oracle HTTP Server configuration:

NameVirtualHost *:7779
<VirtualHost *:7779>
    Port 7778
    ServerName example.iknowbase.com
    RewriteEngine On
    RewriteOptions inherit
    OssoConfigFile /app/oracle/asPortal/Apache/Apache/conf/osso/osso_example.iknowbase.com.conf
    OssoIpCheck off
    <LocationMatch "^(/private|/ikbInstant/private|/ikb\$console|/ikb\$content|/ikb\$runner|/ikbWebServices)">
        #HTTP Basic authentication
        AuthType Basic
        #We only require a valid user - no group/roles check
        require valid-user
    </LocationMatch>
    ProxyPass / http://ikb-server.example.iknowbase.com:8080/
    ProxyPassReverse / http://ikb-server.example.iknowbase.com:8080/
</VirtualHost>

24.9.3. Configure the iKnowBase Header authentication module

Base configuration:

Property name Value

com.iknowbase.spring.security.header.enabled

true

com.iknowbase.spring.security.header.headerNameUser

Osso-User-Dn

com.iknowbase.spring.security.header.headerNameUserExtractExpr

^cn=().$

com.iknowbase.spring.security.header.sendAdditionalHttpBasicChallenge

true

com.iknowbase.spring.security.header.unauthorizedStatusCode

499

com.iknowbase.spring.security.header.unauthorizedResponseHeaders

Osso-Paranoid:true

If users can access the iKnowBase server directly over the network, you should add additional configuration to ensure the trusted requests must come from the Oracle HTTP Server’s IP address:

Property name Value

com.iknowbase.spring.security.header.realRemoteAddrExpr

[IP address to Oracle HTTP Server ]

24.10. Integrating with ADFS using SAML

Authentication with ADFS is supported using SAML.

This example demonstrates SAML authentication on:

  • ADFS 2.0.

  • Account linking using both ikb Auth Token ACTIVATION or automatic link on the Name ID claim.

  • Form based and default login options.

Prerequisites:

  • Active Directory (AD) with users with a corresponding user account in iKnowBase.

  • Active Directory Federation Services (ADFS) installed and configured to use AD and one of the available authentication options (i.e. Windows SSO using Kerberos, Basic auth, Form auth).

  • HTTPS for iKnowBase web site (may be terminated in front of iKnowBase).

24.10.1. Enable social infrastructure

SAML connection leverages the social connection infrastructure, so we need to configure and enable that:

Property name Value

com.iknowbase.spring.security.social.enabled

true

com.iknowbase.spring.security.social.encryptionPassword

<A password for sosial token encryption.>

com.iknowbase.spring.security.social.encryptionSalt

<Even number of 8 or more hex characters.>

24.10.2. Set up iKnowBase as a service provider

Create or reuse a Java keystore for SAML signing and encryption purposes. This example uses a private key with a self signed certificate with two year validity.

keytool -genkey -alias myprivatekeyalias1 -keyalg RSA -keystore <path_to_keystore>/keystore.jks -validity 720 -keysize 2048
<specify a keystore and a key passoword (may be the same)>

Configure iKnowBase with SAML and specify this keystore.

Property name Value

com.iknowbase.spring.security.saml.enabled

true

com.iknowbase.spring.security.saml.keyManager.defaultKeyAlias

myprivatekeyalias1 (must be lower case)

com.iknowbase.spring.security.saml.keyManager.privateKey.1.alias

myprivatekeyalias1 (keyIndex = 1) (must be lower case)

com.iknowbase.spring.security.saml.keyManager.privateKey.1.password

<password for myprivatekeyalias1> (keyIndex = 1)

com.iknowbase.spring.security.saml.keyManager.storeFile

<path to keystore/keystore.jks>

com.iknowbase.spring.security.saml.keyManager.storePassword

<password for keystore.jks>

Start iKnowBase and create service provider metadata using the SAML metadata generator at /ikb$auth/saml/generate (requires admin privileges). The default settings in the generator are normally sufficient, but please check if the identity provider administrator has any special requirements.

The generator displays an XML file containing the SAML service provider metadata. Store the file a file system reachable by the application server.

The generator also displays the configuration needed. Add to iKnowBase Installation properties (or set in any other of the supported property areas). The metadataProvider index must be chosen - select the first available index >=1 (if this is the first provider added, use index 1).

24.10.3. Register ADFS identity provider with iKnowBase

Download the ADFS metadata from https://YOUR_ADFS_SERVER/FederationMetadata/2007-06/FederationMetadata.xml and store the file in a file system reachable by the application server.

Add the identity provider to the iKnowBase configuration with the next available metadata provider index (if the SP was .1, this should be .2).

Property name Value

com.iknowbase.spring.security.saml.metadataProvider.<index>.idpLoginFormShortName

<Name to display on form login button>

com.iknowbase.spring.security.saml.metadataProvider.<index>.idpProviderEntityId

<Entity ID in ADFS XML metadata, i.e. http://YOUR_ADFS_SERVER/adfs/services/trust

com.iknowbase.spring.security.saml.metadataProvider.<index>.providerEntityType

IdP

com.iknowbase.spring.security.saml.metadataProvider.<index>.resourcePath

<path to ADFS XML metadata>

24.10.4. Register iKnowBase service provider with ADFS

The iKnowBase service provider metadata must be registered in the ADFS identity provider.

  • In ADFS console > Trust Relationships > Relying Party Trusts choose Add Relying Party Trust.

  • You may now specify a local XML file containing the iKnowBase service provider metadata or (if reachable) directly download from https://YOUR_IKNOWBASE_SERVER/ikb$auth/saml/metadata.

  • Choose a display name.

  • Choose permit all users to access this relying party (to allow all authenticated users to access).

  • Finish the wizard.

Select properties for the newly added relying party trust and set the secure hash algorithm in the advanced tab. Match the iKnowBaser service provider metadata (defaults to SHA-1).

24.10.5. Map identity provider user account attributes

Edit claim rules for the newly added relying party trust and add a new issuance transform rule.

  • Claim rule template: Send LDAP Attributes as Claims

  • Claim rule name: NameId

  • Attribute store: Active Directory

  • LDAP Attribute: Choose existing attribute (or type attribute name if the source attribute is not in the list) containing the user’s username that will be asserted as NameID

  • Outgoing Claim Type: Name ID

iKnowBase supports using the iKnowBase Auth Token for linking iKnowBase and external user accounts. See description of the iKnowBase Auth Token "ACTIVATION". The default iKnowBase setting will link using the provided Name ID, but you may also configure it to use a specific claim attribute instead.

iKnowBase also supports automatic account linking IF the identity provider can assert a claim containing the iKnowBase username. The default iKnowBase setting will link using the provided Name ID, but you may also configure it to use a specific claim attribute instead. Automatic linking is enabled using:

Property name Value

com.iknowbase.spring.security.saml.metadataProvider.<index>.idpAccountAutoConnectEnabled

true

24.10.6. Login options and verify setup

Setup is now complete and a login button for the identity provider has been added to the login form provided by iKnowBase on /ikb$auth/form/show.

Saml is by default not the default authentication provider, but you may choose to set it as the default by configuring "Saml" as the default module.

24.11. Switch user database procedures

This is an example implementation of the switch user procedures.

24.11.1. Package spec

create or replace
package custom_switch_user is
    procedure access_check (p_switch_user ot_switch_user, p_return_code out number, p_return_message out varchar2);
    procedure audit_user  (p_switch_user ot_switch_user);
end;
/

24.11.2. Package body

create or replace
package body custom_switch_user is

    procedure access_check (p_switch_user ot_switch_user, p_return_code out number, p_return_message out varchar2) is
    begin
        -- log to IKB_ERROR_TAB
        ikb_common_procs.log_error('CUSTOM_SWITCH_USER.ACCESS_CHECK','authenticated_username: '||p_switch_user.authenticated_username||', '|
            'switch_to_username: '||p_switch_user.switch_to_username);

        -- implement access check logic here

        p_return_code := 0; -- permit access
    end;

    procedure audit_user  (p_switch_user ot_switch_user) is
    begin
        -- log to IKB_ERROR_TAB
        ikb_common_procs.log_error('CUSTOM_SWITCH_USER.AUDIT_USER','authenticated_username: '||p_switch_user.authenticated_username||', '|
            'switch_to_username: '||p_switch_user.switch_to_username||' switch_type = '||p_switch_user.switch_type);

        -- do more logging / registrations here, if you need to
    end;

end;
/

The steps needed to enable social authentication with user activation link and default form authentication are:

  • Register an application at the social provider(s) to get key and secret for using the social provider’s API. iKnowBase only needs the minimal set of permissions for authentication.

  • Configure iKnowBase authentication modules and restart iKnowBase web application:

    Property name Value

    com.iknowbase.spring.security.social.enabled

    true

    com.iknowbase.spring.security.social.encryptionPassword

    <A password for sosial token encryption.>

    com.iknowbase.spring.security.social.encryptionSalt

    <Even number of 8 or more hex characters.>

    com.iknowbase.spring.security.social.<provider>.enabled

    true

    com.iknowbase.spring.security.social.<provider>.clientId

    <API key from the application registration>

    com.iknowbase.spring.security.social.<provider>.clientSecret

    <API secret from the application registration>

    com.iknowbase.spring.security.ikbauthtoken.activation.enabled

    true

  • Test the authentication setup by generating an activation token for an existing user and access the web site on any area with the "ikbAuthToken=<your token>" URL parameter. Choose the social provider and authentication should complete.

When inviting users to activate / connect using a social account, you’ll need to implement

  • Create user (user information, groups, ACLs, ..).

  • Send activation link.

    • Create an email to send.

    • If you allow the user to activate by setting account password, you must add the user’s username to this email.

    • Generate the token and insert into email body (token should NOT be presented to the user sending this email).

    • Send mail to user.

25. Troubleshooting

25.1. I only want to change the configuration for a specific web application

A wildcard instance qualifier for a configuration option will match all applications. As an example, if you only want to match a specific application, set the instance qualifier to match the context path ("/" or "/MyCustomContextRoot"). See Installation Guide > Configuration > The ikb_installation_properties table.

25.2. 'AES-256-bit is not supported', 'java.security.InvalidKeyException: Illegal key size' or 'Unable to initialize due to invalid secret key'

All these messages points to that you will need to update the java installation to handle higher security levels.

You will encounter this requirement if you use any of the following:

  • SPNEGO authentication with AES-256 encryption

  • Social authentication

Download and install "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" from http://www.oracle.com/technetwork/java/javase/downloads/index.html.

25.3. Error creating bean with name 'aesBytesEncryptor'

For all these messages:

  • Hex-encoded string must have an even number of characters.

  • The salt parameter must not be empty.

  • Constructor threw exception; nested exception is java.lang.NullPointerException.

Both encryption password and salt must be configured in the social module.

The configured encryption salt set using configuration property "com.iknowbase.spring.security.social.encryptionSalt" must be set to a non empty even number of hex characters.

25.4. On demand LDAP Sync during login fails

LDAP sync log can be viewed in /ikb$console/development/advanced/ldapsync. Select your sync profile and go to the "show log" tab.

25.5. SAML custom ADFS claim as iKnowBase username is not picked up

When using the idpIkbUsernameAttribute setting with ADFS, make sure that you use the claim type as idpIkbUsernameAttribute and NOT the name.

Example:

25.6. java.lang.IllegalArgumentException: encryptionPassword is required

SAML require the social connection infrastructure. Please review documentation for the ADFS sample and enable social login (no external social providers needed).

25.7. Kerberos: Encryption type DES CBC mode with MD5 is not supported/enabled

Java 8 has by default disabled weak crypto and will by default not support DES-CBC-MD5. A stronger encryption mechanism is strongly recommended. It is still possible to allow the weak crypto mechanisms by editing krb5.conf and setting allow_weak_crypto to true.

See The Kerberos 5 GSS-API Mechanism for more information.

25.8. WebLogic: Basic authentication is not validated by iKnowBase Spring Security

WebLogic will by default intercept and validate HTTP Basic credentials even if the resource is not protected by WebLogic (iKnowBase is not). To allow HTTP basic credentials to pass through WebLogic to iKnowBase Spring Security, see WebLogic documentation on Understanding BASIC Authentication with Unsecured Resources.

26. SpringSecurityConfiguration

Application security in iKnowBase relies on the Spring Security Framework and provides multiple modules for authentication and authorization.

See [Application context path]/ikb$console/config/configurations for default and active web application security configuration. All sections start with com.iknowbase.spring.security.

26.1. Debug

Spring Security provides a debug mode documented as:

"Enables Spring Security debugging infrastructure. This will provide human-readable (multi-line) debugging information to monitor requests coming into the security filters. This may include sensitive information, such as request parameters or headers, and should only be used in a development environment."

Property name Description

com.iknowbase.spring.security.debug

Enable or disable Spring Security debug mode

For debugging, you may also want to enable trace logging adjust the logger levels to trace for org.springframework.security and com.iknowbase.spring.security.

Note that this particular debug flag is not visible under /ikb$console/config/configurations.

26.2. Default authentication module

iKnowBase supports having multiple active authentication modules at the same time and these can be explicitly triggered, however, one must be set as the default.

Property name Description

com.iknowbase.spring.security.init.defaultAuthenticationModule

Name of the authentication module to use as the default

26.3. Authentication modules

Module specific configuration is provided in the following sections.

26.3.1. Basic module configuration

No configuration options available.

26.3.2. Container module configuration

Property name Description

com.iknowbase.spring.security.container.enabled

Enable or disable module. Should not be necessary to change this setting.

26.3.3. Form module configuration

Property name Description

com.iknowbase.spring.security.form.loginPageCSS

Path to css (absolute or relative) used by the form based login page.

com.iknowbase.spring.security.form.loginPageURL

Login URL (absolute or relative).

com.iknowbase.spring.security.form.loginErrorURL

Error URL (absolute or relative) if authentication does not succeed.

com.iknowbase.spring.security.form.rememberMeEnabled

Enable (true) or disable (false) RememberMe functionality.

com.iknowbase.spring.security.form.rememberMeTokenValiditySeconds

RememberMe token cookie validity in seconds.

com.iknowbase.spring.security.form.rememberMeTokenCleanupThresholdSeconds

RememberMe token cookie cleanup threshold in seconds. Must be higher than the highest token validity for this iKnowBase database repository.

com.iknowbase.spring.security.form.rememberMeCookieName

Set the cookie name used for RememberMe tokens.

com.iknowbase.spring.security.form.rememberMeCookiePath

Set the cookie path used for RememberMe tokens. Defaults to / (all apps on host).

com.iknowbase.spring.security.form.rememberMeCookieDomain

Set the cookie domain used for RememberMe tokens. Defaults is to send the cookie to the full host name that issued it.

com.iknowbase.spring.security.form.rememberMeParameterName

The HTTP parameter used to indicate to remember the user at time of login. Defaults to _spring_security_remember_me.

com.iknowbase.spring.security.form.rememberMeProviderKey

Key to identify tokens created for remember me authentication. Default is a secure randomly generated key and is normally OK.

com.iknowbase.spring.security.form.exceptionMapping.<index>

Authentication exception to url mapping. Exception full class name:url to redirect to.

com.iknowbase.spring.security.form.webdavFormLoginEnabled

Enable (true) or disable (false) form based login for WebDAV. Defaults to false.

com.iknowbase.spring.security.form.webdavFormLoginPageURL

Login URL (absolute or relative) for the form based login page. Defaults to standard form login page with RememberMe disabled.

com.iknowbase.spring.security.form.webdavFormLoginTriggerURL

Login URL (absolute or relative) with redirect to success URL for WebDAV.

com.iknowbase.spring.security.form.webdavFormLoginSuccessURL

Success URL (absolute or relative). MUST match the URL the user is redirected to if authentication succeeds.

com.iknowbase.spring.security.form.webdavFormLoginDialogSize

Dialog size for the form authentication dialog. Defaults to "800x600", i.e. width=800px,height=600px.

com.iknowbase.spring.security.form.webdavFormLoginUserAgentExpr

Regular expression for matching browser’s User-Agent for WebDAV form based authentication. Defaults to all Microsoft Office clients.

26.3.4. Header module configuration

Property name Description

com.iknowbase.spring.security.header.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.header.serverNameExpr

Regular expression restriction matching against the host name of the server to which the request was sent.

com.iknowbase.spring.security.header.remoteAddrExpr

Regular expression restriction matching against the end client’s IP address.

com.iknowbase.spring.security.header.realRemoteAddrExpr

Regular expression restriction matching against the immediate client’s IP address (typically a reverse proxy). ONLY available for iKnowBase web server.

com.iknowbase.spring.security.header.headerNameUser

Name of HTTP request header containing the authenticated username.

com.iknowbase.spring.security.header.headerNameUserExtractExpr

If necessary, specify a regular expression for extracting the username from the specified request header’s value.

com.iknowbase.spring.security.header.headerNameSecret

Name of HTTP request header containing the authentication shared secret.

com.iknowbase.spring.security.header.headerValueSecret

Value of the shared authentication secret (if any).

com.iknowbase.spring.security.header.requestHeaderName

Restriction defining required HTTP request header name (if any), see requestHeaderExpr for validation expr of value.

com.iknowbase.spring.security.header.requestHeaderExpr

Regular expression restriction matching against the HTTP request header specified in requestHeaderName.

com.iknowbase.spring.security.header.usernameExpr

Regular expression restriction matching against the username.

com.iknowbase.spring.security.header.authSchemeName

The scheme name in use when the server sends an authentication challenge.

com.iknowbase.spring.security.header.sendAdditionalHttpBasicChallenge

Also send a HTTP Basic authentication challenge.

com.iknowbase.spring.security.header.unauthorizedStatusCode

HTTP response status code for authentication challenge.

com.iknowbase.spring.security.header.unauthorizedResponseHeaders

Pipe delimited set of response headers.

26.3.5. Spnego module configuration

Property name Description

com.iknowbase.spring.security.spnego.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.spnego.serverNameExpr

Regular expression restriction matching against the host name of the server to which the request was sent.

com.iknowbase.spring.security.spnego.remoteAddrExpr

Regular expression restriction matching against the end client’s IP address.

com.iknowbase.spring.security.spnego.realRemoteAddrExpr

Regular expression restriction matching against the immediate client’s IP address (typically a reverse proxy). ONLY available for iKnowBase web server.

com.iknowbase.spring.security.spnego.requestHeaderName

Restriction defining required HTTP request header name (if any), see requestHeaderExpr for validation expr of value.

com.iknowbase.spring.security.spnego.requestHeaderExpr

Regular expression restriction matching against the HTTP request header specified in requestHeaderName.

com.iknowbase.spring.security.spnego.keytab

Path to keytab file.

com.iknowbase.spring.security.spnego.targetName

targetName corresponding to the name registered in keytab (HTTP/[NAME]@[DOMAIN]).

com.iknowbase.spring.security.spnego.sendAdditionalHttpBasicChallenge

Also send a HTTP Basic authentication challenge.

com.iknowbase.spring.security.spnego.fallbackRedirectEnabled

Fallback to form based authentication instead of authentication challenge if spnego cannot be completed.

26.3.6. LDAP UsernamePassword authentication provider

Property name Description

com.iknowbase.spring.security.ldap.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.ldap.serverUrl

URL to ldap server. May use LDAPS. TLS is not supported.

com.iknowbase.spring.security.ldap.clientUserDn

Full DN for client ldap user used for user looku

com.iknowbase.spring.security.ldap.clientUserPassword

Password for client ldap user.

com.iknowbase.spring.security.ldap.userSearchBase.<index>

Search base for users within the base dn given in server url. Index >= 1. Will search subtree from this base.

com.iknowbase.spring.security.ldap.usernameAttribute

Attribute matching the authentication username submitted by the web client.

com.iknowbase.spring.security.ldap.ikbUsernameAttribute

Attribute used as iKnowBase authenticated user.

com.iknowbase.spring.security.ldap.serverNameExpr

Regular expression restriction matching against the host name of the server to which the request was sent.

com.iknowbase.spring.security.ldap.remoteAddrExpr

Regular expression restriction matching against the end client’s IP address.

com.iknowbase.spring.security.ldap.realRemoteAddrExpr

Regular expression restriction matching against the immediate client’s IP address (typically a reverse proxy). ONLY available for iKnowBase web server.

com.iknowbase.spring.security.ldap.requestHeaderName

Restriction defining required HTTP request header name (if any), see requestHeaderExpr for validation expr of value.

com.iknowbase.spring.security.ldap.requestHeaderExpr

Regular expression restriction matching against the HTTP request header specified in requestHeaderName.

com.iknowbase.spring.security.ldap.usernameExpr

Regular expression restriction matching against the username.

com.iknowbase.spring.security.ldap.passwordExpr

Regular expression restriction matching against the password.

The LDAP provider may also be used in conjunction with the LDAP sync service. If the user was not found, the LDAP sync service will make an attempt at synchronizing the user into the iKnowBase User Repository.

Property name Description

com.iknowbase.spring.security.ldap.sync.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.ldap.sync.profileExternalKey

External key to LDAP synchronization profile defined in iKnowBase.

com.iknowbase.spring.security.ldap.sync.executionUserName

Execution user. Should normally not be changed.

26.3.7. iKnowBase UsernamePassword authentication provider

Property name Description

com.iknowbase.spring.security.ikbauth.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.ikbauth.serverNameExpr

Regular expression restriction matching against the host name of the server to which the request was sent.

com.iknowbase.spring.security.ikbauth.remoteAddrExpr

Regular expression restriction matching against the end client’s IP address.

com.iknowbase.spring.security.ikbauth.realRemoteAddrExpr

Regular expression restriction matching against the immediate client’s IP address (typically a reverse proxy). ONLY available for iKnowBase web server.

com.iknowbase.spring.security.ikbauth.requestHeaderName

Restriction defining required HTTP request header name (if any), see requestHeaderExpr for validation expr of value.

com.iknowbase.spring.security.ikbauth.requestHeaderExpr

Regular expression restriction matching against the HTTP request header specified in requestHeaderName.

com.iknowbase.spring.security.ikbauth.usernameExpr

Regular expression restriction matching against the username.

com.iknowbase.spring.security.ikbauth.passwordExpr

Regular expression restriction matching against the password.

26.3.8. SAML authentication provider

Property name Description

com.iknowbase.spring.security.saml.defaultFailureUrl

URL to redirect to in case of authentication failure.

com.iknowbase.spring.security.saml.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.saml.idpSelectionCSS

Path to css (absolute or relative) used by the page presenting available SAML identity providers for login.

com.iknowbase.spring.security.saml.idpSelectionURL

URL presenting available SAML identity providers for login if not using the default or custom login form .

com.iknowbase.spring.security.saml.keyManager.defaultKeyAlias

Default key alias to use for signing and encryption

com.iknowbase.spring.security.saml.keyManager.privateKey.<keyIndex>.alias

Alias for the private key in the key store. Configuration index >= 1.

com.iknowbase.spring.security.saml.keyManager.privateKey.<keyIndex>.password

Password for the private key in the key store. Configuration index >= 1.

com.iknowbase.spring.security.saml.keyManager.storeFile

Path to the Java keystore containg private key(s).

com.iknowbase.spring.security.saml.keyManager.storePassword

Password for accessing the Java keystore.

com.iknowbase.spring.security.saml.loginDefaultTargetUrl

Default URL to redirect to if no saved request was found after successful login. Defaults to /

com.iknowbase.spring.security.saml.logoutDefaultTargetUrl

Default URL to redirect to if no saved request was found after successful logout. Defaults to /

com.iknowbase.spring.security.saml.metadataProvider.<index>.enabled

Enable (true) or disable (false) provider.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.requireArtifactResolveSigned

If true, received artifactResolve messages will require a signature, sent artifactResolve will be signed.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.requireLogoutRequestSigned

If true logoutRequests received will require a signature, sent logoutRequests will be signed.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.requireLogoutResponseSigned

Flag indicating whether entity in question requires logout response to be signed.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.alias

Alias for choosing a specific service provider (if more than one).

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.encryptionKey

Alias to private key used for encryption.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.idpDiscoveryEnabled

Enable (true) or disable (false) identity provider discovery mode.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.idpDiscoveryResponseURL

Identity provider discovery response URL.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.idpDiscoveryURL

Identity provider discovery URL.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.local

If true, entity is treated as locally deployed and will be able to accept messages on endpoints determined by the selected alias.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.securityProfile

metaiop = "Uses cryptographic data from the metadata document of the entity in question. No checks for validity or revocation of certificates is done in this mode. All keys must be known in advance". pkix = Signatures are deemed as trusted when credential can be verified using PKIX with trusted keys of the peer configured as trusted anchors.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.signMetadata

Flag indicating whether local metadata will be digitally signed.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.signingAlgorithm

Algorithm used for creation of digital signatures of this entity. Only used for metadata signatures. Only valid for local entities.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.signingKey

Signing key used for signing messages or verifying signatures of this entity.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.sslHostnameVerification

Hostname verifier to use for verification of SSL connections, e.g. for ArtifactResolution.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.sslSecurityProfile

Security profile used for SSL/TLS connections of the local entity. metaiop or pkix.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.tlsKey

Key used to authenticate instance against remote peers when specified on local entity. When specified on remote entity the key is added as a trust anchor during communication with the entity using SSL/TLS.

com.iknowbase.spring.security.saml.metadataProvider.<index>.extended.trustedKeys

Pipe delimited string of key alias for keys included as trusted anchors during PKIX evaluation. All keys in the keyStore are used as trust anchors with null value. Keys are only used with PKIX security profile.

com.iknowbase.spring.security.saml.metadataProvider.<index>.idpAccountAutoConnectEnabled

Enable (true) or disable false) automatic connect/link between iKnowBase and external user account. The iKnowBase username must be present in the SAML response (claim) using Name ID or a specific attribute.

com.iknowbase.spring.security.saml.metadataProvider.<index>.idpAccountSignupUrl

If no linked account could be found, redirect the user to this URL.

com.iknowbase.spring.security.saml.metadataProvider.<index>.idpIkbUsernameAttribute

iKnowBase username attribute in SAML response (claim). Defaults to Name ID claim. Custom attributes for ADFS uses the claim type defined in ADFS > Service > Claim Descriptions.

com.iknowbase.spring.security.saml.metadataProvider.<index>.idpLoginFormCssClass

iKnowBase default login form: Specify css class for the login button.

com.iknowbase.spring.security.saml.metadataProvider.<index>.idpLoginFormShortName

iKnowBase default login form: Specify name that will appear on the login button.

com.iknowbase.spring.security.saml.metadataProvider.<index>.idpProviderEntityId

EntityID, as specified in the provider’s metadata XML.

com.iknowbase.spring.security.saml.metadataProvider.<index>.metadataRequireSignature

When set to true metadata from this provider should only be accepted when correctly signed and verified. Metadata with an invalid signature or signed by a not-trusted credential will be ignored.

com.iknowbase.spring.security.saml.metadataProvider.<index>.metadataTrustCheck

If enabled, verifies metadata signature using pkix signature trust engine.

com.iknowbase.spring.security.saml.metadataProvider.<index>.providerEntityType

Type of provider. SP = Service Provider. IdP = Identity Provider

com.iknowbase.spring.security.saml.metadataProvider.<index>.resourcePath

File system path to XML metadata for this provider.

com.iknowbase.spring.security.saml.metadataProvider.hostedSpName

Name of the default service provider for this application. Must match Entity ID of the service provider.

com.iknowbase.spring.security.saml.metadataProvider.spSelectionStrategy

Strategy for selecting Service Provider. SERVER_NAME or ALIAS_PATH. Defaults to SERVER_NAME (HTTP Request ServerName), which must match Entity ID of the service provider.

26.3.9. Social authentication provider

Property name Description

com.iknowbase.spring.security.social.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.social.socialSignupURL

Signup URL (absolute or relative) to redirect the user to if the social authentication attempt did not match an iKnowBase user account.

com.iknowbase.spring.security.social.socialProvidersEnabled

Comma separated list of providers. Used when rendering login and activation page. Defaults to all enabled providers.

com.iknowbase.spring.security.social.encryptionPassword

Password used when encrypting social authentication tokens before they are persisted to database. Required if you enable social authentication.

com.iknowbase.spring.security.social.encryptionSalt

Salt, which must be an even number of 8 or more hex characters. Used when encrypting social authentication tokens before they are persisted to database. Required if you enable social authentication.

Google specific configuration:

Property name Description

com.iknowbase.spring.security.social.google.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.social.google.clientId

Client ID registered with the social provider.

com.iknowbase.spring.security.social.google.clientSecret

Client Secret registered with the social provider

com.iknowbase.spring.security.social.google.scope

OAuth scope for requesting permissions with the social provider. Default will enable authentication.

Twitter specific configuration:

Property name Description

com.iknowbase.spring.security.social.twitter.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.social.twitter.clientId

API Key registered with the social provider.

com.iknowbase.spring.security.social.twitter.clientSecret

API Secret registered with the social provider

com.iknowbase.spring.security.social.twitter.scope

OAuth scope for requesting permissions with the social provider. Default will enable authentication.

Facebook specific configuration:

Property name Description

com.iknowbase.spring.security.social.facebook.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.social.facebook.clientId

App ID registered with the social provider.

com.iknowbase.spring.security.social.facebook.clientSecret

App Secret registered with the social provider

com.iknowbase.spring.security.social.facebook.scope

OAuth scope for requesting permissions with the social provider. Default will enable authentication.

LinkedIn specific configuration:

Property name Description

com.iknowbase.spring.security.social.linkedin.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.social.linkedin.clientId

API Key registered with the social provider.

com.iknowbase.spring.security.social.linkedin.clientSecret

Secret Key registered with the social provider

com.iknowbase.spring.security.social.linkedin.scope

OAuth scope for requesting permissions with the social provider. Default will enable authentication.

Microsoft Live / Microsoft account specific configuration:

Property name Description

com.iknowbase.spring.security.social.live.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.social.live.clientId

API Key registered with the social provider.

com.iknowbase.spring.security.social.live.clientSecret

Secret Key registered with the social provider

com.iknowbase.spring.security.social.live.scope

OAuth scope for requesting permissions with the social provider. Default will enable authentication.

26.4. Secure Token authentication

Note
The iKnowBase Secure Token Engine configuration is described in The SecureToken engine.
Property name Description

com.iknowbase.spring.security.securetoken.maxAgeSeconds

Max age allowed when validating the iKnowBase secure token.

com.iknowbase.spring.security.securetoken.serverNameExpr

Regular expression restriction matching against the host name of the server to which the request was sent.

com.iknowbase.spring.security.securetoken.remoteAddrExpr

Regular expression restriction matching against the end client’s IP address.

com.iknowbase.spring.security.securetoken.realRemoteAddrExpr

Regular expression restriction matching against the immediate client’s IP address (typically a reverse proxy). ONLY available for iKnowBase web server.

com.iknowbase.spring.security.securetoken.requestHeaderName

Restriction defining required HTTP request header name (if any), see requestHeaderExpr for validation expr of value.

com.iknowbase.spring.security.securetoken.requestHeaderExpr

Regular expression restriction matching against the HTTP request header specified in requestHeaderName.

com.iknowbase.spring.security.securetoken.usernameExpr

Regular expression restriction matching against the username.

26.5. Anonymous / Public authentication provider

Property name Description

com.iknowbase.spring.security.authentication.ikbpublic.anonymousKey

Shared key used by the anonymous authentication provider. Should normally not be set.

26.6. iKnowBase User Details

All authentication attempts must ultimately load a user from the iKnowBase User Repository before the authentication is fully accepted.

Property name Description

com.iknowbase.spring.security.userdetails.executionUserName

Execution user. Should normally not be changed.

26.7. Switch User

Property name Value

com.iknowbase.spring.security.switchuser.enabled

Enable (true) or disable (false) module.

com.iknowbase.spring.security.switchuser.accessCheckProcedureName

Name of check access database procedure.

com.iknowbase.spring.security.switchuser.auditProcedureName

Name of audit database procedure (optional).

26.8. User Account Activation

Property name Value

com.iknowbase.spring.security.activation.showActivationOptionsCSS

Path to css (absolute or relative) used by the activation page.

com.iknowbase.spring.security.activation.showActivationOptionsURL

Activation options URL (absolute or relative) to redirect the user to if a valid activation token is presented.

com.iknowbase.spring.security.activation.activationFailedURL

Failure URL (absolute or relative) to redirect the user to if the user presented an invalid activation token.

com.iknowbase.spring.security.activation.ikbProviderSetPasswordEnabled

Enable users with activation token to set the user’s password in the iKnowBase User Repository.

com.iknowbase.spring.security.activation.ikbProviderSetPasswordAlgorithm

Override default password encryption algorithm when setting password.

26.9. IKB Auth Token

Property name Value

com.iknowbase.spring.security.ikbauthtoken.activation.enabled

Enable (true) or disable (false) processing of token type ACTIVATION.

com.iknowbase.spring.security.ikbauthtoken.login.enabled

Enable (true) or disable (false) processing of token type LOGIN.

External applications

27. Apache Solr Search Server

iKnowBase comes with ready-to-use components for integration with the Apache Solr open source enterprise search platform (http://lucene.apache.org/solr/).

27.1. Installation

To install, do the following:

You should now have a top level structure like.

solr-<version>
solr-<version>/server
  • Unzip the file iknowbase-<version>-solr-distribution.zip to solr-<version>/server. This will create four folders:

lib\ext         - jdbc related files
iknowbase       - core definition files
iknowbase\lib   - iKnowBase security plugin
iknowbase\conf  - Core configuration
  • Security-plugin

iKnowBase ships with a Solr-plugin that verifies document access for all documents returned from the Solr search engine. The principles behind this plugin is that iKnowBase will add security information to the search query sent to Solr, which will then be intercepted by the Solr engine during search. For this to work, two items must be in place. First, the plugin must be able to connect to the iKnowBase database, and second, the iKnowBase viewer application and the Solr plugin must share a common secret used to encrypt the security information.

The common secret is handled by a secure token engine, which is itself configured in two steps. First, the secure key is stored in the ikb_installation_properties table in the database, using a property name of com.iknowbase.secureTokenEngine.secureKey and an instance_qualifier that can be used by the iKnowBase web application (a single star, "*", will always work); then the Solr plugin must be informed about this qualifier, so that it can load the same value.

Configure the security component by filling in proper values for the following properties in iknowbase\conf\configoverlay.json:

Property name Description

jdbcUrl

This points to the database where iKnowBase is installed, eg. jdbc:oracle:thin:@//hostname.example.com:portnumber/service_name.

dbUsername

The database-user where iKnowBase is installed.

dbPassword

The password to the iKnowBase database user.

instanceQualifier

The instance_qualifier used to look up the proper secure token engine configuration from installation_properties in the iKnowBase database.

Set the correct values for :

"jdbcUrl":"jdbc:oracle:thin:@//hostname:port/service name",
"dbUsername":"<username>",
"dbPassword":"<password>",
"instanceQualifier":"*"
  • Start the new solr instance

cd solr-<version>
bin/solr start
or
bin/solr start -p <port number>
  • Create a new core based on a basic config set defined under solr-<version>/server/iknowbase/conf.

cd solr-<version>
bin/solr create_core -c iknowbase -d server/iknowbase/conf/
  • Change solr-version to the correct value:

<luceneMatchVersion>*solr-version*</luceneMatchVersion>

If you are unsure of the valid value, verify the value given in solr-<version>/server/solr/configsets/basic_configs/conf/solrconfig.xml

  • Verifiy the installation

Verify it starts without any errors and access <hostname>:<solr port number> from a browser. Make sure the core is available.

27.2. Upgrade an existing SOLR instance

To upgrade an existing installation, please follow the steps as descriped below:

  • Do the two first steps described under the Installation chapter above.

  • Copy the core from the former solr release.

$ cd solr-<version>/server/solr
$ cp -r <former solr release>/solr/<core>/ .
  • Change solr-version to the correct value:

<luceneMatchVersion>*solr-version*</luceneMatchVersion>

If you are unsure of the valid value, verify the value given in solr-<version>/server/solr/configsets/basic_configs/conf/solrconfig.xml

  • Update the data index to the new version

$ export dir=/fullpath/solr-<version>/server/solr-webapp/webapp/WEB-INF/lib

Verify the version of the index:

$ java -cp $dir/lucene-core-<version>.jar:$dir/lucene-backward-codecs-<version>.jar org.apache.lucene.index.CheckIndex -fast /fullpath/solr-<version>/server/solr/<core>/data/index/

Update the index to the latest version:

$ java -cp $dir/lucene-core-<version>.jar:$dir/lucene-backward-codecs-<version>.jar org.apache.lucene.index.IndexUpgrader -delete-prior-commits /fullpath/solr-<version>/server/solr/<core>/data/index/
  • Stop the former solr release.

  • Start the new solr version and make a verification.

cd solr-<version>
bin/solr start
  • If the file <core>/conf/configoverlay.json doesn’t exist, it must be created. From solr version 6.x this is the preferred way of storing user variables.

Prior 6.x, solrcore.properties was used for this, but it will be deprecated in the future. Recreate all variables defined in the old solrcore.properties, as a mininum the following user variables must be created:

$ curl http://server:port/solr/<core>/config -H'Content-type:application/json' -d '{"set-user-property" : {"jdbcUrl":"jdbc:oracle:thin:@//<server>:<port>/<service name>"}}'
$ curl http://server:port/solr/<core>/config -H'Content-type:application/json' -d '{"set-user-property" : {"dbUsername":"<iknowbase schema>"}}'
$ curl http://server:port/solr/<core>/config -H'Content-type:application/json' -d '{"set-user-property" : {"dbPassword":"<db password>"}}'

Verify it starts without any errors and access <hostname>:<port number> from a browser. Make sure the core is available.

27.3. Starting and stopping

Create a start/stop script for linux. It can be placed under /etc/init.d. To add Solr as a linux service, use the systemctl tool, or chkconfig if you use an older linux version.

Start Solr and use a web browser to see the Admin Console: http://hostname.example.com:8983/solr/admin. If Solr is not running, your browser will complain that it cannot connect to the server.

27.4. Configuration

Before use, the Solr-installation must be configured. Similarly, the iKnowBase applications that will index and search must be configured.

27.4.1. SolrCloud

Apache Solr includes the ability to set up a cluster of Solr servers that combines fault tolerance and high availability. Called SolrCloud, these capabilities provide distributed indexing and search capabilities, supporting the following features:

  • Central configuration for the entire cluster.

  • Automatic load balancing and fail-over for queries.

  • ZooKeeper integration for cluster coordination and configuration.

SolrCloud is the preferred method when it comes to load balancing, fail-over and replication.

We refer to documentation from Apache Solr e.g. https://cwiki.apache.org/confluence/display/solr/SolrCloud for more information on this.

27.4.2. Configure the iKnowBase applications

3rd party application severs

28. iKnowBase web server

Note
This chapter assumes the iKnowBase database repository has been created, as outlined in the Quick installation and upgrade overview section.

iKnowBase comes with an embedded web server based on the Eclipse Jetty server. This is a fast and capable server which requires little resources and is very easy to manager. This is the recommended web server for most installations.

28.1. Spring Boot

Both the iKnowBase application and the embedded web server are developed using Spring Boot and configuration handling and options in Spring Boot for Jetty are applicable for iKnowBase.

We’ve also extended Jetty with settings that are not available in Spring boot. These are prefixed com.iknowbase.server.jetty.

28.2. Preparations

Verify \/ review the recommended installation structure outlined in the Quick installation and upgrade overview section.

28.3. Configure the iKnowBase instance

If you’ve not already done so, set up the iKnowBase instance configuration file described in outlined in the Quick installation and upgrade overview section.

For the examples further down we assume you’ve used the default configuration file name application.properties for a configuration named "production".

28.4. Run and test the iKnowBase instance

With this configuration, you should be able to easily run and test the applications:

cd /opt/iknowbase/production
./iknowbase.sh webServer

Start a web-browser, and navigate to http://YOUR_SERVER_NAME:8080/ressurs/iknowbase (to see documentation) or http://YOUR_SERVER_NAME:8080/ikb$console (for the Management Console). The first should open immediately, while the second one will require login, which requires configuration as shown below.

28.5. Configure modules

The iKnowBase application itself is distributed as a Spring Boot executable jar file. Review configuration sections for the available modules and configure them as needed.

28.6. Configure Web Application Security

The recommended sequence for configuration is to first set up iKnowBase using the internal user directory, and verify sure that you have access to the iKnowBase web applications. After that, you can change to any supported authentication setting you want, but with the knowledge that iKnowBase does indeed work properly with a simple login service.

See the Web Application Security section for additional explanations.

28.7. Configure SSL

We strongly recommend using SSL (https) for all production sites.

28.7.1. Terminating SSL in an external proxy

If you terminate SSL in an external proxy, that proxy will typically use HTTP (an unsecured connection) to talk to the application server. Then, the application server will not be aware that the browser sees a secure connection, and will by default generate links to an unsecure site. To avoid this, note the following items:

  • Configure the load balancer to generate a HTTP header called "X-Forwarded-Proto" with the value "https", ref http://en.wikipedia.org/wiki/List_of_HTTP_header_fields.

  • Configure the iKnowBase server to use a scheme-mapping that understands this header, as shown below.

  • Verify this setup by loading /ikb$console/java/request using from a secure connection; the value "Requested URL" should indicate a https-scheme.

If using Apache httpd for ssl-termination, the following configuration in httpd.conf should set the required header:

<Virtualhost ...>
...
RequestHeader set X-Forwarded-Proto "https"
...
</Virtualhost>

To configure the iKnowBase web server, set the property server.use-forward-headers=true in the property file:

...
server.use-forward-headers=true
...

28.7.2. Configuring SSL listener in iKnowBase web server

The iKnowBase web server can be configured to listen for HTTPS traffic with the following options:

...
server.port=8443
server.ssl.key-store=iknowbase.keystore
server.ssl.key-store-password=<KEYSTORE_PASSWORD>
server.ssl.key-password=<KEY_PASSWORD>
...

If you require both HTTP and HTTPS listeners at the same time, do:

...
server.port=8443
server.ssl.key-store=iknowbase.keystore
server.ssl.key-store-password=<KEYSTORE_PASSWORD>
server.ssl.key-password=<KEY_PASSWORD>
com.iknowbase.server.jetty.httpListener.port=8080
...

The iknowbase.keystore is a standard java keystore in JKS format generated by Java keytool.

The following example demonstrates generating the iknowbase.keystore using preexisting private key, a server certificate and a CA chain file.

$ sudo openssl pkcs12 -inkey ./www_example_com.key -in ./www_example_com.crt -certfile ./ca_chain_file.crt -export -out ./www_example_com.pkcs12 -passout pass:<KEYSTORE_PASSWORD>
$ $JAVA_HOME/bin/keytool -keystore ./iknowbase.keystore -storepass <KEYSTORE_PASSWORD> -importkeystore -srckeystore ./www_example_com.pkcs12 -srcstoretype PKCS12 -srcstorepass <KEYSTORE_PASSWORD>

28.7.3. Multiple certificates (SNI)

Support for multiple certificates is as simple as repeating the previous step for the next certificate and importing into the same keystore.

28.8. Advanced topics

28.8.1. Specify temp directory

During normal execution, the iKnowBase web server needs access to a temporary directory. This defaults to value of the system property java.io.tmpdir. If for some reason you need to use a different temporary directory, change this system property.

Note that iKnowBase before version 7.2 unpacked the web application into a work directory and if that temporary directory was deleted it would fail to serve the unpacked content. From iKnowBase 7.2 this is no longer the case and you may use the normal temp directory.

28.8.2. Configure logging

iKnowBase logs only to console by default. If you want to write the logs to file, set logging.path to absolute or relative path to the log directory you want. We also recommend that you enable the iKnowBase specific log configuration using logging.config=classpath:log4j2-default.properties.

# logging.path=
logging.path=./work/logs
# logging.config=
logging.config=classpath:log4j2-default.properties

The iKnowBase Setup program writes logs to ./work/logs by default, however you may override this by setting:

# com.iknowbase.setup.log.logDirectory=./work/logs
com.iknowbase.setup.log.logDirectory=<A LOG DIRECTORY>

Access logging are by default enabled using daily rolling of the access log file. See application.properties.SAMPLE for details.

28.8.3. Setting max form size

Max form size that can be submitted to the iKnowBase web server is by default set to 200 000 bytes and 1000 keys. This is intended to help in denial of service attack scenarios where malicious clients send huge amount of data.

Please note that this limitation does NOT affect file uploads using multipart/form-data. See multipart.* configuration options in the Java Applications section.

If you need to POST forms larger than 200 000 bytes and/or 1000 keys override the max value in the iknowbase property file:

...
# com.iknowbase.server.jetty.maxFormContentSize=200000
# com.iknowbase.server.jetty.maxFormKeys=1000
...

28.8.4. Shutdown capability and faster restarts

If you enable the shutdown capabilities by setting com.iknowbase.server.jetty.shutdown.token to a string token like com.iknowbase.server.jetty.shutdown.token=YouShallNotPass!!!, any additional start of the application will send a shutdown signal to the currently running application.

Compared to the normal restart (stop + start) procedure, this will accomplish a restart with minimal downtime since the new container will be close to ready when the shutdown signal is sent.

You may also invoke the command "stopWebServer" to just stop the existing one without activating a new server.

Note
Shutdown call is only accepted from localhost. This means that the shutdown handler cannot be invoked from a remote location even if the token is known.

28.9. Troubleshooting

28.9.1. Database connections through firewall or on an unreliable network

When accessing a database through a firewall or on an unreliable network, use the Oracle Net connection descriptor syntax with ENABLE=BROKEN instead of the standard JDBC URL syntax as the database connection string.

Default JDBC URL:

jdbc:oracle:thin:@//localhost:1521/ORCL

Using Oracle Net connection descriptor syntax:

jdbc:oracle:thin:@(DESCRIPTION = (ENABLE = BROKEN)(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521)))(CONNECT_DATA =(SERVER = DEDICATED)(SERVICE_NAME = ORCL)(FAILOVER_MODE =(TYPE = SESSION)(METHOD = BASIC))))

28.9.2. Unexpected error occurred: java.lang.IllegalStateException: Form too large

See Setting max form size.

28.9.3. WARN: bad HTTP parsed: 400 HTTP/0.9 not supported for HttpChannelOverHttp

iKnowBase 7.0 upgraded the embedded web server Jetty from 9.2 to 9.3, which uses updated HTTP specifications.

  • Jetty 9.2 followed RFC2616 (Now Obsoleted by: RFC7230, RFC7231, RFC7232, RFC7233, RFC7234, RFC7235 and Updated by: RFC2817, RFC5785, RFC6266, RFC6585).

  • Jetty 9.3 follows the updates to the venerable (from 1999!) RFC2616 spec. Many things that were valid in the past are no longer valid. We also dropped support for HTTP/0.9 in Jetty 9.3.

This update should not affect end user clients, but it might affect systems requesting information from iKnowBase over HTTP. The systems need to adjust to follow updated HTTP specs.

29. Installing on Oracle WebLogic Server

Note
This chapter assumes the iKnowBase database repository has been created, as outlined in the Quick installation and upgrade overview section.

Installation on Oracle WebLogic Server has the following tasks:

  • Install the Oracle-software.

  • Configure WebLogic.

  • Create a data source and deploy to the target.

  • Configure web application security.

  • Deploy the Resource-directory and java web application to the WebLogic Server.

29.1. Installation and configuration of WebLogic

29.1.1. Non-clustered:

Install a domain containing one or more managed servers.

29.1.2. Clustered:

Install a domain containing

  • A cluster.

  • One or more managed servers supporting the cluster.

  • The Instant module does not support clustering. This requires an additional virtual host, separate managed server or a cluster containing only one managed server. Do one of:

    • Route by vhost: a virtual host exclusively for the non clustered modules backed by one managed server (typically YOURHOSTNAME-nocluster.YOURDOMAINNAME or YOURHOSTNAME-instant.YOURDOMAINNAME).

    • Route by server: a managed server not part of the cluster and route traffic to this instance using a reverse proxy.

29.2. Create and deploy data source

From the administrative console (http://localhost:7001/console), create a data source with

  • Name: iknowbaseDS

  • JNDI Name: jdbc/iknowbaseDS

  • Supports Global Transactions: Disable

  • Target: The cluster where the applications will be deployed.

29.3. Configure web application security

The default web application security mode for iKnowBase deployed to WebLogic is container mode, which means we’ll rely on WebLogic for authentication. You may change to the other web application security modes at any time.

See the Web Application Security section for additional explanations.

However, some of WebLogic’s authentication modules like SPNEGO and SAML2 require special deployment descriptor and role protection not included in the standard web archive to function properly. Contact support for assistance if you require use of these WebLogic authentication modules. Note that iKnowBase’s set of authentication modules includes both SPNEGO and SAML2.

If you are using container mode for authentication, start with adding the orcladmin user to the default realm’s user repository (WebLogic internal is default, but may be set to other supported user repositories).

iKnowBase does not require any roles for these users, as authorization will be done based on the mapped user in the iKnowBase User Repository.

29.4. Deploy applications

29.4.1. Non-clustered

Deployment example using the WebLogic console:

  • Select "deployments" in the domain structure.

  • Select "install" in the "Summary of deployments" screen.

  • Select the relevant web archive.

  • Choose to deploy as an application (and not as a library).

  • Target applications:

    • A managed server or vhost.

    • You may enable all modules on a single deployment, but if you use multiple non clustered managed servers, you must ensure that the Instant module is enabled on only a single manager server.

29.4.2. Clustered

Deployment example using the WebLogic console:

  • Select "deployments" in the domain structure.

  • Select "install" in the "Summary of deployments" screen.

  • Select the relevant web archive.

  • Choose to deploy as an application (and not as a library).

  • Target applications:

    • Deploy iknowbase-boot-weblogic to the cluster on / with all required modules except Instant.

    • Deploy iknowbase-boot-weblogic with a different name like "iknowbase-boot-weblogic-nocluster" to the vhost/managed server on / with the Instant module enabled (all the other modules may be disabled).

    • Instant will respond to the /ikbInstant path.

  • If you want, go to the tab "Configuration, General", and set the context root.

  • If you make configuration changes, and need to save a deployment plan, store it in a safe directory.

Clusters and sessions

By default, the iKnowBase application uses database persisted sessions and you may load balanced the clustered servers without session persistence.

If you change to native sessions (WebLogic sessions)

The iKnowBase web application is configured to replicate HTTP sessions when targeted to an application server cluster. This enhances support for failover and reduces impact for the user during a failover scenario.

The session replication mechanism configured is

<session-descriptor>
<persistent-store-type>replicated_if_clustered</persistent-store-type>
</session-descriptor>

The persistent-store-type "replicated_if_clustered" requires a homogeneous deployment to the cluster. You cannot target applications with this setting to selected parts of the cluster.

The persistent-store-type can be changed with deployment plans. See weblogic.xml session descriptor element for available options.

29.5. Configure user realms (authentication)

See the Web Application Security section for additional authentication options provided by iKnowBase.

The next sections discuss WebLogic Container Mode for authentication.

29.5.1. Using Oracle Internet Directory for authentication

WebLogic allows simple configuration of authentication providers. Configure as appropriate by following this procedure:

  • Chose the realm to change.

  • Under "Providers", "Authentication", add the Oracle Internet Directory provider.

  • Set the control flag as required, normally to "sufficient" to allow users to log in if they exist in this provider.

  • Add further configuration values as required by your OID-configuration.

29.5.2. Using the iKnowBase user repository for authentication

If you do not require WebLogic container mode for authentication, we recommend switching to iKnowBase’s own authentication modules, see the Web Application Security section for additional explanations.

If you require WebLogic container mode it is possible to authenticate directly against the iKnowBase User Repository, through WebLogic’s ReadOnlySQLAuthenticator Authentication Provider .

ReadOnlySQLAuthenticator - Overview

When configured, this provider will lookup usernames and passwords from the IKB_USER-table in the iKnowBase database schema, where the passwords are stored in encrypted form (SHA1-hash algorithm). A user will be authenticated if the username matches the one in the database, and the hashed password from the database matches what the user enters.

ReadOnlySQLAuthenticator - Configuration

Edit WebLogic Security Realm and add a new authentication provider of type "ReadOnlySQLAuthenticator".

Common > Control flag should normally be set to "SUFFICENT" to make sure that it is sufficient for the user to be authenticated through this provider only.

Setting Value Comment

Identity Domain

<blank>

Leave blank (unless you know you are using a Multi Tenant setup and need to configure this)

Plaintext Passwords Enabled

  • ❏ (Disabled)

Data Source Name

iknowbaseDS

Name, not JNDI name, of the configured iKnowBase DataSource

Group Membership Searching

limited

Max Group Membership Search Level

0

We only support direct group membership

SQL Get Users Password

SELECT '{' || PASSWORD_ALGORITHM || '}' || UTL_RAW.CAST_TO_VARCHAR2(UTL_ENCODE.BASE64_ENCODE(PASSWORD_DIGEST)) FROM IKB_USER WHERE UPPER(USER_NAME) = UPPER(?) AND PASSWORD_DIGEST IS NOT NULL

We only support direct group membership

SQL User Exists

SELECT UPPER(USER_NAME) FROM IKB_USER WHERE UPPER(USER_NAME) = UPPER(?)

SQL List Users

SELECT UPPER(USER_NAME) FROM IKB_USER WHERE UPPER(USER_NAME) LIKE UPPER(?)

SQL List Groups

SELECT UPPER(EXTERNAL_KEY) FROM IKB_GROUP WHERE UPPER(EXTERNAL_KEY) LIKE UPPER(?)

SQL Group Exists

SELECT UPPER(EXTERNAL_KEY) FROM IKB_GROUP WHERE UPPER(EXTERNAL_KEY) = UPPER(?)

SQL Is Member

SELECT UPPER(G.EXTERNAL_KEY) FROM IKB_USER U JOIN GROUP_MEMBER GM ON U.ID = GM.USER_ID JOIN IKB_GROUP G ON G.OBJECT_GUID = GM.GROUP_GUID WHERE UPPER(G.EXTERNAL_KEY)=UPPER(?) AND UPPER(U.USER_NAME)=UPPER(?)

SQL List Member Groups

SELECT UPPER(G.EXTERNAL_KEY) FROM IKB_USER U JOIN GROUP_MEMBER GM ON U.ID = GM.USER_ID JOIN IKB_GROUP G ON G.OBJECT_GUID = GM.GROUP_GUID WHERE UPPER(U.USER_NAME)=UPPER(?) AND G.EXTERNAL_KEY IS NOT NULL

Descriptions Supported

  • ✓ (Enabled)

SQL Get User Description

SELECT FULL_NAME || ', ' || FIRST_NAME DESCRIPTION FROM IKB_USER WHERE UPPER(USER_NAME) = UPPER(?)

SQL Get Group Description

SELECT NVL(P.DESCRIPTION, P.VALUE) DESCRIPTION FROM IKB_GROUP G JOIN PROMPT P ON G.PROMPT_ID = P.PROMPT_ID WHERE P.LANG_ID='us' AND UPPER(G.EXTERNAL_KEY) = UPPER(?)
Note
Make sure that the data source you referred to above is deployed to all servers in the domain, since all servers will be using this new authenticator.

29.6. Configure SSL

We strongly recommend using SSL (https) for all production sites.

29.6.1. Terminating SSL in the application server

The procedures for terminating SSL directly in the application server can be found in the WebLogic documentation.

29.6.2. Terminating SSL in an external proxy

If you terminate SSL in an external proxy, that proxy will typically use HTTP (an unsecured connection) to talk to the application server. Then, the application server will not be aware that the browser sees a secure connection, and will by default generate links to an unsecure site. To avoid this, note the following items:

  • Configure the load balancer to generate a HTTP header called "WL-Proxy-SSL" with the value "true".

  • Configure the WebLogic application server domain to detect WebLogic Plugin headers. From the WebLogic console, select your domain, and then Configuration → WebApplications. Here, enable the "WebLogic Plugin Enabled" setting.

  • Verify this setup by loading /ikb$console/java/request using from a secure connection; the value "Requested URL" should indicate a https-scheme.

  • For more information, see http://fusionsecurity.blogspot.no/2011/04/ssl-offloading-and-weblogic-server.html.

If using Apache httpd for ssl-termination, the following configuration in httpd.conf should set the required header:

<Virtualhost ...>
...
RequestHeader set WL-Proxy-SSL true
...
</Virtualhost>

In the WebLogic domain configuration (config.xml), you would find the following snippet:

<web-app-container>
  <weblogic-plugin-enabled>true</weblogic-plugin-enabled>
</web-app-container>
Terminating SSL using Apache with WebLogic Plugin

If you use the Oracle WebLogic Plugin for Apache, also set this parameter WLProxySSLPassThrough On to pass on the SSL information to Oracle WebLogic Server.

29.7. Troubleshooting

29.7.1. Database connections through firewall or on an unreliable network

When accessing a database through a firewall or on an unreliable network, use the Oracle Net connection descriptor syntax with ENABLE=BROKEN instead of the standard JDBC URL syntax as the database connection string.

Default JDBC URL:

jdbc:oracle:thin:@//localhost:1521/ORCL

Using Oracle Net connection descriptor syntax:

jdbc:oracle:thin:@(DESCRIPTION = (ENABLE = BROKEN)(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521)))(CONNECT_DATA =(SERVER = DEDICATED)(SERVICE_NAME = ORCL)(FAILOVER_MODE =(TYPE = SESSION)(METHOD = BASIC))))

29.7.2. WARN - BEA-101388 - The ServletContext was passed to the ServletContextListener.contextInitialized method of a ServletContextListener that was neither declared in web.xml or web-fragment.xml, nor annotated with javax.servlet.annotation.WebListener

Related to activation of the iKnowBase Instant module on WebLogic. This warning can be ignored.

iKnowBase tracking reference: IKB-2893