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