Fundamentals of the SecureSpan Policy Language

In this tutorial we will explore the fundamentals of the SecureSpan Policy Language.

Basic Concepts

The SecureSpan Policy language is a deterministic language comprised of Policy Assertions. Each assertion can be thought of as a function that returns true or false, may set context variables, may transform the message and may act upon an external system (such as an HTTP target, message queue, database, etc). There are two basic types of assertions:

Constraint Assertions

Constraint assertions apply constraints to the policy, such as requiring a message to be sent over SSL, requiring a specific type of credentials, requiring elements to be signed or encrypted, etc.

Action Assertions

Action assertions perform actions, such as authenticating credentials, transforming messages, turning on auditing and routing messages, etc

As illustrated in the snippet of code above, SecureSpan Policy Language is read from top to bottom. The root level of the policy is the left most edge of the policy. In most cases an assertion that return false at the root level of the policy will cause the policy to fail, resulting in a SOAP fault (note). This example policy will perform the following actions, in order:

• Audit Message in Policy will force an audit record to be created every time this policy is executed. Always returns true.
• Require SSL or TLS Transport will enforce that the request was sent over SSL. If not a SOAP Fault will result.
• Require HTTP Basic Credentials ensures that username and password are presented in the HTTP header. If not an HTTP 401 Authentication Required response will be sent.
• Request: Authenticate against L7 Demo LDAP will validate the credentials gathered by the previous Require HTTP Basic Credentials assertions against the L7 Demo LDAP identity provider. Failure to authenticate the credentials will result in an "Authentication Failure" SOAP Fault.
• Route via HTTP to URL sends the request message to the URL over HTTP. Failure to route the message will result in a SOAP fault.

Editing Policy

The Assertions Palette is divided into ten expandable categories arranged as a tree:

• Access Control
• Transport Layer Security (TLS)
• XML Security
• Message Validation/Transformation
• Message Routing
• Service Availability
• Logging, Auditing and Alerts
• Policy Logic
• Threat Protection
• Policy Templates

To add an assertion to the policy simply select the assertion in the palette, drag it into the policy editing window and drop it at the desired point of execution in the policy. Assertions that require parameters to be set will automatically open a configuration dialogue.

Assertions can be moved within the policy by dragging them in the policy editing window with the mouse or by selecting them and clicking the up and down arrows in the center bar.

To disable an assertion either select the assertion and click the disable icon (red circle with X) in the center bar or right-mouse-click the assertion and select Disable Assertion from the context menu. Note that you can select multiple assertions by shift- and control-clicking them.

To delete an assertion select the assertion and either click the delete icon (X icon) in the center bar, press the delete key on the keyboard or right-mouse-click the assertion and select Delete Assertion from the context menu. Note that you can select multiple assertions by shift- and control-clicking them.

You can copy and paste assertions by slecting them and pressing Ctl-C to copy, then select the assertion immediately before where you want to paste and press Ctl-V.

For assertions that have configurable parameters you can access the configuration dialogue by double-clicking the assertion or right-mouse-clicking it and selecting the appropriate option from the context menu.

Policy Branching

A very powerful concept of the SecureSpan Policy Language is the notion of Policy Branching. There are two special folder assertions in the Policy Logic category that are used to facilitate policy branching:

The two folder assertions are so commonly used that they are also available by right-mouse-clicking in the Policy Editing window and selecting them from the pop-up context menu:

---

---

At least one assertion must evaluate to true

Each child assertion that is placed in this folder is processed until one returns true. At that point processing of the child assertions stops and the folder assertion returns true. If all child assertions are in the folder return false then the folder assertion itself returns false.

All assertions must evaluate to true

Each child assertion that is placed in this folder is processed until one returns false. At that point processing of the child assertions stops and the folder assertion returns false. If all child assertions are in the folder return true then the folder assertion itself returns true.

Consider the following use case and compare with the example SecureSpan Policy below:

Access to the ACME Warehouse Service is available to internal users (i.e. those who are calling from an IP address in recognized IP space) who present credentials per the WS-Security Signature standard and successfully authenticate against the LDAP. Additionally there is a single external user, PartnerCo, who also has rights to access the service but must submit the request over SSL and send WS-Security UsernameToken Profile credentials that authenticate to an identity in the Internal Identity Provider.

The policy sets up the two possible cases as two All folders nested in a single At least one folder. If all of the child assertions in the first All folder succeed then the conditions of that folder are met, which in turn satisfies the At least one folder's requirement and the message will be routed without evaluating the second All folder. If any of the child assertions in the first All folder fail then the first All folder fails and the second folder will then be evaulated. Similarly if any child assertions in the second All folder return false then that folder will also fail, thus not meeting the requirement of the At least one parent folder thus resulting in a false condition at the root level of the policy and a SOAP fault message to be returned.

Hints and Tips

• Many assertions, such as the Audit Messages in Policy, Send Email Alert, etc, will always return true and must be considered when writing policy logic. Only the Add Comment to Policy assertion has no impact on the policy.
• When writing complex policy be sure to carefully walk through the policy and evaluate the conditions all the way back to the root level of the policy. There is no "break" statement so policy must be fully evaluated.
• Use the Continue Processing (which always returns true) and Stop Processing (which always returns false) assertions to negate the results of the At least one and All folders as required.
• Always organize policies with security as the first concern, then performance
• For better performance try and arrange the assertions such that they will evaluate "common" situations first. For example, in the above policy fragment the most common access will be from internal users, not the PartnerCo.

For more information on organizing policy refer to the Policy Organization section of Chapter 6 in the SecureSpan Manager User Manual.

Client vs Server View of Policy

When discussing policy, especially with client application developers, it is important to understand that there are two views of a policy. The policy that is displayed in the SecureSpan Manager is the Server View, meaning all the policy to which the SecureSpan SOA Gateway has access. In other words, the Server View of the policy is the full policy itself.

The Client View of the policy is that subset of the Server View of the policy that a requesting client will need to know in order to craft a message that can satisfy the full policy, such as what credential mechanisms are required, whether SSL is required, what elements need to be encrypted and/or signed, etc.

Recap

In this tutorial we have examined the fundamentals of the SecureSpan Policy Language. Users should now have a reasonable understanding of how to write basic policies and be able to explore further the flexibility of the SecureSpan Policy Language.