Professional Documents
Culture Documents
Copyright 2005-2011 Layer 7 Technologies Inc. The Layer 7 Installation and Maintenance Manuals, the Layer 7 Policy Manager User Manual, the Layer 7 Policy Authoring User Manual, the SecureSpan XML VPN Client User Manual, and the Layer 7 Enterprise Service Manager User Manual are the copyright of Layer 7 Technologies Inc. All rights reserved. SecureSpan and CloudSpan are trademarks of Layer 7 Technologies Inc. (registration pending), and is protected by law in Canada, the United States, and other countries. All other trademarks and tradenames belong to their respective owners. Layer 7 Technologies Inc. reserves the right to change the information in this Manual without notice. The content in this Manual is confidential. No part of this Manual may be copied, transmitted, or saved for non-personal purposes without the written permission of Layer 7 Technologies Inc.
Contents
List of Figures ...................................................................................................................... ii List of Tables ....................................................................................................................... ii Chapter One: Introduction ................................................................................................... 1
Background ..................................................................................................................................... 1 About Layer 7 Technologies ........................................................................................................... 1 Why Layer 7? ................................................................................................................................... 1
Chapter Two: Mapping AXG Handlers, Routes, and Service Descriptors ............................3
Introduction ..................................................................................................................................... 3 Understanding Published Services ......................................................................................... 3 Understanding Policies ............................................................................................................ 3 Creating a Virtual Service ............................................................................................................... 4 Request Message Specification ..................................................................................................... 7 Transformation Extensions ............................................................................................................. 9 Response Message Specification .................................................................................................. 9
Chapter Three: Identity and Access Control ..................................................................... 11 Chapter Four: Using the AXG to L7 Migration Utility ......................................................... 13
Technical Overview ....................................................................................................................... 13 Dependencies ................................................................................................................. 13 Installing the Migration Utility ....................................................................................................... 13 Preparation ............................................................................................................................. 14 Using the Migration Utility ............................................................................................................. 15 Using a Browser ..................................................................................................................... 15 Using the Command Line ...................................................................................................... 17 Migration Utility Specifics ............................................................................................................. 18 Sample Policy After Migration ...................................................................................................... 23
Contents
Support Portal ........................................................................................................................ 28 Solutions Architects ............................................................................................................... 28 Professional Services ............................................................................................................ 29 Sample Policies ...................................................................................................................... 29
Index ................................................................................................................................. 31
List of Figures
Figure 1: Types of services you can publish ......................................................................................... 5 Figure 2: Allowing requests for operations not in the WSDL ............................................................... 5 Figure 3: Setting a custom resolution path .......................................................................................... 6 Figure 4: Associating a port with a specific service.............................................................................. 7 Figure 5: Manage Global Resources dialog .......................................................................................... 8 Figure 6: Compare Expression assertion .............................................................................................. 8 Figure 7: Apply XSL Transformation assertion...................................................................................... 9 Figure 8: Route via HTTP(S) assertion ................................................................................................ 10 Figure 9: Using the Access Control assertions ................................................................................... 11 Figure 10: Accessing the migration utility from a browser ................................................................ 15 Figure 11: Authenticating a user ......................................................................................................... 15 Figure 12: Cisco AXG configuration export ......................................................................................... 15 Figure 13: Migration results ................................................................................................................ 16 Figure 14: Reviewing global resources ............................................................................................... 17 Figure 15: Using the cURL command ................................................................................................. 17 Figure 16: Review migration results (command line) ........................................................................ 17 Figure 17: Sample policy after migration ............................................................................................ 23
List of Tables
Table 1: Contacting Layer 7 Technologies .......................................................................................... 27 Table 2: Layer 7 Documentation ......................................................................................................... 27
ii
Additional details and other important dates are available from Cisco at the link above.
Why Layer 7?
Layer 7 offers a proven migration path for existing users of the Cisco ACE XML Gateway. We have helped many customers move their Cisco policies to the fullysupported, industry-leading Layer 7 SecureSpan Gateway. The Layer 7 solution enables customers to: Choose the form factor that is best suited to their deployment environment The Layer 7 SecureSpan Gateway is available in multiple form factors: hardware appliance, software, virtualized appliance (VMWare, Amazon Machine Image, Xen, etc.)
Quickly create and more easily maintain new policies The Layer 7 SecureSpan Gateway includes a Policy Manager that provides a drag-and-drop editor to compose and maintain policies to shared services. These policies serve to: Establish trust and identity sources with existing infrastructure Implement authentication & authorization Ensure message confidentiality, and data integrity Enforce SLA conformance and service availability And much more
The Layer 7 SecureSpan Gateway supports a wide variety of built-in policy assertions, as well as an extensible custom assertion API, to handle any policy requirement that an organization may have.
Migrate policies according to their own project schedules The Layer 7 SecureSpan Gateway can be deployed alongside existing Cisco ACE XML Gateways allowing customers to gradually migrate policies, thereby minimizing any disruptions to services.
Understanding Policies
The Layer 7 Gateway is a Policy Enforcement Point. At runtime, the Layer 7 Gateway receives messages and applies applicable policies as it processes the messages. A Layer 7 Gateway policy contains policy assertions that are organized in a logical tree structure that is evaluated sequentially based on the outcome of previous assertions. The Layer 7 Policy Manager provides a graphical environment to make policy construction as easy as drag-and-drop. But at their core, policies are simply XML files that you can share, export, import, or manipulate programmatically. Layer 7 policies define the behaviour to be used for message validation, access control, routing, transformation, rate limiting, encryption, signatures, and any other aspect of runtime message processing. There are five types of policies: Service Policy: This is the main policy associated with a published service. Each published service has one and only one service policy. For more information, see Working with Service Policies in the Layer 7 Policy Authoring User Manual. Policy Fragment: This is a policy that can be inserted into other policies in any published service. A policy fragment can be thought of as a boilerplate to save
time and help maintain consistency when authoring a policy. For more information, see Working with Policy Fragments in the Layer 7 Policy Authoring User Manual. Global Policy: These are policies that are always run before or after every service policy. They can be used to configure global behaviours such as auditing or logging. Similar to policy fragments, global policies can help ensure consistency and reduce errors. For more information, see Working with Global Policies in the Layer 7 Policy Authoring User Manual. Audit Sink Policy: This is a special policy that can be configured to direct audit messages to an external database, message queue, or other location. It is created by enabling the audit sink. For more information, see Working with the Audit Sink Policy in the Layer 7 Policy Manager User Manual. Internal Use Policies: This is a special preconfigured policy designed for a special purpose. Currently, there are three prepackaged internal use policies. For more information, see Working with Internal Use Policies in the Layer 7 Policy Authoring User Manual.
The main distinction between these two types of services is that the first one has a WSDL property while the second does not. The WSDL document associated with a SOAP Web Service is used for message classification at runtime and to return WSDL documents to front-end requestors. Note that the Layer 7 Gateway can still process SOAP messages from a published service of type REST, Web API, or Other Service.
As AXG does not easily process existing WSDLs when creating virtual services, it is common for AXG users to create a virtual service for a SOAP service but without using the WSDL of that service. To achieve the same approach in the Layer 7 Gateway, you can use either Publish REST, Web API or Other Service or Create WSDL, then complete the wizard without providing WSDL elements. This will leave you with a placeholder WSDL associated with the published service. To prevent resolution failures caused by this placeholder WSDL, ensure that the [Allow requests intended for operations not supported by the WSDL] check box is selected in the service properties:
The exposed local path of a virtual service is specified in the service properties in the Custom resolution path field as shown in Figure 3. Note that you can assign resolution paths that include the * wildcard character to allow one service to be resolved for a number of different entry point URIs. This is especially relevant to REST services but can also be useful in grouping together SOAP entry points in one virtual service that should be processed using similar rules. These are examples of valid custom resolution paths: /servicename/* /*/something
The resolution path is only one of the criteria used by the classification process to determine which virtual service to use for an incoming message. The Gateway also uses the following to resolve the service: service OID URI (e.g., custom resolution path) SOAPAction SOAP payload namespace
If more than one service has an identical combination of these four criteria, then a resolution conflict occurs. This classification behaviour is customizable. To learn more about the classification logic used by the Gateway, please refer to Understanding the Service Resolution Process in the Layer 7 Installation and Maintenance Manual. To learn how to customize the classification logic, refer to Managing Service Resolution in the Layer 7 Policy Manager User Manual.
Note that the port that a service receives requests on is not a property of the service itself. Instead, ports are globally declared at the Gateway level. If a port is configured to receive service message traffic, all published services on the Gateway have the ability to receive message from this port by default. You can change this default behaviour in two ways:
In the [Advanced] tab of the Listen Port Properties, you can create a fixed association between the port and a specific service.
In the service policy, you can validate which port the request came from and enforce that a specific port be used. This lets you restrict the use of a specific service from one or many ports without reserving a port to a single service. For more information on publishing virtual services using the Layer 7 Policy Manager, see Chapter 5, Working with Services in the Layer 7 Policy Manager User Manual.
You can also use context variables to validate properties of the incoming request. For example, to validate that the SOAPAction HTTP header of the incoming request has a specific value, you can use the variable ${request.http.header.soapaction} in the Compare Expression assertion as illustrated below.
In Figure 6, MySOAPAction is the SOAPAction header value that is being validated against the incoming request. Consult the Layer 7 Policy Authoring Manual for additional information on validating any aspect of requests and responses.
Transformation Extensions
Transformation extensions on both request and response messages are achieved in policy. For example, to transform a request message, you would add the Apply XSLT Transformation assertion, specify the XSL transformation to apply, and then associate it with the request. The same can be done to a response message by adding the assertion after a routing assertion (doing this normally populates the response context).
Once this assertion is executed, the transaction context has a response and you can add validations to the response messages (for example, using the Validate XML Schema assertion). All assertions located below the routing assertion in a policy will have access to the response message for validation purposes.
10
For more information, see Chapter 4, Access Control Assertions in the Layer 7 Policy Authoring User Manual.
11
12
Technical Overview
The migration utility is deployed as a service on the Gateway, with a migration policy that is imported to the service. The policy publishes a web form that can be used to upload an export of Cisco AXG configuration to the service. Exports can also be posted to the service from the command line (e.g., using cURL, or a similar command line utility). The policy parses the uploaded export and uses the Gateway Management Service to create Gateway service proxies for each Cisco AXG virtual service (i.e., a handler and one or more related service descriptors) contained in the export. The policy also imports any XML schemas contained in the Cisco AXG export to the Gateways global resource repository. The Gateway service proxies that are created will have active policies that include functional policy assertions that directly support Cisco AXG capabilities configured in the export. The policies will also include informational comments that describe the migrated virtual services and actionable comments that describe configuration that may still need to be done.
Dependencies
The migration utility requires the For Each Loop modular assertion, which is available from Layer 7 Technical Support.
13
b.
Using a privileged shell, copy the For Each Loop assertion from the /home/ssgconfig directory to the /opt/SecureSpan/Gateway/runtime /modules/assertions directory. For more information on the privileged shell, see Using the Privileged Shell in the Layer 7 Installation and Maintenance Manual. Change the ownership of the For Each Loop assertion in the assertions directory with this command:
chown layer7.layer7 *
c.
d.
3. Publish the Gateway Management Service on the target SSG. a. b. Connect to the target Gateway using the Layer 7 Policy Manager. Start the Publish Internal Service Wizard. For information on the different ways to start this wizard, see Publish Internal Service Wizard in the Layer 7 Policy Manager User Manual. Choose Gateway Management Service from the drop-downlist and then click [Finish].
c.
4. Publish a REST service on the target Gateway. a. Start the Publish REST, Web API, or Other Service Wizard. For information on the different ways to start this wizard, see Publish REST, Web API, or Other Service Wizard in the Layer 7 Policy Manager User Manual. In the Service Name field, enter AXG Migration. In the Gateway URL field, enter axg/migration. Click [Finish] to close the wizard.
b. c. d.
5. Import the Cisco AXG Migration Utility policy to the published REST service. a. b. c. On the Policy Editor toolbar, click .
Navigate to the Cisco AXG Migration Utility policy that you received from Layer 7 Technical Support. On the Policy Editor toolbar, click .
Preparation
In preparation for using Layer 7's Cisco AXG Migration Utility, you should export and uncompress your Cisco AXG configuration. The current version of the utility was tested against exports of entire Cisco AXG sub-policies containing multiple handler groups and handlers. Note: Do not select the option to export configuration as WS-Policy.
14
When exporting Cisco AXG configuration, a file with a .ppf extension is created. This is a compressed file that contains XML. This file must be uncompressed using an industry standard compression utility (for example, 7-Zip).
Using a Browser
1. In the browser, navigate to your migration service on the target Gateway.
2. Provide basic authorization credentials for an administrative user in the target Gateways Internal Identity Provider,
3. Browse for the uncompressed Cisco AXG configuration export prepared above.
15
5. Review the service proxies associated policies that were created by the migration (click on the toolbar, if necessary).
6. Review the global XML schema resources that were imported by the migration, using the Manage Global Resources task. For details, see Managing Global Resources in the Layer 7 Policy Authoring User Manual.
16
4. Review the migration results (piped to file with the above command).
17
5. Review the service proxies associated policies that were created by the migration (click on the toolbar, if necessary). 6. Review the global XML schema resources that were imported by the migration, using the Manage Global Resources task. For details, see Managing Global Resources in the Layer 7 Policy Authoring User Manual
Note: The Layer 7 Gateway expects that every global XML schema resource has a unique target namespace. If the Cisco AXG export contains redundant XML schemas, you will need to manually resolve target namespace conflicts using the Manage Global Resources task after migration is complete. Alternatively, you may contact Layer 7 to customize the migration utility to only import one XML schema for a given target namespace. 2. Create a SOAP or REST proxy for each handler found in the Cisco AXG export using these settings: Name set to: axg_<AXG handler name> Proxy disabled URI set to: <AXG handler transport URI> Allowed HTTP methods set to: <AXG handler transport method> For a SOAP proxy, the WSDL is set to a default WSDL as a place holder for when an actual WSDL is made available for the service For a SOAP proxy, allow requests intended for operations not supported by the WSDL is selected For a SOAP proxy, the SOAP version is set to: <AXG handler transport SOAP
version>
Note: Many Cisco AXG environments contain a handler per each distinct operation of a service. By comparison, the Layer 7 Gateway normally creates one proxy and conditional policy for all operations of a service. When replacing Cisco AXG, it is recommended that you consider collapsing the many proxies per handler that are created by the migration utility to fewer proxies per service.
18
3. Create an active policy for each proxy. a. Informational comments will be added for: b. AXG handler's sub-policy AXG handler's group AXG handler's name AXG handler's default service descriptor's name Whether the AXG handler has branched routing to multiple service descriptors (i.e., dynamic routing)
Actionable comments (i.e. TODO comments) will be added for: AXG handler's default log level Name of any access provisions attached to the AXG handler Whether inbound request and/or outbound response schema validation exists Whether dynamic routing exists Whether dynamic route selectors must be configured Whether dynamic route stop processing assertions must be removed Whether HTTP route passwords must be set
c.
If the AXG handler is set to log request messages on error: i. An Audit Messages in Policy assertion is added to the beginning of the policy (after comments): ii. Audit level is set to WARNING Save request = Always
An Audit Messages in Policy assertion will be added to the end of the policy: Audit level is set to INFO Save request = Never
d.
For a SOAP proxy, policy assertions will be added to check the SOAP version of the request. Note: Once a valid WSDL has been added to the SOAP proxy, these verifications are done automatically and this part of the policy is no longer necessary.
e.
For a SOAP proxy, policy assertions will be added to check the SOAP action of the request.
19
Note: Once a valid WSDL has been added to the SOAP proxy, these verifications are done automatically and this part of the policy is no longer necessary. f. If the AXG handler is configured to perform XML schema validation of the inbound request: i. Informational comments will be added for: ii. The name of the element to be schema validated (normally the root element of the message body). The namespace of the element. The name of the AXG XSD bundle resource containing the root schema and dependencies. The original file name of the AXG root schema.
A Validate XML Schema assertion will be added: Targeting the request message Configured to select the previously uploaded root schema from the Gateways global resource repository.
Note: The migration utility does not currently check for outbound request schema validation configured in one or more of the AXG handler's associated service descriptors. This capability can be added through customization of the migration utility. g. Route via HTTP to backside service(s). i. If the AXG handler included branched routing to multiple service descriptors: a) Conditional logic folders will be added to evaluate routing to each non-default service descriptor. 1) Informational comments will be added for the name of the AXG service descriptor. 2) Actionable comments will be added for : The AXG route's selector configuration. Whether HTTP route passwords must be set. To remove the Stop Processing assertion.
3) A Stop Processing assertion is added to ensure this route is not selected until appropriate selector logic has been added to policy.
20
4) An assertion will be added to make sure that routing has not already been attempted and failed for an earlier route destination. 5) A Route via HTTP(S) assertion will be added configured as follows: Target URL set to the AXG service descriptor's back side endpoint Connection and read timeouts set to the AXG service descriptor's timeout Basic authorization user name set, if set in Cisco AXG Pass-through of all HTTP request headers, if set in Cisco AXG
b) If no non-default service descriptor was selected, requests will be routed based on the default service descriptor's AXG configuration. 1) An assertion will be added to make sure that routing has not already been attempted and failed for an earlier route destination. 2) A Route via HTTP(S) assertion will be added configured as follows: ii. Target URL set to the AXG service descriptor's back side endpoint Connection and read timeouts set to the AXG service descriptor's timeout Basic authorization user name set, if set in Cisco AXG Pass-through of all HTTP request headers, if set in Cisco AXG
Otherwise requests will be routed based on the default service descriptor's AXG configuration. a) A Route via HTTP(S) assertion will be added configured as follows: Target URL set to the AXG service descriptor's back side endpoint Connection and read timeouts set to the AXG service descriptor's timeout Basic authorization user name set, if set in Cisco AXG
21
h.
If the AXG handler is configured to perform XML schema validation of the outbound response: i. Informational comments will be added for: ii. Name of the element to be schema validated (normally the root element of the message body) Namespace of the element Name of the AXG XSD bundle resource containing the root schema and dependencies Original file name of the AXG root schema
A Validate XML Schema assertion will be added configured as follows: Targets the response message. Configured to select the previously uploaded root schema from the Gateways global resource repository
Note: The migration utility does not currently check for outbound request schema validation configured in one or more of the AXG handler's associated service descriptors. This capability can be added through customization of the migration utility.
22
23
24
Described environments (Development, Staging, Production). Any new requirements should also clearly be defined.
Please refer to the Layer 7 Installation and Maintenance Manual for deployment instructions.
25
utility is normally installed only on the first target environment (typically a development or staging environment). Once the AXG configuration is migrated and tested on that environment, you can use the Layer 7 Enterprise Service Manager to promote these services to other environments such as production.
Step 7: Test
At this point, you are ready to make end-to-end testing in your development environment. Use the Layer 7 monitoring and auditing to capabilities to verify that the defined behavior is met. If you need to make adjustments to the migration style sheet here, you can go back to step 5. You may proceed to the next step once all your tests come back positive.
26
User Documentation
The Layer 7 products are supported by the following documentation:
Table 2: Layer 7 Documentation Documentation Layer 7 Installation and Maintenance Manual Target Product(s) Gateway, XML VPN Client, and Policy Manager Format(s) PDF and print Description Installation and upgrade information for the Layer 7 products, including Gateway maintenance, operations, monitoring, and troubleshooting information and instructions. There are separate editions of this manual for the appliance (including virtual) and software Gateways.
27
Description Comprehensive user instructions for the Policy Manager. Comprehensive user instructions for the Policy Manager.
Policy Manager
Program-based. Accessed from the Policy Manager [Help] menu. PDF and print
SecureSpan XML VPN Client User Manual SecureSpan XML VPN Client Help System
Comprehensive user instructions for the SecureSpan XML VPN Client. Comprehensive user instructions for the SecureSpan XML VPN Client.
Program-based. Accessed from the XML VPN Client [Help] menu. PDF
Gateway
Instructions for installing and configuring the optional custom assertion packages on the Gateway. User instructions for the custom assertions are provided in the Policy Manager documentation. Release-based information. Also includes a copy of the End User license agreement.
Read Me file
Describes how to use the Layer 7 product suite to comply with version 2.0 of the Payment Card Industry Security Standards Councils Data Security Standards (PCI DSS).
Support Portal
The Layer 7 support portal can be used to download virtual appliance images, software installers, documentation, and other resources. You can access the Layer 7 support portal via http://layer7tech.com/portal/.
Solutions Architects
Contact your local Solutions Architect for advice on how to proceed with your AXG replacement, to answer any technical questions about the capabilities of the Layer 7 Gateway solution, and for assistance with a pilot or POC project. You can reach your local solutions architect by emailing sales@layer7tech.com.
28
Professional Services
The Layer 7 Professional Services engineers will assist you in the implementation phase of your Layer 7 Gateway solution and for specialized training engagements. Layer 7 Professional Services can be contacted via support@layer7tech.com.
Sample Policies
Through the Layer 7 support engineers and professional services, you can get a number of sample policies and scripts to speed up the implementation of any Layer 7 Gateway implementation projects. For more information, please contact support@layer7tech.com.
29
30
Index
A Access control .................................. 11 Audit sink policy .................................. 4 B Browser access to utility .................. 15 C Command line access to utility ....... 17 Contact Layer 7 ................................ 27 Creating virtual service .................................. 4 G Global policy ........................................ 4 I Identity control ................................. 11 Internal use policy ............................... 4 L Layer 7 Resources professional services ................... 29 sample policies ............................ 29 solutions architects ..................... 28 support portal ............................... 28 user documentation .................... 27 Layer 7 Technologies about ............................................... 1 contacting ..................................... 27 resources ...................................... 27 why us? ............................................ 1 M Migration Utility installing ....................................... 13 methodology ................................. 25 preparation ................................... 14 sample policy ............................... 23 specifics........................................ 18 technical overview ....................... 13 using.............................................. 15 browser ..................................... 15 command line ........................... 17 P Policies ................................................ 3 audit sink policy .............................. 4 global policy .................................... 4 internal use policy .......................... 4 policy fragment ............................... 3 service policy .................................. 3 Policy fragment ................................... 3 Professional Services ....................... 29 Published services ............................. 3 R Request message specification ........ 7 Resources ......................................... 27 Response message specification ...... 9 S Sample Policies ................................ 29 Sample policy after migration .......... 23 Service policy ...................................... 3 Solutions Architects ......................... 28 Specify request message ............................ 7 response message ......................... 9 Support Portal .................................. 28 T Transformation extensions ................ 9 U Understanding policies ............................................ 3 published services.......................... 3 User Documentation ........................ 27 V Virtual service ..................................... 4
Index
31
32
Index