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.

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.

Customers that already have an established and managed infrastructure using a supported third party application server may also choose 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.

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.

To run the iKnowBase web server, use:

Using the IKB_INSTALLATION_PROPERTY 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:

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

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 to application.properties :

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:

This command will perform three actions:

For pluggable databases (PDBs), there is an additional step needed, since DATA_PUMP_DIR is defined at the CDB level and does not work properly 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:

You can import startup data with any mechanism 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:

The first command will upload the file IKB_MASTER_83.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_83.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_83.

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_83.log). You can also use the following command to download the logfile to your local directory:

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

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:

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.

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:

This command will perform two actions:

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:

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.

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

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

Go to /ikb$console/development/advanced/importjobs#/ and upload the EXP-IKB_MASTER_<version>.dmp file from the etc/ folder in the iKnowBase zip file and run the import. It will add or change any new metadata considered default/required, such as attributes, doctypes, valuelists, ACLs etc.

Unless you are creating the dev environment for the first time, you must make sure you’re not loosing any data when overwriting.

Ensure there is no new data or code/changes in dev that only exist there (it will be deleted), and ensure you have a backup of dev.

Then export the dev-specific data:

Export the iKnowBase schema from the prod app server, by (optionally) stopping the service, entering the installation directory and running exportFile to dump the schema, then downloadFile to transfer it from the DB server into the current directory.

The dump will contain everything except some log tables and the environment specific IKB_INSTALLATION_PROPERTIES table.

On the dev app server, change to the installation directory of the dev environment, then:

If the solution has a custom schema in addition to the iKnowBase schema, inspect it to see if it contains data that must be cloned.

If you are replacing an existing schema, you should delete it before importing. Note that you may have to delete any queue tables before deleting the schema:

First, using the SQL client of your choice, import into the dev schema the IKB_INSTALLATION_PROPERTIES table you exported, then run on the dev app server:

Restore network ACL entries if any (e.g. for network access or mail sending), see Network access lists.

Restore grants for the iKnowBase schema and any custom schema. To list grants, run something like this SQL. If you run it in the old dev, or current prod, you can use the SQL grant statements it creates, in the new dev. If there are any custom schema, run as sys or run it for and as each user to get all the grants.

Restore database links.

If Solr is deployed as a search backend, you should reindex all documents to ensure consistency now that the document collection is changed. It can be done by going to /ikb$console/development/advanced/events, and for all the Indexing Solr events, go to the "index queue status" tab and click the buttons there. To be sure, empty the index, then reindex all documents.

After this, recompile any invalid packages in the schema(s) if needed, now that grants are ok. Then start the iKnowBase dev service.

Enter the iKnowBase console and:

Finally: Test all the things.

iKnowBase uses a database package header, IKB_GLOBAL_PREFS, to determine methods and options on certain functionality.

Changing settings is a two-step process:

Note that you can also add your own variables to this configuration, for example to identify a test or production environment. Any variable set with the ikb_global_prefs will be reflected in the database package, and can be used in your own code for whatever purpose you deem necessary.

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

To switch back to the standard edition version do:

When running iKnowBase in an Oracle Cloud autonomous database, make note of the following configuration properties.

Connections are managed with certificates in a wallet, and the datasource url looks a bit different from what it typically is. This is nothing special for iKnowBase, so regular JDBC documentation is applicable.

Oracle Cloud autonomous databases does not provide a sysdba user, instead configure the "admin" user like this:

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 compatibility reasons, but the overall goal is to convert all search functionality to SOLR. Meanwhile, you can create a lightweight 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:

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

Some integration features, such as LDAP sync and sending email, open network connections from the database to other hosts. In a default Oracle database configuration this is not allowed, leading to the error message: ORA-24247: network access denied by access control list (ACL).

To fix, create a network access list that allows the iKnowBase database schema access (use iKnowBase schema for principal_name, and required hostname for host).

To list network access lists for a schema, run:

To grant network access, run:

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

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 "../".

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:

The iKnowBase application itself supports clustered deployment, but the "Instant" module does not. If you intend to use this module 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.

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

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

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.

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 disadvantages are:

See the sub sections below for configuration details.

The connected web-clients will be "always connected" using asynchronous 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.

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:

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

You may encounter a session cookie collision if you

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.

Usage of the FileConverter works like this:

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

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:

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

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

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.

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

Available authentication providers for UsernamePassword:

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

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:

Basic steps to enable authentication with an identity provider:

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

iKnowBase relies upon Spring Security OAuth2.

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

The OAuth2 identity providers require that you specify the authorized Redirect URL(s). Use <absolute url to site>/ikb$auth/oauth2/code/<providerid>. Example: https://www.example.com/ikb$auth/oauth2/code/google.

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 to provide the username 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.

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:

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

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

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 path’s (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:

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

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

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

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:

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

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:

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

On the acti ve 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 precise 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.

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)

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

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

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

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:

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.

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:

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

Note that if an LDAP user does not have the ikbUsernameAttribute attribute set, iKnowBase will use the usernameAttribute attribute as username.

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:

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)

This a more complex configuration, with three userbases

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

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:

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

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

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

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

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.

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.

Configure iKnowBase with SAML and specify this keystore.

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

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

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

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

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

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:

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.

No configuration options available.

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.

See also: Spring Security SAML documentation.

See Spring Security OAuth2 sign in configuration for Spring Boot.

Note that an alternative to auto connect is using signupURL and handle the account connection in code. signupURL is configured as part of the form configuration.

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:

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.

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:

If using Apache httpd for ssl-termination, the following configuration in httpd.conf should set the required header:

To configure the iKnowBase web server, set the property server.forward-headers-strategy (called server.use-forward-headers=true in iKB 8.0 and older) in the property file:

The iKnowBase web server can be configured to listen for HTTPS traffic with the following options:

If you require both HTTP and HTTPS listeners at the same time, do:

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.

Support for multiple certificates is as simple as repeating the previous step for the next certificate and importing into the same keystore.

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.

iKnowBase logs only to console by default. If you want to write the logs to file, set logging.file.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.

The iKnowBase Setup program writes logs to ./work/logs by default, however you may override this by setting:

Access logging are by default enabled using daily rolling of the access log file. See application.properties.SAMPLE for details.

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:

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.

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:

Using Oracle Net connection descriptor syntax:

See Setting max form size.

iKnowBase 7.0 upgraded the embedded web server Jetty from 9.2 to 9.3, which uses updated HTTP specifications.

See Header parse error after upgrade to Jetty 9.3 for details:

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.