Contents
When you import a WSDL file into the Web Services Repository to virtualize and secure a protected Web Service, the Policy Studio automatically generates policies. 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 API 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 policies that can then be used to talk to the Web Services defined in the WSDL. The API 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:
![]() |
In this way, administrators can configure complex policies to talk to secure Web Services with only a few clicks and minimal intervention. In addition, the API Gateway uses cryptographic acceleration to reduce the overhead associated with running the cryptographic operations required to secure the message.
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:
-
In the Policy Studio tree view, expand the Business Services -> 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.
-
You can also expose only the operations selected on the WSDL Operations screen in a slimmed down version of the Web Service. Select Remove unselected operations from the WSDL to remove operations that you do not want to secure from the virtualized service that is exposed to clients. Click Next to continue.
-
On the WS-Policy Options screen, if you wish to use a WS-Policy to secure the Web Service, select Secure this virtualized service with a WS-Policy. This means that the Secure Virtual Service dialog is then displayed after the Import WSDL wizard.
-
Ensure that Use the WS-Policy in the WSDL to connect securely to the back-end Web Service is selected. This is enabled (and selected by default) only if the selected WSDL file includes WS-Policy information. 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. For details, see Securing a Virtual Service using Policies.
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, if the API Gateway has also been configured as the recipient for the client, the Configure Recipient Security Settings screen is displayed first. For more details, see Securing a Virtual Service using Policies. The Configure Initiator Security Settings screen is displayed next. This enables you to specify the required filter settings when the API Gateway is configured as the initiator for the Web Service.
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 API 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.
|
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.
|
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.
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 API Gateway, and is determined by the WS-Policy selected in the Secure Virtual Service dialog.
-
Initiator security context: This is between the API 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:
![]() |
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 API Gateway and the back-end Web Service defined in the WSDL. On the request side, any security tokens sent by the client to the API Gateway, which are out of scope of the initiator WS-Policy between the API Gateway and Web Service, are removed before the API 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
API 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 API Gateway, which may contradict the rules in the initiator contract (between the
API Gateway and Web Service) must be stripped out before the API 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 API Gateway. Therefore,
any tokens returned by the Web Service are only intended for use by the API Gateway. They are
not intended for consumption by the client. In other words, the security
context is only between the API Gateway and the Web Service. If the Web Service returns a
UsernameToken
, it is consumed by the API 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 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 the Secure Virtual Service dialog (recipient case), see Securing a Virtual Service using Policies.
![]() |
Important |
---|---|
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. |
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.