# Configuring Security Policies from WSDL Files

## Contents
Overview Importing a WSDL file Configuring Policy Settings Configuring Policy Filters Editing a Policy Removing Security Tokens Further Information

## Overview
When you import a WSDL file into the Web Services Repository to virtualize and secure a protected Web Service, the Policy Studio automatically generates policy circuits. For example, a Service Handler is created to control and validate requests to the Web Service and responses from the Web Service. The information used to configure the Service Handler is automatically taken from the operation definitions in the WSDL. When clients must use message-level or transport-level security mechanisms to communicate with the Web Service, you can include WS-Policy assertions in the WSDL. These policy assertions can then be referenced at the operation or endpoint level in the WSDL. For example, a given Web Service may require the client to sign sensitive parts of the message and include a WS-Security UsernameToken to authenticate to the Web Service. You can include these policy requirements in the WSDL. Whenever a client retrieves the WSDL, it can automatically sign the relevant parts of the message and insert a valid UsernameToken. When you import a WSDL file containing WS-Policy assertions into the Web Services Repository, you can select the operations that you want to protect as normal in the Import WSDL wizard. The Secure Virtual Service dialog enables you to specify the policy that the Enterprise Gateway enforces on the messages that it receives from a client. For more details, see Securing a Virtual Service using Policies. In the Policy Configuration Settings wizard, you can configure specific filters to fulfill the security requirements specified by the policy assertions in the WSDL file. Most of these requirements are met without the need for human intervention. However, a small number of filters require the administrator to configure specific fields. For example, when signing or encrypting a message, you must specify the signing or encrypting key. When configuring the duration of a WS-Security Timestamp, you may need to specify longer or shorter than the default of one hour. However, most of the information required to configure these filters is set automatically based on the policy assertions in the WSDL file. Using WS-Policy assertions, the Policy Studio can automatically generate complicated circuits that can then be used to talk to the Web Services defined in the WSDL. The Enterprise Gateway then becomes the client or initiator of the Web Service, and is responsible for making sure the requests it sends to the service adhere to the security constraints specified in the policy:
Configuring Security Policies from WSDL Files
In this way, administrators can configure complex circuits to talk to secure Web Services with only a few clicks and minimal intervention. In addition, the Enterprise Gateway uses cryptographic acceleration to reduce the overhead associated with running the cryptographic operations required to secure the message.
## Importing a WSDL file
Complete the following steps to import the WSDL file into the Web Service Repository: In the Policy Studio tree view, expand the Web Services Repository node, and select the Web Services node. Right-click the Web Services node, and select Register Web Service. In the Load WSDL screen, browse to the location of the WSDL in the file system, enter the URL of the WSDL, or retrieve it from a UDDI (Universal Description, Discovery, and Integration) repository. Select as appropriate, and click Next. The operations defined in the WSDL and exposed by the Web Service are listed on the WSDL Operations screen. Select the operations that you want to secure, and click Next. When you import the WSDL for this Web Service into the Enterprise Gateway's Web Services Repository, the Enterprise Gateway exposes a virtualized version of this service. This involves changing the host and port where the Web Service is available to point to the machine running the Enterprise Gateway. In this way, a client can retrieve the WSDL for the virtualized Web Service from the Enterprise Gateway without knowing its real location. You can also expose only the operations selected on the WSDL Operations screen in a slimmed down version of the Web Service. To do this, select the checkbox on the WSDL Import Settings screen to remove operations that you do not want to secure from the virtualized service that is exposed to clients. Click Next to continue. Select the Relative Path from the list where you want this service to be deployed (for example, Default Services). Click Finish. When you have completed the steps in the Import WSDL wizard, the Secure Virtual Service dialog is displayed. For details, see Securing a Virtual Service using Policies.
## Configuring Policy Settings
Depending on the type and number of WS-Policy assertions in the WSDL, the Policy Configuration Settings wizard contains configuration screens for the filters used to implement the rules required by the assertions. The exact sequence of screens differs depending on the assertions specified in the WSDL. For example, if an `sp:SamlToken` assertion is specified, the wizard contains a screen for the Insert SAML Authentication Assertion filter. Only certain fields must be specified by the administrator on this filter screen, while the rest are automatically populated based on the assertions and properties defined in the WSDL. In the case of the Sign Message filter, the decision to use asymmetric or symmetric signatures is based on whether the policy uses an asymmetric or symmetric binding. The layout rules are determined by the `sp:Layout` assertion. The digest method, signature method, and key wrap algorithm (for symmetric signatures) are all populated automatically based on the contents of the `sp:AlgorithmSuite` assertion. The `KeyInfo` section of the XML Signature can be taken from various properties set in the WSDL. The parts of the message to be signed can be inferred from assertions such as `sp:SignedParts`, `sp:SignedElements`, and `SignedSupportingTokens`. The same is true for the XML Encryption Settings filter where the encryption algorithms and key types can all be taken from the assertions in the WSDL. The `ConfirmationMethod` for SAML assertions can be inferred from the context of the `SamlToken` assertion. For example, an `sp:SamlToken` that appears as a child of the `sp:SignedSupportingTokens` assertion uses a `sender-vouches` confirmation method, whereas if it appears as a child of an `sp:EndorsingSupportingTokens` assertion, the `holder-of-key` confirmation method can be assumed. In the Policy Configuration Settings wizard, the Configure Initiator Security Settings screen enables you to specify the required filter settings when the Enterprise Gateway is configured as the initiator for the Web Service. If the Enterprise Gateway has also been configured as the recipient for the client, the Configure Recipient Security Settings screen is then displayed. For details, see Securing a Virtual Service using Policies.
## Configuring Policy Filters
The following tables list the types of filters that are created, and which fields must be completed by the administrator in the Configure Initiator Security Settings screen. For simplicity, the tables below list only the filters that require manual input from the administrator. Insert WS-Security Timestamp
Field Name | Description
Expires In | You may want to specify a more appropriate lifetime for the assertion (instead of the default one hour) by configuring the various time period fields.
Sign Message
Field Name | Description
Signing Key | If the policy uses an asymmetric binding, on the Asymmetric tab, click the Signing Key button, and select a key from the Certificate Store to sign the message parts with. Alternatively, if the policy specifies a symmetric binding, on the Symmetric tab, click the Signing Key button, and select a key to wrap the symmetric signing key with.
Insert WS-Security Username
Field Name | Description
Username | Enter the username inserted into the WS-Security `UsernameToken` block. By default, the name of the authenticated user is used, which is stored in the `authentication.subject.id` message attribute. However, any user-specified value can be entered in this field.
Password | If the policy requires a password, the password for the user entered above must be specified here. You can use the default authenticated user password by selecting the `authentication.subject.password` message attribute. Alternatively, you can enter any suitable password manually entered if necessary. The decision to use a Clear or Digest password is taken from the corresponding policy assertions.
Insert SAML Authentication Assertion
Field Name | Description
Expire In | Specify a suitable lifetime for the SAML assertion by configuring the various time period fields.
Drift Time | You may need to specify a drift time value to allow for a time differential between the clock on the machine hosting the Enterprise Gateway and the machine hosting your Web Service.
Issuer Name | Select the alias of the certificate from the Certificate Store that you want to use to identify the issuer of the assertion. The alias name is used as the value of the `Issuer` attribute of the `saml:Assertion` element.
Holder of Key: Signing Key | In cases where the `sp:SamlToken` appears as a child of `EndorsingSupportingTokens` or an `InitiatorToken`, the `holder-of-key` SAML confirmation method is inferred. In this case, if an asymmetric binding is used, on the Asymmetric tab, specify a key from the Certificate Store by clicking the Signing Key button. Alternatively, if a symmetric binding is used in the policy, on the Symmetric tab, specify a key to use to encrypt the symmetric key with by clicking the Signing Key button.
Find Recipient Certificate for Encryption
Field Name | Description
Certificate Store | Select this option, and click the Select button to choose the recipient's certificate from the Certificate Store. The public key contained in this certificate is used to encrypt the message parts so that only the recipient is able to decrypt them using the corresponding private key.
Connect to URL
Field Name | Description
Trusted Certificates | To connect to an external Web Service over SSL, you need to trust that Web Service's SSL certificate. You can do this on the Trusted Certificates tab of the Connect to URL filter. Assuming you have already imported this certificate into the Trusted Certificate Store, simply select it from the list.
Client SSL Authentication | If the Web Service requires the client to present an SSL certificate to it during the SSL handshake, you must select that certificate from the list on the Client SSL Authentication tab. Note that this certificate must have a private key associated with it that is also stored in the Certificate Store.
Extract MTOM Content
Field Name | Description
XPath Location | When the `wsoma:OptimizedMimeSerialization` WS-MTOMPolicy assertion is specified in a policy, you must configure an Extract MTOM Content filter. You need only configure an XPath expression to point to the base64-encoded element content that you want to extract and create an MTOM type attachment for.
## Editing a Policy
You may wish to edit a previously configured WS-Policy (for example, to change the signing key in the auto-generated circuit). You can do this by right-clicking the Web Service in the Policy Studio tree, and selecting Configure Initiator WS-Policy or Configure Recipient WS-Policy. These menu options are described as follows: Configure Initiator WS-Policy: If you have already configured an initiator WS-Policy, you can edit its filters using this menu option. However, if there was no WS-Policy in the imported WSDL file, you can not use this option. You can not add a WS-Policy to the Web Service because that would break the contract between the Enterprise Gateway and the back-end Web Service. If the contract for the Web Service changes (for example, a WS-Policy is applied to it at the back-end), you need to re-import the modified WSDL to reflect the changes. Configure Recipient WS-Policy: If a recipient WS-Policy was configured when the WSDL file was imported into the Web Service Repository, you can edit its filters using this option. If you did not configure a WS-Policy when importing the WSDL file (using the Secure Virtual Service dialog), when you select this option, the Secure Virtual Service dialog is displayed. This enables you to select a WS-policy to secure the service. The next time that you select the Configure Recipient WS-Policy option, you will edit this policy.
## Removing Security Tokens
When you import a WSDL file containing a WS-Policy into the Web Service Repository, the Remove All Security Tokens filter is enabled in the Service Handler for the imported Web Service. You can view the configured policy by double clicking the Service Handler, and selecting the Message Interception Points -> 2. User-defined Request Hooks tab. The Remove All Security Tokens policy ensures that the following security contexts are kept separate: Recipient security context: This is between the client and the Enterprise Gateway, and is determined by the WS-Policy selected in the Secure Virtual Service dialog. Initiator security context: This is between the Enterprise Gateway and the back-end Web Service, and is determined by the WS-Policy contained in the imported WSDL for the back-end Web Service. The Remove All Security Tokens policy prevents tokens from one context passing over into the other context, which could breach the security contract governing that context. This ensures that each security context receives a clean SOAP message, on which it can then act to enforce the security requirements of the relevant WS-Policy. The following diagram shows both security contexts and the Remove All Security Tokens policy:
Removing Security Tokens
Initiator-side WS-Policy only In this case, the WS-Policy is contained in the imported WSDL file. The WS-Policy defines the security contract between the Enterprise Gateway and the back-end Web Service defined in the WSDL. On the request side, any security tokens sent by the client to the Enterprise Gateway, which are out of scope of the initiator WS-Policy between the Enterprise Gateway and Web Service, are removed before the Enterprise Gateway starts enforcing the initiator WS-Policy on the request, and before it sends the request to the Web Service. For example, if the client sends a `wsu:Timestamp` in the request message and the initiator policy stipulates that a `wsu:Timestamp` must be sent by the Enterprise Gateway to the Web Service, two timestamps could be sent in the request, which is invalid. This means that the timestamp and any other security tokens sent by the client to the Enterprise Gateway, which may contradict the rules in the initiator contract (between the Enterprise Gateway and Web Service) must be stripped out before the Enterprise Gateway starts adding security tokens to the message. This ensures that the message adheres to the initiator WS-Policy. Similarly, any security tokens returned by the Web Service are only present because the Web Service complies with the contract between the Web Service and the Enterprise Gateway. Therefore, any tokens returned by the Web Service are only intended for use by the Enterprise Gateway. They are not intended for consumption by the client. In other words, the security context is only between the Enterprise Gateway and the Web Service. If the Web Service returns a `UsernameToken`, it is consumed by the Enterprise Gateway. If a token must be returned to the client, this is a user-enforced rule, which is out of scope of the WS-Policy configuration in the WSDL. If necessary, you can override the default behavior by removing the Remove All Security Tokens filter from the Service Handler to allow the `UsernameToken` to be propagated to the client. Initiator-side and Recipient-side WS-Policy This occurs when you import a WSDL file that includes a WS-Policy (initiator case), and you also select a WS-Policy in the Secure Virtual Service dialog (recipient case). This scenario includes both the recipient security context between the client and the Enterprise Gateway, and the initiator security context between the Enterprise Gateway and the Web Service. It is vital that these security contexts are kept separate because if tokens from one context pass over into the other context, it is highly likely that the security contract for that context will be breached. For example, if the recipient contract between the client and the Enterprise Gateway requires a `UsernameToken`, but the initiator contract between the Enterprise Gateway and the Web Service requires a SAML token, the `UsernameToken` must not pass over into the initiator context and be sent to the Web Service. For more details on the Secure Virtual Service dialog (recipient case), see Securing a Virtual Service using Policies. Important Note The Remove All Security Tokens policy only applies when a WS-Policy is configured, and is not enabled when a WS-Policy is not configured. In addition, any non-standard behavior that requires a security token to be propagated over to another security context can be handled by disabling the Remove All Security Tokens policy in the Service Handler for the imported WSDL.
## Further Information
For more details on configuring policies to protect your Web Services, see the following: Securing a Virtual Service using Policies Configuring Policies Manually Web Services Filter The Web Services filter is the main filter generated when a WSDL file is imported into the Web Services Repository. It contains all the routing information and links all the policies that are to be run on the request and response messages into a logical flow.