Always include a comment block at the top of the policy

This should describe the policy in general terms and define more specific terms, if required. To add a comment block, use the Add Comment to Policy Assertion.

Tip:

Comments display as one continuous line in the policy; they do not line wrap. For longer comments, consider using a series of "Add Comment" assertions.

Include versioning notes in the comment block

Policies migrate through the enterprise and versioning notes are key to tracking changes.

Tip:

If you use revisions extensively, also consider adding a comment for each revision. For more information, see Policy Revisions.

Include information about passed arguments if policy is tied to encapsulated assertions, as well as any cluster-wide properties and global shared context variables.

These should be in the comment block. The actual references are usually buried deep within the policy, so the policy is easier to comprehend if they are documented up front.

Tip:

Remember to update the comment as you add or remove references.

Use "right side" comments extensively to describe what is happening

Many assertions hide their configurations inside their property dialogs, so the only way to understand what is happening is to open each assertion or (preferably) describe the configuration in a right-side comment.

Tips:

(1) The "right" and "left" comments are added through the Add Comment to Policy Assertion. (2) If your comments are not visible, click

Show Comments

in the Policy Tool Bar or use the View menu.

Use "left side" comments sparingly

The policy language is designed to read "VERB ACTION":

"Add comment...", "Authenticate against..."

. Adding left side comments break up this readability. You should add left comments only to draw specific attention to a line, otherwise use right-side comments for everything.

Always start right-side comments with a consistent, familiar delimiter

A common delimiter is '//', which is well known and improves the readability of the comment.

Tip:

Simply relying on the gray text applied to comments is often not clear enough. Moreover, policy fragments also display as gray text, causing it to be indistinguishable from comments added within a fragment.

Composite assertions should always have a comment

Describe the intent of the logical AND ("All assertions must...") and OR ("At least one assertion...") assertions in a comment. This is good practice, so that other users do not need to open the folder and analyze the contents to determine the intent of the composite assertion.

Tip:

For lengthier descriptions, use a series of Add Comment to Policy Assertions instead of one long right-side comment.

Use the "All assertions must..." folder to group functionality

The collapsing nature of this folder (and the "At least..." folder) hides logical structures, while leaving comments visible. When collapsed, the policy may be more readable and it is easier to get the "big picture".

Prevent the "At least one..." folder from failing entire policy

If you do not want the failure of an "At least one assertion..." folder to fail the entire policy, then add a Continue Processing Assertion as a child assertion. This assertion always evaluates to true, preventing the policy from failing due a non-essential or conditional assertion failing.

Never use a template response to return an error message

It may seem logical to create a custom response message using the Return Template Response to Requestor Assertion when an error is encountered, but this is not the correct use of this assertion. Instead, always use the Customize Error Response Assertion and fail the policy. This ensures that the Gateway is correctly notified of the error and records the failure correctly in the logs.

Turn on assertion line numbers

Turn on assertion line numbers to help you edit or troubleshoot a policy. You can jump to a specific line number (Edit > Go to Assertion) or use the search feature (Edit > Find) to quickly locate an assertion. For more information, see Assertion Numbering.

Ordering of assertions

Some policy assertions work together and require the presence of each other to succeed. For example, the Authenticate User or Group Assertion requires an authentication assertion such as the Require HTTP Basic Credential Assertion to provide the credentials for validating the user's identity. Moreover, the authentication assertion must appear before the user or group. This is one example of how the presence and order of assertions can affect the ultimate validity of a policy.

Authentication assertion limitation

An authentication assertion (such as the Require HTTP Basic Credential Assertion) can only provide credentials for a single user or group. The authentication assertion must appear before the identity provider assertion (for example, Authenticate User or Group Assertion).

Identity assertion recommendation

It is best not to include more than one first-level identity assertion in a policy or within an "At least" or "All assertions" folder. If you must because the client expects the Gateway to authenticate more than one identity per request, the policy validator displays a warning but you can still proceed.To add more than one user or group in a policy, place each individual Authenticate User or Group assertion in a separate "At least one assertion" or "All assertions" folder with an authentication assertion (and other assertions, as required).In the following figure, the credentials for user "Bob" are authenticated by the Require HTTP Basic Credential Assertion, while "Sue" is authenticated by the Require SSL or TLS Transport With Client Authentication Assertion.