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 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 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
|
When you import the WSDL for a Web Service into the 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.
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, select Secure this
virtualized service with a WS-Policy. The means that the Secure
Virtual Service dialog is displayed after the Import WSDL
wizard.
-
If the WSDL file includes WS-Policy information, select Use the WS-Policy
in the WSDL to connect securely to the back-end Web Service. 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, in the Security
Policy panel, select a Gateway Policy from the drop-down
list. A description for the currently selected policy is displayed in the dialog.
For details on all the available policies, see the
WS-Policy Reference.
- 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).
The Configure Recipient Security Settings screen is first displayed in the wizard.
This enables you to specify the required settings when the Enterprise 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 Enterprise Gateway is deployed as the initiator for the Web Service.
For more details, see Configuring Security Policies from
WSDL Files.
|
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 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:
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:
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.
|
|