Skip to main content
Skip table of contents

Configuring the user re-authentication settings

After a Blue Cedar-secured app successfully authenticates itself to the gateway, the app can lose its connection to the gateway. For example, the connection could be lost due to a weak wireless network or the gateway itself could terminate the connection to an app.

In order to re-establish the connection, the app must re-authenticate to the gateway. If the app's connection drops multiple times during an app session, this would result in the user experiencing a significant loss of time spent on resubmitting their credentials to the gateway.

To minimize the frequency of forcing users to re-enter their login credentials when a connection is dropped, Blue Cedar provides several mechanisms for managing the re-authentication process:

  • dormant-session-timeout: Controls the length of time a dormant federation session remains cached on the gateway. The federation session is considered dormant when all tunnel sessions are down, that is, not connected. If network-inactivity-timeout-enable is enabled, dormant-session-timeout also defines the amount of time a federation session with established tunnel session(s) can be network inactive. Network inactive is the state when tunnel sessions are still established (due to transport keep alive exchanges) but aren't passing app traffic.
  • dpd: Controls the length of the interval before the gateway and client check to see if the client-side of the connection is still active. This parameter configures Dead Peer Detection for the gateway and client, unless you set the client DPD separately.
  • client-dpd dpd-secondsControls the length of the interval before the client checks to see if the gateway-side of the connection is still active. This setting is optional—by default the client uses the same interval set with dpd, but you can use this setting to override that value for the client. 
  • max-session-duration: Controls the absolute length of time (in minutes) before a session for an app federation ("federation session") is destroyed and the user must re-authenticate to the gateway. This duration is a hard timeout from the time the federation is established, no matter how active any of the apps are. For example, assume max-session-duration is set to 8 hours. The timer starts when the first app in the federation is connected. If another app in the federation connects 7 hours and 59 minutes later, the app federation still expires one minute after that, that is, 8 hours from the initial connection.
  • A client-side mechanism is available with the Local App Authentication policy's re-authentication settings, and is configured from the Blue Cedar Platform (Enforce Accelerator). For details about this mechanism, see the Local App Authentication policy in the platform documentation.

The approach for configuring these parameters depends on the behavior of your mobile device users (such as how long app users stay connected to the gateway) and how good an app's connectivity to the network is.

Guidelines for configuring the re-authentication settings

Configuring the re-authentication parameters depends on how you want to reduce the number of credential re-submissions and optimize the gateway's performance by cleaning up inactive connections. In most cases, Blue Cedar recommends setting the value of each timeout parameter with this relationship to each other (and leaving max-session duration turned off):

client-side user inactivity timeout < dpd < dormant-session-timeout (with or without network-inactivity-timeout-enable)

These are the guidelines:

ScenarioUse this parameter...Description
If you want the user re-authentication to be based on the time of user inactivityLocal App Authentication, re-authentication settings

For information about the client-side re-authentication settings, see the platform documentation.

Note: If you want the user re-authentication to be based on the time of user inactivity, then you must set the gateway's max-session-duration to a larger value than the client-side user inactivity timeout, or do not set max-session-duration at all.

If you set the max-session-duration parameter to a smaller value than the user inactivity-timeout, the Local App Authentication policy's user inactivity-timeout would never come into play (since the max-session-duration parameter would always time out first).

If you have poor or unstable network connectivity and want to detect lost client connections.


client-dpd dpd-seconds

When the gateway detects a dead connection, it reclaims resources associated with tunnels that have not been active. Setting a lower Dead Peer Detection (DPD) value allows the gateway to handle a larger number of connections because the resources are reclaimed more frequently, but on the other hand, a lower DPD value can result in the gateway sending more network traffic to clients, which may impact the battery lifetime of mobile devices.

When the client detects a dead connection, it attempts to re-establish the gateway connection. By default, the client queries the gateway connection at the same interval setting (the value of DPD), but you can also specify a different value for the client (in seconds).

If you have poor or unstable network connectivity and want to allow users to reconnect seamlessly


The dormant-session-timeout parameter sets the time that a federation session can still remain "dormant" when no IPsec connections exist, or where there are IPsec connections but the IPsec connections are network inactive. Network inactive means the connections aren't passing app data, but do respond to DPI requests.

Dormant means the federation session still exists but all tunnel sessions in the federation are disconnected, or if there is no network activity (even if any tunnel sessions remain connected). The federation session can be activated again if any app (in the app federation) has any activity. In this case, the secured app sends a reconnect token to the gateway. Upon verification of the app's credentials, the federation session becomes active again and its IPSec connection is re-established–all this occurring without having the user re-submit their credentials. Setting a higher number for the dormant-session-timeout parameter uses more resources on the gateway but this is more convenient for end-users.

If you want to enforce a security policy in which users must authenticate periodicallymax-session-duration

The max-session-duration parameter sets an absolute time limit that a federation session (and its IPSec connections) can remain alive until the gateway destroys them. When the time limit is reached, the gateway forces the secured app to re-authenticate itself with its username/password credentials. You can ignore setting the dormant-session-timeout and dpd parameters. 

These are the templates for configuring the configuration parameters for re-authentication:

% set aaa auth-group groupname max-session-duration minutes 
% set aaa auth-group groupname dormant-session-timeout minutes 
% set aaa auth-group groupname 
% set security ike dpd minutes
% set security ike client-dpd dpd-seconds seconds

Specify the length of time before the session or connection expires in minutes or seconds, depending on the parameter.


In the following example, the three parameters are configured for an environment where there is poor network connectivity and a security requirement that each user must re-authenticate every 8 hours. This is the scenario:

  • Once the first app in an app federation launches and it successfully authenticates, the gateway starts the timer for a federation session (max-session-duration parameter setting of 480 minutes).

    After 480 minutes, the gateway tears down the connection and any IKE tunnels in that app federation, no matter if the federation session or IKE tunnel sessions are active or not. If an app is disconnected in this way, the app is not able to automatically reconnect using a reconnect token.
  • If the federation session has been connected for less than 480 minutes and if there is no activity from an app for 10 minutes (dpd parameter setting), the gateway cleans up the connection and starts the timer for the "dormant" federation session (dormant-session-timeout parameter setting of 15 minutes).
  • If an app has no network activity within this 15 minutes but is still responding to the gateway DPD requests, all references to the previously connected app federation and its apps are removed from the gateway.

To set the parameters as in this example:

% set aaa auth-group groupname max-session-duration 480 
% set aaa auth-group groupname dormant-session-timeout 15 
% set aaa auth-group groupname network-inactivity-timeout-enable true 
% set security ike dpd 10 
% commit

In this scenario, set the dpd interval to different values for gateway and client. This is useful if the client device is on an unstable network (but power/battery life isn't an issue) and you want to be able to reconnect to the gateway quickly. 

Note that the first DPD value is in minutes, and the client-dpd value is in seconds.

% set security ike dpd 10
% set security ike client-dpd dpd-seconds 30
% commit
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.