Session Controller Properties
- Kim Rasmussen
- Kim Rasmussen (Unlicensed)
- Niels Thykier (Unlicensed)
| Property | Value |
|---|---|
defaultAuthenticationType | <integer>
This property specifies which server authentication plug-in is used as default, if the PTServer interface functions with the authType parameter.
Each authentication plug-in has a unique number. It is this number which is referred to. The list of installed plug-in’s is specified in the session controller in server.authenticationplugins |
server.authenticationplugins | <list of class names which implement interface IauthenticationPlugin>
This list implements the authentication mechanisms.
If a authentication mechanism needs to be added, the mechanism implementation must be added to this list.
Example: dk.itp.security.authplugins.X509CertificatePlugin, dk.itp.security.authplugins.UIDPWAuthenticationPlugin, dk.itp.security.authplugins.SpnegoAuthenticationPlugin, dk.itp.security.authentication.CrossDomainAuthenticationPlugin, dk.itp.security.authentication.ntlm.NTLMAuthenticationPlugin |
| server.authenticationpluginscripts | <List of authentication plugin names> Defines a list of authentication plugin scripts which are loaded. |
| server.authenticationplugin.xxxx | Authentication plugin - xxxx is replaced with script name. Allows you to provide an authentication plugin - the value must start with %{script} for javascript, or %{script:<engine_name>} for other types of script - e.g. %{script:groovy} if you write the script in groovy. See Authentication Plugins for examples. |
| script.prelogon | <Script, JavaScript, Python or Groovy> This script is called just before login, before the authentication plugin is called. If a PTException is thrown (or returned) by the script, login is aborted and considered to be failed. More information at Authentication Plugins |
| script.postlogon | <Script, JavaScript, Python or Groovy> This script is called as part of login, after the authentication plugin is called. If a PTException is thrown (or returned) by the script, login is aborted and considered to be failed. More information at Authentication Plugins |
server.authorizationplugins | <list of class names which implement the IauthorizationPlugin interface>
This class implements the access control in PortalProtect.
Example: com.msl.usiserver.authplugins.ADAuthorizationPlugin |
clusterID | <integer>
This property specifies which cluster a session controller is a member of. Session controllers in the same cluster share sessions, that is, the sessions are replicated in-memory between session controllers in the same cluster. Session controllers which run I separate clusters don’t share sessions.
This can be used to connect large networks together in large installations but won’t share sessions. One could, for example, host many different applications, intranet and internet, in the same installation. For example, 2 session controllers to the internet and 2 to the internet, running in their own cluster. These networks would then be able to see each others sessions. This would mean that the expanse of configuration of the configuration servers and integration servers to back end systems could be saved. Furthermore, the statistics would be centralised in the installation.
Example: 1
In this example the session controller is a member of cluster number 1. The session controller will be able to share sessions with session controllers in the same cluster.
|
mirror.listen | <true | false>
A session controller can function in either a master cluster or a slave cluster. A master cluster machine receives changes in the sessions from the slave machines and distributes these changes to the other slave machines in the cluster. . A cluster-master machine listens for connections on the urls listend in the mirror.listenurls property. Example: <true>
In this example the session controller functions as a master in the cluster setup. The session controller functions as a distributor of sessions to other nodes in the cluster. When a cluster-master machine receives an event for example, session-timeout, it will update its own internal session-state and replicate the change to the other slave nodes in the cluster.
Example: <false> In this example the session controller is a slave node and will only send and receive changes about sessions. |
mirror.listen.port | <port>
This property is the port listened to for the the cluster master node. This port corresponds to one of the defined ports in mirror.servers
Example: 12234 |
mirror.listenurls | <URL list> - defaults to tcp://{mirror.listen.port} where {mirror.listen.port} is the value of the mirror.listen.port property.
List of URLs to listen for connections from configuration clients – The URLs have the following format:
tcp://[hostname:]port – TCP/IP blocking sockets – requires 2 java threads per connection. nio://[hostname:]port – TCP/IP nonblocking (java nio) sockets – does not require any extra threads. local://port – Local queue-based connection, requires 1 thread per connection, only works in the same JVM, but much faster than using sockets. nios://[hostname]:port[?params] – Like NIO, but with SSL encryption
For nios connections, the following parameters can be specified; keystore – Filename of keystore – default is /ptskeystore keystorepassword - Password for keystore keystoretype – Type of keystore, default is JKS enabledciphersuites – List of enabled cipher suites, if not specified, the Java default ones are used.
Note that this list of URLs replaces the older mirror.server.port property – this provides a more flexible way to support multiple communication protocols, and listen on multiple interfaces simultaneously. If this property is not specified, it will default to tcp:// protocol and the port number from the mirror.listen.port setting to remain backward compatible.
Examples: server.listenurls=tcp://12348 – Listens on port 12348, using TCP blocking sockets |
mirror.servers | <host:port> [<,|;> <host:port […] ] – or protocol://hostname:port
This property specifies a list of cluster master machines this session controller needs to connect to.
The protocols tcp:, nio: and local: can be used, see mirror.listenurls for a description.
Example:
In this example the session controller will connect to a mirror computer at 10.0.0.1, port 12234, and to 10.0.0.2, port 12234 |
server.port | <port> - DEPRECATED – replaced by server.listenurls This session controller port is used by servers in the secure intranet zone. When a web application needs to validate a session and log a user onto the session, this session can contain sensitive information. This information must therefore not be accessible in the insecure DMZ. Application servers must connect to this port from the intranet zone in order to read information on the session. This property corresponds to the port in one of the session controllers in. Example: |
server.listenurls | <URL list> - defaults to tcp://{server.port} where {server.port} is the value of the server.port property.
List of URLs to listen for connections from session controller agents, or PP Agents – The URLs have the following format:
tcp://[hostname:]port – TCP/IP blocking sockets – requires 2 java threads per connection. nio://[hostname:]port – TCP/IP nonblocking (java nio) sockets – does not require any extra threads. local://port – Local queue-based connection, requires 1 thread per connection, only works in the same JVM, but much faster than using sockets. nios://[hostname]:port[?params] – Like NIO, but with SSL encryption
For nios connections, the following parameters can be specified; keystore – Filename of keystore – default is /ptskeystore keystorepassword - Password for keystore keystoretype – Type of keystore, default is JKS enabledciphersuites – List of enabled cipher suites, if not specified, the Java default ones are used.
Note that this list of URLs replaces the older server.port and property – this provides a more flexible way to support multiple communication protocols, and listen on multiple interfaces simultaneously. If this property is not specified, it will default to tcp:// protocol and the port number from the server.port setting to remain backward compatible.
Examples: server.listenurls=tcp://21243 – Listens on port 21243, using TCP blocking sockets |
server.restrictedport | <port> - DEPRECATED – replaced by server.restrictedlistenurls This session controller port is used by servers in the insecure DMZ. When a dispatcher needs to validate and create a session, this port is used to communicate with the session controller. Information about the user behind the session is deleted before being sent to the dispatcher in the DMZ. If the server.port is used session information can be read which may be confidential. This information must not be available in the DMZ zone. Application servers must therefore connect to this port, from the intranet zone in order to read information on the session. This oolean corresponds to one of the session controllers in tunnel server > General > ptsserver. Example: In this example the session controller listens on the specified port. Session queries sent to the session controller on this port, must/does not contain confidential information. |
server.restrictedlistenurls | <URL list> - defaults to tcp://{server.port} where {server.port} is the value of the server.port property.
List of URLs to listen for connections from restricted agents.
See server.listenurls for a list of the protocols and their meaning.
The connections/ports specified here is used by restricted agents often those deployed in the DMZ zone. Certain sensitive or non-needed information contained within a users session is deleted before it is sent to the restricted agents, to minimize the impact of an eventual server breach.
Example: |
server.revisionlogclass | <classname>
This class implements either the dk.itp.security.passticket.server.IRevisionLog or dk.itp.security.passticket.server.IRevisionLogExended interface which is uses by the session controller to log revision related events.
The revisions log is used to store events about transactions which can be of a judicial nature. Legislation in these cases requires that information is secure and is stored for a specified time span. For further information regarding revisions logging contact internal revision.
You can use the class “dk.itp.security.passticket.server.Log4jRevisionLog” – it logs relevant information to the logger category “revisionlog” or you can create your own if you have special needs. If you need an example, contact support and we can provide the source code for one of the sample classes.
Example:
In this example the session controller uses a null device, which does not log information to be sent to the revisions log. This information is printed on the console. This must only be used in test systems or in systems which do not require revisions logging. |
sessionTimeout | <time in minutes.>
This is the number of minutes before an inactive session is timed out. Note that session information and access rights are cached in the PortalProtect agents for up to 5 minutes. If the session controller’s sessionTimeout is set to 90 minutes, then 95 minutes can go before the session is deleted.
This timeout can be overridden for individual sessions, by setting the state variable “pp_custom_timeout” to a new value, e.g. “pp_custom_timeout=120” sets the timeout to 2 hours for this specific session.
An individual session expiration date can also be set by setting a state variable; “pp_custom_expiresat” to the number of milliseconds since 1/1 1970 (System.currentTimeMillis()) – if that is set, the session will expire at this exact time at the latest. It might still expire earlier due to idle timeout.
Example:
In this example the session is stored for 90 minutes plus the time the session is cached in the PortalProtect agents: dispatcher and web servers (max 5 mins.)
Example
This is the recommended value for internet applications.
Note that timeouts less than 5 minutes won’t work because of the way the agent caches sessions for up to 5 minutes. |
authenticationTimeout | <time in minutes, 0 to disable> - Default is 0.
Behaves like the session timeout, but does not timeout the entire session – instead it simply logs the user off after the timeout has expired, but keeps the session alive. This can be useful if you want to the user to reauthenticate after a certain timeout, but you wish to keep his state intact if he later reauthenticates before the timeout has expired.
If set to 0, it is disabled and only the regular session timeout is used.
If the timeout is set to a larger value than sessionTimeout, it essentially have no effect.
If you set a state variable, “pp_custom_authenticationtimeout” in the session, this can be used to override the default value for an individual session. |
safeStateVariables | <state variable> [<,| ;> state variable [<,| ;> state variable …] ]
Here it is possible to list a series of safe state variables which will be copied to restricted agents (for example dispatchers which are typically restricted). All state variables not listed here will not be transmitted to restricted clients. Restricted clients will only receive information about user, username, userip, isloggedon, authenticationmethod, isinternal and a few other state variables that are always bound to the users session (those state variables are those with specific get methods on the Agent interface). |
| safeStateVariablesPattern | <Pattern> Any state variables are in addition to the ones specifically mentioned in This allows you to use wildcard matching, e.g. You can use wildcards; * and ? or the pipe sign | to specify multiple values.
Please refer to Oracle's Java documentation for the individual flags and their meaning here: https://docs.oracle.com/javase/tutorial/essential/regex/pattern.html |
hidePasswordFromDispatcher | <true | false> - Default true By default, the users password is removed before sending the request to a restricted agent, such as the dispatcher (restricted since it is usually deployed in a less secure DMZ network zone). Setting this to false allows the users password to be sent to the dispatchers which might need it if they are configured to perform http basic authentication between dispatcher and application server on behalf of the authenticated user. |
maxConcurrentSessions | <number of sessions>
Specifies the maximum number of concurrent sessions in a Session Controller – note that this is not a hard limit, the number of sessions CAN grow beyond what is specified.
When the number of concurrent sessions goes above the max, the session timeout will be temporarily decreased in 5 minute intervals (until it reaches a minimum of >5 minutes) and any anonymous sessions will be considered timed out.
If the number of sessions is still to high after timing out anonymous sessions, the idle timeout will also be reduced for sessions with identified users – this happens in 5 minute intervals, with a minimum of 15 minutes.
Even if decreasing the session timeout does not get rid of all the sessions, new sessions will still be created, so the limit is not a fixed one.
Example: maxConcurrentSessions=50000 |
maxConcurrentSessionsHardLimit | <number of sessions>
Specifies the hard limit for the number of simultaneous sessions – if the number of current sessions has reached the hard limit, no new sessions will be created, and requests for new sessions will fail. Note that this option should only be used to protect the server from running out of memory – the value of this property depends greatly on the amount of memory available, and the contents of the sessions.
Example: maxConcurrentSessionsHardLimit=100000 |
useSSLForRestrictedPeer | <true | false>
This property specifies whether the dispatcher should connect to the session controller via an SSL encrypted line or the connection should be established un encrypted.
If the dispatcher is in the DMZ, it is recommended that the connection between the dispatcher and the session controller is encrypted.
If the dispatcher is in the secure zone then encryption is not I. In this case this property is set to <false> IMPORTANT: This property must be set in the same way in the session controllers configuration. Either both are set to encrypted to both to unencrypted. The dispatcher will not get a stable connection is they are different.
Example: <true> The dispatcher will in this case connect to the session controller via an SSL encrypted connection. In this case the session controller must also run encrypted.
<false> In this example the dispatcher connects to the session controller via an unencrypted connection. In this case the session controller also needs to run unencrypted.
Note that this setting is no longer used, instead the schema on the connection URL decides – e.g. tcps://server:port or nios://server:port for SSL encrypted blocking or nonblocking UI. |
modeluser | <username> Username of the model user which will be used for all anonymous sessions. If non-empty, the user will be used as a ”model” user, which means that all anonymous sessions will have the same access rights as the model user. |
modelpass | <password>
Password to model user, can optionally be encoded or encrypted using ”java dk.itp.utils.PasswordUtils”. |
authenticationplugin.typemapping | <id1=id2,id3=id4>
Can be used to map from one type of authentication plugin to another.
Example: 1=5 – if a client wants to use a plug-in of type 1, 5 will be used instead. |
authorizationplugin.typemapping | <id1=id2,id3=id4>
Can be used to map from one type of authorization plugin to another.
Example: 1=5 – if a client wants to use a plug-in of type 1, 5 will be used instead. |
authenticationplugin.restrictenvironment | <authType1=id1,id2,id3;authType2=id1,id2>
Can be used to restrict from which environments access is allowed – only requests Ids with a valid environment is allowed to access the specified authentication plugin. Note that this environment closely relates to the environment ID specified in the dispatcher.
Example:
In the above example, only environment 1 or 2 has access to authentication plugin 15 (X509 certificate) – and only environment 0 (the default) and 2 have access to plugin 27 (E-Ticket)
The list of values for authTypes can be seen in the class dk.itp.security.passticket.AuthTypes. |
authenticationplugin.restrictsegment | <authType1=id1,id2,id3;authType2=id1,id2>
Functions just like authenticationplugin.restrictenvironment but restricts access to plugins based on segment ID instead of environment ID
|
notifyAllAgentsOnSessionChanges | <true | false> - default false
If true, all Agents will be notified about changes to sessions, such as timeouts – if false (which is the default) only those Agents who have previously used the session will get notifications – this greatly improves performance in environments with many Agents, so you should only set this flag to true, if you need all agents to be notified of all sessions (this could be the case if you have a listener who needs to know about all users logging in or out, no matter which agent they do it on)
Example |
disableNotifyAgentsByDefault | <true | false> - default true
If false, if an Agent disconnects and later reconnects to the session controller, it will be marked as being interested in notifications about all existing sessions, since the session controller has no way of knowing which sessions the particular agent wishes to receive notifications for. A notification is a timeout, or a request for a cache clear. Leaving this value to false might affect performance if you have many thousands of sessions created, and agents which regularly disconnect/reconnects but by setting to true you risk that an applications PTListener might not get notified about a session being removed or timed out, even if it is interested it knowing just that.
Example |
allowRemoveAllSessions | <true | false> (default: false)
If true, a new action is added to the admin GUI in the session controllers details, where you can remove all current sessions, this is mostly useful for testing where you might want to “wipe the slate clean”
Example |
ntlm.<segment>.smb.client.soTimeout | <Timeout in milliseconds> (default is 30000)
To prevent the client from holding domain server resources unnecessarily, sockets are closed after this time period if there is no activity. This time is specified in milliseconds. This parameter will work for the given segment (0 – 255) |
ntlm.<segment>.netbios.cachePolicy | <NetBios name timeout in seconds> (default is 300)
When a NetBIOS name is resolved it is cached to reduce redundant name queries. This parameter controls how long, in seconds, these names are cached. The default is 5 minutes, 0 is no caching, and -1 is forever on the given segment (0 – 255) |
ntlm.<segment>.debug | <true | false> (default is false)
Enable or disable debugging of HEX dumped Smb messages on the given segment (0 – 255) |
ntlm.<segment>.providepassword | <true | false> (default is false)
Enabling this parameter will provide the user domain password as part of the session if the domain controller allows this on the given segment (0 – 255). This is typically not allowed at all on Windows 2003 servers. |
ntlm.<segment>.http.domainController | <IP address | hostname>
This parameter should provide the IP address or hostname of the domain controller used for Smb authentication on the given segment (0 – 25) |
ntlm.<segment>.netbios.hostname | <hostname>
If your Active Directory security policy requires that users only log into the domain from their personal workstations Smb will fail to authenticate and the server security log will have entries like “10_40_4A cannot be authorized”. This occurs because the domain controller is failing to resolve the dynamically generated “calling name” submitted by the client during protocol negotiation. To get around this it is necessary to set this hostname property to a valid NetBIOS name that can be resolved by the NetBIOS name service (e.g. WINS) and add that name to the AD security policy as a permitted client.
This hostname is used on the given segment (0 – 255) |
agentfailuressoftlimit agentfailureshardlimit agentquarantinetime | <number of failures> <number of failures> <time in seconds>
Agents can be quarantined if they generate a lot of failures repeatedly – e.g. if the application they share the JVM with uses all the memory available.
If an agent is slow in responding for a given number of session update requests (specified by <agentfailuressoftlimit>), the timeout is first lowered from the default 5 seconds to 0.5 seconds – this is done to ensure that a slow agent cannot cause the whole system to behave slowly. If the agent continues to respond slowly (<agentfailureshardlimit> times), it will be disconnected. After 3 disconnects the agent will be quarantined for a while (default 10 minutes, specified by <agentquarantinetime>) and will not be allowed to reconnect to the server for that period.
<agentfailuressoftlimit> specifies the number of failures that can occur before the timeout is lowered <agentfailureshardlimit> specifies the number of failures that can occur before the agent is disconnected <agentquarantinetime> specifies the number of seconds that the particular agent will not be allowed to connect.
If either the soft or the hard limit is set to 0, it means they are disabled. |
mirrorfailureshardlimit | <number of failures> (Default is 100)
If the number of failures (e.g. timeouts) go above this limit in communication with a mirror server, then it will be disconnected.
|
peer.socket.recvbuffersize peer.socket.sendbuffersize
| <size in bytes> (default 0) <size in bytes> (default 0)
If set to nonzero, it will be used to set the size of socket receive / send buffers different from the default value. The default depends on the platform, usually it is around 64k.
You should leave this alone unless you specifically need to mess around with it, e.g. to lower the windows kernel memory buffer usage and avoid the socket error “Recv failed: Insufficient buffer space”.
Note that these values can also be set as system properties. |
sessionpersistpassword | <Password>
Password used to encrypt persisted sessions with – must be the same across all session controllers in a cluster. |
server.sessionpersistcheckerclass | <classname>
Name of a class which implements the ISessionPersistChecker interface. It can be used to check if a user/session is allowed to persist or restore the contents of another session. |
lb.changeactive.differenceinconnections | <integer> Default 3
Used with dynamic loadbalancing. Contains the number of connections that a given server must have less than the current server for the client to change to the lesser loaded server.
Note that the lower the value, the higher the risk of setups with many agents will switch back and forth between servers, and the higher the value, the more uneven the load will be across multiple servers. |
lb.reconnectinterval | <integer> Default 30
Used with dynamic loadbalancing. The number of seconds between the client attempting to reconnect to any available servers that it previously was not able to connect to. |
lb.switchactiveinterval | <integer> Default 600
Used with dynamic loadbalancing. The number of seconds between checking all connected active and passive servers and switching active server to a lesser loaded server, if one exists. If the lesser loaded server has at least lb.changeactive.differenceinconnections (default 3) less connections than the current server, the client will change active server. |
delayListenersOnStartup | <true | false> Default true
If set to true, the session controller will delay 20 seconds after startup before listening for connections from agents. This is done to ensure that it has been able to connect to all mirrored servers and synchronize sessions with them before opening up for agents access to these sessions. |
internAclStrings | <true | false> Default false
If set to true, ACL strings on the session will be intern’ed (String.intern() will be called on all ACL strings).
If a session contains hundreds or thousands of ACL entries, they take up quite a lot of memory – by using String.intern() the sessions will all share the same string instance and thus use significantly less memory – also when being serialized and sent to mirror servers. Interned strings have some limitations depending on the version of Java used for running Ceptor. Please consider reading http://java-performance.info/string-intern-in-java-6-7-8/ for details of these limitations and their performance considerations. |
httpSessionKeepAlivePingInterval | <interval in seconds, 0 to disable> Default 0
If a value > 0 is configured (if >0 and less than 60, it is set to 60) every <httpSessionKeepAlivePingInterval> seconds the session controller will run through the list of authenticated sessions and list of applications backend servers being used. It will then ask dispatchers to ping the backend application servers to keep the http session alive.
A dispatcher “pings” an application server by sending an HTTP GET request to the <httpsessionkeepalivepingurl> specified for the application with the users session ID cookies included. This causes the application server to reset the idle timeout for this user essentially keeping the http session alive as long as the portalprotect session is alive. This enables a shared timeout between portalprotect session and all backend application servers.
Note that it requires session cookies to be saved by the dispatcher in the “cookiesToHideFromBrowser” property, or the dispatcher will not have the information needed to ping the backend servers. |
geoip.database geoip.ispdatabase geoip.orgdatabase | <Filenames – Default blank> Specify a GeoIP / GeoLite database containing GeoIP information. geoip.database Contains country/city/postalcode/latitude/longitude information - use either the country or city variant of the database. geoip.ispdatabase Contains ISP (Internet Service Provider) information geoip.orgdatabase Contains Organization information. If you configure the databases, you need a minimum of geoip.database – the others are optional. Note that the databases distributed with PortalProtect are not very accurate on latitude/longitude and city level, but you can purchase a subscription for more accurate databases. Also note that because of the size of the organization database, it is not distributed with the default PP, contact support obtain the database if you need it. |
| geoip.update.directory | <Directory name - default is /tmp> Specify which directory to download GeoIP databases into - use e.g. ${ceptor.home}/config/geoip and set |
| geoip.update.hostname | <Hostname - default is updates.maxmind.com> Specify hostname to call - normally the default is fine. |
| geoip.update.editions | <Comma or semicolon separated list of edition names> Specify which editions to download from MaxMind - see MaxMind.com for information about which editions exists. Examples:
The GeoLite2-* databases are free, but less accurate than the ones you can purchase - so to get the most accurate data, you should purchase a subscription from MaxMind and configure Ceptor to download the editions you need. Note that every |
| geoip.update.accountid | <MaxMind Account ID> Here, you can specify the MaxMind Account ID. As of 1/1 2020 you will need to register with MaxMind for an account, even to download the publicly available GeoLite free databases - see more info here: https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases/ |
| geoip.update.licensekey | <MaxMind License Key> Here, you can specify the MaxMind License Key. |
| geoip.update.proxy.host | <Proxy hostname> If a proxy is used, specify the hostname here. |
| geoip.update.proxy.port | <Proxy port> - default 8080 Proxy port number |
| geoip.update.proxy.user | <Userid> Proxy userid, if any. |
| geoip.update.proxy.password | <Password> Proxy password, if any - can optionally be encrypted. |
| geoip.update.proxy.noproxyfor | <String pattern> Hostnames or IPs matching this pattern will bypass the proxy |
| geoip.update.verifysslcert | <true or false> - default true Set to false if you want to disable SSL server certificate validation. |
| geoip.update.verifysslhostname | <true or false> - default true Set to false if you want to disable SSL server hostname validation - e.g. if you use an IP address instead of a hostname to contact the server. |
| geoip.update.intervalhours | <Number of hours> - default is 24 Specify the interval in hours of which the updater will check if a newer version of the database is available, and download it if it is. |
threadpool.maxthreads | <number of threads> - default is 128 Changes the size of PP’s threadpool – default is 128 threads. The threadpool count can also be changed with the system property pp.threadpool.maxthreads. |
useOldStyleSessionID | <true | false> - default is false Set to true to use the old style session ID – the old type is a request ID of 60 digits, where the first 40 is the session ID, and the last 20 the transaction ID. It was replaced in 2014 with a new dynamic length format that allows it to contain more details like IPv6 addresses, source TCP port number etc. But it requires Portalprotect v5.19 or newer agents for all applications. If you for any reason cannot upgrade all agents, you will need to set this to true in order for the older agents to work. |
| logsuppression | <Pattern>
|
© Ceptor ApS. All Rights Reserved.