We Have Moved
The IBM Application Gateway has a new home - docs.verify.ibm.com/gateway
The documentation on this site will no longer be maintained after v21.02, please update your bookmarks.
Session
Description
Specifies the configuration for client sessions.
Properties
The following table(s) describe the configuration properties for this component:
Name | Type | Constraints | Description |
---|---|---|---|
max_sessions | number | Minimum:1 Maximum:unlimited Default:4096 |
The maximum number of concurrent sessions. |
timeout | number | Minimum:0 Maximum:unlimited Default:3600 |
The maximum lifetime (in seconds) for a session. If set to 0 the sessions will not have a maximum lifetime, however once max_sessions is reached sessions will be reaped using a least recently used algorithm. |
permit_user_switching | boolean | Values: true,false Default:false |
During an obligated re-authentication, depending on the policy and identity provider a different user credential may be returned to the application gateway. By default, the application gateway will not accept a credential if the user name does not match the user which the session was originally established for. Use this entry to change the behaviour and allow the application gateway to accept a credential containing a different user name during re-authentication. |
cookie_name | string | Default:PD-S-SESSION-ID | The name of the session cookie presented to clients. |
redis | REDIS Object | ||
inactive_timeout | number | Minimum:0 Maximum:unlimited Default:600 |
The maximum lifetime (in seconds) a session can remain inactive before it is expired. If set to 0 the sessions will not have a maximum inactive lifetime. |
REDIS Object
Specifies the configuration for distributed sessions using a Redis environment.
Name | Type | Constraints | Description |
---|---|---|---|
default_collection | string | The name of the default collection of Redis servers to be used. |
|
key_prefix | string | The key prefix for all data which is stored on the Redis server. |
|
collections | array[COLLECTIONS Object] | ||
client_list_cache_lifetime | number | Minimum:0 Maximum:unlimited Default:10 |
The server needs to manually delete stale entries from the Redis cache during session creation and idle timeout events. In order to be able to delete the stale entries it needs an up-to-date list of active clients of the Redis server (using the 'CLIENT LIST' Redis command). This command, depending on the number of clients which are registered with the Redis server, can be expensive and so IAG will cache and reuse the returned list of clients for a small period of time. This configuration entry controls the length of time, in seconds, that a client list will be cached. |
concurrent_sessions | CONCURRENT_SESSIONS Object |
COLLECTIONS Object
Used to define the configuration for a collection of replicated Redis servers.
Name | Type | Constraints | Description |
---|---|---|---|
health_check_interval | number | Minimum:1 Maximum:unlimited Default:10 |
The interval (in seconds) between health check requests sent to the Redis server. |
name | string | The name of the redis collection. |
|
cross_domain_support | CROSS_DOMAIN_SUPPORT Object | ||
servers | array[SERVERS Object] | ||
idle_timeout | number | Minimum:0 Maximum:unlimited Default:10 |
The maximum number of seconds a pooled connection can remain idle before the connection is closed. |
io_timeout | number | Minimum:0 Maximum:unlimited Default:30 |
The maximum number of seconds to wait for a valid response from a Redis server. |
matching_host | string | Any specific hosts (obtained from the Host header of the HTTP request) for which this collection should be used. |
|
max_pooled_connections | number | Minimum:0 Maximum:unlimited Default:50 |
The maximum number of pooled connections to a Redis server. |
connect_timeout | number | Minimum:0 Maximum:unlimited Default:2 |
The maximum number of seconds to wait for a connection to be established with a Redis server. |
CROSS_DOMAIN_SUPPORT Object
Specifies the configuration information associated with the sharing of sessions across multiple DNS domains.
Name | Type | Constraints | Description |
---|---|---|---|
master_session_code_lifetime | number | Minimum:1 Maximum:unlimited Default:30 |
The maximum number of seconds that a session code, used when communicating the session information from the master authentication server, will remain valid. |
master_authn_server_url | string | The base URL of the master authentication server for this collection of Redis servers. The master authentication server, if specified, will be responsible for the generation of all new sessions for this collection. The entry should be of the format: http{s}://server{:port}. |
SERVERS Object
Used to define the configuration for the individual Redis servers within the collection.
Name | Type | Constraints | Description |
---|---|---|---|
username | string | The name of the user which is used when authenticating to the Redis server. |
|
ssl | SSL Object | ||
host | string | The server name or IP address of the Redis server. |
|
name | string | A label, or name, which is used to identify this server. |
|
password | string | The password which is used to access the Redis server. |
|
port | number | Minimum:1 Maximum:unlimited Default:6379 |
The port on which the Redis server is listening for requests. |
SSL Object
The SSL information associated with the Redis server.
Name | Type | Constraints | Description |
---|---|---|---|
trust_certificates | array[string] | The PEM based certificates which are to be trusted when communicating with the Redis server. The trusted certificates should include the CA certificate for the Redis server certificate, as well as any intermediate certificates used to sign the client certificate (if mutual authentication is in use). SSL/TLS will not be used when communicating with the Redis server if no trust certificates are specified. |
|
sni | string | The Server Name Indication (SNI) value which is provided when establishing the SSL connection with the Redis server. |
|
client_certificate | array[string] | The PEM based personal certificate files which will be used when performing mutual authentication with the resource server. These certificate files should include the private key, a certificate signed with the private key, and the signer certificate or signer certificate chain (if required). |
CONCURRENT_SESSIONS Object
Specifies the configuration information associated with the tracking and management of concurrent user sessions.
Name | Type | Constraints | Description |
---|---|---|---|
prompt_for_displacement | boolean | Values: true,false Default:true |
If enabled the gateway will prompt users before automatically displacing existing sessions with the same user identity. If disabled the gateway will automatically log out the existing user session. |
enabled | boolean | Values: true,false Default:true |
Is concurrent user session tracking and management enabled? |
max_user_sessions | number | Minimum:-1 Maximum:unlimited Default:0 |
The maximum number of concurrent sessions which are allowed for a single user. A value of '0' indicates that an unlimited number of sessions are allowed, and a value of '-1' indicates that only a single session is allowed for the user and that any existing sessions will be displaced by the new session. The maximum number of user sessions for a particular session can also be defined using the "tagvalue_max_concurrent_web_sessions" attribute of the credential. |
user_identity_attribute_name | string | Default:AZN_CRED_PRINCIPAL_NAME | The name of the credential attribute which holds the unique user identity for the session. If the configured attribute does not exist in the credential the default user identity of 'unknown' will be used. |
Example
server:
session:
cookie_name: sess_cookie
max_sessions: 20
timeout: 600
inactive_timeout: 100
redis:
key_prefix: "iag-"
default_collection: test-collection
client_list_cache_lifetime: 10
concurrent_sessions:
enabled: true
prompt_for_displacement: true
max_user_sessions: 15
user_identity_attribute_name: AZN_CRED_PRINCIPAL_NAME
collections:
- name: "test-collection"
matching_host: "www.webseal.ibm.com"
max_pooled_connections: 50
idle_timeout: 10
connect_timeout: 2
io_timeout: 30
health_check_interval: 15
cross_domain_support:
master_authn_server_url: "https://mas.ibm.com"
master_session_code_lifetime: 30
servers:
- name: "redis-a"
host: "redis-a.ibm.com"
port: 6379
username: "testuser"
password: "passw0rd"
ssl:
trust_certificates:
- "@redis-ca.crt"
client_certificate:
- "@cert.crt"
- "@cert.key"
sni: "redis-a.ibm.com"