Layer 7 Policy Authoring: Working with Service Policies

Overview

* Policy types:
– Service policies
– Global policies
– Policy fragments
– Internal use policies

Global Policies

* Always applied before or after every service policy
* Ensure consistency and reduce error
* Permissions
– Create/Delete: Administrator
– Edit: Administrator, Manage Web Service
– Read: Administrator, Manage Web Service, Operators
* Types of global policies:
– message-received
– pre-security
– pre-servcie
– post-service
– post-security
– message-completed
* How global policies are evaluated
– only one policy of each type is permitted
– in the order shown previously
– not all global policies will be evaluated in all cases
* How a global policy relates to the service policy
– A global policy shares the following with a service policy:
— request/response messages
— message context mappings
— audit/fault settings
— authentication details
— built-in context variables (all other variables local to the policy being run)
– Details in SOAP faults will not include details for global policies
– audit sink policy (if configured) will run after service policy and all global policies are completed
– policy fragments can be included in a global policy
* Supported assertions
– Apply Rate Limit Assertion on page
– Add Audit Detail Assertion on page
– Add Comment to Policy Assertion on page
– All Assertions Must Evaluate to True Assertion on page
– At Least One Assertion Must Evaluate to True Assertion on page
– Audit Messages in Policy Assertion on page
– Capture Identity of Requestor Assertion on page
– Compare Expression Assertion on page
– Continue Processing Assertion on page
– Customize Error Response Assertion on page
– Customize SOAP Fault Response Assertion on page
– Include Policy Fragment Assertion on page
– Limit Availability to Time/Days Assertion on page
– Limit Message Size Assertion on page
– Restrict Access to IP Address Range Assertion on page
– Send Email Alert Assertion on page
– Send SNMP Trap Assertion on page
– Set Context Variable Assertion on page
– Stop Processing Assertion on page
* Limitations of global policies: global policies will not be processed when:
– when the Gateway generates a policy for the SecureSpan XML VPN Client.
– when the Gateway generates the WS-SecurityPolicy document attached to a service WSDL.
– if policy debug tracing is enabled for a service.
– when the service policy is exported.
– in policy migrations.

Internal Use Policies

* wsdm-notifications policy:
– wsdm: web services distributed management
– evaluation for each WSDM notification message (added via WSDM Subscription Service internal service)
– adds a A Route via HTTP(S) assertion that routes to ${esmNotificationUrl}, which refers to the value of the “” tag of the Subscribe method in EsmSubscriptionManagementServiceBinding.
* Audit Message Filter (AMF) policy:
– removes sensitive data from messages
– protect data prior to auditing
– intended to be used in conjunction with the Audit Viewer policy
– message is audited under the following conditions:
1. The policy contains the Audit Messages in Policy assertion, configured with a sufficiently high level.
2. An assertion fails, causing the target message to be audited. (This assumes the audit.hinting cluster property is set to its default value of “true”.)
– Keep in mind:
— only one AMF policy can be created per Gateway cluster
— this policy cannot access context variables created by any other service policy of global policy
— the output of AMF policy must be text/xml for it to work with AV policy
* Audit Viewer
– used to reverse the actions of AMF policy
– can restrict data viewing to individual users
— uses a special “audit viewer” private key to enforce this restricted access
– only one AV policy can be created per Gateway cluster
— this policy cannot access context variables created by any other service policy of global policy
– audit message or detail to be processed must be in XML format (Content-Type text/xml)
– don’t use Run All Assertions Concurrently assertion in AV policy
– default AV policy

Policy Structure

* Service request arrives
* Request is run through WS-Sec processor
– encrypted sections are decrypted and WS-Sec verified
– default security header can be optionally removed before routing
* Request is run through the policy assertions
– routing assertion sends a request to the service provider
– remainder of policy assertions are applied to the service response
* Response is run through the WS-Sec decorator
– default security header is created
– signatures specified by policy are applied
– encryption specified by the policy is performed
* Response is sent back to the client

Special Assertions

* At least one assertion must evaluate to true
* All assertions must evaluate to true

Hints and Tips

* Use Continue Processing assertion to prevent failure of a policy due to the failure of a non-essential assertion
* Some policy assertions work together and require the presence of each other to succeed:
– Require HTTP Basic Credentials
– Authenticate user or Group

* To add more than one user or group in a policy, you should 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).

* Put a Stop Processing assertion after any assertion whose sole purpose is to report on a prior error, for example:
– Audit Messages in Policy
– Send Email Alert
– Send SNMP Trap
– Return Template Response to Requestor.
Reason: These assertions always succeed, even though the intent is to halt the policy and send an HTTP challenge.
* Routing assertion usually should be placed last except:
* Assertions that operate on response should be placed after routing application
– Add Security Token (with target set to ‘Response’)
– Add Timestamp (with target set to ‘Response’)
– Encrypt Element (with target set to ‘Response’)
– Evaluate Response XPath
– Sign Element (with target set to ‘Response’)
– Validate XML Schema Apply XSL Transformation
* Assertions where you can specify the target message to be acted upon will be prefixed with
– “Request:”
– “Response:”
– or “${VARIABLE_NAME}” in the policy window.
For example:
– Request: Authenticate against XYZ
– or Response: Add signed Timestamp.
* Use Policy Validation Messages window to debug
* Use Copy and Paste options on the Edit menu to organize the policy
* Disable assertion instead of deleting
* Disable all assertions in a “All assertions…” folder –> folder succeeds
– Disable all assertions in a “At least one…” folder –> folder fails

Policy Revisions

* Default to 20 revisions
* A new revision is created each time the policy is saved, even if no changes have been made.
* Change with policyVersioning.maxRevisions cluster property
* Versions containing a comment are protected from being overwritten.
* Versions without a comment will be automatically overwritten when the revision limit is reached.
* To view revisions, right click service name and select Revision History

Policy Properties

* Tasks > Create Policy

Services and Policies Folders

* To create new folder: right click root or folder and select Create New Folder

* Also creates folder roles:

* Rename, Delete folder:

Service/Policy Aliases

* Overview:
– Folder cannot have aliases
– an entity may have multiple aliases
– deleting an original removes all its aliases
– deleting an alias does not affect original or other aliases
– access to alias = folder access + original access
* Create an alias:
– right click a service/policy and select Copy as Alias
– right click a destination folder and select Paste as Alias

Multiple Signatures

* To allow multiple signatures:
– select the [Allow multiple signatures] check box in the Require WS-Security Signature Credentials Assertion
– set the cluster property wss.processor.allowMultipleTimestampSignatures to “true“.

CRUD Policies

* Create policy: Tasks > Create Policy
* Disable policy: right click policy > select Revision History > click Clear Active

* Enable policy: right click policy > select Revision History > select revision > click Set Active

* Validate policy

Comments

* Add comment:
– Drag and drop Add Comment to Policy assertion

– Right click assertion and select Add Comment

Export/Import a Policy

Export

* Portable policy XML file exported includes:
– identity providers belonging to the users and groups in the policy
– JMS routing endpoints or destinations, if included in the policy
– any custom assertion, if present in the policy
* To export:

* To import:
– open target service

– drag and drop from Policy Templates > HelloWorldSvc_expPolicy.xml into target service policy

– OR click Import Policy and select HelloWorldSvc_expPolicy.xml
– Edit routing assertion

– validate
– save and activate

Debugging a Policy

Policy Debug Tracing

* For both SOAP and non-SOAP services
* Executes after each assertion has completed
* Captures the following and more:
– service OID
– service ordinal
– policy OID
– policy ordinal
– assertion status
* Best practice: configure an audit sink to be run in addition to a debug trace policy
* To enable:

* Internal Debug Trace Policy:

– shared by all published services that have tracing enabled
– more complex example:

* Save trace information to a file
– open Tasks > Manage Log/Audit Sinks and create a new log sink:

– open Tasks > Manage Cluster-wide Properties and set:
com.l7tech.server.trace.TracePolicyEvaluator.level = FINER
– Configure your trace policy to accumulate any desired trace information in the context variable ${trace.out}. For example, the policy sample under “More Complex Example” above is a good example
– When service consumption is complete, you can find the trace log file in this directory:
/opt/SecureSpan/Gateway/node/default/var/logs

Context Variables in Debug Trace Policy

* Only exists when
– used in a debug trace policy
– or within a policy fragment that is included in a debug trace policy

Managing Global Resources

* e.g. XML schema or DTD
* A global resource can be referenced by an import statement in
– ore or more Validate XML Schema assertions in a policy
– or from another global resource
* The referenced schema, or global schema, must exist in the Manage Global Resources table—and hence in the Gateway—in order for validation to proceed
* Schema dependencies (i.e., import targets) do not need to be in the Manage Global Resources table when monitoring a URL for a schema to validate (“Monitor URL for latest value” option in the Validate XML Schema assertion).
* Default global resources
– SOAP 1.1 and 1.2 XML Schemas:
http://schemas.xmlsoap.org/soap/envelope/ (SOAP 1.1)
http://www.w3.org/2003/05/soap-envelope/ (SOAP 1.2)
http://www.w3.org/2001/xml.xsd (XML namespace)
– DTDs:
http://www.w3.org/2001/XMLSchema.dtd (XML Schema)
http://www.w3.org/2001/datatypes.dtd (XML Schema Datatypes)

* To manage, click: Tasks > Manage Global Resources

* Import a global resource

* Edit a global resource

* Add XML Schema

* Remove a global resource
* Analyze a global resource

Manage UDDI Registries

References

* Layer 7 Policy Authoring User Manual Version 6.2