Defining post-authentication policy match rules

You can define post-authentication policy rules to perform a limited set of actions based on session attributes (such as allow or deny the session or specify a configuration profile to be installed by the connecting client). Define these rules on the gateway to apply a set of dynamic rules to an incoming connection to the gateway.

These rules are applied after the connecting client has completed authentication, meaning that the gateway has confirmed the user's identity using the appropriate authentication providers. Also, if supported by the authentication provider, the gateway can retrieve attributes about that user (such as email address, UPN, or custom attributes). The authentication process can also gather other client attributes such as device and operating system information.

The administrator can use these attributes to create rules that are applied before the incoming connection is considered fully validated and allowed to pass traffic. These rules can be used to perform actions such as denying connection or sending a configuration profile to a client.

% show aaa post-auth-policy-match-rule 
post-auth-policy-match-rule 999 {
 action {
  install-config-profile engineerProfile;
 }
 auth-provider-group-match-regex ^engineers$
}
          
post-auth-policy-match-rule 1000 {
  action {
   install-config-profile salesProfile;
  }
  auth-provider-group-match-regex ^sales$
}

Configuring post-authentication policy match rules

Post-authentication policy match rules have three primary components:

• Priority: specifies the order the rules are applied in
• Match attributes: determine when the rule should be applied
• Actions: performed when a rule is matched

Priority

When creating a post-auth policy match rule, add it to an ordered list of match rules. Rules are processed in order of their specified priority, lowest first, until a rule matches. Once a rule matches, any associated actions are performed and rule processing is concluded. This allows you to create firewall ACL-style rules that perform a specified set of actions if no other rules are matched, useful for, for example, denying connections that don't meet an explicitly white-listed set of criteria.

% set aaa post-auth-policy-match-rule 1000 action access-control access deny

Because rules are applied in order, it is common for an administrator to need to add a rule between two existing rules at some point in the future. While the priority of a rule can be changed with the 'rename' command, it can be cumbersome to rename several consecutive rules to add a new rule between them. We recommend leaving enough distance between rule priorities to allow easily adding new rules in the future.

Match attributes

A rule with no match criteria is considered to always be true.

Pre-defined session attributes:

For any pre-defined tunnel session attributes collected by the gateway, there is a corresponding regular expression match that can be added to a rule to determine whether that rule should be applied. Multiple match regexes are combined, meaning that all configured match regexes must match an incoming connection for a rule to be applied to it. 

The gateway CLI uses POSIX Extended Regular Expression syntax. See https://en.wikipedia.org/wiki/Regular_expression#POSIX_extended for more information. To visualize a regular expression, this site may be helpful:

https://regexper.com/#%5E3%5C.2%5B0-9%5D%7C%5E3%5C.%5B3-9%5D%5B0-9%5D%7C%5E%5B4-9%5D%5C.%7C%5E%5B1-9%5D%5B0-9%5D%5C.

The following is the list of tunnel session attributes that can configured with pre-defined matches:

Custom attributes:

In addition to pre-defined attributes, custom attributes may also be matched. Custom attributes can be collected from some authentication providers, such as LDAP:

% set aaa auth-provider ldap myldap custom-attr MY_CUSTOM_ATTR basic value givenName
% set aaa post-auth-policy-match-rule 800 custom-attr-match MY_CUSTOM_ATTR regex "my_value"

Entering regular expressions

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.

The following is a simple example that checks whether an android device's version is less than 8.0:

% set aaa post-auth-policy-match-rule 900 os-type-match-regex "android"
% set aaa post-auth-policy-match-rule 900 os-version-match-regex
Enter a regular expression: Enter Ctl-D to complete.
^[0-7]\.

Attribute substitution

When creating attribute matches, you can also reference other attributes. For example, you can create a rule specifying that a connection should be denied if a username provided for two-factor authentication does not match the username extracted from a presented client certificate. This can be done by substituting the value of the username extracted from the certificate into a match that compares the username presented for authentication:

% set aaa post-auth-policy-match-rule 800 username-match-regex
Enter a regular expression: Enter Ctl-D to complete.
"^%USERNAME_FROM_CERT%$"

These pre-defined attributes are available for substitution using the syntax %ATTRIBUTE%:

• %USERNAME%
• %DEVICE_ID%
• %FEDERATION_ID%
• %APPLICATION_ID%
• %AUTH_PROVIDER_GROUP%
• %USERNAME_FROM_CERT%
• %DEVICE_ID_FROM_CERT%
• %FEDERATION_ID_FROM_CERT%
• %AUTH_GROUP%
• %EMAIL%
• %UPN%
• %LOCALE%
• %INJECTABLE_VERSION%
• %ANDROID_SECURITY_PATCH_VERSION%
• %APP_VERSION%
• %OS_VERSION%

Custom attributes are also available for attribute substitution, as in %MY_CUSTOM_ATTR%.

Actions

Each rule specifies an action to be triggered by the highest priority rule that has had all its match criteria satisfied. This action is applied before an incoming connection is considered fully validated and allowed to pass traffic. These actions are available:

• install-config-profile: Allow the gateway to send a dynamic configuration profile to the connecting client.
• access-control: Specify whether a connection should be allowed or denied

Install config profile

Install config profile rules allow the gateway to specify a dynamic config profile to be sent to the connecting client for installation. This allows the configuration of the connecting client to be changed dynamically without requiring the app to be re-secured. For more on dynamic configuration profiles, including how to create one and which attributes can be controlled dynamically, see Using dynamic configuration profiles.

% set aaa post-auth-policy-match-rule 1000 action install-config-profile MyConfigProfile

This action is also used to enable policy rules for client events. See Defining policy rules for client events.

Access control

Access control rules specify whether a connection should be allowed or denied. An administrator can also specify a rejection message to be presented to the user when the connection is rejected due to post-auth policy.

This example rejects an incoming connection if the injectable version is 3.17:

% set aaa post-auth-policy-match-rule 1000 injectable-version-match-regex
Enter a regular expression: Enter Ctl-D to complete.
"^3\.17"
% set aaa post-auth-policy-match-rule 1000 action access-control access deny
% commit

The following example accepts an incoming connection only if the OS version is iOS, at least 11.2.5, or if the operating system is Android and its security patch version is at least 2018-01-05, and the injectable version is at least 3.20. Any connections that don't meet these specific criteria will be denied and a message is presented to the user. The message will be localized by the client, if a translation entry with the value "MY_CUSTOM_REJECT_KEY" has been added via the policy console app customization policy:

% edit aaa post-auth-policy-match-rule 900
bcvac:900 % set os-type-match-regex "android"
bcvac:900 % set os-security-patch-match-regex
Enter a regular expression: Enter Ctl-D to complete.
^2018-01-0[5-9]|^2018-01-[1-3][0-9]|^2018-0[2-9]-[0-9][0-9]|^2018-[1-9][0-9]-[0-9][0-9]|^2019-[0-9][0-9]-[0-9][0-9]|^202[0-9]-[0-9][0-9]-[0-9][0-9]
bcvac:900 % set injectable-version-match-regex
Enter a regular expression: Enter Ctl-D to complete.
^3\.2[0-9]\.[0-9]+|^3\.[3-9][0-9]\.[0-9]+|^[4-9]\.[0-9]+\.[0-9]|^[0-9][0-9]\.[0-9]+\.[0-9]+
bcvac:900 % set action access-control access allow
bcvac:900 % up
Use the 'context' command to return to default configuration scope.
bcvac:post-auth-policy-match-rule % edit 950
bcvac:950 % set os-type-match-regex "ios"
bcvac:950 % set os-version-match-regex
Enter a regular expression: Enter Ctl-D to complete.
^11\.2\.[2-9]|^11\.2\.[1-9][0-9]+|^11\.[3-9]\.[0-9]+|^11\.[1-9][0-9]+\.[0-9]+|^1[2-9]\.[0-9]+\.[0-9]+
bcvac:950 % set injectable-version-match-regex
Enter a regular expression: Enter Ctl-D to complete.
^3\.2[0-9]\.[0-9]+|^3\.[3-9][0-9]\.[0-9]+|^[4-9]\.[0-9]+\.[0-9]|^[0-9][0-9]\.[0-9]+\.[0-9]+
bcvac:950 % set action access-control access allow
bcvac:900 % up
Use the 'context' command to return to default configuration scope.
bcvac:post-auth-policy-match-rule % set 1000 action access-control access deny reject-raw-message "Connection denied due to policy. Please ensure you are running an up-to-date operating system, and connecting with the latest version of your Blue Cedar app." reject-user-message-key MY_CUSTOM_REJECT_MESSAGE_KEY
bcvac:post-auth-policy-match-rule % commit

As with many things in security, it is generally better to write rules that explicitly allow access for known quantities, and implicitly deny anything else.