F5 Logo MyF5
Search
  1. MyF5 Home
  2. Knowledge Centers
  3. BIG-IP APM
  4. BIG-IP Access Policy Manager: Authentication and Single Sign-On
  5. Step-Up Authentication with APM
Manual Chapter : Step-Up Authentication with APM

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 13.0.1, 13.0.0
Manual Chapter
Table of Contents | << Previous Chapter | Next Chapter >>

What is step-up authentication?

With step-up authentication, you can authenticate a user at any time during a session.

Use cases for step-up authentication

Step-up authentication can be used to protect layers or parts of a web application that manage more sensitive data. It can be used to increase protection by requiring stronger authentication within an already authenticated access to the web application. Step-up authentication can be a part of using the portal access or web application management (reverse proxy) features of Access Policy Manager® (APM®).

Concepts to know for building step-up authentication policies

Per-session policy
Runs once. Associated with an access profile, which specifies a session lifetime. Can be used to validate that a client satisfies corporate policy, establish user identity, establish policy behavior, and allow or deny access to a virtual server and the resources it protects. Establishes a session. Required.

Per-request policy
Runs each time the client makes an HTTP or HTTPS request during a session. Can be used to determine whether to request step-up authentication, and to allow or reject a request. The purpose of this policy is to control access to the requested resource. Required.

Per-request policy macro
Groups agents. Keeps policy display clean and simple. Optional.
Per-request policy subroutine
A special macro that can handle client interactions. Represents the step-up authentication policy. Establishes a subsession. Runs when no active subsession matches the expected identifying characteristics (subroutine name and any gating criteria). While a matching subsession exists, the subroutine does not run again; the user retains access to the resource and need not authenticate again. Required.

Subroutine settings
Specifies subsession lifetime; a loop count, which can be used if authentication retry is needed; gating criteria; and other timeout values. Default values for these settings are provided when you configure a per-request policy subroutine; you can retain those values or change them.

Gating criteria
A subroutine setting. Specifies a criteria to distinguish subsessions. A distinct subsession is created for each distinct gating criteria value. Gating criteria can be blank (one value) or can be set to a perflow variable (more than one possible value). The default value is blank.
perflow.scratchpad and perflow.custom
Pre-defined custom variables. These are the only custom variables that can be used in a per-request policy or its components (macro, subroutine, subroutine macro). Use of these variables is optional.
Subsession

Starts when a subroutine runs and continues until reaching its maximum lifetime (a subroutine setting), or until the session terminates. Does not count against license limits. Populates subsession variables that persist throughout the subsession. Supports logging. Multiple subsessions can exist at the same time, up to a limit of 128 per access session. (When the 129th session is created, the first subsession is removed.)

Per-request policy subroutine macro
Groups agents. Keeps policy display clean and simple. Optional.

How step-up authentication works

1 User logs in and authenticates through an access policy (per-session policy); Access Policy Manager® (APM®) creates a session. User starts to use an application that's available in the enterprise. User can access all but two parts of the application that APM protects with step-up authentication, which requires:
  • Password-based authentication () for access to one part of the application.
  • Certificate-based authentication () for access to one part of the application.
2 User requests access to part of the application protected with step-up authentication (username and password). APM challenges the user and then starts a subsession; for simplicity, we call it Subsession 1. For the duration of Subsession 1: If the user passed step-up authentication, the user does not need to authenticate again to access that part of the application; If the user failed step-up authentication, the user does not have access and step-up authentication does not run again.
3 User requests access to part of the application protected with step-up authentication certificate authentication. APM challenges the user and then starts another subsession, Subsession 2. If the user passes certificate authentication, for the duration of Subsession 2: If the user passed step-up authentication, the user does not need to authenticate again to access that part of the application; If the user failed step-up authentication, the user does not have access and step-up authentication does not run again.
Tip: A subsession ends when its lifetime expires or when the session ends, whichever is sooner.

Authentication types APM supports for step-up authentication

Access Policy Manager® (APM®) supports these authentication types for step-up authentication:

Multi-factor authentication through RADIUS authentication
APM supports multi-factor authentication providers, such as DUO Security and RSA SecurID, when they are integrated with RADIUS.
Certificate-based authentication
  • On-Demand certificate authentication - APM re-negotiates the SSL connection, requesting and validating the certificate.
  • CRLDP - When coupled with on-demand certificate authentication, Certificate Revocation List Distribution Point (CRLDP) authentication verifies that the certificate is still valid.
  • OCSP - When coupled with on-demand certificate authentication, Online Certificate Status Protocol (OCSP) authentication verifies the certificate is still valid.
Password-based authentication
APM supports these password-based authentication types:
  • Active Directory
  • HTTP
  • LDAP
  • Local Database
  • RADIUS

Example: Step-up authentication at the application layer

One way to identify an application or some part of an application that you want to protect is by using the URL Branching agent in a per-request policy to specify a URI and branch on it.

Example: Determining to step up for an application layer

In this example, the URL Branching agent matches substrings that indicate requests to sensitive areas of a web application named siterequest. Matching requests are protected with Active Directory or multi-factor step-up authentication.

Example: Stepping up with Active Directory and authentication retries

This example subroutine authenticates a user with Active Directory.

The user gets three authentication retries because the Maximum Macro Loop Count is set to 3. Because the Gating Criteria is blank, the subroutine can create only one distinct subsession. While the subsession exists, if the user makes another request that matches the application area, the user is not challenged again for authentication.

Example: Stepping up with multi-factor authentication

This example subroutine uses RADIUS to authenticate a user. This configuration supports multi-factor authentication when it is implemented using third-party products that integrate through RADIUS.

Example: Step-up authentication for an IP address change

Using the Variable Assign agent (renamed as Store Client IP in this example), it's possible to save the client IP address, then compare it to the original client IP address from the start of the session and, if it changes, run LDAP authentication.

Example: Basing step-up authentication on a custom value

In this example, the Variable Assign agent stores a value in a pre-defined custom variable.

In the illustration, Predefined Variables is selected, Group is set to Per-Request Variables, and Variable is set to Scratchpad. An iRule in the Custom Expression field gets the value, which is the client IP address.

Note: A per-request policy does not recognize custom variables that users can define with Variable Assign. Only the predefined per-request variables Scratchpad and Custom serve the purpose of storing custom values for a per-request policy.

Example: Specifying the Scratchpad variable as the gating criteria

In this example, perflow.scratchpad is specified as the Gating Criteria in the subroutine settings. In another example, you can see the per-request policy store the client IP address in the predefined Scratchpad variable. The Scratchpad variable (available through the Variable Assign agent), equates to the perflow.scratchpad variable that is available in subroutine settings.

Example: Using additional criteria to determine when to step up

In this example, a change in the client IP address (stored in the gating criteria, perflow.scratchpad) triggers the step-up authentication subroutine to run. However, we want the user to authenticate using LDAP only if the client IP address is not the same one that started the session. An agent in the subroutine, Source IP Check (configured from the Empty agent), makes this comparison.

Step-up authentication configuration basics

These are the configuration objects and settings you need to create when you implement step-up authentication.

Access profile
The primary use for step-up authentication is to protect resources in a portal access or web access management (reverse proxy) configuration. Access Policy Manager® (APM®) supports it with any of these access profile types:
  • LTM+APM
  • SSL-VPN
  • All
  • SWG-Explicit
  • SWG-Transparent
Per-session policy
A per-session policy, also known as an access policy, can include authentication or not. The policy can be as simple as Start-Allow, or it can be very complex.
Per-request policy subroutine
Part of a per-request policy in which you configure a type of authentication to use for step-up authentication.
Per-request policy subroutine gating criteria setting
A setting that is blank or contains a perflow variable which specifies a distinct value that represents a reason to run step-up authentication.
Per-request policy
A policy that runs for each request throughout a session. It must include a call to the step-up authentication subroutine, and can include logic that determines when to call the step-up authentication subroutine. Unless the gating criteria for the step-up authentication subroutine is set to blank, or to a variable that gets populated automatically, the per-request policy must contain an agent to populate the gating criteria.

Overview: Configuring step-up authentication

These steps guide you through configuring a per-request policy for step-up authentication.

Task summary

Configuring a subroutine for step-up authentication

For step-up authentication, you configure a per-request policy subroutine with authentication actions.
  1. On the Main tab, click Access > Profiles / Policies > Per-Request Policies .
    The Per-Request Policies screen opens.
  2. Create and then open a per-request policy for editing in the visual policy editor.
  3. Click the Add New Subroutine button.
    A popup screen opens.
  4. Select either of these subroutine templates:
    • LDAP Authentication - Includes a Logon Page followed by an LDAP Auth action, Pass and Fail terminals.
    • Empty - Includes In and Out terminals only.
  5. 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. Configure the subroutine with the actions needed to effect the authentication that you want to use.
    Option Description
    AD Auth Add after a Logon Page agent.
    CRLDP Auth To validate a certificate, add after On-Demand Cert Auth.
    HTTP Auth Add after a Logon Page agent.
    LDAP Auth Add after a Logon Page agent.
    LocalDB Auth Add after a Logon Page agent.
    OAuth Client Add after a OAuth Logon Page agent.
    OAuth Scope Add after a OAuth Logon Page agent.
    On-Demand Cert Auth In the agent properties, be sure the set Auth Mode to Require.
    OCSP Auth To validate a certificate, add after On-Demand Cert Auth.
    RADIUS Auth Add after a Logon Page agent.
  8. Make any changes you want to the subroutine terminals:
    1. To add a terminal, click Edit Terminal and configure it.
    2. To change a terminal, click it and select another one.
The subroutine is ready to be added to the per-request policy. Subroutine settings are configured at default values.

Specifying how often a user must step up

You can configure Access Policy Manager® (APM®) so that step-up authentication runs periodically throughout a session. For example, you might want a user to re-authenticate every eight hours for access to a given application.
  1. For step-up authentication to run periodically, verify that the Maximum Session Timeout setting in the access profile is set to a non-zero value.
    The default value is 604800 seconds (or 1 week).
    1. On the Main tab, select Access > Profiles / Policies > Access Profiles (Per-Session Policies) .
    2. Click the name of the access profile you want to verify.
    3. In the Settings area, locate the Maximum Session Timeout setting.
    4. If it is set to 0, on the right of the screen select the Custom check box, in the Maximum Session Timeout field type a value greater than 0, and at the bottom of the screen click Update.
  2. To specify how long you want the user to retain access without needing to re-authenticate, update the Max Subsession Life (sec) setting:
    1. With the per-request policy open in the visual policy editor, expand the subroutine for editing.
    2. Click Subroutine Settings/Rename.
      A popup screen opens.
    3. In the Maximum Subsession Life (sec) field, type the number of seconds that you want users to retain access without needing to authenticate again.
      The default value is 900 (or 15 minutes).
  3. Click Save.
    The popup screen closes.

Setting gating criteria to run step-up authentication more than once per session

A subroutine creates a subsession for each distinct gating criteria value. By default, gating criteria for a subroutine is set to blank and the subroutine runs once. To base step-up authentication on distinct values dynamically set in a variable, you configure a perflow variable as the gating criteria.
  1. Open the per-request policy for editing.
  2. Expand the subroutine.
  3. Click Subroutine Settings/Rename.
  4. Put your cursor in the Gating Criteria field and select one entry from the list.
    If you type in the Gating Criteria field, variables display that match the string you type.
    You can base step-up authentication on custom values or on values provided by specific agents.
    Perflow Variable Description
    perflow.custom or perflow.scratchpad Custom value that you must populate with Variable Assign
    perflow.category_lookup.result.hostname This value is automatically populated.
    perflow.category_lookup.result.url This value is automatically populated.
    • perflow.category_lookup.result.categories
    • perflow.category_lookup.result.effective_category
    • perflow.category_lookup.result.filter_name
    • perflow.category_lookup.result.numcategories
    • perflow.category_lookup.result.numcustomcategories
    • perflow.category_lookup.result.primarycategory
    		URL data, available with an SWG subscription, that you must populate with Category Lookup
    perflow.category_lookup.result.customcategories URL data, available with or without an SWG subscription, that you must populate with Category Lookup
    perflow.resource_assign_pool.name Pool name that you must populate with Pool Assign
    perflow.protocol_lookup.result Protocol type (HTTP or HTTPS) that you must populate with Protocol Lookup
    perflow.ssl_bypass.set Defaults to False; can be set to True with SSL Bypass Set (or set to False with SSL Intercept Set)
    A perflow variable with application_lookup in its name Application name or family that you must populate with Application Lookup
    perflow.session.id This value is automatically populated and does not change. When this variable is selected, step-up authentication will run once.
    perflow.username This value is automatically populated. Username won't usually change but might change.
  5. Click Save.
Important: If you set the gating criteria to a perflow variable that is populated by an agent, you must place that agent before the subroutine call in the per-request policy. Otherwise, the gating criteria does not contain a valid value, the subroutine returns an error, and step-up authentication does not run.

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.

Populating gating criteria for step-up authentication

If the gating criteria for your subroutine is not set to blank, perflow.session.id, or perflow.username, you must include the agent in the per-request policy that populates the gating criteria.
  1. Open the per-request policy for editing.
  2. Locate a point that is before the subroutine and click [+].
    The Add Item screen opens.
  3. If your gating criteria is set to perflow.custom or perflow.scratchpad, on the Assignment tab select Variable Assign, click Add Item, configure an entry that sets a value for the variable, and click Save.
  4. If your gating criteria is not set to perflow.custom or perflow.scratchpad, on the General Purpose tab, select the agent (Protocol Lookup, SSL Bypass Set, SSL Intercept Set, Category Lookup, or Application Lookup) that populates the gating criteria, click Add Item, configure the agent properties, and click Save.

Using Variable Assign to populate gating criteria

When you set subroutine gating criteria to the perflow.custom or perflow.scratchpad variable, you must configure Variable Assign to specify its value.
Important: Using Variable Assign to populate a perflow variable other than perflow.custom and perflow.scratchpad causes subroutine results to become unreliable.
  1. Open the per-request policy for editing.
  2. Click the name of the Variable Assign agent.
    A Properties screen opens.
  3. Click Add new entry, and in the new entry, click the change link.
    A popup screen opens with Custom Variable selected on the left and Custom Expression selected on the right.
  4. On the left, select Predefined Variables.
    Additional fields display.
  5. For Groups, select Per-Request Variables.
  6. For Variable, select one of the following:
    • Custom - Populates the perflow.custom variable.
    • Scratchpad - Populates the perflow.scratchpad variable.
  7. On the right, retain Custom Expression and configure the expression to provide a value.
    The Custom Expression option provides the greatest flexibility; you can select any other option and configure it.
  8. Click Save.
    The Properties screen closes.

Configuring URL branching for step-up authentication

Add a URL branching agent to a per-request policy or to a per-request policy subroutine to create simple branching rules based on URLs. You might use URL branching to run different types of step-up authentication for different URLs or to skip step-up authentication altogether for a group of URLs.
  1. Open the per-request policy for editing.
  2. To edit a per-request policy subroutine, expand it.
  3. In the per-request policy or in the per-request policy subroutine, in the branch where you want to add URL branching, click [+].
    The Add Item popup screen opens.
  4. On the General tab, select URL Branching and click Add Item.
    The Properties screen opens.
  5. Click the Branch Rules tab.
    The screen displays the default rule, Allow, and the expression, URL contains: domain.com.
  6. If you do not want a rule that matches a URL substring, delete the default rule; (click x).
    The URL Branching agent can be configured to exactly match a URL, or to match a substring or a prefix or a suffix in a URL, or to perform glob pattern matching on a URL.
  7. If you want to replace the value (domain.com) in the default rule:
    Note: You can use AND and OR operators to configure expressions for your rules. For simplicity of illustration, the examples do not include these operators.
    1. Click the change link.
      An additional popup screen opens.
    2. In the URL contains field, delete domain.com, and type the substring that you want to match.
    3. Click Finished.
      The popup screen closes.
    4. If you have no more changes to make, click Save.
  8. To add a rule, click Add Branch Rule.
    1. In the Name field, replace the default name Branch Rule number with a name for the branch.
    2. For Expression: Empty, click the change link.
      A popup screen opens.
    3. Click Add Expression.
      Fields with default values display.
    4. For the Agent Sel field, select or retain URL Branching.
    5. For Condition, select one from the list.
      When you select a condition, a related input field displays.
    6. For Condition Equals in the URL is field, type the URL that you want to exactly match.
    7. For Condition Substring in the URL contains field, type the string that you want to match.
    8. For Condition Prefix Match in the URL begins with field, type the prefix that you want to match.
    9. For Condition Suffix Match in the URL ends with field, type the suffix that you want to match.
    10. For Condition Glob Match in the URL glob pattern field, type the globbing pattern that you want to match.
      URL branching supports these globbing patterns:
      • * Matches any number of characters (none or one or more).
      • ? Matches a single character in these sets: [a-z] or [0-9] or [A-Za-z].
      • [ characters ] Matches one of the specified characters.
      • [^ characters ] Matches any characters except for those specified.
      • [! characters ] Matches any characters except for those specified.
    11. Click Add Expression, then click Finished.
      The popup screen closes; the updated expression displays on the Branch Rules screen.
    12. Click Save.
      The popup screen closes; the visual policy editor displays.
The per-request policy or subroutine includes URL branching.
After the URL branch, you can add step-up authentication if that's what you are trying to do. In a per-request policy, you can insert a call to a subroutine after a URL branch. Or, in a subroutine, you can insert an authentication agent after a URL branch.

Session variables for more granular access control in step-up authentication

Session variables might not change throughout a session. However, in conjunction with other data, they can be used to create distinctive subsessions that control which resources a user can reach. A Variable Assign agent or an iRule agent could put a string into the perflow.custom or perflow.scratchpad variable like this example:

Senior_Executive_After_Hours_04_06_2017

An administrator can derive the example string from a session variable and date-time information.

  • Senior_Executive - Added to the string based on a group name in the session.ldap.last.attr.memberOf session variable.
  • After_Hours - Appended to the string if the current time is after 5 PM today and before 7 AM tomorrow; otherwise, Office_Hours could be appended to the string.
  • 04_06_2017 - The most recent 24-hour period that started at 7 AM is appended to the string.

The F5 DevCentral online community is the source for information about iRules®. BIG-IP® Access Policy Manager®: Visual Policy Editor on the AskF5™ web site located at support.f5.com provides information about session variables, perflow variables, and Tcl usage, all of which can be helpful when working with Variable Assign.

Table of Contents | << Previous Chapter | Next Chapter >>
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5 Networks, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information