Use the Conditions UI to create and change user interactions.
When a Gateways evaluates the access criteria using any of the modes covered earlier and the result is false; in this situation a user interaction may be initiated and sent to the Client.
What is a user interaction?
A user interaction is an optional setting that can be used to mitigate the situation where the user could be left unable to connect. If the user provides new input, then this sets a new user response claim in the system. This triggers a re-evaluation of the access criteria and if configured appropriately should now evaluate to true (because of this new user response claim), thus allowing the user to connect.
It is therefore important that the user response claim suffix (set by the user interaction) is included in the access criteria evaluated in the expression. If you fail to do this, the system might trigger a user interaction such as password, and because the user response claim is never checked, the evaluation will continue to return false. For more information on configuring user interactions refer to: Configure conditions.
It is possible to configure multiple user interactions. Users will be asked to perform ALL or ONE of these. You can set the order in which they will appear in the Client.
The ONE option is very useful where you have a primary MFA solution (i.e. SMS OTP) and a backup for when the user is out of phone coverage. The user is then able to select the alternative user interaction method. This can also be very useful during a transition period when moving from one MFA solution to another.
The ALL option allows you to for instance enforce stronger authentication while also capturing the reason why a user requires access.
Four types of user interaction
When configuring a user interaction the user will see a message on their device which relates to the type of action required (if any). This may simply provide useful information about why access is denied, or prompt them for some input (such as a password). The message field is where this is configured and this supports the use of variables. Variables allow the use of claims to be substituted into any text that is displayed tot he user. So for instance you might set up a message that looks like: ${claims.user.firstName}, please re-enter the password for the ${claims.user.ag.identityProviderName} identity provider you used earlier.
Substituting risk scores is done using the risk rule identifier that can be found in the user claims in session details. Given that the risk rule you want to substitute has the identifier a59003de-4eea-4bc9-90f9-7a8be1acd561, an example would be:
${claims.user.ag.risk.a59003de-4eea-4bc9-90f9-7a8be1acd561.reason.message}
NOTE
It is only possible to replace integers (from 6.4.2) and strings. E.g. objects and arrays will not be substituted.
Display Message
Use this user interaction to provide helpful information - maybe why access has been blocked (when the Condition is false). Display message does not set a user response claim. Claims known by the Gateways can be used as variables in the message and can be specified using this type of syntax: ${claims.firstName}
Display Message usage
The Display Message user interaction can be used in a number of different ways:
For explanation
Because user interactions are only triggered when the access criteria equates to false, the Display Message user interaction is normally used to explain why access is being denied.
To allow access
Because access is denied; instructions for gaining access could be provided such as 'please use wired network not WiFi to get access'.
NOTE
There is also the Message of the Day feature which can be used to display messages to users. Refer to: Global Settings
Require MFA
Use this user interaction to prompt the user to enter some form of multi-factor authentication response as defined by the choice of MFA provider.
Require MFA usage
The MFA user interaction is used to prompt the user to to enter some form of multi-factor authentication for specific systems that require it. This allows users to sign-in with a lesser form of authentication and access low risk systems, then elevate their privileges when they attempt to access any high risk systems.
When the MFA user interaction is triggered by the Gateway:
The Client prompts the user to enter a valid MFA
The Controller validates the MFA using the MFA provider configured in the user interaction.
If the response is not valid, the Controller will send a message to the Client to indicate that access has not been authorized.
When a valid response has been entered, the Controller updates the user's claims token with the new user response claim. The Client sends the new token to the Gateway which re-evaluates the Entitlement's Conditions and re-configures the firewall rules.
NOTE
if MFA at sign-in is used - then by using the same user response claim suffix, the user will not be required to perform MFA twice in succession.
Provide Reason
Use this user interaction to capture additional information when a user connects to a specific service, maybe to capture the support ticket number when Helpdesk personnel connect to a service in response to an incident.
Provide Reason usage
The Provide Reason user interaction can be used in two different ways:
For audit
The <Provide reason> user interaction in the drop down list checks whether the user has typed in a reason for the claim reason.#name#. Once the user has responded to the user interaction, the claim will become true and the Condition will pass. The text entered by the user is not validated but is logged by the Gateway and can be included in log reports, such as for monitoring who is accessing particular resources and why.
For access control
The internal claim reason.#name# becomes exposed once a Condition containing the access criteria Provide Reason has been created. This means it is now possible to create Conditions based on the text entered by users in response to the Provide Reason user interaction. The new internal claim reason.#name# will be listed under device claims in the pick list. Using this claim now allows you to control access based on the text entered by the user.
For example: To confirm the ticket number that the helpdesk user is working on before provisioning access to the system in question:
Create a new Condition:
Add a new access criteria and select Provided reason
give it a claim suffix (name) of your choosing i.e. ticket
Add a user interaction of type Provide Reason
enter a message to prompt users to type in their helpdesk ticket number
enter the same claim suffix (name) i.e. ticket
Save the Condition. The new internal claim reason.ticket will now be added to the system and will be listed under device claims in the pick list.
Edit the Condition (above):
Change the access criteria logic to script returns true
Edit the expression to include the existing Provided reason AND check that the format of the new device claim reason.ticket is valid (using a regular expression).
Save the Condition
By combining these two claims in the Condition the user must enter a semi-valid ticket number (i.e. begins with TN and is followed by 6 digits) before being granted access. An enhancement is to use an external REST call to check the reason.ticket claim against an external system to verify whether the exact ticket number exists.
Password
Use this user interaction to prompt the user to (re)enter their password or to enter a second password.
Password usage
The Password user interaction can be very useful in two different ways:
To protect high value assets
Because a user might have signed-in with their password some hours ago, an extra check can be made at the time they access high value assets such as a payroll system. This can be achieved by configuring a Password user interaction using the original sign-in IdP.
NOTE
Initial user sign-in will not set the user response claim Retyped Password.
For multi-factor authentication
The Password user interaction can be configured to use a different IdP, This would require the user to know two passwords - so we have multi-factor authentication. When using this option the same username MUST be used for both IdPs as the username claim is used in this user interaction. It is important to use the message content displayed in the Client to indicate very clearly which password is required as this information is not provided otherwise.
Using User response claims as access criteria
Access criteria expressions are claims-based and define what Actions are allowed (when they evaluate to true). They are evaluated by the Gateways at connect time and at various times thereafter - so they can use static or dynamic claims that may change during the day; such as IP address, time, etc.
Conditions differ from Policy assignment in as much as the pick list includes three user response claim types: Provided MFA, Provided Reason or Retyped Password. Unlike all other claims, which have their name hard-coded or pre-configured (for instance within the identity provider), user response claims are given their name (Claim suffix) within the Condition itself when setting the User Actions. This will be the same Claim suffix that you must include in the access criteria expression.
User response claims
When a user enters their Password or uses MFA, the user response claim created includes the (claim suffix) name and a time stamp.
User response claims in Access Criteria comprise:
Type
Claim suffix (name)
Minutes (time window)
Internal claim name
Criteria check method used
The claim name that refers to this occurrence of the user interaction
Time window during which the claim shall evaluate to true
The internal user response claim generated from the given claim suffix (name)
Matching criteria check method used to evaluate if the claim is true or false
Provided MFA
i.e. general
i.e. 60
user.otp.general
claims.user.hasOtp("general", 60)
Retyped Password
i.e. finance
i.e. 60
user.password.finance
claims.user.hasPassword("finance", 60)
Provided Reason
i.e. github
n/a
device.reason.github
claims.device.hasReason("github")
The MFA and Password based Access Criteria include the temporal element (less than 60 minutes old). This prevents the Condition evaluation triggering the related user interactions (such as the retype password) with every new tcp/udp connection to the network resource that is established. This means that it might be a good idea to set a re-evaluation time, so later on the user interaction will be triggered again when the claim has expired.
You can include multiple user response claims in your access criteria, for example: if you want to ensure the user has entered their Password and used MFA you can require both Retyped password AND Provided MFA before allowing access a protected resource.
You can create user interactions of a different type that use the same user response claim suffix names. The prefixes given by the system are different - so these will be treated as two different claims.
You can create user interactions of the same type that use the same user response claim suffix names. If you have set two alternative MFA user interactions (with the same suffix name) then you only need to include this one user response claim in your access criteria - and either method will set this claim.
You can create user interactions of the same type that use different user response claim suffix names. This allows you to force the use of say MFA in two different situations which might occur only a few minutes apart.
More on user response claim naming
The use of user interaction claim suffix names allows several occurrences of say the <Provided MFA> user interaction to be created, all using the same MFA provider but behaving independently of one another.
For example, the company policy may require users to authenticate once per day (using MFA) for access to hosts A, B, and C, each with their own Entitlement. To avoid the situation where users would trigger MFA repeatedly (once with each Entitlement) a general Condition is shared across many Entitlements.
Create a new general Condition:
Add a new access criteria and select <Provided MFA>
give it a claim suffix (name) of your choosing i.e. pincode
set the time interval to 480 minutes (8 hours)
Add a new user interaction of type <Provide MFA>
enter a message to prompt users to type in their pin code
enter the same claim suffix (name) i.e. pincode
Include this Condition in all the Entitlements used to access the company's hosts A B and C.
The first time any of these Entitlements are used, the criteria hasOtp "pincode" will be false, the Condition will fail and the user interaction will be triggered. The user will see the Provide MFA message on their device with the dialogue box. Once the user has entered their MFA, the check criteria will become true and the Condition will pass.
When a user tries another Entitlement (with the same Condition), the Condition will pass and the user interaction will not be re-triggered.
Now, say the company buys a new finance system and decides on a new policy that requires users to authenticate immediately before being granted any access and hourly thereafter (using the same MFA provider). By using a specific Condition with the related user interaction tied to just the finance system, users can be forced to enter a separate MFA response even if they just did the more general one 5 minutes ago).
Create a new specific Condition:
Add a new access criteria and select <Provided MFA>
give it a claim suffix (name) of your choosing i.e. finance
set the time interval to 60 minutes (1 hour)
Add a user interaction of type <Provide MFA>
enter a message to prompt users to type in their pin code
enter the same claim suffix (name) i.e. finance
Include this Condition in the Entitlement used to access the new finance system
Modify the general Condition (created previously):
Change the access criteria logic to <any below are true>
Add a new access criteria and select <Provided MFA>
set the claim suffix (name) finance
set the time interval to 480 minutes (8 hours)
The first time a non-finance Entitlements is used, both criteria hasOtp "pincode" and hasOtp "finance"will be false, the Condition will fail and the user interaction will be triggered. The user will see the Provide MFA message and dialogue box on their device. Once the user has entered their MFA the criteria hasOtp "pincode" will become true and the Condition will pass. When the user goes on to try the new finance system Entitlement the criteria hasOtp "finance" will still be false, the Condition will fail and the user interaction will be triggered. The user will see the Provide MFA message and dialogue box on their device. Once the user has entered their MFA the criteria hasOtp "finance" will become true and the Condition will pass.
If the finance system Entitlement is used first then criteria hasOtp "finance"will be false, the Condition will fail and the user interaction will be triggered. The user will see the Provide MFA message and dialogue box on their device. Once the user has entered their MFA the criteria hasOtp "finance" will become true and the Condition will pass. When that user goes on to try a non-finance system Entitlement the internal claim hasOtp "finance"will be true, the Condition will pass (because either of the criteria hasOtp "pincode" or hasOtp "finance" can be true) and the user interaction will not be triggered.