# Securing a Virtual Service using Policies

## Contents
Overview Importing a WSDL File Configuring a Security Policy Configuring Policy Settings Configuring Policy Filters Editing a Security Policy Using WCF WS-Policies Removing Security Tokens Further Information

## Overview
You can specify a WS-Policy to enforce security between a client and the Enterprise Gateway. In this deployment scenario, the Enterprise Gateway exhibits recipient-side WS-Policy behavior, where the Enterprise Gateway is the recipient, and the client is the initiator. The following architecture diagram shows where the recipient WS-Policy applies in a typical message flow between a client and the Enterprise Gateway:
Securing a Virtual Service using a WS-Security Policy
When you import a WSDL file into the Web Services Repository, you can select the operations that you want to secure in the Import WSDL wizard. The Secure Virtual Service dialog then enables you to specify the policy that the Enterprise Gateway enforces on the messages that it receives from the client. In the Policy Configuration Settings wizard, you can configure specific fields in the filters that are necessary to fulfill the security requirements specified in the Secure Virtual Service dialog. 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 selected WS-Policy. Using policies in this way, the Policy Studio automatically generates the complicated circuits that the Enterprise Gateway uses to talk to the client. The Enterprise Gateway then becomes the recipient of the client, and is responsible for enforcing the selected policies on the messages that it receives from the client. The main advantage is that administrators can configure complex circuits to talk to clients in a secure manner with only a few clicks and minimal intervention.
## 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 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.
## Configuring a Security Policy
The Secure Virtual Service dialog enables you to specify the policy that the Enterprise Gateway enforces on the messages that it receives from the client. To specify a policy, perform the following steps: In the Secure Virtual Service dialog, select the Secure Virtual Service checkbox. In the Security Policy panel, select a Gateway Policy from the drop-down list. The following table shows some example policies. The full list of available policies and descriptions are displayed in the dialog.
Policy | Description
AsymmetricBinding with Encrypted UsernameToken | Service exposes an AsymmetricBinding where the client and server use their respective X.509v3 tokens to sign and encrypt the message. An encrypted UsernameToken with hash password must be included in all messages from the client to the server.
Username SupportingToken Plaintext Password | Client must authenticate with a WS-Security UsernameToken with plaintext password.
SAML 1.1 Bearer | Client must include a SAML 1.1 Assertion (bearer) representing the Requestor in all messages from the client to the service.
SymmetricBinding with Signed and Encrypted UsernameToken | Service uses a SymmetricBinding where the client and service use the same X.509v3 token to sign and encrypt the message. A signed and encrypted UsernameToken with plaintext password must be included in all messages from the client to the service. The Policy uses WSS SOAP Message Security 1.1 options.
SSL Transport Binding | Service is secured by SSL (HTTPS).
SAML 2.0 Sender-Vouches over SSL | Client includes a SAML 2.0 Assertion (sender vouches) on behalf of the Requestor to all messages from the client to the service. The service uses a TransportBinding to ensure that all messages are signed and encrypted.
WCF MutualCertificate Service | Service exposes an AsymmetricBinding protected by mutual X.509 certificates.
In the Message-Level Policy panel, select a Request Policy from the drop-down list. The available policies are as follows: Encrypt SOAP Body Sign SOAP Body Sign and Encrypt SOAP Body Select a Response Policy from the drop-down list. The available policies are the same as for Request Policy. Click OK. The Policy Configuration Settings wizard is displayed. This enables you to set some of the fields in the filters that require human intervention (for example, the signing and encrypting key).
## Configuring Policy Settings
Depending on the policy configured in the Secure Virtual Service dialog, the Policy Configuration Settings wizard displays configuration screens for the filters that implement the rules required by the configured policy. The exact sequence of screens differs depending on the policy that is selected. For example, if a policy with a SAML token is selected, the Validate SAML Authentication Assertion filter is displayed instead of the Validate WS-Security UsernameToken filter. The effort in configuring these screens is minimal because the information is taken automatically from the WS-Policy assertions. For example, the layout, signing, encryption, and key wrapping algorithms, key referencing method, Username digest, and clear password are all automatically taken from the WS-Policy assertions. This means that the administrator has only to configure a small number of settings. For example, the signing key, encryption certificate, and Timestamp validity period). If your WSDL file includes WS-Policy assertions, the Configure Initiator Security Settings screen is first displayed in the wizard. This screen enables you to specify the required settings when the Enterprise Gateway is deployed as the initiator for the Web Service. For details, see Configuring Security Policies from WSDL Files. The Configure Recipient Security Settings screen then enables you to specify the required settings when the Enterprise Gateway is deployed as the recipient for the client.
## Configuring Policy Filters
The following tables show examples of the types of filters that are created, and which fields must be completed by the administrator in the Configure Recipient Security Settings screen. For simplicity, these tables list only filters that require manual input from the administrator. Insert Timestamp Filter
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.
Signed Parts Outbound Filter
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.
Find Recipient Certificate for Encryption
Field Name | Description
Certificate Store | 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.
Validate SAML Authentication Assertion
Field Name | Description
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.
Trusted Issuers | On the Trusted Issuers tab, click Add to specify the Distinguished Name of a SAML Authority whose certificate has been added to the Certificate Store, and click OK. Repeat this step to add more SAML Authorities to the list of trusted issuers.
Configure SSL Certificate
Field Name | Description
X.509 Certificate | On the Network tab, click the X.509 Certificate button to create or import an SSL certificate.
SSL Server Name Identifier (SNI) | On the Network tab, click the Add button to configure a server name in the SSL Server Name Identifier (SNI) dialog. You can specify the server name in the Client requests server name field. Click the Server assumes identity button to import a Certificate Authority certificate into the Trusted Certificate Store.
Mutual Authentication | On the Mutual Authentication tab, select root Certificate Authorities trusted for mutual authentication.
Insert MTOM Content
Field Name | Description
XPath Location | When the `wsoma:OptimizedMimeSerialization` WS-MTOMPolicy assertion is specified in a policy, you must configure an Insert MTOM Content filter. You need only configure an XPath expression to point to the base64-encoded element content that you want to insert and create an MTOM type attachment for.
## Editing a Security 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.
## Using WCF WS-Policies
The Enterprise Gateway provides four WS-Policies that are identical to those exposed by WCF (Windows Communication Foundation) Web Services. When one of these policies is exposed by a virtual service in the Enterprise Gateway, the `svcutil` .NET Web Services utility can consume the WS-Policy and auto-generate clients that communicate securely with the Enterprise Gateway. The security settings for a WCF Web Service are configured in its `web.config` file, in which the `security` element determines the WS-Policy applied to the service. For example, the following extract from a WCF Web Service `web.config` file shows the configuration:
    <customBinding>
      binding name="MyCustomBinding">
       <textMessageEncoding messageVersion="Soap11" />
       <security defaultAlgorithmSuite="Basic256"
         allowSerializedSigningTokenOnReply="true"
         authenticationMode="MutualCertificate" requireDerivedKeys="false"
         includeTimestamp="true" messageProtectionOrder="SignBeforeEncrypt"
         messageSecurityVersion="WSSecurity10..."
         requireSecurityContextCancellation="false">
       </security>
      </binding>
    </customBinding>
In this example, the `authenticationMode` for a `customBinding` is set to `MutualCertificate`, which means that messages sent to and from the Web Service must be signed and encrypted with mutual certificates. The following example shows an example of the WCF `wsHttpBinding` configuration, which is less verbose:
    <wsHttpBinding>
     <binding name="MyWsHttpBinding">
     <security mode="Message">
      <message clientCredentialType="Certificate" />
     </security>
     </binding>
    </wsHttpBinding>
The following table shows how the WCF WS-policies provided with the Enterprise Gateway correspond to a particular configuration of the `security` element in the WCF Web Service `web.config` file. As shown in the preceding examples, the configuration settings are slightly different, depending on the WCF binding (`customBinding` or `wsHttpBinding`). The following table shows the available settings:
WS-Policy Name | WCF Binding | Authentication Mode | Security Mode | Client Credential Type
WCF MutualCertificate Service | `customBinding` | `MutualCertificate` |  |
WCF UsernameForCertificate Service | `customBinding` | `UserNameForCertificate` |  |
WCF UsernameOverTransport Service | `customBinding` | `UsernameForTransport` |  |
WCF BrokeredX509Authentication Service | `wsHttpBinding` |  | `Message` | `Certificate`
Important Note: If you intend to consume the WS-Policy exposed by the Enterprise Gateway with a WCF client, you should use one of the WCF WS-Policies. All of these policies can be consumed seamlessly by the WCF `svcutil` utility to auto-generate secure clients. While the other WS-Policies exposed by the Enterprise Gateway can be consumed by `svcutil`, you need to make additional configuration changes to the auto-generated WCF client to communicate securely with the Enterprise Gateway. For more details on making any necessary configuration changes, see your WCF documentation.
## Removing Security Tokens
When you configure a recipient WS-Policy in the Secure Virtual Service dialog, the Remove All Security Tokens policy 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
Recipient-side WS-Policy only In this case, a recipient WS-Policy is configured in the Secure Virtual Service dialog to protect a virtual service exposed by the Enterprise Gateway. The recipient WS-Policy defines the security contract between the client and the Enterprise Gateway. Any security tokens sent by the client are intended for consumption by the Enterprise Gateway. They are not intended for the back-end Web Service. For example, the Web Service may not understand SAML, WS-Security, XML Signature, and so on, which may result in a serialization error if these tokens are propagated to it. In addition, it would add unnecessary overhead to the message to propagate security tokens to it. On the response side, the response that the Enterprise Gateway returns to the client must adhere to the selected recipient WS-Policy. For example, if the Web Service has returned a SAML Token (out of scope of any WS-Policy requirements), this must not be returned to the client because it would breach the recipient WS-Policy. 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 importing WSDL files that include WS-Policies (initiator case), see Configuring Security Policies from WSDL Files. Important Note The Remove All Security Tokens policy only applies when a WS-Policy is configured, and is not configured when a WS-Policy is not used. 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: Configuring Security Policies from WSDL Files 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.