Securing Caché Web Services
Creating and Using Policies
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes how to use WS-Policy support in Caché. WS-Policy enables you to specify the WS-Security headers to use or to expect. It also enables you to specify use of WS-Addressing headers and MTOM (which are described in Creating Web Services and Web Clients in Caché). You create policies in separate classes rather than editing the web service or web client directly. In most cases, no low-level programming is required.

This chapter discusses the following topics:
Overview
In Caché, the policy (or collection of policies) for a web service or client is contained in a separate configuration class, a subclass of %SOAP.Configuration. The policies are in effect when the class is compiled.
If the WSDL for the web service has already been defined, you can generate the configuration class. If you are creating the web service first, you can use the Web Service/Client Configuration Wizard to choose and configure a predefined policy to apply to the web service. You can also create the class manually.
No coding is generally required. However, in some cases, you can specify a detail programmatically, rather than having that element hardcoded into the policy.
Effect of the Configuration Class
When you compile a configuration class, the future operation of the web service or client is affected as follows:
Important:
If the configuration class is mapped to multiple namespaces, you must compile it in each of those namespaces.
Relationship to WS-Security, WS-Addressing, and MTOM Support
Caché support for WS-Policy is built on Caché support for WS-Security, WS-Addressing, and MTOM. Note the following points:
Relationship of Web Service and Web Client
When you attach a policy to a web service, all clients must be able to obey that policy. If the web service policy does not include any policy alternatives, then the clients must have the same policy as the web service, substituting a client-side certificate for the server-side certificate, if needed.
Similarly, if you attach a policy to a web client, the service must be able to obey that policy.
In practice, if both the service and the client are created in Caché, the following procedure is the simplest:
  1. Create the web service class.
  2. Create the web service configuration class, with the service policy.
  3. Use the SOAP Wizard to generate the client classes, including the client configuration class.
    After you do so, examine the generated client classes and make changes if needed. The most common change is to adjust method signatures for long strings.
    You usually also create a wrapper class for it.
    For information on these tasks, see Creating Web Services and Web Clients in Caché.
  4. Examine the generated configuration classes and make changes if needed. See Editing the Generated Policy.”
For details on the configuration class, see the next chapter, WS-Policy Configuration Class Details.”
Creating and Attaching Policies
To create a policy and attach it to a web service or client, you create and compile a configuration class. There are several ways to create this class:
If you generate the policy class from a WSDL, you may need to edit it as described in the next section.
Using the Web Service/Client Configuration Wizard
You can create and attach policies by using the Web Service/Client Configuration Wizard in Studio. To use this wizard:
  1. Click File > New....
  2. Click OK.
    Studio then displays a dialog box.
  3. Select the web service or a web client to which the policies will apply. The wizard lists only the services and clients that are compiled.
    To do so, click either the Service or the Client drop-down menu as appropriate and then click the web service class or web client class.
  4. Click Next.
    Studio then displays another dialog box.
  5. Optionally edit the configuration class name, which is shown in the second field on this dialog box.
    Note:
    If this class already exists, this wizard ignores its existing contents and overwrites it. The new class is not created until you reach the end of the wizard.
    The default configuration class name is the web service or client class name, with Config appended to it.
  6. For details on the rest of this page, see Security Policy Descriptions and Policy Option Reference.”
  7. Click Finish.
    The wizard creates and saves the class.
  8. Review the generated configuration class, which also includes a policy expression that adds timestamps to outbound messages:
    <sp:IncludeTimestamp/>
  9. Optionally edit the configuration class and re-save it.
    You would do this, for example, to add policy alternatives or to fine-tune the policy created by the wizard.
The class is not automatically compiled and the policy is not in effect until the class is compiled.
Tip:
If you compile the configuration class and then want to disable it, comment out the XData block and recompile it.
Generating the Policy from the WSDL
In some cases, you might already have client classes, but not the corresponding configuration classes. This could occur, for example, if you generate the client classes from the WSDL and later the WSDL is modified to include WS-Policy information. In such cases, you can generate the configuration class alone by using a utility method in %SOAP.WSDL.Reader, as follows:
  1. Create an instance of %SOAP.WSDL.Reader.
  2. Set properties of that instance as applicable. See the class documentation for %SOAP.WSDL.Reader.
    Do not use the Process() method.
  3. Invoke the GeneratePolicyFromWSDL() method of your instance.
    This method has the following signature:
    method GeneratePolicyFromWSDL(wsdlURL As %String, 
        clientWebServiceClass As %String, 
        policyConfigClass As %String) as %Status
    Where:
This creates (or overwrites) a configuration class for a web service client which contains the policy specified by the WSDL of the web service. If there is no policy in the WSDL, an empty configuration class is created. The configuration class will be compiled if the CompileClasses property of the instance equals 1.
Editing the Generated Policy
If you generate a configuration class from a WSDL and if the WSDL is external to this instance of Caché, you must edit the configuration class to include information about the certificates and SSL/TLS configurations to use. Or you could specify this information at runtime.
Also, if you select Establish Secure Session (Secure Conversation), you can edit the policy to specify an optional lifetime for the secure conversation.
The following table gives the details:
If the Generated Policy Includes ... Do the following ...
<sp:HttpsToken> For a policy attached to client, do one of the following:For a policy attached to a service, no change is needed.
<sp:InitiatorToken> For a policy attached to client, do one of the following:In either case, this must be a credential set owned by the client.
For a policy attached to a service, no change is needed.
<sp:RecipientToken> Do one of the following:In either case, this must be a credential set owned by the service.
<sp:SecureConversationToken> Optionally add the cfg:Lifetime attribute as described in Adding InterSystems Extension Attributes in the next chapter. The default lifetime is 5 minutes.
Security Policy Descriptions
The primary purpose of the wizard is to provide configurable security policies. The choices for Security Policy are as follows:
The following section lists all the policy options.
SSL/TLS Connection Security
This policy requires use of HTTP over SSL/TLS (HTTPS) between the web client and the web service. It provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
Username Authentication over SSL/TLS
This policy requires the client to send a <UsernameToken> (with username and password). This policy also requires HTTP over SSL/TLS (HTTPS), which provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
At runtime, the web client must create and add the username token with the default password type. See Adding a Username Token,” later in this book.
X.509 Certificate Authentication over SSL/TLS
This policy requires the client to send messages with signed body and timestamp and the X.509 certificate that can verify the signature. WS-Addressing headers, if included, are also signed. This policy also requires HTTP over SSL/TLS (HTTPS), which provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
Authentication with Symmetric Keys
This policy requires a single, shared secret key that is used to both sign and encrypt the message. This symmetric key is generated at runtime and is encrypted using the public key of the service’s certificate.
The service can optionally require an encrypted username and password with the default password type for authentication; if you choose this option, the client must add the <UsernameToken> at runtime, as described in Adding a Username Token,” later in this book. It is not necessary to manually encrypt the <UsernameToken>; Caché automatically encrypts it.
Symmetric Keys with Endorsing Certificate
This policy requires a single, shared secret key that is used to both sign and encrypt the message. This symmetric key is generated at runtime and is encrypted using the public key of the service’s certificate.
The service can optionally require an encrypted username and password with the default password type for authentication; if you choose this option, the client must add the <UsernameToken> at runtime, as described in Adding a Username Token,” later in this book. It is not necessary to manually encrypt the <UsernameToken>; Caché automatically encrypts it.
This mechanism uses an endorsing client certificate to augment the token associated with the message signature.
Mutual X.509 Certificates Security
This policy requires all peers to sign the message body and timestamp, as well as WS-Addressing headers, if included. It also optionally encrypts the message body with the public key of the peer's certificate.
The service can optionally require an encrypted username and password with the default password type for authentication; if you choose this option, the client must add the <UsernameToken> at runtime, as described in Adding a Username Token,” later in this book. It is not necessary to manually encrypt the <UsernameToken>; Caché automatically encrypts it.
SAML Authorization over SSL/TLS
This policy requires the client to send a SAML token that contains an X.509 certificate or a public key. The corresponding private key signs the message body and timestamp, as well as WS-Addressing headers, if included. This policy also requires HTTP over SSL/TLS (HTTPS), which provides confidentiality and integrity of the data stream, authentication of the server, and optional authentication of the client.
SAML with X.509 Certificates
This policy requires the client to send a SAML token. This policy also signs the message body and timestamp, as well as WS-Addressing headers, if included. It also optionally encrypts the message body with the public key of the peer's certificate.
Policy Option Reference
The predefined policies have many of the same options. The following list provides details on all the options, following the order they are shown in the wizard.
Establish Secure Session (Secure Conversation)
Where applicable: All security policies.
If you select this option, the web service and web client establish and use a shared, secret security context. Then both parties can generate the same symmetric key and use it for signing, encryption, signature validation, and decryption.
Require Derived Keys
Where applicable: All security policies.
This option is applicable only if the previous option is also selected. If you select Require Derived Keys, then a derived key is used in the messages, rather than the original session key.
Reliable Message Delivery
Where applicable: All security policies.
This option specifies that the WS-ReliableMessaging protocol must be used when sending messages. This protocol allows SOAP messages to be reliably delivered even in the presence of software component, system, or network failures.
Note:
You can specify parameters in a Caché web service to fine-tune its behavior with WS-ReliableMessaging. See Controlling How the Web Service Handles Reliable Messaging,” later in this book.
SSL Configuration
Where applicable: All policies that use SSL/TLS. Applies only to the client.
SSL/TLS configuration for the client to use.
In all applicable policies, you can either choose an SSL/TLS configuration within the wizard (hardcoding that selection), or you can programmatically select and add one in the web service or client; see Specifying the SSL/TLS Configuration to Use,” earlier in this book.
SSL/TLS Connection Requires Client Certificate
Where applicable: All policies that use SSL/TLS.
Optionally select this option if the SSL/TLS connection requires the client to authenticate itself. See the comments for SSL Configuration.
Encrypt SOAP Body
Where applicable: All policies that do not use SSL/TLS.
Optionally select this to encrypt the SOAP body with the public key of the peer’s certificate.
Encrypt Before Signing
Where applicable: All policies that do not use SSL/TLS.
Optionally select this to require that the messages are encrypted before being signed. If this option is not selected, the messages are signed and then encrypted.
Token Protection - Signature must cover the token used to generate the signature
Where applicable: All policies that do not use SSL/TLS.
Optionally select this to require that the message signature is applied to the binary security token that carries the certificate whose associated private key signs the message.
X.509 Credentials
Where applicable: X.509 Certificate Authentication over SSL/TLS. Applies only to the client.
Caché credential set for the client to use when signing messages. The signature uses the private key in the associated certificate. See the subsection Credential Sets.”
Include Encrypted Username Token
Where applicable: Several policies.
Optionally select this to require the client to send an encrypted element that contains a <UsernameToken>.
If you choose this option, you must add the <UsernameToken> at runtime as described in Adding a Username Token,” later in this book. It is not necessary to manually encrypt the <UsernameToken>; Caché automatically encrypts it.
Protection Token
Where applicable: Policies that use symmetric keys. Applies only to the client.
Caché credential set for the client to use to generate the symmetric key; this should be the certificate of the service. The symmetric key is generated with the public key of the certificate. See the subsection Credential Sets.”
Endorsing Token
Where applicable: Symmetric Keys with Endorsing Certificate. Applies only to the client.
Caché credential set for the client to use to endorse the protection token. This should be the certificate of the client. See the subsection Credential Sets.”
Initiator Token
Where applicable: Mutual X.509 Certificates Security and SAML with X.509 Certificates. Applies only to the client.
Caché credential set for the web client to use. The client uses the associated private key for message signing and sends the initiator token to the service to enable the service to verify signatures and encrypt the response. See the subsection Credential Sets.”
Recipient Token
Where applicable: Mutual X.509 Certificates Security and SAML with X.509 Certificates.
Caché credential set for the web service to use. The client uses the public key in the certificate in the recipient token to encrypt the outbound message body. The service uses the associated private key for message signing. See the subsection Credential Sets.”
Algorithm Suite
Where applicable: All security policies.
Algorithm suite for the web server and client to use. For details, see section 6.1 in the WS-SecurityPolicy specification.
Strict Security Header Layout
Where applicable: All security policies.
Optionally select this option to enforce a strict layout of security header elements.
Enable WS-Addressing
Where applicable: All policies.
If you select this option, the web service or web client includes WS-Addressing header elements in outbound messages and expects them in inbound messages.
If you use Enable WS-Addressing, Caché uses a default set of WS-Addressing header elements; for details on the included elements, see Adding WS-Addressing Header Elements in the chapter “Adding and Using SOAP Headers” in Creating Web Services and Web Clients in Caché.
Even when you select Enable WS-Addressing, you can manually create WS-Addressing header elements and attach them as described in that book; if you do so, the web service or client uses those header elements instead of the default ones.
Optimize transfer of binary data (MTOM)
Where applicable: All policies.
If you select this option, the web service or web client uses MTOM packaging in outbound messages and expects MTOM packaging in inbound messages.
Credential Sets
In many of the policies, you can select a Caché credential set as follows:
Or you can programmatically select a credential set; see Retrieving Credential Sets Programmatically,” earlier in this book. In this case, you also need to package the certificate in a binary security token and add it to the outbound messages, as described in Adding a Certificate at Runtime,” later in this chapter.
Adding a Certificate at Runtime
If your web service or client must select and include a certificate programmatically, use the following procedure:
  1. Retrieve an instance of %SYS.X509Credentials, as described in Retrieving Credential Sets Programmatically,” earlier in this book.
    For example:
     set credset=##class(%SYS.X509Credentials).GetByAlias(alias,password)
    Or:
     set credset=..SecurityIn.Signature.X509Credentials 
  2. Create an instance of %SOAP.Security.BinarySecurityToken that contains the certificate from that credential set. For example:
     set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
    Where credentials is the credential set you retrieved in the previous step.
    This returns an object that represents the <BinarySecurityToken> element, which carries the certificate in serialized, base-64–encoded form.
  3. Call the AddSecurityElement() method of the SecurityOut property of your web client or web service. For the method argument, use the binary security token you created previously. For example:
     do ..SecurityOut.AddSecurityElement(bst)
Important:
In some cases, two binary security tokens are needed: one for encryption and one for signing. Be sure to add these in the appropriate order, depending on whether you selected the Encrypt Before Signing option. If the policy encrypts the message and then signs it, be sure to add the binary security token used for encryption before you add the one used for signing. Conversely, if the policy signs and then encrypts, the first binary security token must be the one used for signing.
The following shows an example within a web method in a web service:
 //get credentials
 set x509alias = "something"
 set pwd = "password"
 set credset = ##class(%SYS.X509Credentials).GetByAlias(x509alias,pwd)

 //get certificate and add it as binary security token
 set cert = ##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
 do ..SecurityOut.AddSecurityElement(cert)
The code would be slightly different for a web client, because you do not typically edit the proxy client:
 set client=##class(proxyclient.classname).%New()
 //get credentials
 set x509alias = "something"
 set pwd = "password"
 set credset = ##class(%SYS.X509Credentials).GetByAlias(x509alias,pwd)

 //get certificate and add it as binary security token
 set cert = ##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)
 do client.SecurityOut.AddSecurityElement(cert)
 //invoke web method of client
Specifying a Policy at Runtime
For a Caché web client, you can specify the policy to use at runtime; this overrides any policy configuration class. To specify the policy at runtime, set the PolicyConfiguration property of the web client instance. The value must have the following form:
Configuration class name:Configuration name
Where Configuration class name is the full package and class name of a policy configuration class, as described earlier in this chapter, and Configuration name is the value of the name attribute of the <configuration> element for the policy in that class
Suppressing Compilation Errors for Unsupported Policies
By default, when you compile a configuration class, Caché issues an error if the configuration includes any policy expressions that are not supported in Caché. To suppress such errors, include the following in the configuration class:
Parameter REPORTANYERROR=0;
When you use the SOAP Wizard to generate a web client or web service from a WSDL, if Caché also generates a configuration class, it includes this parameter setting in that class.
Unsupported alternatives can be ignored as long as there is one supported policy alternative.