Tomcat 8 will automatically insert a "JSessionID" value into every redirect URL created by the web application, which can cause a number of issues in the SLS / HSP setup. This can be globally disabled in Tomcat in the file "$CATALINA_BASE/conf/web.xml", with this tag:

<session-config>
    <tracking-mode>COOKIE</tracking-mode>
</session-config>

Generally, cookies exchanged between the browser client and the login service are blocked by the SES for security reasons. However, this happens completely transparent to the protected application server. The HSP stores cookies created by a protected application server (and also the SLS) in its cookie-store instead of sending them through to the client, and inserts them in any subsequent request coming from the client. So, to an application server which sets a cookie, this process is transparent, and it cannot determine if the cookie comes from the actual client or the HSP cookie store.

Cookies in the HSP's cookie store are not stored persistently. They exist only as long as the SSL session between the HSP and the client browser.

If a cookie needs to be sent to the client in order to be stored there persistently (a typical example for this are GUI preferences), it must be enabled in the SRManager configuration. This process is called setting the cookie 'transparent\'. For more detailled information about the functionality of the HSP Cookie Store, please refer to [HTTPADMIN].

###
# Definitions for cookie filter
###
<IfModule mod_l1_cd_store.c>
<IfModule mod_session_int_handler_cookie.c>
SE_IntCookie_PersistentCookies SLSLanguage
</IfModule>
</IfModule>

In the configuration of the SRManager, appropriate locations must be specified for the protected application as well as for the SLS instance used to authenticate the users of that application.

<Location /sls/auth>
AC_StartPage                /sls/auth
AC_LoginPage                /sls/auth
AC_StartQueryString         ^.\*$
</Location>

<Location /staticfiles>
AC_AccessArea                                                           Public
</Location>

<Location /demo/app>
SetHandler                  http_1_1_gw_handler
# The following setting points to the SLS Tomcat
HGW_Host                    slshost.acme.com:8080
HGW_RequestHeaders          %HTTP11_std %HSP_std %HSP_ssl %HLS_std
AC_AccessArea               Customer
AC_AuthorizedPath           /demo
AC_LoginPage                /demo/sls/auth
</Location>

USP supplies a pre-configured Apache Tomcat installation with the according JDK to simplify your installation process. Currently there is a Solaris package available.

# groupdadd webadm
# useradd -G webadm sls

# pkgadd -d usp-sls-base-solaris-x-x-x.pkg

NOTE: In case of conflicting properties (a certain property appears multiple times in the configuration), the SLS will either log a WARN message about it, if the properties all have the same values, or fail startup with an ERROR log message, if the properties have conflicting values (since it cannot know which value would be the "correct" one).

It is possible to override properties defined in ".properties" files by setting them with a different value in a file with the suffix ".overrides". This could be used, for example, to have default values in the file "sls.properties", but override some of them in test environments etc., just by adding a file "test-environment-xy.overrides".

NOTE: The only property that MUST NOT be in an ".overrides" file is the property that allows to define custom configuration directories, "custom.config.path". This property MUST be in a file with the suffix ".properties".

NOTE: In case of conflicting overrides (a certain property appears multiple times in the override file(s)), the SLS will either log a WARN message about it, if the properties all have the same values, or fail startup with an ERROR log message, if the override properties have conflicting values (since it cannot know which value would be the "correct" one).

It is possible to define custom subdirectories within the SLS' "WEB-INF" directory to contain configuration property and overrides files as well. This allows, for example, to use such sub-directories for grouping certain property files together, e.g. model configurations where each model is in a separate property file.

custom.properties.path[suffix]

This optional property can be stored just once without any "suffix" part, if only one custom subdirectory shall be defined. It has to be in a properties file in the "WEB-INF" directory, e.g. the default "sls.properties" file. Example:

custom.properties.path=customconfigs

In which case the SLS would look for a subdirectory "WEB-INF/customconfigs" and scan it for property files as well. If multiple custom config directories should be added, a suffix can be added to the property, e.g.

custom.properties.path.1=customconfigs
custom.properties.path.2=models

Usually the SLS loads all property files found in the "WEB-INF"-directory and merges them internally to one configuration. It is also possible to define a finite list of files to be processed:

config.files

Defines a comma-separated list of file names. Each name must be defined relative to the "WEB-INF"-directory of the SLS.

Note: It is very difficult to define reasonable default values for JVM memory settings, since the memory consumption of any given SLS instance depends heavily on how it is used, what features are enabled, the number of logins per minute etc.

A very bare-bone, minimal SLS setup can already run with less than 100MB ram. However, as soon as more sophisticated functionality (especially Groovy/JEXL scripting) is used, and the number of concurrent users rises, the required value can be much higher. The following settings seem reasonable for a standard setup which may have to serve up to a few thousand users within minutes in peak times:

-Xms128m -Xmx2048m -XX:MaxMetaspaceSize=512m

This configures the JVM to reserve 128MB RAM from the start, and use up to 2GB if necessary. Also, the "Metadata" space of the Java 8 VM can use up to 512MB, which should be enough even for high traffic environments.

Note:

For more information on this complex topic, please consult the JVM documentation of Oracle.

Other useful settings for dealing with situations where the SLS does run out of memory would be:

-XX:+HeapDumpOnOutOfMemoryError

This settings will trigger a complete dump of the memory (RAM) into a file at the moment of an OutOfMemoryError. This file can be useful for the USP 3rd level support to analyze the problem and find the cause, especially in a situation where there is reason to assume there might be some kind of memory leak.

Note: The following parameter should be used together with this one, otherwise the JVM will save the memory dump file in an undefined location in the filesystem.

-XX:HeapDumpPath=/.../logs/sls-dump.hprof

This defines the path where the JVM should write the memory dump file. It is important to make sure that the SLS process has the correct, required permissions to do so.

Also, the following parameter can be very helpful:

-XX:OnOutOfMemoryError=...restart-trigger-script...

This one allows to define a custom shell script which is executed the moment the OutOfMemoryError occurs. That script can then do anything - including restarting the SLS instance. Since an OutOfMemoryError usually means a complete breakdown of the SLS functionality, requiring a restart anyway, this feature can help to reduce downtime of the service.

Nowadays, it is almost always a good idea to use UTF-8 as the default encoding in the SLS and the application servers, so that in cases where headers with special non-ASCII characters should be propagated to the application, the values can be properly processed on the receiving end.

Since the Java VM usually relies on the default encoding of the underlying operating system as its own default encoding, it’s a good practice to enforce the use of a certain encoding with this JVM system property in the startup script:

-Dfile.encoding=UTF-8

Despite the confusing name, this property does not only affect file-related operations, but has a general impact on situations where strings are to be created from an array of raw byte data.

-Djava.security.egd=file:/dev/./urandom

NOTE: This settings is really mandatory on Linux platforms. It configures the JVM to use a technically (cryptographically) less secure random number generator, but one that will ALWAYS be able to provide entropy. Without this setting, the default random number generator can occasionally run out of entropy data (which is generated from things like I/O traffic, mouse movements etc.). When that happens, any crypto operation within the SLS can get stuck in a reading operation, waiting until new entropy data becomes available. This is usually far less acceptable than the slightly reduced level of security caused by the software-only random value generator.

Tomcat 7 introduced scanning of an application’s JAR files at startup time, in order to support certain types of dynamic feature registration. However, this feature is not used by the SLS webapp, and can slow down startup considerably. Therefore, it’s recommended to disable it completely by setting the following Java System property in the startup script:

-Dtomcat.util.scan.StandardJarScanFilter.jarsToSkip=*.jar

The following properties are usually set in the file "sls.properties".

# Automatically adapt POST action in JSPs based
# on URI which triggered the model
form.use.dynamic.actions=true


# Avoid having the same error show up multiple times in the global error message
jsp.globalerror.last=true

# Make sure JEXL 2 is not fault-tolerant by default.
jexl2.lenient=false

# JSP bean should show internal error ID. Should
# be used for testing purposes only.
error.details=false

# Send HTTP header "SLSError" with error information
# to client (useful for automated clients, but use
# with caution)
error.header=false


# Allows to restrict basic auth to HTTPS locations
basic.auth.https.only=true


# Make sure SLS session attribute values are URL-encoded by default
session-attribute.encodings=true

# Enable BID-check functionality by default
bid.check.enable=true

# Disable creating Log4j variables for headers and parameters
log.disable.log4j.vars=true

# Respond with a self-redirect to POST requests
# (instead of a 200 with a HTML page)
selfredirect.enable=true

# Allows to enable automatic setting of the "host" request
# header through the SLS HttpRequestWrapper implementation, based on
# the always-present HSP header "hsp_https_host". This eliminates the
# need for setting the SRM directive "HGW_ForceHost" for SAML logins.
auto.host.header.enable=true

# Optional: If set to "true", the SLS will fail at startup if strong cryptography
# is not available (which is usually caused by not having installed the unlimited
# jurisdiction strength policy files in the JVM). Defaults to "false" for reasons
# of backwards compatibility. It it is false, only a warning will be logged.
fail.on.limited.crypto=true


# Login slowdown mechanism
slowdown.active=true
slowdown.usepage=false
slowdown.time=10
slowdown.type=doubling
slowdown.threshold=3

ldap.enable.escaping=true

Performs LDAP escaping on configuration strings for LDAP URLs and filters.

com.sun.jndi.ldap.connect.timeout=60000

Timeout for opening a new LDAP connection during a bind operation.

com.sun.jndi.ldap.read.timeout=10000

Timeout for read operations on an existing connection.

com.sun.jndi.ldap.connect.pool=false

Enables or disables connection pooling (defaults to "true"). Although using connection pooling generally seems to be a good idea, long-lived connections can sometimes cause hard to track issues with firewall infrastructures that don’t allow for long-lived connections. So, as long as there are no performance issues that indicate that a connection pooling might be required, it is recommended to keep it disabled.

If an error occurs during the login process the SLS will show a human readable info message and the internal error code if configured. In most cases displaying the internal error codes is not necessary in a productive environment and should therefore be disabled:

error.details=false

If not needed by a non-browser client, it is also recommended to disable the creation of an HTTP response header containing the internal error code:

error.header=false

Please note that both of these configuration options are disabled by default, if the properties are not set at all.

In a case where the SLS instance cannot handle as many requests at once as the HSP settings would allow, it may make sense to reduce the thread pool of Tomcat and thereby reduce the number of requests the SLS will process concurrently, e.g.

maxThreads=100

As a result, as soon as all 100 threads are busy processing a request, any newly incoming requests will still be accepted (until the value of "acceptCount" is exceeded), but are kept waiting until one of the busy threads is freed up.

Each time the SLS receives a GET requests, the model state remains unchanged (with some exceptions for login procedures that require GET requests). This means that the current state (usually a JSP state like "get.cred") remains active, and the page is displayed again. Which is the common, expected behaviour if the user, for instance, performs a page refresh in the browser.

On POST requests, the model is forwarded at request entry, from the current state to the next state, specifically:

There is a special model state named "do.generic" which, by itself, does nothing. It’s typical use-case is executing custom JEXL- or Groovy-actions somewhere in the model. But there is another special use related to the previously mentioned behaviour of the SLS when processing a POST request.

Because POST requests always immediately advance the model to the next state at request entry, there are some special cases where this can be a problem. A typical example is when the exactly same model should be used for cases where the very first request can be both a GET request (e.g. from a web browser, after being redirected to the SLS) or a POST request (e.g. from a rich client, as explained in the following paragraphs). Another example is a SAML-based login model, where the first request can be a GET or a POST, depending on the chosen binding.

In such cases, it may be necessary to put an additional "do.generic" state at the beginning of the model, knowing that it will have no effect for a GET request (it will just pass through to the following state), while during a POST request, it will be skipped - instead of the next state, which is really the first one, and which should always be processed.

Usually, in any SAML Identity Provider login model or any OpenID Connect (OIDC) login model, the first model state is one which processes the incoming SAML or OIDC message, e.g.

do.saml.idp.handlemsg

or

do.oidc.op.handlemsg

This state (which is explained in more detail later) basically extracts all SAML or OIDC elements from the incoming request and processes them. But if the incoming request is a POST request, and this state was the first in the model, it would immediately be skipped, and the SAML or OIDC request would not be processed at all. Which would then lead to a number of errors in the rest of the model. So, in order to support POST-binding in SAML and OIDC flows, an additional "dummy" state must be put in front of the message processing state, e.g.

do.generic
do.saml.idp.handlemsg

That way, when the first request is a POST, it will skip the first state - but that is just a dummy no-operation state. In case of a GET, the "do.generic" will be executed, but since it doesn’t do anything by itself, the model also continues to the next state, and processes the SAML or OIDC message.

The previously described SLS behaviour is often (ab-)used to support authentication for rich-clients in the same login model as for browser clients. For example, consider this simple model:

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.10.name=get.cred
model.login.state.20.name=do.auth
model.login.state.30.name=do.success

Also we are assuming that the SLS will be configured to accept basic authentication credentials, and that the rich-client will send a basic authentication header in its POST request.

With a browser client, the first request is a GET request (redirect sent from the HSP reverse proxy to the SLS). The model starts at the first state "get.cred", the corresponding JSP is displayed.

With a rich-client sending a POST request, the model also starts at the "get.cred" request, but because it is a POST request, is immediately forwarded to the next state - "do.auth". So, conveniently, no JSP will be displayed, which is fine for the rich-client (which couldn't handle a HTML page anyway).

However, the problem starts as soon as there are other states before the "get.cred" state, e.g. something like

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.10.name=do.generic-log
model.login.state.10.action.1=${function.logAudit('Starting login')}
model.login.state.20.name=get.cred
model.login.state.30.name=do.auth
model.login.state.40.name=do.success

In this example, the POST request from the rich-client will result in skipping the "do.generic-log" state (which doesn't to anyhing by itself), altough the JEXL-action attached to it will still be executed. But then, obviously, the next state is "get.cred", so the HTML page will be sent back to the client. In cases like these, there are two options:

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.10.name=do.generic-log
model.login.state.10.action.1=${function.logAudit('Starting login')}
model.login.state.10.nextState.1=do.auth
model.login.state.10.nextState.1.if=${...is rich-client...}
model.login.state.20.name=get.cred
model.login.state.30.name=do.auth
model.login.state.40.name=do.success

See "Triggering a model" for details on how to use a certain model under certain conditions.

Each state has the following attributes:

A state can have more than one "Failed States", and more than one "Next States". In that case, conditions (usually based on JEXL expressions) are used to determine at runtime to which state to switch. This allows to implement logical branches in the login flow, just by changing the configuration.

The model itself also requires that a default "Failed State" is defined, which will be used for all states in case of a failure, as long as no specific failed state has been defined.

A model state property always has certain attributes:

model.login.state.1.<attribute>=<value>

An example would be:

model.login.state.1.nextState=15

Where "nextState" is the attribute, and "15" the value. The following list shows all possible attributes and the meaning of their property values, and which ones are optional:

..action.1=${function.doSomething()}
..action.2=${function.doMore()}
..action.2.if.1=${...cond 1...}
..action.2.if.2=${...cond 2...}

Note that the "do.success" (or "do.success.jsp") state must be the last in the process. It does not have to be the last in the model, but all states following it can only be reached through explicit branching from previous states.

The reason is that this state sends a response back to the client (either a redirect or a JSP), so control is handed back to the client, and it also terminates the SLS session (NOT the client’s session with the WAF).

So, if any custom operations should be performed using the "do.generic" state in the case of success, it has to be done before the "do.success" state, like this:

4> model.login.state.2.name=do.auth
5> model.login.state.2.name=do.generic
5> model.login.state.2.action.1=${...do something...}
6> model.login.state.3.name=do.success

The optional suffix of a state name is ignored as far as dispatch mapping is concerned. Example:

do.generic-something

In this example, "do.generic" is the actual name part that will be looked up in the dispatch configuration. "-something" is the suffix that will be ignored.

Here, the first step is displaying the login page ("get.cred"), then performing the authentication ("do.auth"), and then executing the actions after a successful authentication ("do.success"), such as creating authorization headers etc.

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.1.name=get.cred
model.login.state.2.name=do.auth
model.login.state.3.name=do.success

This slightly extended model tries to authenticate the user against two different back-end systems, first LDAP and then RADIUS. If the LDAP authentication attempt in step one fails, it just continues to the RADIUS authentication. If that fails as well, it will switch back to the default failed state, "get.cred" (the login page).

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.1.name=get.cred
model.login.state.2.name=do.auth
model.login.state.2.adapter=ldap
model.login.state.2.nextState=do.success
model.login.state.2.failedState=do.auth-radius
model.login.state.3.name=do.auth-radius
model.login.state.3.adapter=radius
model.login.state.4.name=do.success

Note that the "next state" for state 2 ("do.auth", the first authentication attempt with LDAP) is set to "do.success". This means that in case of a successful authentication, the regular next state should be state 4 ("do.success").

If the authentication fails, on the other hand, the model should just switch to the next state in the list, no. 3 ("do.auth-radius"), in order to try to perform the second authentication call with RADIUS. If that one fails too, it will switch back to the default failed state of the model, "get.cred", which is the first state, so the whole process begins anew.

As mentioned before, each state can have an optional action, which means a JEXL-function that is executed at that time. Since custom JEXL-functions can easily be implemented and actived through the configuration (see "JEXL Expressions"), this allows to incorporate custom Java functionality to be executed in a login flow.

A custom action is configured like this:

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.1.name=get.cred
model.login.state.2.name=do.auth
model.login.state.2.action=${session.setValue('myValue', 'abcdef')}
model.login.state.3.name=do.success

After the authentication has been performed by the "do.auth"-State, the custom JEXL-function "session.setValue()" is executed, which stores a value in the SLS session (just for the sake of this example).

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.1.name=get.cred
model.login.state.2.name=do.auth
model.login.state.2.action.1=${session.setValue('myValue', 'abcdef')}
model.login.state.2.action.2=${session.setValue('otherValue', 'xyz')}
model.login.state.3.name=do.success

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.1.name=get.cred
model.login.state.2.name=do.auth
model.login.state.2.action.1=${session.setValue('myValue', 'abcdef')}
model.login.state.2.action.1.if.1=${session.getValue('someValue') != ''}
model.login.state.2.action.2=${session.setValue('otherValue', 'xyz')}
model.login.state.3.name=do.success

It is also possible to add so-called generic states to the model at any point, which refer to a dummy (aka "do-nothing") action. Such generic states basically just serve as holders to which to attach some custom JEXL-functions to be executed.

An example would look like this:

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.1.name=get.cred
model.login.state.2.name=do.auth
model.login.state.3.name=do.generic
model.login.state.3.action=${session.setValue('myValue', 'abcdef')}
odel.login.state.4.name=do.success

Especially the "do.generic" state is often used multiple times within the same model. In order to reference one as a failed- or next-state, the number must be used (because the name alone would be ambiguous), or a name with suffix. The suffix provides the advantage that no numerical references must be updated, should the model ever be changed by inserting new states or removing existing ones.

model.login.uri=/auth
model.login.failedState=get.cred
model.login.state.1.name=get.cred
model.login.state.2.name=do.auth
model.login.state.2.nextState.1=do.generic-two
model.login.state.2.nextState.1.if=${some.variable == 'someValue'}
model.login.state.3.name=do.generic-one
model.login.state.3.action=${session.setValue('myValue', 'abcdef')}
model.login.state.4.name=do.generic-two
model.login.state.4.action=${session.setValue('myValue', 'xyz')}
oodel.login.state.5.name=do.success

As shown in the previous examples, it is possible to define multiple "nextState" values for one given state. The following rules apply for adding "nextState" entries to one state:

There is always a default!

model.state.10.name=do.ldap
model.state.10.nextState=get.cred

or just the following state in the model, if nothing else is declared.

"if" required for additional

model.state.10.name=do.ldap
model.state.10.nextState.1=do.auth
model.state.10.nextState.1.if=${myvar eq 'abc'}
model.state.20.name=create.challenge

In this example, the default "nextState" of the state 10 ("do.ldap") is the following state in the model, state 20 ("create.challenge"). So, if the condition for the numbered "nextState" does not resolve to "true", the model will proceed to state 20.

"else" = default nextState

In other words, the default "nextState" of a state always serves as the "else" case, if none of the conditions for the numbered "nextStates" are fulfilled. Example for "if" / "else" conditional branching:

model.state.10.name=get.cred

# Go to state 50, if JEXL variable "domain" equals "acme.com"
# Otherwise ("else"), go to default nextState ("create.challenge")
model.state.10.nextState.1=do.ldap
model.state.10.nextState.1.if=${domain eq 'acme.com'}

# Perform some challenge / response
model.state.20.name=create.challenge
model.state.30.name=get.cred.challenge
model.state.40.name=do.authresponse

# Perform an LDAP lookup
model.state.50.name=do.ldap
model.state.50.property=userlookup
# By default ("else"), continue with state 80 ("do.auth")
model.state.50.nextState=80
# If LDAP attribute "grp" equals "admin", go to state 70
model.state.50.nextState.1=70
model.state.50.nextState.1.if=${attribute.ldap.grp eq 'admin'}

# Perform some HTTP callout notification
model.state.70.name=do.http
model.state.70.property=sendnotification

# Authenticate and complete.
model.state.80.name=do.auth
model.state.90.name=do.success

It is possible to define multiple triggers for one model, e.g. an URI and a JEXL condition. Example:

model.special.uri=/special
model.special.if=${header.trigger == 'special'}
model.special.failedState=get.cred
model.state.100.name=get.cred

In this example, the model will be triggered by both a "/special" request URI, as well as a HTTP request header named "trigger" which contains the string "special". In such a case, those triggers will still be processed as explained in "Trigger Priority".

This is the typical use-case. The default action URI of the SLS is "/auth", so the default login model should be configured to be used if for that URI (any incoming request with an unmapped / unconfigured URI will be forwarded to this path):

model.login.uri=/auth

For other processes, such as password change, other URIs should be defined (in the "web.xml" configuration file), and the models for those processes should be configured accordingly:

model.changepwd.uri=/changepwd

It is also possible to map multiple URLs to one model:

model.changepwd.uri.1=/one
model.changepwd.uri.2=/two
model.changepwd.uri.3=/three

The "changepwd" model could then be triggered by invoking any of the three URLs "/one", "/two" or "/three" (or using the "cmd" parameter, like "cmd=one", "cmd=two" or "cmd=three").

..../sls/auth?cmd=changepwd

Triggers the model if the script expression evaluates to "true". This trigger is evaluated on every request, so it can also be used to re-start the model already being processed in the current session, or to switch to another model entirely. In this example, if the request has a parameter "restart" with the value "yes":

model.login.alwaysIf=${parameter.restart == 'yes'}
model.login.failedState=get.usererror
model.login.state.1.name=get.cred.token
model.login.state.100.name=get.usererror

Triggers the model if the script expression evaluates to "true" (but only if there was no model yet in the session). In this example, if the request has a parameter "abc" with the value "dothis":

model.login.if=${parameter.abc == 'dothis'}
model.login.failedState=get.usererror
model.login.state.1.name=get.cred.token
model.login.state.100.name=get.usererror

If a missing authorization was the reason for the redirect of the client to the SLS, that authorization is signaled to the SLS through some custom HTTP headers by the reverse proxy. The authorization itself is just a string, defined with the "AC_RequireAz" directive in the SRM location.

The following example would trigger the SLS to use the "tokenlogin" model in case that a user needs the authorization "token":

model.tokenlogin.missingAuthorization=token

The HSP/SES session (which has no direct correlation to the SLS session) carries an internal state. At the beginning, when a client browser connects to the HSP but isn't authenticated yet, the state is "Invalid". After a successful authentication, the state changes to "Valid".

For certain special functionality such as transaction verification, the HSP (or the application, to be specific) will change the value of an active, authenticated session to any custom value such as "CredVerify" in order to start a process like verification of a pending transaction. Once the HSP session is not in state "Valid" anymore, any following request from the client will be directed to the SLS. The application session is still valid at this point, though; this serves just as a mechanism to implement processes that require interaction with the SLS while a user is working with an application.

A good example is an E-Banking application, where the user needs to verify transactions. While the application session remains active, the user must be forced to switch to the SLS in order to perform a transaction verification. To achieve this, the application will change the state of the HSP session (by setting a special HTTP header) to a custom value, like "CredVerify". The next request from the client is then redirected to the SLS by the HSP automatically.

At that point, a special model should be invoked to process the verification of a transaction, but the request URI will just be the default URI of the SLS (such as "/auth"), so the URI cannot be used to trigger the right model. Instead, the HSP session credential state can be used:

model.trxverify.credentialState=CredVerify

In some cases, the SLS might need to cooperate with adjoining services to perform certain operations. In cases where no direct communication with these services is possible, data is exchanged through the client redirect, in an encrypted URL-parameter named "req".

This parameter internally consists of a number of key/value-pairs; one of which is named "cmd" and can be used to trigger a certain model:

model.clearvr.reqCmd=clearvr

This table lists all available model states that are mapped to a JSP.

This table lists all available model states that are mapped to actions.

adapter.authentication2

<action path="/doauth" scope="request"
  parameter="adapter.authentication"
  name="loginForm" validate="true"
  input="jsp.login" type="....LoginAction">
</action>

<action path="/doauth2" scope="request"
  parameter="adapter.authentication2"
  name="loginForm" validate="true"
  input="jsp.login" type="....LoginAction">
</action>

<action path="/doauth3" scope="request"
  parameter="adapter.authentication3"
  name="loginForm" validate="true"
  input="jsp.login" type="....LoginAction">
</action>

<forward name="do.auth" path="/doauth.do"/>
<forward name="do.auth2" path="/doauth2.do" />
<forward name="do.auth3" path="/doauth3.do" />

adapter.*authentication3*=radius

model.xyz.state.3.name=do.http
model.xyz.state.3.property=myoperation

model.xyz.state.3.name=do.ldap
model.xyz.state.3.property=myoperation

model.state.10.name=do.redirect
model.state.10.property=/some/app

model.state.10.name=do.redirect
model.state.10.param.url=/some/app

model.state.10.param.invalidate=false

model.state.10.param.url.absolute.allow=true

model.state.10.param.goto.next.state=false

model.example.state.1.name=show.json
# 1st Example: Define relative file path
model.example.state.1.param.jsonFile=/WEB-INF/json/SomeResponse.json
# Set custom HTTP response code
model.example.state.1.param.statusCode=277

model.example.state.1.name=show.json
# 2nd Example: Define inline JSON
model.example.state.1.param.json={ "content": { "say": "hello" }}
# And invalidate session right here
model.example.state.1.param.invalidate=true

model.example.state.1.name=show.json
# 3rd Example: Define inline JSON, but get content from a template file
model.example.state.1.param.json=#{function.getTemplateContent('jsonResponse')}
# also set custom content-type
model.example.state.1.param.contentType=text/json

model.example.state.1.name=show.jsp
# 1st Example: Define relative file path
model.example.state.1.param.jsp=/WEB-INF/jsp/My.jsp

model.example.state.1.name=show.jsp
# 2nd Example: Define file with resource key
model.example.state.1.param.jsp=jsp.login

A real-world example for the default JSP login forms provided with the SLS delivery package would look like this:

In this example, the request parameter "userid" (which is defined by the name "userid" of the corresponding HTML form field in the login JSP) is used as a credential of the semantic type "username". And the request parameter "password" is used for a credential of the semantic type "password".

As a special case, there is also a JEXL credential provider available. This provider is always active, so it is not necessary to configure just to activate it. It is also always the last one in the list, so it will always override the credentials of the other providers. But this also means that it can be used to "post-process" credentials created by other providers through JEXL.

Because the JEXL provider does not have a number, but an internal ID "jexl", the configuration properties used to configure credentials handled by it must always have the prefix

cred.provider.jexl.cred.

The following example shows how to add a prefix to the value of the username credential created by the "http" provider:

cred.provider.jexl.cred.1.type=username
cred.provider.jexl.cred.1.source=${'acme:' + session.getCred('username')}
cred.provider.jexl.cred.1.name=undefined

Note: Due to internal dependencies, the property ".name" must be set with some value, altough it is really ignored by the JEXL credential provider. But not setting it will result in a configuration error.

The "basechallenge" adapter creates either a 6-digit number or a text string. The following properties can be set in "sls.properties" to configure the base challenges:

adapter.challenge

Set to "basechallenge" to activate using the internal base challenge / response adapter.

challenge.type

Optional: Set to "numeric" to create a number, by default with 6 digits, or to "string" to create a random alphanumeric string, by default with 40 characters. Defaults to "numeric" if not set.

challenge.lifespan

Optional: Allows to define the lifespan (validity period) of the response, in number of seconds. Defaults to 1800 (generous 30 minutes) if not set.

challenge.characters

Optional: Allows to define the list of characters to be used in the generated challenges; this should usually be alphanumeric ASCII characters. Defaults to:

ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789

NOTE: The default characters intentionally avoid using any characters that are easily confused, such as one ("1") and lower-case L ("l"), or zero ("0") and "O". Consider this issue when configuring a custom set of characters.

challenge.length

Optional: Allows to define the length of the generated challenge. For numeric challenges, the default is 6 characters, for strings it is 40 characters.

The generic challenge-/response adapter is referred to by the alias "basechallenge":

sls.properties

adapter.challenge=basechallenge

challenge.type=string

sls.properties

adapter.authentication=ldap

ldap-adapter.properties

ldap.url=ldap://ldap.acme.com:389
ldap.principal.default=cn=Manager,dc=acme,dc=com
ldap.password.default=humptydumpty
ldap.auth.type=bind
ldap.auth.bind.dn.1=cn=${session.getCred('USERNAME')}, org=usa,dc=acme,dc=com

Define a group of HTTP adapter properties with the group alias "sendsms" (which will be used in the model to refer to these properties). This example assumes that the HTTP interface of the mobile phone provider takes four POST parameters:

http-adapter.properties

# The url of the sms provider.
http.sendsms.url=http://global.phone.com/sendsms

# The HTTP method.
http.sendsms.method=post

# HTTP Header properties
http.sendsms.header.Content-Type=text/xml

# The body of the HTTP request. The challenge is stored
# in the JEXL variable "challenge", and the mobile phone
# number in the variable "attribute.ldap.phone".
http.sendsms.body=customer=acme&password=secu8932&number=${attribute.ldap.phone}&text=code:${challenge}

# Error codes
http.sendsms.code.error=500,503

# Deny codes
http.sendsms.code.denied=401,403

If the SMS provider CGI interface requires to post an XML structure, the JEXL templating mechanism can be used. See "Templates" for details on how to define and use templates.

Once a template is defined, insert it into the body of the HTTP POST request:

http.sendsms.body=${function.getTemplateContent('msg')}

The following model puts everything together:

sls.properties

model.login.uri=/auth
model.login.failedState=get.cred

# Show login page
model.login.state.1.name=get.cred

# Perform authentication (password check with LDAP)
model.login.state.2.name=do.auth

# Create challenge
model.login.state.3.name=create.challenge

# Use HTTP adapter to send response code with SMS
model.login.state.4.name=do.http
model.login.state.4.property=sendsms

# Display response code page
model.login.state.5.name=get.cred.challenge

# Verify response code
model.login.state.6.name=do.authresponse
model.login.state.6.failedstate=get.cred.challenge

# Authentication completed.
model.login.state.10.name=do.success

Background: If a user enters data into a HTML form and posts it, current browsers will cache the form data if the response to the request was a HTTP 200 - but not when it's a redirect (HTTP 302). In environments where computers are potentially shared by multiple users, one user could perform a complete login, and another malicious user could then later "replay" that login by pressing the "back" button of the Browser in order to have it post the same form data again.

selfredirect.enable

Optional: If set to "true" the SLS will perform a redirect to itself after every POST request, in order to eliminate that problem. Defaults to "false" for reasons of backward compatibility.

ignore.requested.page

Forces the SLS to redirect the client always to the configured default redirect URL (property "redirect.default"), regardless of what page the client originally wanted to access.

redirect.default

Default URL to which the client browser should be redirected after a successful login. Usually, if a browser tries to access an application URL and the HSP redirects the request to the SLS, the originally requested application URL is preserved in the request, and the SLS will automatically redirect the client to it after successful authentication. But if a browser accessed the SLS directly (due to a bookmark, for example), and no requested page could be retrieved from the request, this default URL will be used instead.

The redirect.default URL is also used as the default redirect location during logout, unless an explicit redirect.logout URL has been configured. See this property below.

requested.page.whitelist

This optional property holds a regular expression which is a whitelist for allowed requested pages. Only if the regex matches, the requeste page is valid, else it is rejected ant the SLS will redirect to the default page "redirect.default".

requested.page.blacklist

This optional property holds a regular expression which is a blacklist for allowed requested pages. If the regex matches, the requeste page is is rejected ant the SLS will redirect to "redirect.default".

requested.page.postinform

Defines if the requested page is included in any <sls:form> as a hidden POST parameter to distinguish different tabs. Default is true.

redirect.logout

URL to which the client browser should be redirected after a successful logout. This can be overridden by a "target" request parameter.

If redirect.logout is not set, the redirect.default property is instead used as the default redirect location.

The model state "do.redirect" also allows to perform a redirect at any point in the model (see "Action states"). Please note that this state, by default, invalidates the login session before executing the redirect! If a redirect should be performed without invalidating the SLS session, the state parameter ".param.invalidate=false" must be set:

model.state....name=do.redirect
model.state....param.invalidate=false

Note also, that actions attached to the do.redirect model state are only executed if the SLS login session is not invalidated and only if/when a following request comes in.

IMPORTANT: The SLS session will NOT be terminated automatically if an internal forward is made, instead of the usual redirect performed by the "do.success" state.

As a consequence, when using an internal forward, it is the responsibility of the JSP or custom action, to handle and invalidate the session properly (in a JSP, the JEXL function "session.invalidate()" may be used with the "getJexl" JSP tag).

forward.logout

Internal SLS path to which the request should be forwarded after a successful logout.

The checker can be enabled or disabled globally through this configuration property:

http.parameter.check.enforce

Default is "false". The checker can be enabled by setting it to "true".

However, since verifying the request parameters is also a security issue, it is strongly advised to keep this functionality enabled.

parameter.http.<id>.xxx=...

parameter.http.x.methods=POST,GET

parameter.http.loginpage1.name=password
parameter.http.loginpage1.uri=/doauth.do
parameter.http.loginpage1.methods=POST,GET
parameter.http.loginpage1.required=false
parameter.http.loginpage1.regex=[a-zA-Z0-9]
parameter.http.loginpage1.min-length=6
parameter.http.loginpage1.max-length=20

In this example, the request parameter "password" is allowed to be sent through both GET and POST requests to the URI path

"/doauth.do".

According to the regular expression, the parameter may contain all characters from "a-z", "A-Z" and "0-9", and must be between 6 and 20 characters.

The links must point to the SLS application, with the parameter "language" containing the 2-character code of the desired language ("de" for german, "en" for english etc.). For example:

<a href="?language=en">English</a>
<a href="?language=de">Deutsch</a>
<a href="?language=it">Italiano</a>

The user's language choice is then stored in a persistent cookie named "SLSLanguage" so that the same language will be used automatically the next time the same user performs an authentication again.

Sometimes applications use their URI to decide which language to use, e.g. an application "/demoapp" might use URIs such as:

If a user tries to access such a URI and is redirected to the SLS, the URI of the requested page is sent to the SLS as well. This makes it possible to select the language for the login session based on this URI. There are two options available:

lang.uri.regex=/.*/(.*?)/

lang.uri.part=2

See "Language Cookie" for information on how to configure the default language.

It is possible to configure additional subdirectories in the "WEB-INF" directory, which can contain more message resource property files. These files must follow the exact same name conventions as explained above; and they will ALWAYS have precedence over the files in the "classes" directory. This means that by adding an additional subdirectory for custom resource files, it is possible to just override the properties that need to be different than the SLS’s own default values; either per language, or per tenant, or both.

custom.resources.path

This property allows to define either an absolute path to a directory anywhere in the filesystem, or a relative path for a subdirectory of the SLS "WEB-INF" directory, to contain additional message resources, e.g.

custom.resources.path=more_resources

If multiple subdirectories should be used (for example, if message resources should be split up in separate directories for each tenant), then an arbitrary suffix can be added to this property to add it multiple times, e.g.

custom.resources.path.1=acme_resources
custom.resources.path.2=store_resources

The resource files also contain properties which hold names of JSP-files that could be used for the given language. The default login page JSP, for example, is named "Login.jsp". The file used for a german user, however, could be named "Login_de.jsp", or it could be in a separated directory, like "de/Login.jsp".

This is somewhat contrary to the 'official\' approach of JSP applications as propagated by Sun, where there is only one single JSP page which localizes text through a Java bean. Of course a JSP developer is still free to do it this way. But experience shows that in many companies tools are not available to efficiently handle JSPs with bean-based text localization, and the preferred way is to just create static text for each language by creating a separate set of JSP files. That is why the SLS provides the mechanism to use a custom JSP for each language.

An example file and directory structure could look like this:

sls-webapp/
  WEB-INF/...
  jsp_en/
      Login.jsp
      Welcome.jsp
      ...
  jsp_de
      Login.jsp
      Welcome.jsp
      ...
  jsp_fr
      Login.jsp
      Welcome.jsp
      ...

In each "sls-resources_XX.properties" file, all the jsp path properties would have to be adjusted acordingly as follows:

sls-resources.properties

jsp.login=/jsp_en/Login.jsp
jsp.welcome=/jsp_en/Welcome.jsp

sls-resources_de.properties

jsp.login=/jsp_de/Login.jsp
jsp.welcome=/jsp_de/Welcome.jsp

The following components can be adapted to customize the JSPs (besides the JSP files themselves):

jsp.globalerror.first

Optional: If set to "true", only the first error message from the parameter checker is shown when the message tag (<sls:message>) is called with the special key "global.error.msg". If set to "false", all error messages are displayed. When i.e. the username is too short and contains an illegal character, both messages are displayed.

Defaults to false.

NOTE: This property has higher priority than jsp.globalerror.last, if both are set to "true".

jsp.globalerror.last

Optional: If set to "true", only the last error message from the parameter checker is shown when the message tag (<sls:message>) is called with the special key "global.error.msg". If set to "false", all error messages are displayed. When i.e. the username is too short and contains an illegal character, both messages are displayed.

Defaults to false.

NOTE: This property has lower priority than jsp.globalerror.first, if both are set to "true".

jsp.javascript.minimize

Optional: If set to "true", all the SLS JSP tags that would normally render JavaScript for some functions just won't do it. This should only be used in cases where it is certain that the client browsers do not support JavaScript, and it is important to keep the HTML free of any JavaScript as a result.

Defaults to "false".

A few style names were changed with Bootstrap 4 and 5. Replace the name prefixes of these style classes accordingly in the JSPs and/or include files:

*Old*

*New*

col-xs-*

col-*

col-sm-offset-*

offset-sm-*

col-md-offset-*

offset-md-*

col-lg-offset-*

offset-lg-*

Remove the following include statements from all JSPs and/or include files:

Unless, of course, you are making explicit use of any functionality in the Bootstrap JavaScript files in your customized JSPs. Please consult the official Bootstrap 5 documentation page for more information about breaking changes in the new Bootstrap releases.

The "bootstrap.min.js" file is still included in the "includes" folder of the SLS static files, but it’s not used by the SLS JSPs by default. But it can be used if its functionality is required for any customized JSPs.

To send a mail, the model state "do.sendmail" can be used. It requires an additional "property"-State to define which group of properties to use:

model.state.50.name=do.sendmail
model.state.50.property=<alias>

The "<alias>" value refers to a group of properties which define the details of the mail to be sent:

email.<alias>.to

The list of receiver e-mail addresses. It can be a single address or a comma-separated list.

email.<alias>.from

Address which will be set as sender in the e-mail header.

email.<alias>.subject

The subject of the message

email.<alias>.body

The body/content of the message. As it is desirable to have longer message there are two ways to fill this property:

email.<alias>.body=This is the body.

If the text should continue on the next line add a back-slash ("\") at the end of the line.

email.<alias>.body=This is a long line of the body \
which continues here.

Be aware the whole text will be shown as one line in the body. It will not create a line break at the intended position.

email.<alias>.body=${function.getTemplateContent('XY')}

email.<alias>.mimeType

Optional: The MIME type of the mail. Defaults to "text/plain".

The function needs four parameters similar to the model state. The method header is:

sendMail(to, from, subject, body)

The body can use the same template function as the model state. A complete model state could look like this:

model.sendmail.state.25.name=do.generic
model.sendmail.state.25.action.1=${function.sendMail('receiver@domain.com', 'sender@domain.com', 'Mail Subject', function.getTemplateContent('infomail'))}

All tenant specific resources should be in separate resource property files which follow the regular Java language resource file naming convention, extended with a tenant prefix:

sls-resources-<tenant>_<lang>.properties

Where "<lang>" is a two-letter language code like "en", "it" etc., and "<tenant>" is the tenant alias, like "acme". For example, in addition to the regular resource file holding all english messages, named

sls-resources_en.properties

there could also be an additional file named

sls-resources-acme_en.properties

which holds all paths, messages etc. that are different for the tenant "acme".

Determine the tenant based on a part of the requests' URL path, defined through a regular expression. Example:

multitenancy.resolving.1=urlregex

The regular expression for matching the URL must be defined in a property of the following type:

tenant.<no>.regex

Regular expression for matching with the URL path (or a part of it).

The value of a URL parameter is used to determine the tenant. Example:

multitenancy.resolving.1=urlparam

The URL parameter name is pre-defined:

mand

So by invoking the SLS URL with the URL-parameter "mand" set to one of the defined tenant aliases, the corresponding tenant can be triggered:

..../sls/auth?mand=acme

The first part (prefix) of the hostname of the request is used to determine the tenant. Example configuration property:

multitenancy.resolving.1=hostprefix

So if this property is set like this, and the incoming request would be for the host

acme.corp.com

it would result in the usage of the tenant "acme".

NOTE: For this type of tenant resolution, the SRM configuration must also be adapted correctly, or the SLS will not receive the correct host header value. See "Step 3: Configure SRM" for details.

Determine the tenant based on the alias of the sender of the current SAML message. For example, in an SLS Identity Provider setup, all registered Service Providers are configured and usually given an alias, to easily refer to them when using SAML-related JEXL functions etc. Based on that alias, the tenant can be triggered as well.

multitenancy.resolving.1=samlalias

The alias for each tenant, that corresponds to the alias of the SAML provider, must be configured like that:

tenant.<no>.samlalias

Example of an SP registered in the Identity Provider under the alias "acme-ltd-sp":

idp.sp.1.alias=acme-ltd-sp
idp.sp.1.metadata.provider=file
idp.sp.1.metadata.location=WEB-INF/idp/acmesp-metadata.xml
...

tenant.2.samlalias=acme-ltd-sp

The JEXL function "session.setTenant(alias)" allows to enforce a certain tenant from within the model:

model...state.10.name=do.generic
model...state.10.action=${session.setTenant('acme')}

Note: Even if this JEXL function is used, at least one of the previously mentioned resolve mechanisms must still be configured, if the multi tenancy feature is enabled!

There is a JEXL variable that holds the value of the current tenant:

current.tenant

So, in order to define a condition - for example in a customized model - based on the tenant, the JEXL expression would look something like this:

..state.3.nextState.if=${current.tenant eq 'acme'}

If the goal is to have a complete set of JSPs for each tenant, the JSP paths must be defined in the tenant-specific resource files in the SLS web application subdirectory "WEB-INF/classes". For example:

In file "sls-resources-acme_en.properties":

jsp.login=/jsp/acme/Login.jsp

In file "sls-resources-multicorp_en.properties":

jsp.login=/jsp/multicorp/Login.jsp

If there should be only one single set of JSPs that should display different content for different tenants, a number of JSP tags can be used. All relevant SLS JSP tags automatically support usage of tenant-specific resource files, if they are available. So in order to have tenant-specific messages, a message key must be moved from the default resource file "sls-resources.properties" into the tenant-specific resource files.

See "Language Cookie" for information on how to configure a default language for a certain tenant.

There is a jexl function session.getTenantSpecific(), wich allows setting of the following configuration properties in a tenant specific way:

Consult the [JEXLGUIDE] for details about the jexl function.

There are more SLS features, that can be used tenant specific. For example the "Parameter Checker / Aliases" and the "Browser Blacklist".

It is possible to use separate log files for each tenant. In case of URI-separated tenants, it is even recommended, because of potential problems that might occur with log file rotation (see "Log rotation problem with URI-based multi-tenancy" for details).

For details on how to configure Log4J to use separate log files for each tenant, please read "Tenant-specific logging".

NOTE: If multitenancy is enabled, but the logging configuration is not adapted accordingly, some log records may not get written anywhere as a result!

First, the additional resource files with the tenant-specific messages should be created. They are to be put into the SLS web applications\' subdirectory "WEB-INF/classes".

The first file, "sls-resources-asia_en.properties" must contain the following property:

page.heading=Welcome to ASIA Corp.

And the other resource file, "sls-resources-euro_en.properties", must contain the same property, but with a different value:

page.heading=Welcome to EURO Corp.

Now in order to have a JSP display the correct heading for the current tenant, include this JSP tag:

<sls:message key="page.heading" />

However, it will not work yet as long as the following steps are not completed.

A few properties must be defined in the "sls.properties" configuration file, as described above:

multitenancy.enabled=true

tenant.1=asia
tenant.2=euro

tenant.resolving.1=hostprefix

If tenant resolution is done by hostname (hostprefix), it is mandatory to add the following directive to the login location of the SRM configuration:

HGW_ForceHost    <hostname>

<hostname> must be the actual hostname of the virtual host, e.g.

HGW_ForceHost    www.acme.com

If this directive is not set, the SLS usually receives "127.0.0.1" as the hostname. This prevents the hostname-based tenant resolution from working correctly.

The order in which the regular expressions in the file are processed is unspecified. Therefore, it is not guaranteed that the expressions are processed top-down.

Syntax: <rule name>=<regular expression>

The first property contains the regular expression. That expression is used to evaluate the HTTP header "User-Agent" sent by the client. If it matches, the action defined by the property set is performed.

See "Regular expressions reference" for more information about regular expressions in the SLS.

Syntax: <rule name>.desc=Default description
Syntax: <rule name>.desc.<lang>=Language-specific description

This property allows to specify a text description that will be displayed to the user by the actions "popup" and "info". Since each session has a language defined by the SLS language cookie, it is possible to create descriptions for each supported language. The <lang> part of the property name must be a 2-letter language code similar to the codes used by the Java localization API ("de", "en", "fr" etc.).

If no description is found for the language code of the session, the default description is used. If no default description is available, an empty String will be used.

Syntax: <rule name>.fixsslsid=on

This property allows to enable or disable the SSL session ID fixation functionality of the HSP for a client that matches with this rule. This value will override the global default setting.

Syntax: <rule name>.tenant=<tenant>

The scope of a rule can be limited to a tenant. If this rule-limitation +.tenant=<tenant>+is used, that rule it is only valid for the given tenant. If an other - or no - tenant is selected, the rule is not active.

The followin rule would deny the IE browser for tenant "secur".

IE=MSIE.
IE.desc=No IE Browser allowed.
IE.tenant=secur

Syntax: <rule name>.action=[popup | info | deny]

This property defines the action that should be performed for requests sent by clients matched by this rule. There are three possible values:

There is a header that the SLS can set in its response which has a special semantical meaning for the HSP. This HTTP header is usually referred to as "LoginUserData" header throughout SLS and HSP documentation files.

This HTTP response header is basically the standard means for the SLS to propagate any kind of credential to the application after a successful login. The mechanism works like this:

In the SLS, the configuration looks like this:

hsp.header.LoginData=${session.getCred('username')}

This will instruct the SLS to create an HTTP response header named "LoginUserData" with the value of the username credential.

Now, to have this information sent to the application in a custom HTTP request header "UserCreds", the corresponding application location in the HSP configuration would need this directive:

HSP configuration

AC_LoginUserDataHeaderName    UserCreds

(The default for the header name if not configured is "LoginCredentials".)

There is also a generic mechanism for propagating custom headers to the application. The main advantage over the "LoginUserData" header mechanism is that it doesn't require any specific configuration on the HSP side. However, it also means that the header will always have the same name for all applications, while the "LoginUserData"-header mechanism allows to implement a mapping in the SRM configuration.

This property triggers the HSP to send a custom HTTP header with a certain value to the application server with each client request once authentication was completed:

app.header.<headername>=<headervalue>

Where <headername> is the name of the HTTP request header that must be propagated to the application server, and <headervalue> the text value of that header. The value can also contain variables (see chapter "JEXL Expressions") or a combination of hardcoded strings and variables. The following example shows how to propagate a header with the name "userid" and the value of the username credential to the application:

app.header.userid=${session.getCred('username')}

The same example but with a hardcoded prefix "User:" in the value:

app.header.userid=User:${session.getCred('username')}

IMPORTANT NOTE!

Any custom HTTP header that should be sent to the application server must also be enabled in the HSP configuration (see [HTTPADMIN]). Otherwise, it will be blocked and not be forwarded to the application.

Encoding can be tailored. For example in order to propagate an ISO-8859-1 encoded header to the application do this:

app.header.userid=${function.urlEncode(session.getCred('username'), 'ISO-8859-1')}
app.header.userId.isValueEncoded=true
app.header.userId.encoding=url

In this case the header is propagated from the SLS to the HSP using URL encoding and the URL encoding is already provided in the expression for the header value. The HSP then URL decodes the received header and forwards it URL decoded (and thus now in ISO-8859-1 charset) to the application. That way headers can be forwarded to applications in practically any encodings that the Java VM supports. (Note that this mechanism is meant to be used with encoding "url" (or "base64"), but not with the legacy encoding "string".)

The following types of SSO filters are available currently:

Not all filters support the exact same range of functionality. There are three filter modes:

The following table shows which filters currently support which types of credential handling:

The various Java-based filter types provided by the SLS share the same core functionality, and mostly the same configuration settings. The main difference is that in one case (J2EE filter) those settings must be defined as initialization parameters in a "<filter>"-tag in a "web.xml" file, and in the other case (Tomcat Authenticator module) as properties in a Java property file.

Since the settings themselves are the same, this chapter describes each setting and what it does. It serves as a list of reference for the following chapters about the configuration of the various filters.

NOTE: The settings names (left column) in the list below are (depending on the type of filter used) sometimes just a part of a full configuration property name. Example:

The setting "mode" from the reference list maps to

There are some complete configuration examples for different types of authentication setups in "SSO Configuration Examples". The examples include both filter and SLS configuration.

Especially in cases where the SLS which performs the login and creates the propagated header, and the application with the filter are not running on the same platform / OS, problems may arise with headers containing special characters. In that case, it is recommended to ensure the usage of the same default encoding in both JVMs (SLS and application server), by setting this JVM startup option:

-Dfile.encoding=<encoding>

Where <encoding> is a value like "UTF-8" or "UTF-16".

The filters provided by USP employ Apache’s Commons Logging API for their logging functionality. The library is included in the delivery of each filter for convenience.

NOTE: The commons logging library may already be available in your servlet container of choice. In that case, it may not be advisable to deploy the commons-logging-<version>.jar file, or classloader issues may occur (especially if the library version provided by the container differs from the one in the filter delivery).

Commons Logging Configuration

A general way to enable the Commons Logging mechanism and have simple debug logs written to standard output would be by setting these two system properties, usually as Java VM parameters:

-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Dorg.apache.commons.logging.simplelog.defaultlog=trace

This results in a lot of debug logging information in one of the Tomcat log files; which one depends on the logging configuration of Tomcat. A typical default is the file "localhost.<timestamp>.log".

mode

(Optional) Allows to choose the type of authentication used. The following types are available:

roid=123456;LoginKennung=Hugo;[SourceIP=172.130.4.101];

a regex to parse "Hugo" as user name would be:

regex=.*LoginKennung=([a-zA-Z]*);.*

The regex mode also supports the possibility of verifiying a signature included in the header. For using that, several configuration properties are needed (see "keyIndexFile", "checksign" and "signkeyid").

Default is "plaintext".

headerName

The name of the header to get the user credential information. This is the HTTP SSO header propagated from the SLS which contains either just the user ID (if "mode" = "plaintext"), or a list of key-/value pairs (if "mode" = "regex") or an SES ticket (if "mode" = " sesticket").

Default is "userinfo".

requireValidUser

(Optional) If the filter should enforce authentication and enforce an error if a user is not authenticated. Set this property to "false" to disable this behaviour.

Default is "true".

checktimestamp

(Optional) Can only be used with "mode" = "regex". If set to "true", the filter will check the timestamp in the "Timestamp="-key using the configured "threshold". This is basically an expiration check, used to prevent replay attacks. Note that if this option is used, the SLS must be configured correspondingly to actually create a "Timestamp="-key in the propagated custom header.

Default is "false".

threshold

(Optional) Defines the expiration threshold in number of seconds, if "checktimestamp" = "true".

denyResponseCode

The HTTP response code to send to the client if access is denied.

Default is "401".

denyResponseMessage

The HTTP response message to send to the client if access is denied.

keyIndexFile

(Optional) Required if (a) "mode" = "sesticket", or (b) "mode" = "regex" and "checksign" = "true". This key index file contains the path of the public key required to verify the ticket or the regex signature, and optionally the path to the encryption key required to decrypt a ticket.

Example Tomcat Authenticator:

authentication.keyIndexFile=/var/list.keyindex

Example J2EE Filter:

<init-param>
  <param-name>keyIndexFile</param-name>
  <param-value>/var/list.keyindex</param-value>
</init-param>

regex

(Optional) If "mode" = "regex", this parameter defines the regular expression required to parse the user ID from the header.

checksign

(Optional) Can be used only if "mode" = "regex". If set to "true", the filter will verify the signature (key: "Signature=") in the header.

Default is "false".

signkeyid

(Optional) If "checksign" is set to "true", this parameter must be set to define the ID of the public key used to verify the signature. This is the ID of the key in the key index file configured with "keyIndexFile".

Example Tomcat Authenticator:

authentication.signkey=key_2

Example J2EE Filter:

<init-param>
  <param-name>signkeyid</param-name>
  <param-value>key_2</param-value>
</init-param>

The application might need to retrieve further information from the principal and not only the principal name. In this case, all needed information should be added to the userdata header configured in SLS.

The authenticator will store all key-value pairs from this header in the principal and make them available for a later retrieval by the application.

The application can access these values by casting the principal to the following interface, which defines the customized principal with the added key-value-pair store and retrieval capability:

com.usp.sls.appserver.base.IExtendedPrincipal

This class is an extension of the standard principal class java.security.Principal. Now the proprietary method

getValue(<key>)

of the casted object instance can be called to retrieve a value. For example, if the following header was configured in the SLS:

app.header.userinfo=${function.addSigAndTime('LoginKennung=' + session.getCred('username') + ';SrcIP=' + header.hsp_client_addr + ';' )}

Then the value of the source IP from the application could be retrieved in the following way:

((com.usp.sls.appserver.base.IExtendedPrincipal)request.getUserPrincipal()).getValue("SrcIP");

The same can be applied to all key-value pairs defined in the configuration file of the SLS.

Please note that, in order to be able to use this feature, it is mandatory to configure the header key-value pairs (in the SLS properties file) in the following format:

...some content...;<key>=<value>;...more content...

A semicolon must be used to separate each key-value pair from the other ones and from the rest of the header. And an equal sign must separate the value and the corresponding key.

usp-j2ee-filter-<version>.jar
usp-tomcat-authenticator-<version>.jar

The J2EE filter provides the means to easily integrate J2EE applications with a HSP (Secure Entry Server) environment. It allows to use either a SES ticket, a plain text header or a header consisting of custom key-/value-pair strings to map the username to. The extracted credentials are then made available to the application through the following standard servlet API methods:

javax.servlet.http.HttpServletRequest

java.lang.String getRemoteUser()

Returns the login of the user making this request,

if the user has been authenticated, or null if the user has

not been authenticated.

java.security.Principal         getUserPrincipal()

Returns a java.security.Principal object containing the name of

the current authenticated user.

<!-- HSP authentication filter -->
<filter>
<filter-name>AuthenticationFilter</filter-name>
<filter-class>com.usp.ses.authapi.AuthenticationFilter</filter-class>
<description>This filter handles the user credentials.</description>
...
<init-param>
<param-name>headerName</param-name>
<param-value></param-value>
</init-param>
...
</filter>

<filter-mapping>
<filter-name>AuthenticationFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

/appserver/j2ee-filter/libs/

<init-param>
<param-name>mode</param-name>
<param-name>regex</param-name>
</init-param>

The Apache Tomcat servlet container supports a proprietary filtering mechanism called "Authenticators". An authenticator basically has a similar job as a servlet filter, the main difference being the fact that it works server-wide, for all applications deployed in that container. Hence, it is configured in the Tomcat container itself, not in each applications "web.xml" file (see "Step by Step Installation Notes" for details).

Note: The JAAS module contained in the SLS Tomcat Authenticator delivery is a requirement by the authenticator, but cannot be used in any other context.

The SLS "Tomcat Authenticator" allows to use either a SES ticket, a plain text header or a header consisting of custom key-/value-pair strings to map the username to. The credentials are then made available to the application through the same servlet API methods as with the J2EE servlet filter (see "SSO Request Filters").

<Realm className="org.apache.catalina.realm.JAASRealm"
appName="SES"
userClassNames="com.usp.sls.appserver.jaas.UserPrincipalImpl"
roleClassNames="com.usp.sls.appserver.jaas.RolePrincipalImpl" />

JAVA_OPTS="$JAVA_OPTS -Djava.security.auth.login.config=$CATALINA_BASE/conf/jaas.conf"

<security-constraint>
<web-resource-collection>
<web-resource-name>all</web-resource-name>
<url-pattern>/\*</url-pattern>
<http-method>POST</http-method>
<http-method>GET</http-method>
</web-resource-collection>

<auth-constraint>
<role-name>role</role-name>
</auth-constraint>

</security-constraint>

<security-role>
<description>unique role</description>
<role-name>role</role-name>
</security-role>

<login-config>
<auth-method>SESTICKET</auth-method>
<realm-name>any</realm-name>
</login-config>

authentication.mode=regex

com.usp.sls.appserver.level = FINE

<appender name="AUTHENTICATOR_LOG"
class="org.apache.log4j.DailyRollingFileAppender">
<param name="Threshold" value="TRACE" />
<param name="datePattern" value="\'.\'yyyy-MM-dd" />
<param name="file" value="${catalina.base}/logs/authent.log" />
<param name="Append" value="true" />
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern"
value="%d %-5p %c:%M() %m%n" />
</layout>
</appender>

<logger name="com.usp">
<level value="TRACE" />
<appender-ref ref="AUTHENTICATOR_LOG" />
</logger>

A custom header named "username" shall be propagated to the application. The header is supposed to contain just the plain user ID.

SLS

app.header.username=${session.getCred(username)}

J2EE filter

<init-param>
<param-name>mode</param-name>
<param-value>plaintext</param-value>
</init-param>
<!--Optional (because "username" is default) -->
<init-param>
<param-name>headerName</param-name>
<param-value>username</param-value>
</init-param>

Tomcat Authenticator

authentication.mode=plaintext
# Optional (because "username" is default)
authentication.headerName=username

A header named "userinfo" containing various key-/value pairs with user information should be created. One of the fields, "loginName", contains the user ID. The header should also be signed and have a timestamp with a 4 hour (14400 seconds) expiration time.

Signature Keys

Note: This example assumes that there are "SES Ticket API" keys available, an RSA public and private key pair. Each key is referenced in the index file (which is a simple text file) "list.keyindex", which must be available on both the SLS and the application server.

On the SLS, the file must contain the path of the private key with the alias "key_1", on the application server it must hold the path of the public key with the alias "key_2".

Please see "26 SES Login Ticket"for more information about SES Ticket API functionality in general, or "SES Ticket API Tool" for information about how to create your own keys and key index files.

SLS

app.header.userinfo=${function.addSigAndTime( + 'loginName=' + session.getCred('username') + ';SrcIP=' + header.hsp_client_addr + ';' )}

This property configures the HTTP header "userinfo" to be propagated to the application. The value of the header will be a key-/value pair string:

loginName=<loginName>;SrcIP=<Client-IP>;sig=<sig>

Where <loginName> contains the user’s login ID, <Client-IP> the IP address of the browser client, and <sig> is the actual signature and a timestamp, created by the JEXL function "addSigAndTime()".

The following properties are required to configure the private key with the alias "key_1" defined in the index file "list.keyindex" to create the signature:

ses.ticketapi.keyIndexFile=/var/list.keyindex
ses.ticketapi.keyId=key_1

Without these two properties, the JEXL function "addSigAndTime()" will fail with a runtime error message!

J2EE filter

<init-param>
<param-name>_mode_</param-name>
<param-value>regex</param-value>
</init-param>
<init-param>
<param-name>_headerName_</param-name>
<param-value>_userinfo_</param-value>
</init-param>
<init-param>
<param-name>regex</param-name>
<param-value>.\*loginName=([a-zA-Z]\*);.*</param-value>
</init-param>
<init-param>
<param-name>keyIndexFile</param-name>
<param-value>/var/list.keyindex</param-value>
</init-param>
<init-param>
<param-name>signkeyid</param-name>
<param-value>key_2</param-value>
</init-param>
<init-param>
<param-name>checksign</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>checktimestamp</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>threshold</param-name>
<param-value>14400</param-value>
</init-param>

Tomcat Authenticator

authentication.mode=regex
authentication.headerName=userinfo
authentication.regex=.*loginName=([a-zA-Z]*);.*
authentication.keyIndexFile=/var/list.keyindex
authentication.signkeyid=key_2
authentication.checksign=true
authentication.checktimestamp=true
authentication.threshold=14400

A header named "sesticket" containing a SES ticket should be created. The ticket should have an expiration time of 4 hours.

SLS

ses.ticket.One.realm=ACME Corp.
ses.ticket.One.lifetime=14400
ses.ticket.One.keyIndexFile=/var/list.keyindex
ses.ticket.One.public.key=key_2
ses.ticket.One.private.key=key_1
ses.ticket.One.attr.userid=${function.getVerifiedCred('username')}

app.header.sesticket=${function.createTicket('One',function.getCred('username'))}

J2EE filter

<init-param>
  <param-name>mode</param-name>
  <param-value>sesticket</param-value>
</init-param>
<init-param>
  <param-name>headerName</param-name>
  <param-value>sesticket</param-value>
</init-param>
<init-param>
  <param-name>keyIndexFile</param-name>
  <param-value>/var/list.keyindex</param-value>
</init-param>

Tomcat Authenticator

authentication.mode=sesticket
authentication.headerName=sesticket
authentication.keyIndexFile=/var/list.keyindex

Please read chapter "SES Login Ticket" for detailed information about SES tickets.

If the application server is configured to identify clients through HTTP basic authentication, the HSP must send the required HTTP headers to the application server once the SLS has authenticated the user.

If the application server uses a custom HTML login form, the HSP must fill in the correct values into that login form and post it to the application server (completely transparent to the client browser) once the SLS has successfully authenticated the user.

In both cases, the SLS must send certain login information to the HSP after a successful login in order to enable the HSP to perform the automatic basic or form authentication against the application server.

auth.type=basic

auth.type=form

formauth.parameter.<name for HSP>=<field name in the login form>

formauth.parameter.thirdCred=thirdCred