Applying Policies to Services in JaxView

About Web Service Governance Policies

Some of the challenges facing small to medium-sized companies as they migrate to service-oriented architectures for business services is a cost effective means of integrating evolving or disparate systems and enforcing access and messaging policies. JaxView provides several useful policy and governance features to help IT development and operations teams meet these challenges. Along with its versatile performance monitoring capabilities, JaxView can be used as an authentication server for accessing Web services. When JaxView is used as a proxy or gateway to Web service producers, it can also be used to modifiy service requests and responses or to limit the size of number of messages that can be passed to service producers. The following table gives an overview of the policy subsections and the runtime governance capabilities available in JaxView.

Working with Service Governance Policies in JaxView

You create or edit Web service governance policies using Service node action menus in the the Services object tree. At present, service governance policies are not displayed as objects in the Services object tree. The following sections describe how to work with serve policies in JaxView.

Service Policy Object Assignment

Each Service node in the Services object tree may have policies defined for it. The Service node acts as a container for the policy definitions. Normally, you will define the policies for the operations of a particular service under the Service definition node for those operations. The policy is then active for all operations from that service location. The following is an illustration of the policy object assignment in JaxView.

With the object assignment model used by JaxView, the policies defined under one service node may be different than those applied under another node. Conversely, policies created and applied under one service node may be applied to another service nodes in the tree. This enables policies to be applied globally to any or all services.

Configuring Service Governance Policies in JaxView

The following is an outline of the steps you use to create a new Web service governance policy definition. See the sections below for more details about defining specific policies.

1. Select the Services tab from the Main View navigation menu.

2. Click on the Service node in the left side object tree menu for which you want to define governance policies.

3. Right-click the mouse to display the action menu for the node and select Edit. The Edit service page is displayed in the right panel.

4. Expand the applicable sub panels in the Policies section of the Service Edit page to define the governance policy. See the sections below for details of the properties used for each policy.

5. Click Save to record the policy.

Once you have defined service governance policies for one Service node they are active and in force for the service node under which they are defined. The same policy definition can be applied to other service definitions in the Services object tree. The following are the steps you use to apply a Web service governance policy to one or more Web services:

To apply policies to other Web service definitions:

1. Click on the Service node in the left side object tree menu for which you want to enable governance policies.

2. Right-click the mouse to display the action menu for the node and select Assign Policies to Services.

3. Expand the applicable sub panels in the Policies section of the Apply Policies page to that correspond with the governance policies you defined in the previous steps.

4. Check the check box in the applicable sub panel to activate the policy.

5. Use the Services assignment sub tree in the lower part of the page to select the service nodes to which the policy will be enforced. Click to expand the nodes in the menu tree as necessary and mark the check box to the left of the service name(s).

6. Click the Assign button to make the policy assignment.

The following figure illustrates the policy application in JaxView. As noted, you use the Edit option for the Service node to Assign Policies to Services option to assign them to another service node.

After policies are defined and applied, they remain in force until they are removed from the service nodes. To cancel or remove a policy, all the fields in the policy definition section that is to be canceled must be cleared. Use the following steps to cancel a policy.

To cancel policies for Web service definitions:

1. Select the Services tab from the Main View navigation menu

2. Click on the Service node in the left side object tree menu for which you want to define governance policies.

3. Right-click the mouse to display the action menu for the node and select Edit. The Edit service page is displayed in the right panel

4. Expand the applicable sub panels in the Policies section of the Service Edit page for the policy that is to be removed.

5. Clear all of the fields in the policy definition form.

6. Click Save to record the change.

The following sections describe the policy configuration properties and how to use them to create Web service governance policies in JaxView.

Request/Response Modification Policies

Use this section to define expressions that JaxView will use to modify the content of incoming request messages or response messages. Message modification policies are only effective when JaxView is used as a proxy for the service. The service requests and responses must be routed through JaxView in order to for the modification policies to be implemented. The policy is effective for messages to all operations under the service node to which it is applied.

To create a request/response modification policy:

1. Select the Services tab from the Main View navigation menu.

2. Click on the Service node in the left side object tree menu for which you want to define the modification policy

3. Right-click the mouse to display the action menu for the node and select Edit. The Edit service page is displayed in the right panel.

4. Expand the Request/Response Modification Policies sub panel in the Policies section of the Service Edit page.

5. To modify service request or response messages, enter one or more pattern matching expressions in the applicable Modification Expressions field. Separate multiple expressions with the XPATH: or REGEX: prefix indicating the applicable expression type. See the sections below for details of the properties used for each policy.

6. Enter the text to be substituted into the location(s) matched by the Modification expressions. For multiple pattern matching expressions, separate the substitution strings with commas, maintaining the order that maps to the expression where the string should be inserted.

7. Click Save to record the policy.

Request/Response Modification Policy Properties

Response Modification Expressions:

Enter one or more XPath expressions or regular expression patterns that JaxView should run against the response messages to locate the content strings to be replaced. You can have multiple expressions prefixed with the text string "XPATH:" or “REGEX:” to indicate the beginning of each expression string. For example, two XPath expressions can be entered as: XPATH//Post[@onlineResource]XPATH://Get[@onlineResource]. See the section JaxView Tools for examples of regular expression syntax.

Modify Response With:

Enter the text string or strings the JaxView should substitute into the response message. JaxView will replace the text matched by the pattern matching expressions in the Response Modification Expressions field above. For multiple replacement values, separate the text strings with commas. For example: http://appsrv1.company.com,http://ws.company.com.

Response Mod Class Name:

Optional: Use this drop down menu to select an user-provided class name to call to modify the response message. This is an alternative to using the “Response Modification Expressions” and “Modify Response With” fields above. This Java class must be located in the com.hubble.proxyserver.server.modresponse package path and must end with the naming pattern of : “...ModifyResponse.class”. See the section JaxView Open API for more information on this option.

Request Modification Expressions:

Enter one or more XPath expressions or regular expression patterns that JaxView should run against the request messages to locate the content strings to be replaced. You can have multiple expressions prefixed with the text string "XPATH:" or “REGEX:” to indicate the beginning of each expression string. For example, two XPath expressions can be entered as: XPATH//Post[@onlineResource]XPATH://Get[@onlineResource]. See the section JaxView Tools for examples of regular expression syntax.

Modify Request With:

Enter the text string or strings the JaxView should substitute into the request message. JaxView will replace the text matched by the pattern matching expressions in the Request Modification Expressions field above. For multiple replacement values, separate the text strings with commas. For example: http://appsrv1.company.com,http://ws.company.com.

Request Mod Class Name:

Optional: Use this drop down menu to select an user-provided class name to call to modify the request message. This is an alternative to using the “Request Modification Expressions” and “Modify Request With” fields above. This Java class must be located in the com.hubble.proxyserver.server.modrequest package path and must end with the naming pattern of : “...ModifyRequest.class”. See the section JaxView Open API for more information on this option.

Security Policies

The Security Policies sub section includes a number of properties used to enable service client authentication policies. You use this section to configure policies for the following governance options:

• Authentication using JaxView Client lists or an external LDAP data store
• Authentication of digitally signed requests
• Encryption of service response messages and decryption of XML encrypted requests
• Secure Socket Layer (SSL) hand shake between JaxView and the service endpoint

Some properties in this section are used both for the JaxView native authentication options and in combination with LDAP/AD Authentication Policies. As with other policies, Security policies are only valid when JaxView is used as a proxy server to the Web services being managed.

Security Policy Properties

The following describes the properties in the Security Policies section. The properties you define will depend on which policy type you want to enable.

Authenticate Clients

Use this section to have JaxView enforce user authentication when it is used as a proxy or service gateway.

Authenticate Clients

Check this box to have JaxView attempt to authenticate the request against the username and password for a record in the internal JaxView Client list. This option must be checked in addition to completing the other applicable fields in this section in order to activate authentication. If the username and password match a JaxView Client record, the message will be forwarded to the service location. See the Admin Tab section for more information on defining client records in JaxView.

Username Xpath:

Enter the XPath expression or regular expression that JaxView should use to extract the username in the request messages. Where the username is contained inside a SOAP envelope element Prefix the expression with the string “XPATH:”. This also could be a regular expression which will extract the username out of the header or the body of the request. See the section JaxView Tools for examples of regular expression syntax.

Password Xpath:

This is an XPath to tell JaxView how to get to the Password. JaxView will then replace the password before saving message to disk This also could be a regular Expression which will extract the password out of the header or the body of the request

Encryption/Decryption

Enable this option if JaxView is used as a proxy and if service requests or reponses need encryption or decryption before being forwarded to their destination.

Decrypt Request:

Check this box to have JaxView attempt to decrypt encrypted requests before sending them to the service producer. See the W3.org Web site for more information on XML encryption and decryption.

Encrypt Response:

Check this box to have JaxView encrypt response messages before sending them to the service consumer. See the W3.org Web site for more information on XML encryption and decryption.

Digital Signature

Use this option if incoming requests use XML digital signature.

Validate XML Digital Signature:

Check this box to have JaxView validate digitally signed requests before forwarding the request to the service. See the W3.org Web site for more information on XML digital Signatures.

Digital Certificates

This section is for Web services that require SSL certificate authentication. When JaxView is used as a proxy the certificate can be installed on the JaxView Server. This will have the effect of moving the SSL hand shake from the Web service endpoint to the JaxView server.

Server Side Certificate

KeyStore Path:

If digital signatures are used, enter the path of keyStore where the certificate is stored. See the section SSL Certificates with JaxView Proxy Configuration for more information on working with certificate keystores.

Key Password:

The password for the certificate in the keystore.

Key Store Password:

The password for accessing the keystore

SSL Port:

The port on which JaxView will listen for SSL requests for this Web service. NOTE: There needs to be a separate port for each Web service that uses an SSL connection.

WS-Security Validation

You use this section to setup JaxView to validate WS-Security headers in SOAP messages. The properties are similar to properties set in a deployment descriptor in an Apache Axis container. It can peform the certificate validation and decryption. You can find more information here.

Validate WSSE Request

Check this box to have JaxView validate the WS-Security request according to the properties set in the Axis WS-Security Properties entry field below this item.

Axis WS-Security Props

Enter the applicable Apache Axis Ws-Security Properties in this text area. An example property is:

passwordCallbackClass=org.apache.ws.axis.oasis.PWCallback 
action=Signature Signature 
signaturePropFile=crypto.properties

Secure Token Service Options

Use this section to configure JaxView to authenticate clients through a Secure Token Service. This can be done using WS-Trust or other protocols by customizing a class file in the JaxView package. JaxView includes a class that enables authentication using WS-Trust.

Secure Token Service

The secure token service to use. You can add a new secure token service from the Admin tab and STS node

STS Algorithm Class

This is the class that will be called when a request for this service comes in. This class will send the request to STS and awaits response before forwarding the request to the Web service. An example of this type of class file is found in:
<install_path>/JaxView/tomcat/webapps/Hubble/WEB-INF/classes/sts/WS_TRUST_STS.java.

You can create a new class and put it in this package and it will get loaded automatically. IMPORTANT: The class name must end with the letters "STS".

LDAP/AD Authentication

When used as a proxy server or gateway, JaxView can secure Web services using an LDAP database or Active Directory (AD). There are three options for doing this kind of authentication. The following describes these options and the settings that need to be used for each option.

Note: JaxView makes use of a substitution variables to match and retain the values from service messages. The LDAP/AD Authentication options make use of two of these variables. One of these, USER_ID, is used to construct certain policy property strings . In order to use these variables and configure the LDAP authentication policies, you must provide content match expressions for the Username Xpath and Password Xpath properties in the Security Policies sub section.

Options for LDAP Authentication

Option A

Direct LDAP server bind using user name and password from the request message. JaxView try to bind to the LDAP server with the user name and password in the request. If the binding is successful then the request is authenticated.

Use this option if:

• the relative location of the distinguished names (DN) in the Directory Information Tree of the users is known already and

• all users that need to be authenticated to this policy are found in the same relative location in the Directory Information Tree of the LDAP database.

The following are the steps you use to configure authentication option A:

1. Select the Services tab from the Main View navigation menu.

2. Click on the Service node in the left side object tree menu for which you want to define the modification policy

3. Right-click the mouse to display the action menu for the node and select Edit. The Edit service page is displayed in the right panel.

4. Expand the Security Policies sub panel in the Policies section of the Service Edit page.

5. Enter the XPath match expression or regular expression that will match on the username in the service request messages. This match will be assigne to the USER_ID retained value variable.

6. Enter the XPath match expression or regular expression that will match on the user password in the service request messages.

7. Expand the LDAP/AD Authentication Policies sub panel in the Policies section of the Service Edit page.

8. Click the Enable LDAP Authentication check box at the top of the sub panel. This box must be checked to enable the policy enforcement.

9. Enter the address for the LDAP or AD server to use for authentication in the LDAP Provider URL field.

10. Enter the string for the Security Principal field using the USER_ID retained value variable variable. For example, uid=[USER_ID],ou=operations, o=smecompany,dc=com.

11. Click Save to record the policy.

Option B

This option uses a defined security principal (not the [USER_ID] variable) and password to perform a query on the database for a user. JaxView will use the security principal and the default password to bind to the LDAP server and search using the search filter to find the DN for the user. If a DN is returned, JaxView then it uses the DN and the user password to rebind to the LDAP server. If any portion of this fails, JaxView will not authenticate the user and an error is sent in response.

Use this option if:

• the relative location of the distinguished names (DN) in the Directory Information Tree of the users is not known already and

• the DN for users that need to be authenticated to this policy are not all in the same relative location in the Directory Information Tree of the LDAP database.

The following are the steps you use to configure authentication option B:

1. Select the Services tab from the Main View navigation menu.

2. Click on the Service node in the left side object tree menu for which you want to define the modification policy

3. Right-click the mouse to display the action menu for the node and select Edit. The Edit service page is displayed in the right panel.

4. Expand the Security Policies sub panel in the Policies section of the Service Edit page.

5. Enter the XPath match expression or regular expression that will match on the username in the service request messages. This match will be assigne to the USER_ID retained value variable.

6. Enter the XPath match expression or regular expression that will match on the user password in the service request messages.

7. Expand the LDAP/AD Authentication Policies sub panel in the Policies section of the Service Edit page.

8. Click the Enable LDAP Authentication check box at the top of the sub panel. This box must be checked to enable the policy enforcement.

9. Enter the address for the LDAP or AD server to use for authentication in the LDAP Provider URL field. For example, ldap://dirsrv.smecompany.com:389.

10. Enter the string for the Security Principal field using a known, authorized user name. For example, uid=Manager,ou=operations, o=smecompany,dc=com.

11. Enter the password for the authorized user name in the Password field.

12. Enter the a valid LDAP search filter (see RFC 2554 for reference) to locate the user identified in the incoming request message. Use the USER_ID retained value variable. For example, (uid=[USER_ID]).

13. Enter the root DN in which the search should be made. For example, o=smecompany,dc=com .

14. Click Save to record the policy.

Option C

This option is similar to Option B except JaxView will search for Roles. The search filter entered needs to include the queries for the applicable roles that the service belongs to. If any result is returned then the request is authenticated. JaxView assumes that there is not a password in the request.

The following are the steps you use to configure authentication option C:

1. Configure the authentication policy using the steps for Option B above.

2. Check the Check in Roles option check box.

3. Enter the a valid LDAP search filter (see RFC 2554 for reference) to locate the user identified in the incoming request message and role query. Use the USER_ID retained value variable. For example, (uid=[USER_ID])(!(role=admin)(role=test))).

4. Click Save to record the policy.

LDAP/AD Authentication Policy Properties

The following describe the settings in the LDAP/AD Authentication sub panel.

Enable LDAP Authentication:

Check this box to enable LDAP authentication. The other fields on the form need to be filled in for LDAP authentication to take place.

LDAP Provider URL:

Enter the LDAP provider URL. For example: ldap://ldap.managedmethods.com:389

Security Principal:

Enter the LDAP security principal. For example:uid=testid,ou=test,o=ManagedMethods For option A the format is uid=[USER_ID],ou=test,o=ManagedMethods where [USER_ID] will be replace by the username in the request

Password:

Enter the password for above security principal entered above. This password needed if using option B or C for authentication. Please see documentation for more information.

Search Filter:

The search filter for the attribute the user name in the request corresponds to. See RFC 2254. For example (objectClass=user)(uid=[USER_ID]) where [USER_ID] will be replaced by userName in request. This is needed for LDAP Authentication option B. Please see documentation for more information.

Root DN:

The root security principal or distinguish name to search under for user in the incoming request. This is needed for LDAP Authentication option B and C. Please see documentation for more information.

Web Service General Policies

You use the Web Services General Policies section to set message size limits, service daily message traffic limits, or to configure JaxView to forward messages to another JaxView server for recording. The properties you define will depend on the policy you want to enable. The following describe the settings in the Web Services General Policies section.

Maximum Message Size:

This is the size of the maximum size of the messages being sent from the Stub or the proxy. If the request or response from your Service are of larger size you might no need the whole message sent back to JaxView server for processing. This is value will be the size limit on the message.

Processing Server URL:

If JaxView is being used as a proxy, there may be a need to separate the load on the the proxy server from the JaxView monitoring processing server for performance reasons. Adding this URL to the Web service policy will tell the JaxView proxy to forward the messages to the other server for processing instead of the local server.

Web Service Daily Threshold:

This is the number of the daily limit requests allowed to reach this web service. If left blank then there is no limit. Note that this is only when JaxView is used in a proxy configuration.

Days to Save Messages:

Enter the number of days for which messages sent to this Web service should be stored by JaxView. If this field is left blank, messages will be saved indefinitely; no messages will be deleted

Fault Element Name:

If response messages from the service use custom elements if faults are generated, enter one or more XML element tags in this field. Use a comma delimited list to include more than one element. Each tag name must be exactly as it appears in the response XML message, including character case. For example: <errorList>,<badBehaviour> JaxView sees any of these tags in response messages from this service, it will report that message as a fault instance.

JMS Policies

Use these settings in this section if JaxView is installed as a proxy in front of an Enterprise Service Bus (ESB) and service request messages need to be forwarded using the JMS protocol instead of the HTTP protocol.

The following describe the properties for the JMS policies option. You must add a ESB connection object for the ESB to which you want to send JMS messages. See the ESB/Message Broker section of the Admin tab for more information. You also must know the Topic Name and Queue Name to which messages sent to this service should be forwarded.

End Point ESB

Select the ESB that the target Web service endpoint is located on. JaxView will send a JMS message to a topic on this ESB. The list is populated with ESB objects that you define in the Admin tab. See the section Connecting to an Enterprise Service Bus or Message Broker for more information.

Topic Name

Enter the name of the topic which is to be the destination of the JMS SOAP message. Either a topic name or a queue name needs to be provided in this field.

Queue Name

Enter the name of the queue which is to be the destination JMS SOAP message. Either a topic name or a queue name needs to be provided.

Routing Policies

Use the Routing Policies section to define a pattern matching expression that JaxView should use as a criteria to re-route a message to a different service location. If the pattern expression is matched, JaxView will forward the message to the Service URL entered in this section. These policies are only effective when JaxView is used as a proxy server or service gateway.

Brokering and Routing Policies

Content Expression:

Enter a regular expression the JaxView will use to match content in the header or body of the request. If the match is made, JaxView will route the message to the URL entered in the Routing Service URL property.

Block requests:

Check this option if you want to completely block the request from being forwarded to a Web Service endpoint if the above Content Expression matches against the incoming request.

Response to client:

When using the Block requests option above, enter a response text string to be sent back to any client from whom a service request was blocked.

Routing Service URL:

Enter the URL of the Web service where messages should be re-routed if the content is matched by the Routing Regular Expression.
NOTE: If the service at the new routing location is unavailable the message will be routed to the original destination specified for the message.

Routing Schedule:

Use the drop down list to select the schedule during which message routing should be active. Selecting NONE means enable routing all day every day. See the Admin Tab section for more information on defining schedules in JaxView.

Roles

Roles in JaxView are defined to control the access and action permissions for different JaxView user profiles. User access roles are managed using the Roles node of the Admin object tree. You can also assign access to a service node using the Roles policy sub panel.

Roles:

To allow access to this Service node, select the JaxView roles from the list box to grant access to this Service object within JaxView. The change will be reflected in the definition for that role in the Admin tab.

WS-Policy

Use this section to activate an imported WS-Policy to the Web Service. Use the WS-Policy node in the admin tab to import new policies into the JaxView system.

Enforce WS-Policies

Check this box to have JaxView enforce all WS-Policies assigned according to the XPath or regular expression set in the policy definition. See the applicable policy definition object under the WS-Policy node of the Admin tab for the specifics of any policy expression.

WS-Policies

This area displays a list of WS-Polcy objects currently configured in JaxView. If no WS-Policy objects are set, the area will be blank. To activate a policy for the Web service you are editing, click the checkbox to the right of the policy title in the list displayed.

IMPORTANT: The Policy Expression associate with the WS-Policy object must return a valid match for ALL messages to which you want to apply the the selected WS-Policy See the section WS-Policy under the Admin tab for more information.

Block Web Service Operations

Use the Block Web Service Operations section to have JaxView block as requests to selected operations made available by a service endpoint. This can be useful when a service exposes operations that should not be accessible to external clients such as an internal system administration operation.
Note: This policy is only effective when JaxView is deployed as a service gateway or proxy.

To block access to a Web service operation:

1. Select the Services tab from the Main View navigation menu.
2. Click on the Service node in the left side object tree menu for which you want to block an operatione.
3. Right-click the mouse to display the action menu for the node and select Edit. The Edit service page is displayed in the right panel.
4. Expand the Block Web Service Operations section of the Service Edit page.
5. Select the checkbox to the left of the operation name that you want to block.
6. To have the operation blocked only during a certain schedule, select the applicable JaxView schedule item using the Operation Block Schedule drop down menu. To have the operation blocked at all times, select None.
7. To have an text message returned to clients making requests to the blocked service operation, enter the optional text string in the Client Response Message field for that operation.
8. Click Save to record the policy