Layer 7 Policy Authoring

* Used to group assertions
* Can be used in any published service
* Two types of policy fragments:
– included policy fragments: need to be manually included in service policy
– global policy fragments: will run at predefined points, will not show in service policy
* Tasks:
– create a new policy fragment

– policy fragment revisions

– add a policy fragment to a policy
– delete a policy fragment
– edit a policy fragment
* Tips
– policy fragments are listed in the Services and Policies list
– can import items from a policy template into a fragment
– can not import items from UDDI registry
– you can drag and drop one fragment into another (fragment composition)
– policy fragments have their own revision history
– If the fragment contains assertions that create custom context variables and these variables will be referenced in an including policy, ensure that a Export Variables from Fragment assertion is added to the fragment.
— An example of assertions that create context variables are the XPath-based assertions (Evaluate Request XPath or Evaluate Response XPath).

* Open target service policy
* Drag and drop Include Policy Fragment assertion to desired position within service policy

* A policy defines restrictions for the consumption of a published service that is protected by the Gateway
* Policy assertions are building blocks for policies

* Access Control
* Transport Layer Security
* XML Security
* Message Validation/Transformation
* Message Routing
* Service Availability
* Logging, Auditing, and Alerts
* Policy Logic
* Threat Protection
* Internal Assertions
* Custom Assertions
* Policy Templates: contains exported policies

* Generate a keytab file for Layer 7. See here
* Open Tasks > Manage Cluster-Wide Properties and set krb5.kdc to target KDC IP address

* Open Tasks > Manage Kerberos Configuration
* Click Load Keytab button
* Browse to keytab file, e.g. layer7.keytab

* Loaded:

* Error: Could not login ‘Clock skew too great (37)’
– This is due to time sync off between Layer 7 and domain controller
– Solution:
— Setup NTP client on Layer 7 to use domain controller NTP server (ssh to gateway, select 1: Configure system settings, then 1: Configure networking and system time settings)
— Increase Maximum tolerance for computer clock synchronization setting in domain controller

* Authenticate users and/or groups from
– LDAP, e.g. AD

– Simple LDAP (cannot do groups)
– FIP (Federated IdP)
– IIP (Internal IdP)

* Only users, not groups, can be authenticated against simple LDAP

* Steps:
– extract credentials from preceding assertion
– send credentials to WS-Trust STS via WS-Trust RequestSecurityToken (RST) SOAP request
– extract RequestedSecurityToken (SAML or UsernameToken) from WS-Trust RequestSecurityTokenResponse (RSTR)
– replace original request’s credentials with RequestedSecurityToken
* Caveats:
– must configure the Route via HTTP(S) or Route via SecureSpan Bridge assertions to maintain the Security header in the message.
— The Exchange Credentials using WS-Trust assertion will be invalidated if the routing assertion in the policy is set to remove processed Security headers
— must select the “Leave current Security header in request before routing” option in the HTTP(S) Routing Properties that is used by both assertions.
– If the credentials in a message are covered by an XML Signature using the Sign Element assertion, then the signature will be invalidated when the credentials are replaced by the Exchange Credentials using WS-Trust assertion.

* Extracts information from X.509 Certificate of the last authenticated user and places them in context variables:
– subject/issuer DN fields
– some extended attributes
* Must be preceded by:
– at least one credential source assertion:
— Require SSL or TLS Transport with Client Authentication
— Require WS-Secure Conversation
— Require WS-Security Signature Credentials
— Require SAML Token Profile (Subject Confirmation: Holder of Key, Require Message Signature)
– an identity assertion, e.g. Authenticate User or Group

* Used to create context variables based on the attributes of a previously authenticated user
* Intended primarily to be used by Create SAML Token assertion
* Can also be read by any assertion that uses context variables

* Reads attributes from LDAP entries and stores them in context variables

* Requires an encrypted Username Token element to be present and that it be encrypted with the same key that was used to sign the timestamp or other parts of the message
* Requires message security features contained in WS-Security version 1.1 or later.

* Checks that a request contains a cookie with the same name as that specified in the assertion.
* If the request does not contain a cookie with this name, then the assertion fails.
* Does not check the validity or expiry of a cookie. It only checks for the presence of a cookie

* Need to pair with SecureSpan XML VPN Client.
* Enables the Windows Domain Injection feature in the SecureSpan XML VPN Client.

* Supports both the SAML 1.1 and 2.0 standards
* When used to validate an Attribute Statement, the attribute values that were validated are placed into context variables with the names: saml.attr.att_name

The Require SSH Credentials assertion allows you to require a user’s SSH credentials in a request. You can require either the user name and plain text password only, or the user name and public key only, or the user name and either the plain text password or the public key.
This assertion is a credential source that saves the user name with the password or public key from the SSH session for later authentication and authorization using the Authenticate User or Group Assertion

* Requires the presence of credentials from a Windows domain in the request
* Make sure no other credential sources (e.g. Require HTTP Basic Credentials) are present in the policy
* Places realm of the client into the kerberos.realm context variable
* Realm is displayed when using Manage Kerberos Configuration task

* Requires that the request message contains a valid WSS1.1 Kerberos Token (specifically, a GSS wrapped Kerberos v5 AP-REQ, as defined in the GSSAPI specification).
* This assertion places the realm of the client in the kerberos.realm context variable
* Must validate realm before performing authentication

* Requires WSS Digest token present and matches with username and password
* Can optionally check the presence of timestamp or nonce
– Does not check:
— timestamp expiration
— reuse of nonce

* Requires:
– presence of WS-Sec X.509 BinarySecurityToken containing a client certificate
– at least one element is signed
* Supports WS-Sec 1.0
* Best practices:
– use together with Protect Against Message Replay assertion to enforce timestamp

* Requires presence of
– user name
– plain text password
– authentication realm
* Supports WS-Sec 1.0

* Retrieves X.509 cert contained in a specified context variable

* Uses the credentials in a request message to obtain a SAML Browser Artifact from a SAML SSO endpoint

* Submits credentials from the current request to the local ADFS server
* Two modes of operation:
– Token request:
— submit previously authenticated login/password (by other assertions) to ADFS
— add successfully returned SAML token to current request’s SOAP security header
– Token exchange:
— submit previously authenticated SAML token to ADFS
— add successfully returned SAML token to current request’s SOAP security header

* Used to apply pending WS-Sec decorations to a message or to remove security headers
* Should be placed after the following WS-Sec assertions in a policy and if the target message is the request message or context variable
– Add Security Token
– Add Timestamp
– Configure WS-Sec Decoration
– Encrypt Element
– Sign Element

// TODO

* Used to add <wsu:Timestamp> element into the SOAP security header of all target messages
* You can:
– specify expiry time period
-choose the method used to include SSL cert for the Gateway

* Deprecated. Use Add Security Token Assertion instead

* Used to create a SOAP message containing a Request Security Token (RST) in the SOAP body.
* RST can be:
– Security Context Token (SCT)
– SAML oToken

* Used to create a SOAP response message containing a RequestSecurityTokenResponse (RSTR) element
* Two types of responses:
– token issuance
– token cancellation
* Example

<wst:RequestSecurityTokenResponse Context="..." xmlns:wst="...">
  <wst:TokenType>...</wst:TokenType>
  <wst:RequestedSecurityToken>
    // The issued security token appears here
  </wst:RequestedSecurityToken>
...
</wst:RequestSecurityTokenResponse>

* Context Variables created:
prefix.rstrResponse
prefix.wsaNamespace
prefix.rstrWsaAction

* Used to create a SAMLP request from either
– request message
– response message
– message variable
* Typically used with:
– Build SAML Protocol Request
– Route via HTTP(S)
– Evaluate SAML Protocol Response

// TODO

* Used to
– place a SAML token into a SAML Protocl Response message
– allow various attributes/elements of Response to be specified

* Used to cancel a security conversion session that is no longer in use
* Can be either:
– inbound
– outbound
* Cancel inbound session:
– cancel token
– build RSTR SOAP Response Assertion

<wst:RequestSecurityTokenResponse>
  <wst:RequestedTokenCancelled/>
</wst:RequestSecurityTokenResponse>

* Cancel outbound session:
– Outbound sessions are established using the Establish Outbound Secure Conversation assertion.
– You simply need to specify the URL of the session being cancelled

* Used to specify or override pending security decorations for a message
* Provides a convenient location to set security attributes that were previously configured in other assertions:
– WS-Security Version
– Signature Digest Algorithm
– Encryption Algorithm(s)
– Signature Key Reference
– Encryption Key Reference
– Add Timestamp
– Security Token Signing
– Key Encryption Algorithm
– Use DerivedKey Token
* Four tabs to configure:
– General
– Signing
– Encryption
– Advanced

* Used to create and optionally sign a SAML otken
// TODO

* Used to process an inbound message containing a RST request
* It will
– issue a Security Context Token (SCT)
– establish a secure conversation session
– save the session
* The secure conversation is mapped by the identifier defined in SCT

* Used to
– build a valid XACML request
– place it in the specified target (req msg, resp msg, or msg var)
* Can be used
– in Evaluate XACML Policy assertion
– routed to any other PDP for a decision
* Contains 4 attributes:
– Subject: 1 or more per request
– Resource: exactly one for XACML 1.0/1.1, 1 or more for XACML 2.0
– Action: exactly one per request
– Environment: exactly one for XACML 2.0, 1 or 1 for 1.0/1.1

* used to select message elements to be encrypted in target message:
– if the target is response message, encryption will occur automatically
– if the target is request message or a message CV, then Add or Remove WS-Security assertion must be added after the Encrypt Element assertion in the policy to perform the encryption
* Supports W3C Signature 1.0 standard
* Can only be used in a web service policy
– should be placed before the routing assertion in a policy

* Used to create a new secure outbound conversation session using the security context identifier extracted from a Security Context Token
* The outbound session includes a shared secret to be used for message decoration in future message exchanges
* Context variables created by this assertion:
– outboundSC.session
– outboundSC.session.<attribute> e.g. ${outboundSC.session.id}
id: The session identifier
user: The authenticated user
providerId: The user’s Identity Provider ID
id: The user’s identifier
login: The user’s login ID
firstName: The user’s first name
lastName: The user’s last name
email: The user’s email address
department: The user’s department
subjectDn: The user’s X.509 subject DN
creation: The session creation time
expiration: The session’s expiration time
scNamespace: The namespace of WSSecure Conversation

* Used to evaluate a SAML protocol response

* Used to evaluate a XACML policy and renders an authorization decision for a resource based on the set of attributes found in a XACML request
* Fails with a policy that contains empty Description Element

* Used to lookup an outbound secure conversation session that has been mapped to the authenticated user and the back-end service on which the secure conversation session is established
* Succeeds if at least one unexpired session is found
* CV created (see here for session attributes):
– <.session e.g. scLookup.session.id

* Used to lookup trusted certs based on CN value
– store certs in a CV for later user in a policy

* Used to check the contents of the context variables produced by the (Non-SOAP)Verify XML Element Assertion

* used to immediately decrypt one or more EncryptedData elements in an XML message (non-soap)
* Context variables created:
– <prefix>.elementsDecrypted
– <prefix>.encryptionMethodsUris
– <prefix>.recipientCertificates

* Used to immediately encrypt one or more elements in an XML message (non-soap)

* Used to immediately sign one or more elements in an XML message (non-soap)
– use Sign Element Assertion for SOAP messages

* used to immediately verify one or more EncryptedData elements in an XML message (non-soap)
* Supports the special prefix ‘local:‘ in the ID attribute, for matching the namespace URI against the owning element rather than the attribute
* Context variables created:
– <prefix>.elementsVerified
– <prefix>.signatureMethodUris
– <prefix>.digestMethodUris
– <prefix>.signingCertificates
– <prefix>.signatureValues
– <prefix>.signatureElements

* Used to process RSTR response message to get the security context
* Context variables created:
– <prefix>.token
– <prefix>.createTime
– <prefix>.expiryTime
– <prefix>.serverEntropy
– <prefix>.fullKey
– <prefix>.keySize

* Used to protect Gateway against possible replay attacks
* Can be either cluster-wide (default) or per node
* Uses an internal reply ID
* Two modes:
– Default mode: reject if:
— dup creation times tamp in a msg
— expired time stamp
– creation time stamp is more than 30 days old
– Custom mode
* Considerations:
– place after an Authenticate User or Group assertion to improve performance
– should not be used in any policy that will process messages from JMS destinations that are configured with the “On completion” acknowledgement mode without a specified failure queue

* Check that specific message elements are encrypted in target message
* Intended for use in a web service policy
– Supports WS-Sec 1.0/1.1
* Should be placed before the routing assertion in a policy when targeting the request message

* Check that specific message elements in the target message have been signed by the specified identity
* Intended for use in a web service policy
– Supports WS-Sec 1.0/1.1
* Context variable created:
– ${prefix.element}: contains the signature element
– ${prefix.token.type}: contains token type, i.e. Kerberos, sAML, SymmetricKey, X.509
– ${prefix.token.element}: contains security token element, e.g. a binary security token
– ${prefix.token.attributes.*}: contains token attributes (X.509: cert, SAML: issuer.certificate, subject.certificate, signing.certifcate)

* Check for the presence of a timestamp in the target message:
– SOAP header contains a valid <wsu:Timestamp> element and the date contained is no more than one minute in the future
– an expiry date is present in the timestamp and that date is no more than one minute in the past
– an expiry time is present in the timestamp and the current time of the Gateway is no later than the <wsu:Created> time + the Maximum Expiry Time configured in this assertion or the request SOAP <wsu:Expires> time, whichever occurs earlier.
* Optionally check for security signature for all timestamps

* Used to sign selected message elements in the target message
– if target is response message, signing occur automatically
– if target is request message or message context variable, then the Add or Remove WS-Security assertion must be added after the Encrypt Element assertion in the policy to perform the signing
* Supports WS-Sec 1.0/1.1

* Check that policy is compliant with WS-Security 1.1 including:
– the Use WS-Security 1.1 assertion
– at least one WS-Security signing/encryption assertion enforced on the request (for example, Require WS-Security Signature Credentials, Require WS-Secure Conversation, Sign Element, Encrypt Element)
– at least one WS-Security signing/encryption assertion acting on the response (for example, Add Timestamp, Sign Element, Encrypt Element)

* Used to add custom headers to a message that will either be sent out over HTTP or returned as the default HTTP response
* Will always succeed

* Copies the inbound request exactly as it appears at the current point in the policy
– echo back request

* Used to define a message to be returned to the requestor
– useful for debugging messages

* Used to route requests to a backend FTP(S) server
– using passive mode FTP

* Used defines
– where a web service or XML application message is sent
– what authentication credentials to use
* If client authentication is requested by a service, then
– Gateway will use its certificate for the SSL-TLS handshake
* Supports HTTP 1.1 standard
* Automatically added when using
– Publish SOAP Web Service Wizard
– Create WSDL Wizard
– Publish XML Application Wizard
* Notes:
– Requests are routed downstream using the same HTTP verb (i.e. GET, POST) as incoming request
– HTTP POST is always used if request message source is a context variable

* URL: you can use context variables in URL, e.g.
– ${request.http.header.sample-http-header}
– http://${gateway.warehouse.hostname}/ACMEWarehouseWS/Service1.asmx
* How IP addresses should be retrieved:
– Lookup IP Addresses in DNS
– Use the following IP addresses
– Use multiple URLs
* IP fail strategy
– Ordered Sticky with Failover
– Random Sticky with Failover
– Round Robin
* Connection timeout:
– defined by io.outConnectTimeout cluster property
– defaults to 30 seconds
* Read timeout:
– defined by io.outTimeout cluster property
– defaults to 60 seconds
* Maximum retries
– choose between 1 and 100
– defaults to 3
* Follow Redirects:
– check to instruct the Route via HTTP(S) assertion to follow HTTP redirect responses from the downstream target.
– otherwise, redirect responses are sent back to the requestor.
* Assertion Outcome:
– Fail if target returns error status (>=400)
– Pass through SOAP faults with error status 500
– Never fail as long as target returns an answer

* Specify HTTP Credentials
* Use HTTP Credentials from Request
* Attach SAML Sender-Vouches
– enabled only for SOAP web service policies
* Send TAI (Trusted Association Interceptor) Header
* Use Windows Integrated
– use delegated credentials
– use Gateway Keytab
– use configured credendials
* TLS Version
* Current WSS Header Handling: specify how to handle security header
– Don’t modify the request Security header
– Remove Layer 7 actor and mustUnderstand attributes from processed Security header
– Remove processed Security header from request before routing
– Promote other security header as default before routing

* Used if the custom transport protocol “l7.raw.tcp” has been configured for a listen port.
* This assertion acts as a client of the server-side transport:
– it will
— transmit the request,
— close the sending side,
— read the response (if possible),
— and then initialize the response message with a preconfigured Content-Type.
* This assertion will succeed if the raw TCP routing is successful.

* User has no control
* Internal messages
* Severity levels:
– Fine
– Finer
– Finest
* Always available in the audit event log

* User can control with cluster property:
– audit.adminThreshod

* User has full control
* Generated during the processing of a policy
* Defaults to Warning
* Cluster properties to control thresholds:
– audit.messageThreshold
– audit.detailThreshold

* Add Audit Messages in Policy assertion
– set its trigger severity level to Warning which has results:
— Info becomes Warning
— Warning remains Warning
— Severe remains Severe

* Used to define a custom message in audit message

* Used to enable auditing of messages within a policy
* Records events related to the processing of a policy
– assertion violations
– authentication failures
– routing errors
* Events can be viewed in Gateway Audit Events window

* Used to capture requestor’s identity for auditing or reporting:
– requestor’s IP address
– requestor’s authenticated user ID
– value from a context variable that contains identifying info abou the requestor
* Can define upto 5 mappings in a Capture Identity of Requestor assertion

* Can be viewed in the Details tab of the Gateway Audit Events window

* Used to configure SOAP fault response on a policy-by-policy basis
* SOAP fault detail levels:
– Drop connection
– Generic SOAP fault
– Medium detail
– Full detail
– Template
* Must be placed within a message received or pre security global policy, i.e. at the beginning of the policy

* Built-in protectino
* Cannot be disabled

* All TCP/IP based attacks, e.g.
– ICMP flood
– ping of death
– routing redirect style attacks
* Coercive Parsing and XML Bomb
* External Entity Attack
– Gateway does not resolve external entities by default
– Gateway can be configured using the Evaluate Request XPath and Evaluate Response XPath assertions to block all messages containing references to external entities.
* Schema poisoning
– Schema poisoning involves an attacker attempting to compromise a system by replacing or tampering with the schema.
– Gateway does not load schemas from unauthorized locations
– All schemas must be loaded by the admin
– Dynamic loading is not permitted
* WSDL Scanning
* XML Routing Detours

* Used to specify a size limit for
– an entire message (including attachments)
– a port of XML message (not including attachments)
* Should be placed before the routing assertion in the policy

* Provides two mechanisms:
– double submit cookie validation: This can be used to validate the contents of a cookie that contains some session identifier, to see if it matches the same session identifier contained in a request parameter.
– HTTP referer validation:This can be used to ensure that the referer value belongs to a whitelist of domains. Although the referer domain is easily spoofed, this validation reduces the attack vectors for a CSRF attack.
* Context variable created:
– csrf.valid.token contains the value of the cookie

* Used to specify size limits for incoming XML requests
– protects against XDoS attacks using oversized files

see previous

* Checks request message for patterns associated with potential SQL injection attacks

* Allows Gateway to connect to an antivirus server that supports the ICAP protocol, such as McAfee®, Sophos®, or Symantec™.
* Context variables created:
– icap.response.infected
– icap.response.header.names.X
– icap.response.header.values.X
– icap.response.header.values.X.headerName

* Used to validate JSON data against JSON schema:
– validate JSON data structure
– validate JSON data property type
– validate JSON data property values

* Can be used to validate or change the Content-Type of any target message

* Protect against:
– XML parameter tampering
– XDoS attacks
* Schema is provided by Gateway Admin
* WSDL contained schema can also be extracted and used
* A policy can contain multiple Validate XML Schema assertions.
* Schema validation failure is captured in context variable ${chema.failure}
* Tarari Schema Validation Limitations
– can be used to accelerate schema validation

* Used to collect metrics for a specified resource that is interoperable with the Web Services Distributed Management (WSDM) specification.
* Automatically added to a policy when the WSDM QosMetrics internal service is published

* This assertion forwards GetMultipleResourceProperties requests to the Layer 7 implementation of the WSDM service
* Requires that the cluster property serviceMetrics.enabled be set to true (default setting).
* Supported metrics:
– muws2:OperationalStatus
– mows:NumberOfRequests
– mows:NumberOfFailedRequests
– mows:NumberOfSuccessfulRequests
– mows:ServiceTime
– mows:MaxResponseTime
– mows:LastResponseTime
– qosm:Throughput
– qosm:AvgResponseTime

* Converts current audit record into XML code as an in-memory DOM tree, overwriting the targeted message
* This assertion is designed to populate the request in an audit sink policy with some XML. The resulting XML is not enclosed in a SOAP envelope

* Processes the request as a management SOAP message
* Will populate the response message
* Automatically added to a policy when the Gateway Management internal service is published
* Context variables created:
– prefix.action
– prefix.entityType
– prefix.entityId
– prefix.message

* Used to send subscription requests to a specific resouce that is interoperable with the DoD Joint Web Services Distributed Management (WSDM) specification.
* Automatically added to a policy when the WSDM Subscription internal service is published
* Recognizes three methods:
– Subscribe
– Renew
– Unsubscribe

* Layer 7 Policy Authoring User Manual v6.2.pdf