General Purpose Items¶
The general purpose items can be used in any case and placed anywhere in a policy. These items support miscellaneous actions such as HTTP header modification, presenting a message or decision box, logging, and others.
Refer to Create Access policy for the OpenAPI specification document.
Confirm Box¶
The Confirm Box item is available within the per-request policy subroutine. Similar to a decision box, a confirm box displays a web page with two link options. These options (Continue and Cancel) are presented as link text preceded by images. The end-user has to click a link to continue with the Access policy. The policy execution is paused until the user clicks on one of the link texts. The Confirm Box item stores the user’s choice in the perflow variable: perflow.decision_box.result and based on the configured expression, the policy is branched. Similar to Decision Box, the Confirm Box item supports customization and localization.
Note: In this release, localization is limited to the default English language.
Example: The following example shows the Confirm box configuration in an Access policy.
{
"policyType": "PerRequest",
"name": "prp1",
"policy": {
"objectContent": {
"languages": [
"zh-cn",
"en"
],
"defaultLanguage": "en",
"start": {
"caption": "Fallback",
"itemType": "macro-call",
"name": "Sub_confirm",
"macro": "sr_confirm",
"nextItems": [
{
"itemType": "allow",
"caption": "successful"
},
{
"itemType": "reject",
"caption": "fallback"
}
]
},
"macros": [
{
"name": "sr_confirm",
"type": "subroutine",
"maxMacroLoopCount": 2,
"inactivityTimeout": 1200,
"maxSubsessionLifetime": 600,
"subroutineTimeout": 124,
"gatingCriteria": "perflow.category_lookup.result.url",
"start": {
"caption": "Fallback",
"itemType": "confirm-box",
"name": "ConfirmS",
"customization": [
{
"language": "en",
"strings": {
"confirmTitle": "Click Continue to proceed:",
"continueMessage": "Continue",
"cancelMessage": "Cancel"
}
},
{
"language": "zh-cn",
"strings": {
"confirmTitle": "按继续继续:",
"continueMessage": "继续",
"cancelMessage": "取消"
}
}
],
"nextItems": [
{
"caption": "Continue",
"expression": "expr {[mcget {perflow.decision_box.result}] == 1}",
"itemType": "terminal-out",
"name": "successful"
},
{
"caption": "fallback",
"itemType": "terminal-out",
"name": "fallback",
"loop": true
}
]
}
}
]
}
}
}
The table below lists the objects for customizing Confirm box:
| Object | Type | Description |
|---|---|---|
| itemType | string | Specifies the Access policy item. For the Confirm Box item, the value is confirm-box. This is a required setting. |
| name | string | Specifies the name of the BIG-IP Next Access policy item. |
| caption | string | Specifies a human-readable description of the policy branch. |
| expression | string | Specifies the Tcl expression. The mcget command is an abbreviation for "get the session variable from the memory cache." When evaluating a branch rule, BIG-IP Next Access obtains session variables from the system memory using the Tcl command mcget. The Tcl expression can also contain one or more expressions (expr) or return commands. An expr command evaluates an expression and returns the result. A return command simply returns the result, and can be used to set the variable to a numeric value or string. For example, "expression": "expr { "[mcget session.custom.value1] + [mcget session.custom.value2]" }", "expression": "expr { "[mcget {session.logon.last.domain}]\[mcget {session.logon.last.username}]" }", and "expression": "expr {1800}". For details on Tcl expressions, refer to https://www.tcl.tk/man/tcl8.5/TclCmd/expr.html. For a list of session variables, refer to Reference: Session Variables. |
| customization | array | Specifies an array of customization objects. This is a required setting. |
|
string | Specifies the language to use to customize the decision box. ISO 639-1 language codes should be used. This is a required setting. |
|
object | Definitions for customization strings for Confirm Box customization group. To configure a customization string, define the following properties:
|
| nextItems | array | Specifies the branches to the next policy item. This is a required setting. |
Decision Box¶
The Decision box item presents two options to the user. These options are presented as link text preceded by images. The end-user makes a decision to click a link to continue with the Access policy. The execution is paused until the user clicks on one of the link texts.
A Decision box can be helpful after a client fails an endpoint security check or after a user fails to authenticate. For example, suppose a user fails authentication. In that case, you can provide the option to attempt to authenticate again or to continue to an allowed resource, like public Internet access, without allowing internal network access.
Another example would be to provide one option of continuing onto a guest or quarantine network with limited access to a segregated subnet and a second option to present a deny ending and log out the user. You can also use the Decision box to take the user to a helpful URL, for example, an antivirus vendor’s website, to download virus database updates.
Note: The Decision box item is supported only for a per-session Access policy.
Example: The following example shows the Decision box objects in an Access policy.
{
"languages": [ "en" ],
"defaultLanguage": "en",
"start": {
"caption": "Decision Box AP Item",
"itemType": "decision-box",
"customization": [
{
"language": "en",
"strings": {
"decisionTitle": "Custom Decision Box Title",
"confirmTitle": "Custom Confirm Decision Box Title",
"decision1Message": "custom option 1",
"decision2Message": "custom option 2"
}
}
],
"nextItems": [
{
"itemType": "allow",
"expression": "expr {[mcget {session.decision_box.last.result}] == 1}",
"name": "Allow",
"caption": "fallback"
},
{
"itemType": "deny",
"name": "Deny",
"caption": "fallback"
}
]
}
}
The table below lists the objects used for customizing the decision box:
| Object | Type | Description |
|---|---|---|
| itemType | string | Specifies the BIG-IP Next Access policy item. For the Decision box item, the value is decision-box. This is a required setting. |
| name | string | Specifies the name of the BIG-IP Next Access policy item. |
| caption | string | Specifies a human-readable description of the policy branch. |
| expression | string | Specifies the Tcl expression. The mcget command is an abbreviation for "get the session variable from the memory cache." When evaluating a branch rule, BIG-IP Next Access obtains session variables from the system memory using the Tcl command mcget. The Tcl expression can also contain one or more expressions (expr) or return commands. An expr command evaluates an expression and returns the result. A return command simply returns the result, and can be used to set the variable to a numeric value or string. For example, "expression": "return {1800}", "expression": "return {Hello World}", "expression": "expr { "[mcget session.custom.value1] + [mcget session.custom.value2]" }", "expression": "expr { "[mcget {session.logon.last.domain}]\[mcget {session.logon.last.username}]" }", and "expression": "expr {1800}". For details on Tcl expressions, refer to https://www.tcl.tk/man/tcl8.5/TclCmd/expr.html. For a list of session variables, refer to Reference: Session Variables. |
| customization | array | Specifies an array of customization objects. This is a required setting. |
|
string | Specifies the language to use to customize the decision box. ISO 639-1 language codes should be used. This is a required setting. |
|
object | Customizable strings and settings for the decision box. To configure customization string, define the following properties:
|
| nextItems | array | Specifies the branches to the next policy item. This is a required setting. |
Email Item¶
The Email Item allows BIG-IP Next to send emails using an external SMTP server configuration. In the BIG-IP Next Access policy, you define the Email item in the policy object.
To configure sending an email during policy execution, you must create SMTP config and Email Item objects in an Access policy.
For instructions on creating an SMTP configuration for sending emails, refer to How To: Configure an SMTP Configuration.
Note: The Email Item is supported only for a per-session Access policy.
Example: The following example shows an Access policy with the SMTP config and Email Item configuration.
{
"policyType": "PerSession",
"name": "apssp1",
"profileType": "ltm-apm",
"scope": "global",
"externalServers": [
{
"name": "smtp-server",
"sourceMachineAddress": "local.host.name",
"smtpServerAddress": "smtp.host.com",
"serverType": "Smtp"
}
],
"policy": {
"objectContent": {
"languages": [
"en"
],
"defaultLanguage": "en",
"start": {
"smtpConfiguration": "smtp-server",
"itemType": "email",
"from": "from@email.com",
"to": "admin@email.com; 123@gmail.com",
"cc": "j_smith@email.com; admin@abc.com",
"name": "email-agent",
"subject": "email subject",
"message": "email message",
"nextItems": [
{
"itemType": "allow",
"name": "Allow",
"caption": "Successful"
}
]
}
}
}
}
The table below lists the objects for the Email item:
| Object | Type | Description |
|---|---|---|
| caption | string | Specifies a human-readable description of the policy branch. |
| message | string | Specifies the message to send. This can be a string, a session variable name, or a combination of strings and session variable names. For example, One Time Passcode: %{session.otp.assigned.val}. Expires after use or in %{session.otp.assigned.ttl} seconds. |
| cc | string | Specifies the list of recipients to be copied on the email, separated by semicolons. This can be fully qualified email addresses or session variable names. For example, %{session.ad.last.attr.mail}; admin@email.com; %{session.logon.last.username}@mail.com. |
| from | string | Specifies the sender's email address on BIG-IP Next. This is a required setting. This can be a fully qualified email address or a session variable name. For example, %{session.ad.last.attr.mail} or %{session.logon.last.username}@mail.com. |
| to | string | Specifies the list of the recipient's email addresses, separated by semicolons. This is a required setting. This can be a fully qualified email address or a session variable name. For example,
|
| subject | string | Specifies the subject of the email message. This can be a string, a session variable name, or a combination of strings and session variable names. |
| expression | string | Specifies the Tcl expression. The mcget command is an abbreviation for "get the session variable from the memory cache." When evaluating a branch rule, BIG-IP Next Access obtains session variables from the system memory using the Tcl command mcget. The Tcl expression can also contain one or more expressions (expr) or return commands. An expr command evaluates an expression and returns the result. A return command simply returns the result, and can be used to set the variable to a numeric value or string. For example, "expression": "expr {[mcget {session.email.last.result}] == 1}" For details on Tcl expressions, refer to https://www.tcl.tk/man/tcl8.5/TclCmd/expr.html. For a list of session variables, refer to Reference: Session Variables. |
| itemType | string | Specifies the Access policy item. For the Email item, the value is email. This is a required setting. |
| name | string | Specifies the name of the Access policy item. |
| nextItems | array | Specifies the different branches of the Access Policy item. This is a required setting. |
| smtpConfiguration | string | Specifies the name value of the SMTP server that you configured in the externalServers array. This is a required setting. In the above example, smtp-server is the name given to the SMTP configuration in the externalServers array ("name": "smtp-server"). |
Empty Item¶
The Empty item allows you to add built-in or custom branch rules with TCL expressions to your per-request and per-session policy. It is used if branches need to be built outside an authentication or assignment. The Empty item allows conditional branching of a policy without needing to configure an item, giving fine-grain access control and a better security posture. It triggers and evaluates TCL expressions against session variable values in the outgoing branches and routes the logic flow to policy completion.
Example: The following example shows the Empty item in a BIG-IP Next Access policy.
{
"languages": [ "en" ],
"defaultLanguage": "en",
"start": {
"caption": "Empty item",
"itemType": "empty",
"nextItems": [
{
"caption": "Deny",
"expression": "expr {[mcget {session.client.platform}] == \\"MacOS\\" }",
"itemType": "deny"
},
{
"caption": "Allow",
"expression": "expr {[mcget {session.client.platform}] == \\"Windows\\" }",
"itemType": "allow"
},
{
"caption": "Fallback",
"itemType": "deny"
}
]
}
}
The table below lists the objects used for customizing the empty item:
| Object | Type | Description |
|---|---|---|
| itemType | string | Specifies the BIG-IP Next Access policy item. For the Empty item, the value is empty. This is a required setting. |
| name | string | Specifies the name of the Access policy item. |
| caption | string | Specifies a human-readable description of the policy branch. |
| expression | string | Specifies the Tcl expression. The mcget command is an abbreviation for "get the session variable from the memory cache." When evaluating a branch rule, BIG-IP Next Access obtains session variables from the system memory using the Tcl command mcget. In the above example, the mcget command returns the data inside the session.client.platform and checks the client OS for macOS or Windows. BIG-IP Next Access evaluates the expression and assigns the value of the expression to a newly created variable. The Tcl expression can also contain one or more expressions (expr) or return commands. An expr command evaluates an expression and returns the result. A return command simply returns the result, and can be used to set the variable to a numeric value or string. For example, "expression": "return {1800}", "expression": "return {Hello World}", "expression": "expr { "[mcget session.custom.value1] + [mcget session.custom.value2]" }", "expression": "expr { "[mcget {session.logon.last.domain}]\[mcget {session.logon.last.username}]" }", and "expression": "expr {1800}". For details on Tcl expressions, refer to https://www.tcl.tk/man/tcl8.5/TclCmd/expr.html. For a list of session variables, refer to Reference: Session Variables. |
| nextItems | array | Specifies the branches to the next policy item. This is a required setting. |
HTTP Header and Cookies¶
BIG-IP Next Access lets you modify HTTP Headers in a PerRequest Access policy. The HTTP Headers item supports modifying the outgoing HTTP request’ headers and cookies before being sent to back-end servers. Operations supported for HTTP header include insert, append, replace and remove, while for cookie, only update and delete operations are available.
To create an Access policy with HTTP Headers modification, define headerEntries and cookieEntries that set the headers and cookies configuration properties.
The following tree structure shows how an HTTP Headers item runs in an Access policy:
Example: The following example showsheaderEntries and cookieEntries properties.
"headerEntries": [
{
"headerOperation": "insert",
"headerName": "X-Authenticated-User",
"headerValue": "%{session.logon.last.username}"
},
{
"headerOperation": "append",
"headerName": "User-item",
"headerValue": "Mozilla/5.0",
"headerDelimiter": ";"
},
{
"headerOperation": "replace",
"headerName": "X-Forwarded-For",
"headerValue": "%{session.user.clientip}"
},
{
"headerOperation": "remove",
"headerName": "Cache-Control"
}
],
"cookieEntries": [
{
"cookieOperation": "update",
"cookieName": "PHPSESSID",
"cookieValue": "1234"
},
{
"cookieOperation": "delete",
"cookieName": "mySession"
}
]
The table below lists objects and properties for headers and cookies configuration:
| Object | Type | Description |
|---|---|---|
| headerOperation | string | Specifies an operation on the HTTP headerName. This is a required setting. Valid values are:
|
| headerName | string | Specifies the HTTP header name on which to operate. This is a required setting. |
| headerValue | string | Specifies the HTTP header value on which to operate. This is a required setting. Any per-flow or session variable can be used as a header value. For example, %{session.user.clientip} or %{perflow.session.id}. |
| headerDelimiter | string | Specifies delimiter character to use when appending a header. |
| cookieOperation | string | Specifies an operation on the cookieName. This is a required setting. Valid values are:
|
| cookieName | string | Specifies the cookie name on which to operate. This is a required setting. |
| cookieValue | string | Specifies the new value to set when updating a cookie. This is a required setting. Any per-flow or session variable can be used as a cookie value. |
Logging¶
The Logging item allows you to log session variables in the per-session Access policy at various stages. Access can capture individual session variables in the log file. You can also control when the system captures information and adds it to the log file. You can use this item for debugging per-session policy development or identifying the path taken by the Access policy execution. For example, a Logging item can help troubleshoot policies, create and monitor custom or predefined session variables, and add custom log messages.
If the Logging item is used excessively it can degrade performance; therefore use it with discretion.
Note: A session variable may or may not exist depending on the result of the Access policy run. Therefore, you must configure the Logging option directly after the action that gathers the information you want to capture.
Example: The following example shows the Logging item objects in an Access policy.
{
"languages": [ "en" ],
"defaultLanguage": "en",
"start": {
"caption": "Fallback",
"itemType": "logging",
"logMessage" : "Sample log message",
"sessionVariables": [
{
"sessionvar": "session.logon.last.username"
},
{
"sessionvar": "session.logon.last.password"
}
],
"nextItems" : [
{
"itemType": "allow"
}
]
}
}
The table below lists the objects for logging item configuration:
| Object | Type | Description |
|---|---|---|
| caption | string | Specifies a human-readable description of the policy item. |
| expression | string | Specifies the Tcl expression. The mcget command is an abbreviation for "get the session variable from the memory cache." When evaluating a branch rule, BIG-IP Next Access obtains session variables from the system memory using the Tcl command mcget. The Tcl expression can also contain one or more expressions (expr) or return commands. An expr command evaluates an expression and returns the result. A return command simply returns the result, and can be used to set the variable to a numeric value or string. For example, "expression": "return {1800}", "expression": "return {Hello World}", "expression": "expr { "[mcget session.custom.value1] + [mcget session.custom.value2]" }", "expression": "expr { "[mcget {session.logon.last.domain}]\[mcget {session.logon.last.username}]" }", and "expression": "expr {1800}". For details on Tcl expressions, refer to https://www.tcl.tk/man/tcl8.5/TclCmd/expr.html. For a list of session variables, refer to Reference: Session Variables. |
| itemType | string | Specifies the BIG-IP Next Access policy item. For the Logging item, the value is logging. This is a required setting. |
| logMessage | string | Specifies the log message to display. This is a required setting. |
| name | string | Specifies the name of the BIG-IP Next Access policy item. |
| nextItems | array | Specifies the branches to the next policy item. This is a required setting. |
| sessionVariables | array | Specifies a list of predefined session variables or custom session variable. |
|
string | Specifies a session variable that indicates which actions the system logs. This is a required setting. |
Message Box¶
The Message box item presents a message to the user and prompts the user to click a link to continue. The message box does not affect the user’s access to the network or the preceding or following Access policy checks. For example, a message box can warn a user about a redirect to a guest network, a failed client certificate authentication, or a message about the results of a rule branch in the Access policy. It can be helpful to present any message that needs to be communicated to the user before allowing them access to the resources protected by the Access policy. Additionally, since the Message box acts like a pause button during the Access policy’s run, it can be used to troubleshoot Access policy issues and examine things like session variable values that can change at different points in the Access policy.
Note: The Message box item is supported only for a per-session Access policy.
Example: The following example shows the Message box objects in an Access policy.
{
"languages": ["en"],
"defaultLanguage": "en",
"start":
{
"itemType": "message-box",
"caption": "Message Box AP Item",
"customization": [
{
"language": "en",
"strings":
{
"title": "Custom Message Box Title",
"message": "message to acknowledge",
"proceedMessage": "acknowledge button"
}
}
],
"nextItems": [
{
"itemType": "allow",
"name": "Allow",
"caption": "fallback"
}
]
}
}
The table below lists the objects for customizing a message box:
| Object | Type | Description |
|---|---|---|
| itemType | string | Specifies the BIG-IP Next Access policy item. For the Message box item, the value is message-box. This is a required setting. |
| name | string | Specifies the name of the BIG-IP Next Access policy item. |
| caption | string | Specifies a human-readable description of the policy branch. |
| expression | string | Specifies the Tcl expression. The mcget command is an abbreviation for "get the session variable from the memory cache." When evaluating a branch rule, BIG-IP Next Access obtains session variables from the system memory using the Tcl command mcget. The Tcl expression can also contain one or more expressions (expr) or return commands. An expr command evaluates an expression and returns the result. A return command simply returns the result, and can be used to set the variable to a numeric value or string. For example, "expression": "return {1800}", "expression": "return {Hello World}", "expression": "expr { "[mcget session.custom.value1] + [mcget session.custom.value2]" }", "expression": "expr { "[mcget {session.logon.last.domain}]\[mcget {session.logon.last.username}]" }", and "expression": "expr {1800}". For details on Tcl expressions, refer to https://www.tcl.tk/man/tcl8.5/TclCmd/expr.html. For a list of session variables, refer to Reference: Session Variables. |
| customization | array | Specifies an array of customization objects. This is a required setting. |
|
string | Specifies the language to use to customize the message box. Use ISO 639-1 language codes. This is a required setting. |
|
object | Customizable strings and settings for the message box. This is a required setting. To configure a customization string, define the following properties:
|
| nextItems | array | Specifies the branches to the next policy item. This is a required setting. |