Authentication prompt scenarios

Various scenarios prompt users to authenticate with Secure Hub by entering their credentials on their devices.

The scenarios change depending on these factors:

  • Your MDX app policy and Client Property configuration in the Endpoint Management console settings.
  • Whether the authentication occurs offline or online (the device needs a network connection to Endpoint Management).

In addition, the kind of credentials that users enter, such as the Active Directory password, Citrix PIN or passcode, one-time password, fingerprint authentication (known as Touch ID in iOS), which also change based on the type of authentication and the frequency of authentication.

Let’s start with the scenarios that result in an authentication prompt.

  • Device restart: When users restart their device, they must reauthenticate with Secure Hub.

  • Offline inactivity (time-out): With the App Passcode MDX policy enabled (by default), the Endpoint Management client property called Inactivity Timer comes into play. The Inactivity Timer limits the length of time that can pass without user activity in any of the apps that use the secure container.

When the Inactivity Timer expires, users must reauthenticate to the secure container on the device. For example, when users set down their devices and walk away, and the Inactivity Timer has expired, someone else can’t pick up the device and access sensitive data within the container. You set the Inactivity Timer client property in the Endpoint Management console. The default is 15 minutes. The combination of the App Passcode set to ON and the Inactivity Timer client property is responsible for probably the most common of the authentication prompt scenarios.

  • Signing off from Secure Hub:. When users sign off from Secure Hub, they have to reauthenticate the next time they access Secure Hub or any MDX app, when the app requires a passcode as determined by the App Passcode MDX policy and the Inactivity Timer status.

  • Maximum offline period:. This scenario is specific to individual apps because it is driven by a per-app MDX policy. The Maximum offline period MDX policy has a default setting of 3 days. If the time period for an app to run without online authentication with Secure Hub elapses, a check-in with Endpoint Management is required to confirm app entitlement and to refresh policies. When this check-in occurs, the app triggers Secure Hub for an online authentication. Users must reauthenticate before they can access the MDX app.

Note the relationship between the Maximum offline period and the Active poll period MDX policy:

  • The Active poll period is the interval during which apps check in with Endpoint Management for performing security actions, such as app lock and app wipe. In addition, the app also checks for updated app policies.
  • After a successful check for policies via the Active poll period policy, the Maximum offline period timer is reset and begins counting down again.

Both check-ins with Endpoint Management, for Active poll period and Maximum offline period expiry, require a valid Citrix Gateway token on the device. If the device has a valid Citrix Gateway token, the app retrieves new policies from Endpoint Management without any interruption to users. If the app needs a Citrix Gateway token, a flip to Secure Hub occurs, and users see an authentication prompt in Secure Hub.

On Android devices, the Secure Hub activity screens open directly on top of the current app screen. On iOS devices, however, Secure Hub must come to the foreground, which temporarily displaces the current app.

After users enter their credentials, Secure Hub flips back to the original app. If, in this case, you allow for cached Active Directory credentials or you have a client certificate configured, users can enter a PIN, password, or fingerprint authentication. If you do not, users must enter their complete Active Directory credentials.

The Citrix ADC token may become invalid due to Citrix Gateway session inactivity or a forced session time-out policy, as discussed in the following list of Citrix Gateway policies. When users sign on to Secure Hub again, they can continue running the app.

  • Citrix Gateway session policies: Two Citrix Gateway policies also affect when users are prompted to authenticate. In these cases, they authenticate to create an online session with Citrix ADC for connecting to Endpoint Management.

    • Session time-out: The Citrix ADC session for Endpoint Management is disconnected if no network activity occurs for the set period. The default is 30 minutes. If you use the Citrix Gateway wizard to configure the policy, however, the default is 1440 minutes. Users see an authentication prompt to reconnect to their corporate network.
    • Forced time-out: If On, the Citrix ADC session for Endpoint Management is disconnected after the forced time-out period elapses. The forced time-out makes reauthentication mandatory after a set period. Users will then see an authentication prompt to reconnect to their corporate network upon the next use. The default is Off. If you use the Citrix Gateway wizard to configure the policy, however, the default is 1440 minutes.

Credential types

The preceding section discussed when users are prompted to authenticate. This section discusses the kinds of credentials they must enter. Authentication is necessary through various authentication methods to gain access to encrypted data on the device. To initially unlock the device, you unlock the primary container. After this occurs and the container is secured again, to gain access again, you unlock a secondary container.


The term managed app refers to an app wrapped by the MDX Toolkit, in which you’ve left the App Passcode MDX policy enabled by default and are using the Inactivity Timer client property.

The circumstances that determine the credential types are as follows:

  • Primary container unlock: An Active Directory password, Citrix PIN or passcode, one-time password, Touch ID or fingerprint ID are required to unlock the primary container.
    • On iOS, when users open Secure Hub or a managed app for the first time after the app is installed on the device.
    • On iOS, when users restart a device and then open Secure Hub.
    • On Android, when users open a managed app if Secure Hub is not running.
    • On Android, when users restart Secure Hub for any reason, including a device restart.
  • Secondary container unlock: Fingerprint authentication (if configured), a Citrix PIN or passcode, or Active Directory credentials, to unlock the secondary container.
    • When users open a managed app after the inactivity timer expires.
    • When users sign off from Secure Hub and then open a managed app.

Active Directory credentials are required for either container unlock circumstance when the following conditions are true:

  • When users change the passcode associated with their corporate account.
  • When you have not set the client properties in the Endpoint Management console to enable the Citrix PIN: ENABLE_PASSCODE_AUTH and ENABLE_PASSWORD_CACHING.
  • When the NetScaler Gateway session ends, which occurs in the following circumstances: when the session time-out or forced time-out policy timer expires, if the device does not cache the credentials or does not have a client certificate.

When fingerprint authentication is enabled, users can sign on by using a fingerprint when offline authentication is required because of app inactivity. Users still have to enter a PIN when signing on to Secure Hub for the first time and when restarting the device. For information about enabling fingerprint authentication, see Fingerprint or touch ID authentication.

The following flowchart summarizes the decision flow that determines which credentials a user must enter when prompted to authenticate.

Image of user credentials flowchart

About Secure Hub screen flips

Another situation to note is when a flip from an app to Secure Hub and then back to an app is required. The flip displays a notification that users must acknowledge. Authentication is not required when this occurs. The situation occurs after a check-in happens with Endpoint Management, as specified by the Maximum offline period and Active poll period MDX policies, and Endpoint Management detects updated policies that need to be pushed to the device through Secure Hub.

Authentication prompt scenarios