iKnowBase Quickstart embedded web server

The iKnowBase distribution contains an embedded web server usable for small to medium installations, with very small footprint and very easy installation.

Preparations

We recommend an installation structure like the one below:

Begin by creating the directories and unzipping the software:

$ mkdir /opt/iknowbase
$
$ mkdir /opt/iknowbase/distributions
$
$ mkdir /opt/iknowbase/development
$ mkdir /opt/iknowbase/development/.runtime
$ mkdir /opt/iknowbase/development/custom-resource
$
$ mkdir /opt/iknowbase/production
$ mkdir /opt/iknowbase/production/.runtime
$ mkdir /opt/iknowbase/production/custom-resource
$
$ cd /opt/iknowbase/distributions
$ # Copy iknowbase-6.4.zip to this directory (/opt/iknowbase/distributions)
$ cd /opt/iknowbase
$ unzip /opt/iknowbase/distributions/iknowbase-6.4.zip
$ # Note: the .zip-file contains top level directory "iknowbase-6.4"

Configure the quickstart instance

For each instance directory, set up a property file that configures the installation. You may copy one of the samples from the software installation, or you may make one from scratch, but the end result should look something like shown below. Use any filename you like; for the examples further down we assume production.properties.

# Database connection information
db.URL = jdbc:oracle:thin:@//localhost:1521/xe
db.ikbUser = iknowbase_prod
db.ikbPassword = SECRETPASSWORD
db.sysUser = sys
db.sysPassword = SECRETPASSWORD

# Specify temporary runtime directory (defaults to OS tmp directory) for Quickstart deployments
System.java.io.tmpdir=/opt/iknowbase/production/.runtime

# Web server configuration
web.port=8080

Run and test the quickstart instance

With this configuration, you should be able to easily run and test the applications:

$ cd /opt/iknowbase/production
$ bash /opt/iknowbase/iknowbase-6.4/quickstart.sh production.properties webServer
...

Start a web-browser, and navigate to http://server.example.com:8080/ressurs/iknowbase (to see documentation), http://server.example.com:8080/index.html (for the viewer application), or http://server.example.com:8080/ikbStudio (for the Development Studio). The first two should open immediately, while the second one will require login, which requires configuration as shown below.

Deploy the applications

Using the Quickstart embedded web server, application deployments is specified in the same property file as all other configuration.

Default deployment

The Quickstart program contains a default configuration that automatically deploys the most relevant applications: /ressurs, /ikbStudio and /ikbViewer. If this is what you want, you don’t have to make any changes or configure any deployments.

Specify applications to deploy

If you want to customize the deployment, start by specifying which applications to deploy. The names are only used internally to the property file, but pick names that are easy to understand:

# Web server configuration
web.apps=webRessurs,webIkbViewer,webIkbStudio

Next, add two entries for each application. First add an entry for the application path, which is where the application will be mounted. Next add an entry for the application WAR-file, which is where the application itself is located. These entries will be the name of the application, followed by “.path” and “.war” respectively:

# Web server configuration
web.apps=webRessurs,webIkbViewer,webIkbStudio

# Web application definitions
webRessurs.path=/ressurs
webRessurs.war=iknowbase-resources-VERSION.war
webIkbViewer.path=/
webIkbViewer.war=iknowbase-viewer-webapp-VERSION.war
webIkbStudio.path=/ikbStudio
webIkbStudio.war=iknowbase-studio-webapp-VERSION.war

Add custom applications

Often, you will want to add custom deployment, such as a your own resources (images, scripts, etc). This is done the exact same way, but note that the file-property is here used to point to a directory:

# Web server configuration
web.apps=webRessurs,webCustomResource,webIkbStudio,webIkbViewer

# Web application definitions
webRessurs.path=/ressurs
webRessurs.war=iknowbase-resources-VERSION.war
webIkbViewer.path=/
webIkbViewer.war=iknowbase-viewer-webapp-VERSION.war
webIkbStudio.path=/ikbStudio
webIkbStudio.war=iknowbase-studio-webapp-VERSION.war
webCustomResource.path=/custom-resource
webCustomResource.war=/opt/iknowbase/production/custom-resource

Customizing the url mount point

As you can see in the examples, you can change the url mount point at will. Note that the Quickstart web server will visit the mount points in the order they appear in the web.apps property, and that having the wrong order is important. Look at the partial example below:

web.apps=root,ressurs
root.path=/
ressurs.path=/ressurs

If a client asks for “/ressurs”, this will be captured by the application “root”, and served from there. Therefore, remember to set the longest paths to the beginning of the “web.apps” definition.

Defining virtual hosts

It will sometimes be required to have multiple applications deployed towards different hosts, for example to mount webdav at root of “webdav” and “webdav.example.com” and ikbViewer at the root of all other servers. This can be handled by defined virtual hosts for the required applications:

web.apps=webIkbViewer,webIkbWebdav
webIkbViewer.path=/
webIkbViewer.war=iknowbase-viewer-webapp-VERSION.war
webIkbWebdav.path=/
webIkbWebdav.war=iknowbase-webdav-webapp-VERSION.war
webikbWebdav.vhosts=webdav.example.org, webdav

In the example below, when a client asks for “http://webdav/” or “http://webdav.example.org”, the request will be served by the iknowbase-webdav application. Root requests to all other hosts (such as http://intranet.example.org or http://testserver.example.org) are handled by the iknowbase-viewer application, which has no particular host name affinity.

Configure user repository (authentication)

The quickstart web server supports three login configurations:

• iKnowBase (iknowbase)
• ActiveDirectory LDAP (ad.ldap)
• ActiveDirectory SPNEGO+LDAP (ad.spnegoAndLdap)

You may combine one of the ActiveDirectory modules with the iKnowBase module.

The recommended sequence for configuration is to first set up iKnowBase as an internal user directory, and verify sure that you have access to the iKnowBase web applications. After that, you can enable Active Directory, but with the knowledge that iKnowBase does indeed work properly with a simple login service.

iKnowBase internal user repository

The default configuration will authenticate using the internal iKnowBase user repository. The only configuration required is to set up passwords on the required users. 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
$ bash /opt/iknowbase/iknowbase-<VERSION>/quickstart.sh production.properties setIkbPassword orcladmin SECRETPASSWORD

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

Configuring authentication with Active Directory

It is possible to configure the quickstart web server to authenticate directly to Active Directory using LDAP only (disable SPNEGO).

There are several steps to this process:

• Create a user in Active Directory, which will be used by the web server when handling the authentication
• Configure the webserver with information on the Active Directory connection

# Use Active Directory with LDAP authentication only (no SPNEGO)
loginService = ad.ldap
# See below for common ad.ldap options

Configuring single sign-on using the SPNEGO protocol with Active Directory

It is possible to configure the quickstart web server 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:

• Create a user in Active Directory, which will be used by the web server when handling the authentication
• Generate a keytab file on the Active Directory server; this will be used by the webserver instead of a password
• Configure the webserver with information on the Active Directory connection

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 quickstart 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 quickstart 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"

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 iKnowBase QuickStarts 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)

Configure the quickstart web server

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.

On the web server, configure the quickstart property file:

• First, specify that you want SPNEGO with Active Directory (or combine with iKnowBase internal)
• Next, specify the LDAP connection properties; this is used to lookup security roles during login.
• 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, the property “username” is the name of an iKnowBase user on whose behalf the synchronization will happen:

# Use spnegoAndLdap for single sign on with Active Directory with fallback to ldap authentication
loginService = ad.spnegoAndLdap

# Connection information for SPNEGO connection to the Active Directory server
ad.spnego.keytab = iknowbase.webserver-01.example.com.krb5.keytab
ad.spnego.targetName = HTTP/webserver-01.example.com@AD.IKNOWBASE.COM
# ad.spnego.debug = true

# LDAP connection to Active Directory, for group membership lookups
ad.ldap.url = ldap://ad-server.example.com:389
ad.ldap.bindDn = CN=iknowbase.webserver-01.example.com,CN=Users,DC=ad,DC=example,DC=com
ad.ldap.bindPassword = SecretPassword!GlobalMilk
ad.ldap.userbase = CN=Users,DC=ad,DC=example,DC=com

# iKnowBase LDAP synch information, for on-demand user sync
ad.ldap.sync.profile = ADSYNC_PROFILE_EXTERNALKEY
ad.ldap.sync.username = orcladmin

Next, verify the configuration using the quickstart “verifySpnego” command:

[iknowbase@webserver-01 production]$ bash /opt/iknowbase/iKnowBase-5.9.3 production.properties verifySpnego
Enabling spnego and security debugging
---------------------------------------------------------------------------
SUCCESS: The system need to support 256-bit AES, and max bit length is 2147483647
SUCCESS: loginService is set to spnego-ad
SUCCESS: targetName is set; the current value is HTTP/webserver-01.example.com@AD.EXAMPLE.COM
SUCCESS: keytab is set; the current value is iknowbase.webserver-01.example.com.krb5.keytab
SUCCESS: All the relevant ldap settings have been set
SUCCESS: Verified connection to LDAP server
NOTE   : Could not create new GSSContext for targetName=HTTP/webserver-01.example.com@AD.EXAMPLE.COM; this may only be possible during runtime. Exception=GSSException: No valid credentials provided (Mechanism level: Failed to find any Kerberos Key)
---------------------------------------------------------------------------

If the verification prints a note that 256-bit AES is not supported AND your keytab requires AES-256, you will need to update the java installation to handle higher security levels. Download and install “Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files” from http://www.oracle.com/technetwork/java/javase/downloads/index.html.

Configure Active Directory for end users

In order for users to be able to log in to iKnowBase, the need to have a certain number of “roles”. These are implemented as Active Directory group memberships, and you should configure the following groups:

• First, make a group “IKB_USERS”. Any user that needs to log in to iKnowBase should be a member of this group.
• Next, make a group “IKB_DEVELOPERS”. Any user that needs to access the iKnowBase development tools should be a member of this group.
• Finally, make a group “IKB_SYSADMINS”. Any user that needs to access the iKnowBase administration tools should be a member of this group.

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:

• Create an AD-user called “orcladmin”, and make him a member of the groups IKB_USERS, IKB_DEVELOPERS, IKB_SYSADMINS.

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.

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 quickstart property file with a username mapping as shown below

# Expose the username found in the "ipPhone" attribute
ad.ldap.usernameAttribute = ipPhone

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

Configuring multiple and separate user- and group roots

The most frequently used setup is to have all users and groups 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 quickstart application allows multiple and separate user- and group bases. The application uses the following logic when looking for these values:

• Always look for “ad.ldap.userbase” and "spnego-ad.ldap.groupbase"
• Always look for “ad.ldap.userbase.1” and "ad.ldap.groupbase.1"
• Keep looking for incremented numbers as long as they exist (e.g “.1”, “.2”, “.3”, etc, but if “.3” is missing, don’t look further)
• At the end, if no groupbase is specified, use all values specified for userbase also for groupbase

# This is the simplest possible configuration, with a single userbase which is also used as the groupbase
ad.ldap.userbase = CN=Users,DC=ad,DC=example,DC=com

# This is the most complex possible configuration, with three userbases and two groupbases
ad.ldap.userbase = CN=Employees,DC=ad,DC=example,DC=com
ad.ldap.userbase.1 = CN=Premium Members,DC=ad,DC=example,DC=com
ad.ldap.userbase.2 = CN=Basic Members,DC=ad,DC=example,DC=com
ad.ldap.groupbase.1 = CN=Security Groups,DC=ad,DC=example,DC=com
ad.ldap.groupbase.2 = CN=Application Groups,DC=ad,DC=example,DC=com

Combined Active Directory and iknowbase

You may use a combination of Active Directory and iKnowBase login. When you enable this, 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 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.

This configuration is an extended version of the spnego-configuration, specifying multiple login services:

# Use both ad.spnegoAndLdap for single sign on with Active Directory *and* iknowbase internal authentication
loginService = ad.spnegoAndLdap,iknowbase
...
# (additional ad.spnego and ad.ldap configuration as before)

Configuring 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 behave like the Active Directory LDAP module.

To restrict the negotiation to a set of specific hosts:

ad.spnego.requestServerNameExpr=SERVER_NAME FROM REQUEST
# Example
# ad.spnego.requestServerNameExpr=webserver-01.example.com

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

ad.spnego.requestRemoteAddrExpr=10.*
# Example all IP-addresses in 10.x.y.z range
# ad.spnego.requestRemoteAddrExpr=10.*

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

ad.spnego.requestHeaderName=HEADER_NAME
ad.spnego.requestHeaderExpr=EXPRESSION
# Example only for Firefox version 25 browsers:
# ad.spnego.requestHeaderName=User-Agent
# ad.spnego.requestHeaderExpr=.*Firefox/25.*

Configure SSL

We strongly recomment using SSL (https) for all production sites.

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 quickstart 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 Quickstart application server, set the property web.honorXForwardedHeaders in the property file:

...
web.honorXForwardedHeaders=true
...

Advanced topics

Specify session cookie domain

By default, the quickstart server 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”.

Note also that specifying a sesision cookie domain means that a single quickstart server can only serve sites belonging to that domain. If you specify a session cookie domain of iknowbase.com means that the same server may no longer serve content from example.com. If you need this scenario, for example to serve http://www.example.com, http://intranett.example.com and http://www.iknowbase.com from the same iKnowBase repository, use two quickstart servers (one for *.example.com and one for *.iknowbase.com) listening at different ports, and use a proxy server (such as Varnish or Apache Traffic Server) to direct requests appropriately.

...
web.sessionCookieDomain=example.com
...

Troubleshooting

iKnowBase applications can become partially unavailable if temp files are cleaned during runtime

The Quickstart server will by default use the Operating System’s temporary directory to store all currently deployed applications. If these files are deleted, parts of the iKnowBase applications will be unavailable as the required files are no longer present.

On Linux systems, this cleanup task is typically done by tmpwatch scheduled in /etc/cron.daily.

To solve the problem, do one of the following:

• Create a directory for the Quickstart server’s runtime applications, i.e. /home/iknowbase/.runtime, and point the Quickstart server to this directory using the configuration property System.java.io.tmpdir=/home/iknowbase/.runtime
• Exclude /tmp/jetty-* from tmpwatch