Applies To:

Show Versions Show Versions

Manual Chapter: Per-Request Policy Subroutine for Additional Authentication
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Per-Request Policy Subroutine for Additional Authentication

About per-request policy subroutines

A per-request policy subroutine is a collection of actions. What distinguishes a subroutine from other collections of actions (such as macros), is that a subroutine starts a subsession that, for its duration, controls user access to specified resources. Subroutine properties not only specify resources but also specify subsession timeout values and maximum subsession duration.

About subsessions

A subsession starts when a subroutine runs and continues until reaching the maximum lifetime specified in the subroutine properties, or until the session terminates. A subsession does not count against license limits. A subsession populates subsession variables that are available for the duration of the subsession. Subsession variables and events that occur during a subsession are logged. Multiple subsessions can exist at the same time.

About typical per-request policy subroutine uses

These are some typical uses for a per-request policy subroutine:
  • Request additional authentication from a user after a period of time or before granting access to sensitive resources.
  • Revalidate webtop resources using Active Directory credentials.
  • Certificate-based authentication (provided by On-Demand Certificate authentication) when going to a specific URI.
  • After SharePoint anonymous access, authenticate a user against Active Directory and do a group lookup.

Additional authentication subroutine example

Per-request Policy: Category Lookup and subroutine for authentication

Category Lookup reverse proxy configuration example

Category Lookup properties for reverse proxy must specify custom categories

Note: Categorization Input must not be set to Use Subject.CN in Server Cert.

Category Lookup branch configuration example

The branch rule specifies the homedir branch and the homedir custom category

Custom category configuration example

Properties for a custom category homedir

Overview: Requiring additional authentication for sensitive resources

Typically, an access policy verifies endpoint security and authenticates a user before starting an access session. If the user requests access to a sensitive resource after the session is established, you can require additional authentication or revalidation of the credentials for that resource by configuring a per-request policy subroutine.

Task summary

Configuring a per-request policy subroutine

Configure a per-request policy subroutine to prepare it for use in the per-request policy.
  1. On the Main tab, click Access Policy > Per-Request Policies .
    The Per-Request Policies screen opens.
  2. In the Access Policy column for the per-request policy that you want to update, click the Edit link.
    The visual policy editor opens in another tab.
  3. Click the Add New Subroutine button.
    A popup screen displays.
  4. To preview the available templates, select them one at a time from the Subroutine from template list.
    A description of the selected template and the items in it display.
  5. Select a template and click Save.
    The popup screen closes. The subroutine, with the heading [+] Subroutine: Name , displays below the main editor.
  6. Expand the subroutine by clicking the [+] icon.
    A red asterisk displays by the name of any item that needs some configuration.
  7. Edit the properties of any item as needed.
    If the subroutine includes an AAA authentication item, you must specify an AAA server in the item properties.
Configure any additional items that you require in the subroutine.

Specifying resources for the subroutine to validate and protect

Configure the gating criteria for a per-request policy subroutine to specify the resources associated with the subroutine.
Note: When a subsession for matching resources exists, Access Policy Manager® does not run the subroutine again, but takes the same branch that the subroutine took the last time that it ran.
  1. With the per-request policy open in the visual policy editor, expand the subroutine for editing by clicking the (+) icon in the subroutine heading.
    The heading ([+] Subroutine: Name) for the subroutine, displays below the main editor.
  2. Click Subroutine Settings/Rename.
    A popup screen displays.
  3. In the Gating Criteria field, type the name of a per-flow variable that contains a resource or resources.
    Important: If the Gating Criteria field remains blank, the subroutine runs once and applies the same ending to all requests for resources for the duration of the subsession.
    Important: If you specify a per-flow variable as the gating criteria for a subroutine and the per-request policy does not populate it, the subroutine is invalidated and does not run.
    A Category Lookup item that runs before a subroutine populates the perflow.category_lookup. name variables and an Application Lookup item that runs before a subroutine populates the perflow.application_lookup. name variables.
    For example, type perflow.category_lookup.result.url or perflow.application_lookup.result.families, or the name of any documented per-flow variable that returns resources instead of a Boolean result.
  4. Click Save.
    The popup screen closes.
The subroutine is ready to be added to the per-request policy.

Configuring multiple logon attempts for a subroutine

If you are configuring a per-request policy subroutine to obtain additional authentication and you want to provide users with more than one chance to supply credentials, you must configure and assign a Loop terminal.
Note: When you configure the properties for an authentication item in a subroutine, a property to enable multiple logon attempts is not available.
  1. With the per-request policy open in the visual policy editor, expand the subroutine for editing by clicking the (+) icon in the subroutine heading.
    The heading ([+] Subroutine: Name) for the subroutine, displays below the main editor.
  2. If Loop does not display in the list of terminals in the heading, add a Loop terminal:
    1. Click Subroutine Settings/Rename.
      A popup screen displays.
    2. From the Maximum Macro Loop Count list, select a value greater than 1.
      The maximum value is 5.
    3. Click Save.
      The popup screen closes. Loop displays in the subroutine heading on the list of terminals.
  3. To create a loop on a branch in the subroutine:
    1. Click the name of an existing terminal.
      A popup screen displays.
    2. Select Loop.
  4. Click Save.
    Note: When you specify Loop as a terminal, it enables repetition of the actions on the branch for up to the specified count. An action that does not complete successfully after the maximum count exits through the Loop terminal onto a Loop branch.
    The popup screen closes.

Adding a subroutine to a per-request policy

Put the subroutine that you configured to use by adding it to the per-request policy.
  1. With the per-request policy open in the visual policy editor, click the (+) icon on a per-request policy branch.
    A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
  2. Select the Subroutines tab.
  3. Select a subroutine and click Add Item.
    The popup screen closes and the per-request policy displays in the visual policy editor.
Ensure that the per-request policy includes an action that populates the gating criteria specified in the subroutine properties.

Requesting authentication periodically throughout a session

Check the value of the Maximum Session Timeout setting in the access profile. If it is zero (0), this procedure cannot work.
Configure the subroutine so that it runs periodically during a session, forcing the user to reauthenticate to gain access to resources.
  1. With the per-request policy open in the visual policy editor, expand the subroutine for editing by clicking the (+) icon in the subroutine heading.
    The heading ([+] Subroutine: Name) for the subroutine, displays below the main editor.
  2. Click Subroutine Settings/Rename.
    A popup screen displays.
  3. In the Max Subsession Life (sec) field, type a number that is less than the maximum session timeout specified in the access profile.
    The default maximum timeout for a session is one week, 604800 seconds.
    For example, if the session times out after a week and you want users to authenticate every day, type 86400.
  4. In the Gating Criteria field, type the name of a per-flow variable that contains a resource or resources.
    Important: If the Gating Criteria field remains blank, the subroutine runs once and applies the same ending to all requests for resources for the duration of the subsession.
    Important: If you specify a per-flow variable as the gating criteria for a subroutine and the per-request policy does not populate it, the subroutine is invalidated and does not run.
    A Category Lookup item that runs before a subroutine populates the perflow.category_lookup. name variables and an Application Lookup item that runs before a subroutine populates the perflow.application_lookup. name variables.
    For example, type perflow.category_lookup.result.url or perflow.application_lookup.result.families, or the name of any documented per-flow variable that returns resources instead of a Boolean result.
  5. Click Save.
    The popup screen closes.
The subroutine is ready to be added to the per-request policy.
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.



Incorrect answer. Please try again: Please enter the words to the right: Please enter the numbers you hear:

Additional Comments (optional)