Oracle® Fusion Middleware
Part 4. Governance

You can specify a WS-Policy to enforce security between a client and the API Gateway. In this deployment scenario, the API Gateway exhibits recipient-side WS-Policy behavior, where the API 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 API Gateway:

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 API Gateway enforces on the messages that it receives from the client.

In the Policy Configuration Settings wizard, you can then 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 policies that the API Gateway uses to talk to the client. The API 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 policies to talk to clients in a secure manner with only a few clicks and minimal intervention.

When you import the WSDL for a Web Service into the Web Services Repository, the API 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 API Gateway. In this way, a client can retrieve the WSDL for the virtualized Web Service from the API Gateway without knowing its real location.

To import the WSDL file into the Web Service Repository, complete the following steps:

When you have completed the steps in the Import WSDL wizard, the Secure Virtual Service dialog is displayed.

The Secure Virtual Service dialog enables you to specify the policy that the API Gateway enforces on the messages that it receives from the client. To specify a policy, perform the following steps:

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).

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).

The Configure Recipient Security Settings screen is first displayed in the wizard. This enables you to specify the required settings when the API Gateway is deployed as the recipient for the client. If your WSDL file includes WS-Policy assertions, the Configure Initiator Security Settings screen is then displayed in the wizard. This screen enables you to specify the required settings when the API Gateway is deployed as the initiator for the Web Service. For more details, see Configuring Security Policies from WSDL Files.

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

Signed Parts Outbound Filter

Find Recipient Certificate for Encryption

Validate SAML Authentication Assertion

Configure SSL Certificate

Insert MTOM Content

You may wish to edit a previously configured WS-Policy (for example, to change the signing key in the auto-generated policy). 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 API 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.

The API 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 API Gateway, the svcutil .NET Web Services utility can consume the WS-Policy and auto-generate clients that communicate securely with the API 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 API 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:

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:

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:

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 API Gateway. The recipient WS-Policy defines the security contract between the client and the API Gateway. Any security tokens sent by the client are intended for consumption by the API 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 API 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 API Gateway, and the initiator security context between the API 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 API Gateway requires a UsernameToken, but the initiator contract between the API 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.

For more details on configuring policies to protect your Web Services, see the following:

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.