This section describes the built-in run-time actions that you can include in run-time policies for virtual services. You use these actions only when you are using CentraSite Control to create run-time policies for virtual services. The content is organized under the following sections:
You can include the following kinds of built-in run-time actions in the run-time policies for virtual services:
Mediator provides two kinds of actions that support WS-SecurityPolicy 1.2: authentication actions and XML security actions.
Mediator uses the following authentication actions to verify that the requests for virtual services contain a specified WS-Security element:
Require WSS Username Token
|
Uses WS-SecurityPolicy authentication to validate user names and passwords that are transmitted in the SOAP message header for the WSS Username token. |
Require WSS X.509 Token
|
Identifies consumers based on a WSS X.509 token. |
Require WSS SAML Token
|
Uses a WSS Security Assertion Markup Language (SAML) assertion token to validate service consumers. |
These actions provide confidentiality (through encryption) and integrity (through signatures) for request and response messages.
Require Signing
|
Requires that a request's XML element (which is represented by an XPath expression) be signed. |
Require Encryption
|
Requires that a request's XML element (which is represented by an XPath expression) be encrypted. |
Require SSL
|
Requires that requests be sent via SSL client certificates, and can be used by both SOAP and REST services. |
Require Timestamps
|
Requires that timestamps be included in the request header. Mediator checks the timestamp value against the current time to ensure that the request is not an old message. This serves to protect your system against attempts at message tampering, such as replay attacks. |
Mediator provides the following run-time monitoring actions:
Monitor Service Performance
|
This action monitors a user-specified set of run-time performance conditions for a virtual service, and sends alerts to a specified destination when these performance conditions are violated. |
Monitor Service Level
Agreement
|
This action provides the same functionality as "Monitor Service Performance" but this action is different because it enables you to monitor a virtual service's run-time performance especially for particular consumer(s). You can configure this action to define a Service Level Agreement (SLA), which is set of conditions that defines the level of performance that a specified consumer should expect from a service. |
Throttling Traffic
Optimization
|
(Not available in Mediator versions below 9.0.) This action limits the number of service invocations during a specified time interval, and sends alerts to a specified destination when the performance conditions are violated. You can use this action to avoid overloading the back-end services and their infrastructure, to limit specific consumers in terms of resource usage, etc. |
Mediator provides the following actions, which you can use in conjunction with the actions above.
Identify Consumer
|
You use this action in conjunction with an authentication action ("Require WSS Username Token", "Require WSS X.509 Token" or "Require HTTP Basic Authentication"). Alternatively, you can use this action alone to identify consumers only by host name or IP address. |
Require HTTP Basic
Authentication
|
This action uses HTTP basic authentication to verify the consumer's authentication credentials contained in the request's Authorization header against the Integration Server's user account. |
Authorize User
|
This action authorizes consumers against a list of users and/or a list of groups registered in the Integration Server on which Mediator is running. You use this action in conjunction with an authentication action "Require WSS Username Token", "Require WSS SAML Token" or "Require HTTP Basic Authentication". |
Authorize Against Registered
Consumers
|
This action authorizes consumer applications against all Application assets that are registered in CentraSite as consumers for the service. |
Log Invocations
|
Logs request/response payloads to a destination you specify. |
Validate Schema
|
Validates all XML request and/or response messages against an XML schema referenced in the WSDL. |
When you deploy a virtualized service, CentraSite automatically validates the service's run-time policy (or policies) to ensure that:
Any action that appears in a single policy multiple times is allowed to appear multiple times.
For those actions that can appear in a policy only once (for example, Identify Consumer), Mediator will choose only one, which might cause problems or unintended results.
All action dependencies are properly met. That is, some actions must be used in conjunction with another particular action.
CentraSite will inform you of any violation, and you will need to correct the violations before deploying the service.
When you deploy a virtual service to Mediator, CentraSite combines the actions specified within the service's run-time policy (or policies) that apply to the virtual service, and generates what is called the effective policy for the virtual service. For example, suppose your virtual service is within the scope of two run-time policies: one policy that performs a logging action and another policy that performs a security action. When you deploy the virtual service, CentraSite automatically combines the two policies into one effective policy. The effective policy, which contains both the logging action and the security action, is the policy that CentraSite actually deploys to Mediator with the virtual service.
When CentraSite generates the effective policy, it validates the resulting action list to ensure that it contains no conflicting or incompatible actions. If the list contains conflicts or inconsistencies, CentraSite resolves them according to Policy Resolution Rules. For example, an action list can include only one Identify Consumer action. If the resulting action list contains multiple Identify Consumer actions, CentraSite resolves the conflict by including only one of the actions (selected according to a set of internal rules) in the effective policy and omitting the others.
The effective policy that CentraSite produces for a virtual service is contained in an object called a virtual service definition (VSD). The VSD is given to Mediator when you deploy the virtual service. After you deploy a virtual service, you can view its VSD (and thus examine the effective policy that CentraSite generated for it) from the CentraSite user interface or from the Mediator user interface.
The following table shows:
The order in which Mediator evaluates the actions.
Action dependencies (that is, whether an action must be used in conjunction with another particular action).
Whether an action can be included multiple times in a single policy. If an action cannot be included multiple times in a single policy, Mediator selects just one for the effective policy, which may cause problems or unintended results.
Evaluation Order | Action | Dependency | Can include multiple times in a policy? |
---|---|---|---|
1 | Require SSL | None. | If multiple actions appear, and one of them has its Client Certificate Required parameter set to Yes, only one occurrence of the action appears in the effective policy. |
2 | Require HTTP Basic Authentication |
In Mediator versions below 9.0: None. In Mediator version 9.0 and above: Identify Consumer. |
No. Mediator includes only one action in the effective policy. |
3 | Require WSS Username Token | Identify Consumer action. | No. Mediator includes only one action in the effective policy. |
4 | Require WSS X.509 Token | Identify Consumer action. | No. Mediator includes only one action in the effective policy. |
5 | Require WSS SAML Token | None. | No. Mediator includes only one action in the effective policy. |
6 | Require Signing | Identify Consumer action. | Yes. Mediator generates a UNION of all Require Signing actions for the effective policy. |
7 | Require Encryption | Identify Consumer action. | Yes. Mediator generates a UNION of all Require Encryption actions for the effective policy. |
8 | Require Timestamps | Require SSL, Require Signing and Require Encryption. | No. Mediator includes only one action in the effective policy. |
9 | Identify Consumer | If Identify Consumer's identifier field is set
to:
|
No. Mediator includes only one action in the effective policy. |
10 | Authorize User | Require HTTP Basic Authentication, Require WSS Username Token or Require WSS SAML Token. | No. Mediator includes only one action in the effective policy. |
11 | Authorize Against Registered Consumers | Identify Consumer action. | No. Mediator includes only one action in the effective policy. |
12 | Validate Schema | None. | If at least one occurrence of the action is configured to validate requests, and at least one occurrence of the action is configured to validate responses, then Mediator includes in the effective policy an action to validate both requests and responses. Otherwise, an action is chosen which validates only requests or only responses (depending on the value of the Validate SOAP Messages parameter of the action). |
13 | Log Invocation | None. | No. Mediator includes only one action in the effective policy. |
14 | Monitor Service Performance | None. | Yes. Mediator includes all Monitor Service Performance actions in the effective policy. |
15 | Monitor Service Level Agreement | Identify Consumer action. | Yes. Mediator includes all Monitor Service Level Agreement actions in the effective policy. |
16 | Throttling Traffic Optimization | Identify Consumer (if the Limit Traffic for Applications option is selected). | Yes. Mediator includes all Throttling Traffic Optimization actions in the effective policy. |
When deciding which type of identifier to use to identify a consumer application, consider the following points:
Whatever identifier you choose to identify a consumer application, it must be unique to the application. Identifiers that represent user names are often not suitable because the identified users might submit requests for multiple applications.
Identifying applications by IP address or host name is often a suitable choice, however, it does create a dependency on the network infrastructure. If a consumer application moves to a new machine, or its IP address changes, you must update the identifiers in the application asset.
Using X.509 certificates or a custom token that is extracted from the SOAP message itself (using an XPATH expression), is often the most trouble-free way to identify a consumer application.
Following are some common combinations of actions used to authenticate/identify consumers.
The simplest way to identify consumers is to use the Identify
Consumer action and set its Identify User Using
parameter to specify either a host name or an IP address (or a range of IP
addresses).
Scenario 2: Authenticate consumers by HTTP authentication
token
Use the following actions:
Identify Consumer action, and set its Identify User
Using
parameter to HTTP Authentication Token (to identify consumers
using the token derived from the HTTP header).
Require HTTP Basic Authentication.
Additionally, you can use one or both of the following:
Authorize User action (to authorize a list of users and/or groups registered in the Integration Server on which Mediator is running).
Authorize Against Registered Consumers action (to authorize consumer applications against all Application assets registered as consumers for a service in CentraSite).
Scenario 3: Authenticate consumers by WS-Security authentication
token
Use the following actions:
Identify Consumer action, and set its Identify User
Using
parameter to WS-Security Authentication Token (to identify
consumers using the token derived from the WSS Header).
Require WSS Username Token action.
Additionally, you can use one or both of the following:
Authorize User action (to authorize a list of users and/or groups registered in the Integration Server on which Mediator is running).
Authorize Against Registered Consumers action (to authorize consumer applications against all Application assets registered as consumers for a service in CentraSite).
Identify Consumer action, and set its Identify User
Using
parameter to Consumer Certificate (to identify consumers
using the WSS X.509 token).
Require WSS X.509 Token action
Require SSL action.
This section describes the following built-in run-time actions that you can include in run-time policies for virtual services:
Note:
Dependency requirement: A policy that includes this action must also
include the Identify Consumer action.
However, if the Identify Consumer
action is set to identify users via the HTTP Authentication
Token option, then "Authorize Against Registered
Consumers" should not be included in the policy.
Authorizes consumer applications against all Application assets that are registered in CentraSite as consumers for the service.
None.
Note:
Dependency requirement: A policy that includes this action must also
include one of the following: the Require
WSS SAML Token action or the Identify
Consumer action with one of the following options selected:
"HTTP Authentication Token" or "WS-Security Authentication
Token".
Authorizes consumers against a list of users and/or a list of groups registered in the Integration Server on which Mediator is running.
Perform authorization against list of
users |
Boolean Authorizes consumers against a list of users who are registered in the Integration Server on which Mediator is running. Specify one or more users in the fields below this option. |
Perform authorization against list of
groups |
Boolean Authorizes consumers against a list of groups who are registered in the Integration Server on which Mediator is running. Specify one or more groups in the fields below this option. |
Note:
By default, both of the input parameters are selected. If you
de-select one of these parameters, the fields showing the list of users (or
groups) is not displayed.
Mediator uses this action to identify consumer applications based on the kind of consumer identifier (IP address, HTTP authorization token, etc.) you specify. Alternatively, this action provides an option to allow anonymous users to access the assets.
Anonymous
Usage Allowed |
Boolean Specifies whether to allow all users to access the asset, without restriction. | |
Value
|
Description
|
|
False |
Default. Allows only the users specified in the
|
|
True |
Allow all users to access the asset. In this case, do not
configure the |
|
Identify User
Using |
String Specifies the kind of consumer identifier that the action will use to identify consumer applications. | |
Value
|
Description
|
|
IP Address |
Identifies one or more consumer applications based on their originating IP addresses. | |
Host Name |
Identifies consumer applications based on a host name. | |
HTTP Authentication Token |
Uses HTTP Basic authentication to verify the consumer's authentication credentials contained in the request's Authorization header. Mediator authorizes the credentials against the list of users registered in the Integration Server on which Mediator is running. This type of consumer authentication is referred to as "preemptive authentication". If you want to use "preemptive authentication", you should also include the action Require HTTP Basic Authentication in the policy. If you choose to omit "Require HTTP Basic Authentication", the client will be presented with a security challenge. If the client successfully responds to the challenge, the user is authenticated. This type of consumer authentication is referred to as "non-preemptive authentication". For more information, see Require HTTP Basic Authentication. Note: |
|
WS-Security Authentication Token |
Validate user names and passwords that are transmitted in the SOAP message header in the WSS Username Token. If you select this value, you should also include the action Require WSS Username Token in the policy. | |
Custom Identification |
Validates consumer applications based on an XML element (represented by an XPath expression). | |
Consumer Certificate |
Identifies consumer applications based on information in a WSS X.509 certificate. If you select this value, you should also include the action Require WSS X.509 Token or the action Require Signing in the policy. | |
Client Certificate for SSL Connectivity |
Validates the client's certificate that the consumer application submits to the asset in CentraSite. The client certificate that is used to identify the consumer is supplied by the client to the Mediator during the SSL handshake over the transport layer. In order to identify consumers by transport-level certificates, the run-time communication between the client and the Mediator must be over HTTPS and the client must pass a valid certificate. To use this option, the following prerequisites must be met:
|
Logs request/response payloads. You can specify the log destination and the logging frequency. This action also logs other information about the requests/responses, such as the service name, operation name, the Integration Server user, a timestamp, and the response time.
Note:
You can include this action multiple times in a policy.
Log the
Following Payloads |
String Optional. Specifies whether to log all request payloads, all response payloads, or both. | |
Value
|
Description
|
|
Request |
Log all request payloads. | |
Response |
Log all response payloads. | |
Log Generation
Frequency |
String Specifies how frequently to log the payload. | |
Value
|
Description
|
|
Always |
Log all requests and/or responses. | |
On Success |
Log only the successful responses and/or requests. | |
On Failure |
Log only the failed requests and/or responses. | |
Send Data
To |
String Specifies where to log
the payload.
Important: |
|
Value
|
Description
|
|
CentraSite |
Logs the payloads in the virtual service's Events profile in CentraSite. Prerequisite: You must configure Mediator to communicate with CentraSite (in the Integration Server Administrator, go to ). For the procedure, see the section Configuring Communication with CentraSite in the document Administering webMethods Mediator. |
|
Local Log |
Logs the payloads in the server log of the Integration Server on which Mediator is running. Also choose a value in the
Important: |
|
SNMP |
Logs the payloads in CentraSite's SNMP server or a third-party SNMP server. Prerequisite: You must configure the SNMP server destination (in the Integration Server Administrator, go to ). For the procedure, see the section SNMP Destinations for Run-Time Events in the document Administering webMethods Mediator. |
|
|
Sends the payloads to an SMTP email server, which sends them to the email address(es) you specify here. Mediator sends the payloads as email attachments that are compressed using gzip data compression. To specify multiple addresses, use the button to add rows. Prerequisite: You must configure the SMTP server destination (in the Integration Server Administrator, go to ). For the procedure, see the section SMTP Destinations for Run-Time Events in the document Administering webMethods Mediator. |
|
Audit Log |
Logs the payload to the Integration Server audit logger. For information, see the webMethods Audit Logging Guide. Note: |
This action monitors a user-specified set of run-time performance conditions for a virtual service, and sends alerts to a specified destination when the performance conditions are violated. You can include this action multiple times in a single policy.
For the counter-based metrics (Total Request Count, Success Count, Fault Count), Mediator sends an alert as soon as the performance condition is violated, without having to wait until the end of the metrics tracking interval. You can choose whether to send an alert only once during the interval, or every time the violation occurs during the interval. (Mediator will send another alert the next time a condition is violated during a subsequent interval.) For information about the metrics tracking interval, see The Metrics Tracking Interval.
For the aggregated metrics (Average Response Time, Minimum Response Time, Maximum Response Time), Mediator aggregates the response times at the end of the interval, and then sends an alert if the performance condition is violated.
This action does not include metrics for failed invocations.
Note:
To enable Mediator to publish performance metrics, you must
configure Mediator to communicate with CentraSite (in the Integration Server
Administrator, go to ). For the procedure, see the
section Configuring Communication with CentraSite in the
document Administering webMethods Mediator.
Action Configuration
parameters |
Specify one or more conditions to monitor. To do this, specify a metric, operator, and a value for each metric. To specify multiple conditions, use the button to add multiple rows. If multiple parameters are used, they are connected by the AND operator. | |
Name |
String Array The metrics to monitor. | |
Value
|
Description
|
|
Availability |
Indicates whether the service was available to the specified consumers in the current interval. | |
Average Response Time |
The average amount of time it took the service to complete all invocations in the current interval. Response time is measured from the moment Mediator receives the request until the moment it returns the response to the caller. | |
Fault Count |
The number of faults returned in the current interval. | |
Maximum Response Time |
The maximum amount of time to respond to a request in the current interval. | |
Minimum Response Time |
The minimum amount of time to respond to a request in the current interval. | |
Successful Request Count |
The number of successful requests in the current interval. | |
Total Request Count |
The total number of requests (successful and unsuccessful) in the current interval. | |
String Array Choose an appropriate operator. | ||
Operator |
||
Value |
String Array Specify an appropriate value. | |
Alert
parameters |
Object Specify the following parameters for the alerts that will report on the conditions: | |
Alert
Interval |
Number The time period (in minutes) in which to monitor performance before sending an alert if a condition is violated. For information about the metrics tracking interval, see The Metrics Tracking Interval. | |
Alert
Frequency |
String Specifies how frequently to issue alerts for the counter-based metrics (Total Request Count, Success Count, Fault Count). | |
Value
|
Description
|
|
Every Time |
Issue an alert every time one of the specified conditions is violated. | |
Only Once |
Issue an alert only the first time one of the specified conditions is violated. | |
Reply to
Destination |
String Specifies
where to send the alerts.
Important: |
|
Value
|
Description
|
|
CentraSite |
Sends the alerts to the virtual service's Events profile in CentraSite. Prerequisite: You must configure Mediator to communicate with CentraSite (in the Integration Server Administrator, go to ). For the procedure, see the section Configuring Communication with CentraSite in the document Administering webMethods Mediator. |
|
Local Log |
Sends the alerts to the server log of the Integration Server on which Mediator is running. Also choose a value in the
Important: |
|
SNMP |
Sends the alerts to CentraSite's SNMP server or a third-party SNMP server. Prerequisite: You must configure the SNMP server destination (in the Integration Server Administrator, go to ). For the procedure, see the section SNMP Destinations for Run-Time Events in the document Administering webMethods Mediator. |
|
|
Sends the alerts to an SMTP email server, which sends them to the email address(es) you specify here. To specify multiple addresses, use the button to add rows. Prerequisite: You must configure the SMTP server destination (in the Integration Server Administrator, go to ). For the procedure, see the section SMTP Destinations for Run-Time Events in the document Administering webMethods Mediator. |
|
Alert
Message |
String Optional. Specify a text message to include in the alert. |
Note:
Dependency requirement: A policy that includes this action must also
include the Identify Consumer
action.
This action is similar to the Monitor Service Performance action. Both actions can monitor the same set of run-time performance conditions for a virtual service, and then send alerts when the performance conditions are violated. This action is different because it enables you to monitor run-time performance for one or more specified consumers. You can include this action multiple times in a single policy.
You can configure this action to define a Service Level Agreement (SLA), which is a set of conditions that defines the level of performance that a consumer should expect from a service. You can use this action to identify whether a service's threshold rules are met or exceeded. For example, you might define an agreement with a particular consumer that sends an alert to the consumer if responses are not sent within a certain maximum response time. You can configure SLAs for each virtual service/consumer application combination.
For the counter-based metrics (Total Request Count, Success Count, Fault Count), Mediator sends an alert as soon as the performance condition is violated, without having to wait until the end of the metrics tracking interval. You can choose whether to send an alert only once during the interval, or every time the violation occurs during the interval. (Mediator will send another alert the next time a condition is violated during a subsequent interval.) For information about the metrics tracking interval, see The Metrics Tracking Interval.
For the aggregated metrics (Average Response Time, Minimum Response Time, Maximum Response Time), Mediator aggregates the response times at the end of the interval, and then sends an alert if the performance condition is violated.
This action does not include metrics for failed invocations.
Note:
To enable Mediator to publish performance metrics, you must
configure Mediator to communicate with CentraSite (in the Integration Server
Administrator, go to ). For the procedure, see the
section Configuring Communication with CentraSite in the
document Administering webMethods Mediator.
Action Configuration
parameters |
Specify one or more conditions to monitor. To do this, specify a metric, operator, and value for each metric. To specify multiple conditions, use the button to add multiple rows. If multiple parameters are used, they are connected by the AND operator. | |
Name |
String Array The metrics to monitor. | |
Value
|
Description
|
|
Availability |
Indicates whether the service was available to the specified consumers in the current interval. | |
Average Response Time |
The average amount of time it took the service to complete all invocations in the current interval. Response time is measured from the moment Mediator receives the request until the moment it returns the response to the caller. | |
Fault Count |
Indicates the number of faults returned in the current interval. | |
Maximum Response Time |
The maximum amount of time to respond to a request in the current interval. | |
Minimum Response Time |
The minimum amount of time to respond to a request in the current interval. | |
Successful Request Count |
The number of successful requests in the current interval. | |
Total Request Count |
The total number of requests (successful and unsuccessful) in the current interval. | |
String Array Choose an appropriate operator. | ||
Operator |
||
Value |
String Array Specify an appropriate value. | |
Alert for Consumer
Applications |
Object Array Specify the Application asset(s) to which this Service Level Agreement will apply. To specify multiple Application assets, use the button to add multiple rows. | |
Alert
parameters |
Object Specify the following parameters for the alerts that will report on the Service Level Agreement conditions: | |
Alert
Interval |
Number The time period (in minutes) in which to monitor performance before sending an alert if a condition is violated. For information about the metrics tracking interval, see The Metrics Tracking Interval. | |
Alert
Frequency |
String Specifies how frequently to issue alerts for the counter-based metrics (Total Request Count, Success Count, Fault Count). | |
Value
|
Description
|
|
Every Time |
Issue an alert every time one of the specified conditions is violated. | |
Only Once |
Issue an alert only the first time one of the specified conditions is violated. | |
Reply to
Destination |
String Specifies where to log
the alert.
Important: |
|
Value
|
Description
|
|
CentraSite |
Sends the alerts to the virtual service's Events profile in CentraSite. Prerequisite: You must configure Mediator to communicate with CentraSite (in the Integration Server Administrator, go to ). For the procedure, see the section Configuring Communication with CentraSite in the document Administering webMethods Mediator. |
|
Local Log |
Sends the alerts to the server log of the Integration Server on which Mediator is running. Also choose a value in the
Important: |
|
SNMP |
Sends the alerts to CentraSite's SNMP server or a third-party SNMP server. Prerequisite: You must configure the SNMP server destination (in the Integration Server Administrator, go to ). For the procedure, see the section SNMP Destinations for Run-Time Events in the document Administering webMethods Mediator. |
|
|
Sends the alerts to an SMTP email server, which sends them to the email address(es) you specify here. To specify multiple addresses, use the button to add rows. Prerequisite: You must configure the SMTP server destination (in the Integration Server Administrator, go to ). For the procedure, see the section SMTP Destinations for Run-Time Events in the document Administering webMethods Mediator. |
|
Alert
Message |
String Optional. Specify a text message to include in the alert. |
Requires that a request's XML element (which is represented by an XPath expression) be encrypted. This action supports WS-SecurityPolicy 1.2 and cannot be used with REST services.
Configure Integration Server: Set up keystores and truststores in Integration Server, as described in Securing Communications with the Server in the document Administering webMethods Integration Server.
Configure Mediator: In the Integration Server Administrator, navigate to Solutions > Mediator > Administration > General and complete the IS Keystore Name, IS Truststore Name and Alias (signing) fields, as described in Keystore Configuration in the document Administering WebMethods Mediator.
When this policy action is set for the virtual service, Mediator provides decryption of incoming requests and encryption of outgoing responses. Mediator can encrypt and decrypt only individual elements in the SOAP message body that are defined by the XPath expressions configured for the policy action. Mediator requires that requests contain the encrypted elements that match those in the XPath expression. You must encrypt the entire element, not just the data between the element tags. Mediator rejects requests if the element name is not encrypted.
Important:
Do not encrypt the entire SOAP body because a SOAP request
without an element will appear to Mediator to be malformed.
Mediator attempts to encrypt the response elements that match the XPath expressions with those defined for the policy. If the response does not have any elements that match the XPath expression, Mediator will not encrypt the response before sending. If the XPath expression resolves a portion of the response message, but Mediator cannot locate a certificate to encrypt the response, then Mediator sends a SOAP fault exception to the consumer and a Policy Violation event notification to CentraSite.
The Require Encryption action encrypts the response back to the client by dynamically setting a public key alias at run time. Mediator determines the public key alias as follows:
If Mediator can access the X.509 certificate of the client (based on the incoming request signature), it will use "useReqSigCert" as the public key alias.
OR
If the Identify Consumer action is present in the policy (and it successfully identifies a consumer application), then Mediator will look for a public key alias with that consumer name in the "IS Keystore Name" property. The "IS Keystore Name" property is specified in the Integration Server Administrator, under Solutions > Mediator > Administration > General. This property should be set to an Integration Server keystore that Mediator will use.
For an Identify Consumer action that allows for anonymous usage, Mediator does not require a consumer name in order to send encrypted responses. In this case, Mediator can use one of the following to encrypt the response in the following order, depending on what is present in the security element:
A signing certificate.
Consumer name.
WSS username, SAML token or X.509 certificate.
HTTP authorized user.
OR
If Mediator can determine the current IS user from the request (i.e., if an Integration Server WS-Stack determined that Subject is present), then the first principal in that subject is used.
OR
If the above steps all fail, then Mediator will use either the WS-Security username token or the HTTP Basic-Auth user name value. There should be a public key entry with the same name as the identified username.
Note:
You can include this action multiple times in a single
policy.
Namespace |
String Optional. Namespace of the element required to be encrypted. Note: The generated XPath element in the policy should look similar to this: <sp:SignedElements xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"> <sp:XPath xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">//soapenv:Body</sp:XPath> </sp:SignedElements> |
Element Required to be
Encrypted |
String An XPath expression that represents the XML element that is required to be encrypted. |
This action uses HTTP Basic authentication to verify the consumer's authentication credentials contained in the request's Authorization header. Mediator authorizes the credentials against the list of users registered in the Integration Server on which Mediator is running. This type of consumer authentication is referred to as "preemptive authentication". If you want to perform "preemptive authentication", a policy that includes this action must also include the Identify Consumer action.
If the user/password value in the Authorization header cannot be authenticated as a valid Integration Server user (or if the Authorization header is not present in the request), a 500 SOAP fault is returned, and the client is presented with a security challenge. If the client successfully responds to the challenge, the user is authenticated. This type of consumer authentication is referred to as "non-preemptive authentication". If the client does not successfully respond to the challenge, a 401 "WWW-Authenticate: Basic" response is returned and the invocation is not routed to the policy engine. As a result, no events are recorded for that invocation, and its key performance indicator (KPI) data are not included in the performance metrics.
If you choose to omit the "Require HTTP Basic Authentication" action (and regardless of whether an Authorization header is present in the request or not), then:
Mediator forwards the request to the native service, without attempting to authenticate the request.
The native service returns a 401 "WWW-Authenticate: Basic" response, which Mediator will forward to the client; the client is presented with a security challenge. If the client successfully responds to the challenge, the user is authenticated.
In the case where a consumer sends a request with transport credentials (HTTP Basic authentication) and message credentials (WSS Username or WSS X.509 token), the message credentials take precedence over the transport credentials when Integration Server determines which credentials it should use for the session. For more information, see Require WSS Username Token and Require WSS X.509 Token. In addition, you must ensure that the service consumer that connects to the virtual service has an Integration Server user account.
Note:
Do not include the "Require HTTP Basic Authentication"
action in a virtual service's run-time policy if you selected the
OAuth2 option in the virtual service's Routing Protocol
step.
Note:
This input parameter is not available in Mediator versions prior to
9.0.
Authenticate
Credentials |
Required. Authorizes consumers against the list of users registered in the Integration Server on which Mediator is running. |
This action requires that a request's XML element (which is represented by an XPath expression) be signed. This action supports WS-SecurityPolicy 1.2.
Configure Integration Server: Set up keystores and truststores in Integration Server, as described in Securing Communications with the Server in the document Administering webMethods Integration Server.
Configure Mediator: In the Integration Server Administrator, navigate to Solutions > Mediator > Administration > General and complete the IS Keystore Name, IS Truststore Name and Alias (signing) fields, as described in Keystore Configuration in the document Administering WebMethods Mediator. Mediator uses the signing alias specified in the Alias (signing) field to sign the response.
When this action is set for the virtual service, Mediator validates that the requests are properly signed, and provides signing for responses. Mediator provides support both for signing an entire SOAP message body or individual elements of the SOAP message body.
Mediator uses a digital signature element in the security header to verify that all elements matching the XPath expression were signed. If the request contains elements that were not signed or no signature is present, then Mediator rejects the request.
Notes:
Namespace |
String Optional. Namespace of the element required to be signed. Note: The generated XPath element in the policy should look similar to this: <sp:SignedElements xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"> <sp:XPath xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">//soapenv:Body</sp:XPath> </sp:SignedElements> |
Element Required to be
Signed |
String An XPath expression that represents the XML element that is required to be signed. |
Requires that requests be sent via SSL client certificates. This action supports WSSecurityPolicy 1.2 but can be used for both SOAP and REST services.
When this policy action is set for the virtual service, Mediator ensures that requests are sent to the server using the HTTPS protocol (SSL). The policy also specifies whether the client certificate is required. This allows Mediator to verify the client sending the request. If the policy requires the client certificate, but it is not presented, Mediator rejects the message.
When a client certificate is required by the policy, the Integration Server HTTPS port should be configured to request or require a client certificate.
Client
Certificate Required |
Boolean Specifies
whether client certificates are required for the purposes of:
|
|
Value
|
Description
|
|
Yes |
Require client certificates. | |
No |
Default. Do not require client certificates. |
Note:
Dependency requirement: A policy that includes this action must also
include all of the following actions: Require
SSL, Require Signing,
Require Encryption.
When this policy action is set for the virtual service, Mediator requires that timestamps be included in the request header. Mediator checks the timestamp value against the current time to ensure that the request is not an old message. This serves to protect your system against attempts at message tampering, such as replay attacks. This action supports WS-SecurityPolicy 1.2 and cannot be used with REST services.
Mediator rejects the request if either of the following happens:
Mediator receives a timestamp that exceeds the time defined by the timestamp element.
A timestamp element is not included in the request.
None.
When this action is set for a virtual service, Mediator uses a WSS Security Assertion Markup Language (SAML) assertion token to validate service consumers. This action supports WS-SecurityPolicy 1.2 and cannot be used with REST services and cannot be used with REST services.
For more information about configuring your system for SAML token processing, see SAML Support in Mediator in the document Administering webMethods Mediator.
SAML Subject
Confirmation |
String Select one of the following SAML subject confirmation methods: |
|
Value
|
Description
|
|
Holder of Key |
Default. Select this option if consumers use the SAML V1.1 or V2.0 Holder-of-Key Web Browser SSO Profile, which allows for transport of holder-of-key assertions. In this scenario, the consumer presents a holder-of-key SAML assertion acquired from its preferred identity provider to access a web-based resource at a service provider. If you select |
|
Bearer |
Select this option if consumers use SAML V1.1 Bearer token authentication, in which a Bearer token mechanism relies upon bearer semantics as a means by which the consumer conveys to Mediator the sender's identity. If you select Note: |
|
SAML
Version |
String Specifies the WSS SAML Token version to use: 1.1 or 2.0. |
Note:
Dependency requirement: A policy that includes this action must also
include the Identify Consumer action.
When this policy action is set for the virtual service, Mediator uses WS-SecurityPolicy authentication to validate user names and passwords that are transmitted in the SOAP message header for the WSS Username token. This action supports WS-SecurityPolicy 1.2 and cannot be used with REST services.
In the case where a consumer is sending a request with both transport credentials (HTTP basic authentication) and message credentials (WSS Username or X.509 token), the message credentials take precedent over the transport credentials when Integration Server is determining which credentials it should use for the session. For more information, see Require HTTP Basic Authentication.
Mediator rejects requests that do not include the username token and password of an Integration Server user. Mediator only supports clear text passwords with this kind of authentication
None.
Note:
Dependency requirement: A policy that includes this action must also
include the Identify Consumer action.
Identifies consumers based on a WSS X.509 token. This action supports WSSecurityPolicy 1.2 and cannot be used with REST services.
In the case where a consumer is sending a request with both transport credentials (HTTP Basic authentication) and message credentials (WSS X.509 token or WSS Username), the message credentials take precedence over the transport credentials when Integration Server is determining which credentials it should use for the session. For more information, see Require HTTP Basic Authentication. In addition, you must ensure that the service consumer that connects to the virtual service has an Integration Server user account.
None.
Notes:
Limit Traffic for Applications
option is
selected.
This action limits the number of service invocations during a specified time interval, and sends alerts to a specified destination when the performance conditions are violated.
Reasons for limiting the service invocation traffic include:
To avoid overloading the back-end services and their infrastructure.
To limit specific consumers in terms of resource usage (that is, you can use the "Monitor Service Level Agreement" action to monitor performance conditions for a particular consumer, together with "Throttling Traffic Optimization" to limit the resource usage).
To shield vulnerable servers, services, and even specific operations.
For service consumption metering (billable pay-per-use services).
Note:
To enable Mediator to publish performance metrics, you must
configure Mediator to communicate with CentraSite (in the Integration Server
Administrator, go to ). For the procedure, see the
section Configuring Communication with CentraSite in the
document Administering webMethods Mediator.
Soft
Limit |
Number Optional.
Specifies the maximum number of invocations allowed per
Interval before issuing an alert. Reaching the soft
limit will not affect further processing of requests (until the Hard
Limit is reached).
Note: |
|
Hard
Limit |
Number Required.
Specifies the maximum number of invocations allowed per alert interval before
stopping the processing of further requests and issuing an alert. Typically,
this number should be higher than the soft limit.
Note: |
|
Limit Traffic for
Applications |
String Specifies the consumer application(s) that this action applies to. To specify multiple consumer applications, use the button to add rows, or select | to apply this action to any consumer application.|
Interval |
Number Specifies the amount of time for the soft limit and hard limit to be reached. | |
Frequency |
String Specifies how frequently to issue alerts. | |
Value
|
Description
|
|
Every Time |
Issue an alert every time the specified condition is violated. | |
Only Once |
Issue an alert only the first time the specified condition is violated. | |
Reply To
Destination |
String Optional.
Specifies where to log the alerts.
Important: |
|
Value
|
Description
|
|
CentraSite |
Sends the alerts to the virtual service's Events profile in CentraSite. Prerequisite: You must configure Mediator to communicate with CentraSite (in the Integration Server Administrator, go to ). For the procedure, see the section Configuring Communication with CentraSite in the document Administering webMethods Mediator. |
|
Local Log |
Sends the alerts to the server log of the Integration Server on which Mediator is running. Also choose a value in the
Important: |
|
SNMP |
Sends the alerts to CentraSite's SNMP server or a third-party SNMP server. Prerequisite: You must configure the SNMP server destination (in the Integration Server Administrator, go to ). For the procedure, see the section SNMP Destinations for Run-Time Events in the document Administering webMethods Mediator. |
|
|
Sends the alerts to an SMTP email server, which sends them to the email address(es) you specify here. To specify multiple addresses, use the button to add rows. Prerequisite: You must configure the SMTP server destination (in the Integration Server Administrator, go to ). For the procedure, see the section SMTP Destinations for Run-Time Events in the document Administering webMethods Mediator. |
|
Alert Message for Soft
Limit |
String Optional. Specify a text message to include in the soft limit alert. | |
Alert Message for Hard
Limit |
String Optional. Specify a text message to include in the hard limit alert. |
This action validates all XML request and/or response messages against an XML schema referenced in the WSDL.
Mediator can enforce this policy action for messages sent between services. When this policy is set for the virtual service, Mediator validates XML request messages, response messages, or both, against the XML schema referenced in the WSDL.
Validate SOAP
Message(s) |
Object Validates request and/or response messages. You may select both Request and Response. | |
Value
|
Description
|
|
Request |
Validate all requests. | |
Response |
Validate all responses. |
Important:
Be aware that Mediator does not remove
wsu:Id
attributes that may have been added to a
request by a consumer as a result of security operations against request
elements (i.e., signatures and encryptions). In this case, to avoid schema
validation failures you would have to add a Request Processing step to the
virtual service so that the requests are passed to an XSLT transformation file
that removes the wsu:Id
attribute. For details
about the Request Processing step, see the section Virtual Services in
CentraSite Control .