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: For iOS, use the Apple identifier: https://www.theiphonewiki.com/wiki/Models For Android, use a string of one of these forms (see https://developer.android.com/reference/android/os/Build.html) If "Build.RADIO" is present: `<Build.MANUFACTURER> <Build.MODEL> - <Build.PRODUCT> - <Build.RADIO>` If "Build.RADIO" is not present: `<Build.MANUFACTURER> <Build.MODEL> - <Build.PRODUCT>`
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.

BASH

% 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:

BASH

% 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:

BASH

% 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.

BASH

% 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

BASH

% 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

JS

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.

BASH

% 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

JS

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

BASH

% 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

JS

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.

BASH

% 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

JS

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

BASH

% 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

JS

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

BASH

% 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:

JS

"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."
...
    }
  }
}

Defining policy rules for client events

Dynamic policy rules

Triggers

Conditions

Actions

Defining and enabling the policy rules profile

Examples

On this page

Related topics