This section explains the security policies available to you, and how to configure the security properties, truststores, and keystores.

Prior to deploying a web service, you must decide how you want the service to be secured. The following are all supported security policies:

This mechanism protects messages with mutual certificates for integrity and confidentiality, as well as with a Sender Vouchers SAML token for authorization.

When using this security policy, the SOAP client provides an SAML Subject (within an SAML Assertion) containing the name identifier, which signifies the username the server should run the request as. In this case the message payload is signed and encrypted, because the client and server have established a trust relationship using the contents of their respective keystores and truststores.

In this situation, the server only verifies that the supplied username is valid prior to handling the request.

This policy requires that the client have both a keystore and truststore corresponding to the server’s. In addition, Java clients require a callback handler that provides the SAML Assertion containing the username that the server should trust.

The username authentication with symmetric keys mechanism protects SOAP interactions for both integrity and confidentiality. Symmetric key cryptography relies on a single, shared secret key that is used to both sign and encrypt a message. Symmetric keys are usually faster than public key cryptography.

For this mechanism the client does not possess any certificate or key of its own, but instead sends its username and password for authentication. The client and the server share a secret key. This shared, symmetric key is generated at runtime and encrypted using the service’s certificate. The client must specify the alias in the truststore by identifying the server’s certificate alias.

In this situation, the server authenticates the given username using the corresponding supplied password.

This policy requires that the client have a truststore corresponding to the server’s configuration. In addition, Java clients require callback handlers to provide the username and password to send along with the request for the server to validate. For an example of this mechanism, see Username Authentication with Symmetric Keys Example.

This security policy uses SSL (https) for confidentiality and an X.509 certificate to authenticate the user. The user’s certificate must be trusted by the server, and the username that is validated with Windchill is extracted from the certificate. By default, the username is extracted from the subject of the certificate (stripping any preceding CN= from the participant). Since the basic mapping of the certificate to a Windchill username may be insufficient, the logic used to extract the username is configurable. You can implement the com.ptc.jws.security.SubjectToUidHandler interface and configure your servlet implementation using the following:

which specifies your implementation.

<ServletName> within the property name refers to the servlet for which the SubjectToUidHandler implementation should be used.

The Apache Ant build tooling requires a security configuration for the server that specifies the security policy to use, as well as the truststore and keystore configurations. You must edit the security.properties file to specify this information before deploying a web service.

The server security.properties file is found at:

It contains comments describing its contents.

For writing or testing Java clients, there is a parallel client properties file found at:

It contains similar comments describing its contents.

Unless you are manually configuring your web service behind web server authentication, you are required to secure your web service using X509 v3 certificates. Note that the security mechanisms used require the SubjectKeyIdentifier extension. The keytool utility released with Java does not generate this extension.

The Apache Ant build script is located at:

This build script can generate client or server keystore and truststore pairs for use by Info*Engine web service examples. You can also use it for testing and development purposes. The Apache Ant build script uses OpenSSL to generate client and server certificates, and then uses the Java keytool utility to import these certificates into client or server keystore and truststore files.

You can use the jws-stores.xml build script as an illustration on how to use your own certificate to create truststores and keystores for your web services and clients. This script only generates a single server and client certificate, and then imports those certificates into their corresponding keystores before generating the truststores for the client and server.

To generate these files, run the following script from a windchill shell:

While the script is running, you are prompted several times for user input. You can choose to either accept the defaults (presented surrounded by brackets like [ws-server]) by simply pressing Enter when prompted, or supply your own input. If you choose the default input, then the released configured security.properties files should contain the proper configuration. If you decide to supply other input when running the script, then you need to update the corresponding security.properties configuration accordingly. When the script has finished running, the <Windchill>/prog_examples/jws/stores directory is created. This directory contains the following files: