Defining policy rules for client events
Dynamic policy rules are defined and updated in configuration profiles on the gateway, but they are evaluated within the secured app. Configuration profiles (managed on the gateway) can dynamically modify the policies that were applied when the app was secured (via the policy console). The rules in these profiles apply when certain events happen on the device. This section describes the syntax and behavior of dynamic policy rules and provides several examples.
Dynamic policy rules
Dynamic policy rules include these components. Each component definition must include an index number (see examples below):
- Triggers: Events that determine when the rule is evaluated.
- Conditions: Conditions that are evaluated when the rule is triggered.
- Actions: Actions to take when a triggered rule's conditions are all true.
When a secured app connects to the gateway, it downloads policy rules from the gateway and caches them in the client. When you change a rule (for example, to change the contents of a message), you need to consider any triggers that execute before the connection to the gateway is established—in such a case, the user sees the content of the original message.
Given this need to fully connect to the gateway to update rules, please be careful with terminal messages that cause the app to exit before connecting to the gateway. If a terminal rule is specified in error, it can lock out an app.
Triggers
These events are available to trigger a rule evaluation:
Trigger | Notes |
---|---|
app-start | Evaluates at app startup or when the rules are dynamically updated by connecting to an gateway. |
foreground | Evaluates when the app is brought to the foreground. |
background | Evaluates when the app is brought to the background. |
vnet-up | Virtual networking is available, that is, all connectivity policies (Secure Microtunnel, Secure Web Stack, OS network monitoring) are able to pass traffic. |
vnet-down | Virtual networking is unavailable, that is, one or more connectivity policies report inability to pass traffic. |
Conditions
There are three types of conditions. Each individual condition must choose between one of these types, but complex conditions can be formed by adding more than one condition to a rule. When multiple conditions are present, all conditions must match before the action is taken.
Condition type | Notes |
---|---|
always | This condition always evaluates to true. Rules with no conditions are treated as though they have an implicit "always" condition. |
attribute | Matches an attribute (see table below) with an operator. Regular expression (POSIX-extended format) matches and simple string equality matches are supported. |
when | Matches only when the rule is evaluated within the specified time window. "When" conditions can have a "utcStartDate" and "utcEndDate" attribute. If a start date with no end date is specified, all dates after the start date match. If an end date with no start date is specified, all dates before that date match . Times must be specified in ISO_8601 format, with the UTC trailing "Z" required. |
Available attributes:
Attribute | Values | Notes |
---|---|---|
app-name | string | User visible name of the app. |
app-package-id | string | CFBundleIdentifier / Android package identifier. |
app-version | string | Platform-specific version identifier for the app. |
client-interactive | true / false | Indicates whether the client was in an interactive (foregrounded) state when policy rule evaluation was triggered. |
hardware | string | Description of the device hardware. For example, "iPhone6,2". Values:
|
injectable-version | string | Version of the Blue Cedar injectable, for example, "3.20.0". |
language-tag | string | Two letter ISO-standard language identifier. For example, "en" for English. |
model | string | Generic model identifier of the device. |
os-type | Android / iOS | Operating system platform. |
os-version | string | Version of the operating system |
region-tag | string | Two letter ISO-standard region identifier. For example, "US" for United States English. |
security-patch-version | string | Version of the security patch. Only available on Android, and typically structured as a date, for example "2018-01-05". |
Actions
Once triggers and conditions are true, rules produce actions:
Action | Notes |
---|---|
show-message | Shows a dialog with an OK button. Takes a message. Optionally takes a link URL and link text. Messages can take two message types: message-type informational: (Default) User is notified through a dialog which can only be dismissed. Suitable for notifications of system downtime. message-type terminal: Users must confirm the notification and the app terminates. |
show-notification | Shows a notification using OS-specific APIs. An optional link opens when the user presses the notification. |
show-reminder | Shows a reminder with dismiss and snooze buttons. You can configure the snooze interval, text, and an optional URL. |
Link attributes:
You may specify links for any of the above actions. Links have three attributes:
Attribute | Notes |
---|---|
url | The URL for the link. If a URL is specified without raw-text or user-text key, the UI shows the URL itself. |
raw-text | Custom text to be displayed. |
user-text-key | Display the user message associated with the provided key. Use this attribute to translate or localize the text to be displayed. User messages are controlled and can be localized through the App Customization policy's custom translation strings. You can use built-in ATLAS_* strings or create custom strings with the CUSTOM_ prefix. See the example below and see the policy console documentation for more information. Note that the text is stored in the policy console translation file and secured with the static policy, therefore it cannot be modified dynamically. The dynamic rule can access the pre-defined text. |
On iOS, links open in the system browser to facilitate the installation of files via web-based app stores.
On Android, the current app cannot open the link, because the policy rules block the app logic while the rules are being resolved. Thus, if the app is Compass on Android, Compass does not appear in the list of apps available to open links.
Defining and enabling the policy rules profile
To add policy rules to a configuration profile, use this template. "Options" includes triggers, conditions, and actions.
To simplify your CLI entries, you can use multiple CLI commands to define a rule in several steps, and you can use the edit command to change the level of the command hierarchy. (See Using the CLI configuration editor.)
To input regular expressions that contain special characters, omit the value for the expression from the set command. You will see a message that says "Enter a regular expression: Enter Ctl-D to complete." Enter your regular expression, then press Ctl-D (without hitting enter) to exit multi-line input mode and submit the value.
See the examples below.
% set aaa config-profile profile-name policy-rules rules rule-number options...
To show the policy rules set for a configuration profile, use the show command:
% show aaa config-profile PolicyRulesProfile policy-rules
Once you have defined a policy rules profile, you can enable the rules for users with this command:
% set aaa post-auth-policy-match-rule 1000 action install-config-profile PolicyRulesProfile
% commit
Note that the 1000 in this example is a relative priority. If higher priority (lower number) rules match, this rule is not executed. See Defining post-authentication policy match rules for more about priority.
To change the type for a condition or action (for example, to switch an attribute condition to a when condition, or a show-message action to a show-notification action), you need to delete the previous condition or action container, otherwise the gateway rejects the new commit with a validation failure.
% show aaa config-profile PolicyRulesProfile
[...]
actions 10 {
show-message {
message-type terminal;
raw-message "This app is not supported on this device.";
}
}
}
% delete aaa config-profile PolicyRulesProfile rules 1 actions 10
% commit
Examples
Example 1: Terminal message based on unsupported operating system
This rule checks if the operating system version is Android 19 or 20 (KitKat). If so, it shows the terminal message "Your operating system has reached end of life for support. This app is not supported on this device."
Example: show terminal message
% edit aaa config-profile PolicyRulesProfile policy-rules rules 1
1 % set triggers 10 event app-start
1 % set conditions 10 attribute name os-version operator regex-match value
Enter a regular expression: Enter Ctl-D to complete.
19|20
1 % set conditions 11 attribute name os-type operator equals value android
1 % set actions 10 show-message message-type terminal raw-message "Your operating system has reached end of life for support. This app is not supported on this device."
1 % commit
Show rule
1 % show
rules 1 {
triggers 10 {
event app-start;
}
conditions 10 {
attribute {
name os-version;
operator regex-match;
value 19|20;
}
}
conditions 11 {
attribute {
name os-type;
operator equals;
value android;
}
}
actions 10 {
show-message {
message-type terminal;
raw-message "Your operating system has reached end of life for support. This app is not supported on this device.";
}
}
}
Example 2: Reminder to upgrade app with a link
This rule checks if the app version is earlier than 5.9 by matching 0.0[...]–5.8[...]. If so, it shows a custom message saying "Your app is out of date, and version 5.9 is available," followed by "Install now" with a link to a server.
% edit aaa config-profile PolicyRulesProfile policy-rules rules 2
2 % set triggers 20 event app-start
2 % set conditions 20 attribute name app-version operator regex-match value
Enter a regular expression: Enter Ctl-D to complete.
^[0-4]\..+|5\.[0-8].*
2 % set actions 20 show-reminder raw-message "Your app is out of date, and version 5.9 is available."
2 % set actions 20 show-reminder link url "http://appstore.qwe.com" raw-text "Install now."
2 % commit
Show rule
2 % show
rules 2 {
triggers 20 {
event app-start;
}
conditions 20 {
attribute {
name app-version;
operator regex-match;
value ^[0-4]\..+|5\.[0-8].*;
}
}
actions 20 {
show-reminder {
raw-message "Your app is out of date, and version 5.9 is available.";
link {
url http://appstore.qwe.com;
raw-text "Install now.";
}
}
}
}
Example 3: Notification about app unavailability
This rule displays a system notification saying, "This app will be unavailable during the winter shutdown period." This notification displays from Dec 24–Jan 1.
Example: show notification during shutdown
% edit aaa config-profile PolicyRulesProfile policy-rules rules 5
5 % set triggers 5 event app-start
5 % set conditions 3 when utc-start-date 2018-12-24T00:00:00Z utc-end-date 2019-01-01T23:59:00Z
5 % set actions 1 show-notification raw-message "This app will be unavailable during the winter shutdown period."
5 % commit
Show rule
5 % show
rules 5 {
actions 1 {
show-notification {
raw-message "This app will be unavailable during the winter shutdown period.";
}
}
triggers 5 {
event app-start;
}
conditions 3 {
when {
utc-start-date 2018-12-24T00:00:00Z;
utc-end-date 2019-01-01T23:59:00Z;
}
}
}
Example 4: Reminder about app deprecation
This rule shows a custom message saying, "This app will no longer be supported after Jan-1-2019. Please contact your manager to migrate." with the option to dismiss the message for a day at a time.
% edit aaa config-profile PolicyRulesProfile policy-rules rules 8
8 % set triggers 3 event app-start
8 % set conditions 4 when utc-end-date 2019-01-01T00:00:00Z
8 % set actions 1 show-reminder raw-message "This app will no longer be supported after Jan-1-2019. Please contact your manager to migrate." snooze-interval-sec 86400
8 % commit
Show rule
8 % show
rules 8 {
triggers 3 {
event app-start;
}
conditions 4 {
when {
utc-end-date 2019-01-01T00:00:00Z;
}
}
actions 1 {
show-reminder {
raw-message "This app will no longer be supported after Jan-1-2019. Please contact your manager to migrate.";
snooze-interval-sec 86400;
}
}
}
Example 5: Message about beta version with link to report bugs
This rule always shows a message with a link when the app is launched interactively. (It does not block background interactions, like emails.) The message says, "This app is an internal beta: report bugs at this link" followed by the link with clickable text. Note that it takes two set commands to define the message and the link
% edit aaa config-profile PolicyRulesProfile policy-rules rules 10
10 % set triggers 1 event app-start
10 % set conditions 1 attribute name client-interactive operator equals value true
10 % set actions 1 show-message raw-message "This app is an internal beta: report bugs at this link"
10 % set actions 1 show-message link url "https://beta.qwe.com" raw-text "QWE Beta"
10 % commit
Show rule
10 % show
rules 10 {
triggers 1 {
event app-start;
}
conditions 1 {
attribute {
name client-interactive;
operator equals;
value true;
}
}
actions 1 {
show-message {
raw-message "This app is an internal beta: report bugs at this link:";
link {
url https://beta.qwe.com;
raw-text "QWE Beta";
}
message-type informational;
}
}
}
Example 6: Same as example 1, using custom translation strings
This rule checks if the operating system version is Android 19 or 20 (KitKat). If so, it shows the terminal message CUSTOM_MESSAGE_UNSUPPORTED_OS, "Your operating system has reached end of life for support. This app is not supported on this device."
Example: show terminal message
% edit aaa config-profile PolicyRulesProfile policy-rules rules 1
1 % set triggers 1 event app-start
1 % set conditions 1 attribute name os-version operator regex-match value
Enter a regular expression: Enter Ctl-D to complete.
19|20
1 % set conditions 2 attribute name os-type operator equals value android
1 % set actions 1 show-message message-type terminal user-message-key CUSTOM_MESSAGE_UNSUPPORTED_OS
1 % commit
To specify the value of CUSTOM_MESSAGE_UNSUPPORTED_OS and localize the text, use the policy console's App Customization policy. To use this custom key, add it with appropriately translated lines to the user strings file in the App Customization policy. See Custom translation strings in the policy console documentation for details:
"translations": [
{
"language": "en",
"region": "US",
"strings": {
"CUSTOM_MESSAGE_UNSUPPORTED_OS" : "Your operating system has reached end of life for support. This app is not supported on this device."
...
}
{
"language" : "es",
"region" : "US",
"strings" : {
"CUSTOM_MESSAGE_UNSUPPORTED_OS" : "Su sistema operativo ha llegado a su fin de soporte. Esta aplicación no es compatible con este dispositivo."
...
}
}
}