Web Application Security

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.

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.

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:

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:

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

Configuration

Web Application Security is configured using configuration properties .

See iKnowBase Installation Guide > Configuration > Spring Security Configuration for detailed configuration options.

Authentication

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:

Instant

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

1. Header
2. Spnego
3. 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.

WebDAV

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

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

Available authentication modules

Available authentication mechanisms:

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.

Username and password capable Providers

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.

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:

SAML endpoints:

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

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. Use <absolute url to site><iknowbase-webapp contextPath>/ikb$auth/<providerid>. Example: https://www.example.com/ikb$auth/google or https://www.example.com/ikb$auth/google.

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.

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:

Tokens are generated using PL/SQL IKB_AUTH_API and used as URL parameter “ikbAuthToken”.

Example: 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 successfull activation.

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

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

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 web applications have the following access requirements:

iKnowBase WebServices requires that the user is registered as a trusted principal through membership in the trusted principal ACL. See iKnowBase Installation Guide > Configuration > Web Services Security Configuration 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 Guide > Access-Control-Lists .

Administrator

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

Development toolkit

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

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:

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

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.

Switch user audit procedure

Whenever a user switch to or exit 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
);

Switch user database object ot_switch_user

The ot_switch_user object has the following properties:

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.

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-webapp multiple times, then each will have a /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.

Custom security implementation

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

Examples

This section covers common setup scenarios and explains the necessary setup. Refer to the Configuration section for detailed configuration names and options.

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.

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 production.properties setIkbPassword orcladmin SECRETPASSWORD

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

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

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/
• MUST have a input named “scope” for specifying social provider permissions.

Login form RememberMe requirements:

• RememberMe input MUST be named "_spring_security_remember_me"

An authenticated sessions is valid for one web application only. If you deploy multiple applications, e.g. iknowbase-webapp-1, iknowbase-webapp-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-webapp 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.

Basic authentication against iKnowBase User Repository

• Change the default authentication module to: Basic

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"

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

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"

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"

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)

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)

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

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)

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

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.

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 LDAP UsernamePassword authentication provider with a username mapping as shown below

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

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)

This a more complex configuration, with three userbases

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

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:

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

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 agains the enabled UsernamePassowrd 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.

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

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.

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.

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>

Configure the iKnowBase Header authentication module

Base configuration:

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 Orache HTTP Server’s IP address:

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)

Enable social infrastructure

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

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.

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

Register ADFS identity provider with iKnowBase

Download the ADFS metadata from https://YOUR_ADFS_SERVER/FederationMetadata/2007-06/FederationMetadata.xml and store the file 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).

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

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:

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.

Switch user database procedures

This is an example implementation of the switch user procedures.

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;
/

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;
/

Enable Social authentication with user activation link

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.
  • We only need the minimal set of permissions for authentication.
• Configure iKnowBase authentication modules and restart iKnowBase web application:

• 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

Troubleshooting

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 > Qualifier_

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

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.

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.

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:

• DO: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ipphone
• DON’T: ipPhone

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

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.

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 .

SpringSecurityConfiguration

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

See iKnowBase Installation Guide > Web Application Security for additional explanations.

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

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

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.

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.

Authentication modules

Module specific configuration is provided in the following sections.

Basic module configuration

No configuration options available.

Container module configuration

Form module configuration

FormAuto module configuration

No configuration options available.

Header module configuration

Spnego module configuration

LDAP UsernamePassword authentication provider

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.

iKnowBase UsernamePassword authentication provider

SAML authentication provider

See also: Spring Security SAML documentation .

Social authentication provider

Google specific configuration:

Twitter specific configuration:

Facebook specific configuration:

LinkedIn specific configuration:

Microsoft Live / Microsoft account specific configuration:

Secure Token authentication

Note: The iKnowBase Secure Token Engine configuration is described in SecureTokenEngine

Anonymous / Public authentication provider

iKnowBase User Details

All authentication attempts must ultimately load a user from the iKnowBase User Repository before the authentication is fully accepted.

Switch User

User Account Activation

IKB Auth Token