Personalizzazione avanzata > Info*Engine User's Guide (Guida dell'utente Info*Engine) > Web Services Framework > Understanding the Security Requirements
  
Understanding the Security Requirements
This section explains the security policies available to you, and how to configure the security properties, truststores, and keystores.
Security Policies
Prior to deploying a web service, you must decide how you want the service to be secured. The following are all supported security policies:
SAML Sender Vouchers with Certificates
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.
* 
It is extremely important to understand that when using this mechanism the client is “vouching” for the username associated with the SOAP request. The SOAP client is, in essence, impersonating a given user or users without being required to supply corresponding passwords. This mechanism is really only appropriate for an SSO (Single Sign On) type scenario, in which you are certain that the client application has appropriately authenticated the users, and you are willing to extend trust to that client using certificate exchange in the keystore and truststore configuration.
Username Authentication with Symmetric Keys
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.
X.509 Certificate Authentication Over SSL
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:
wt.property com.ptc.jws.security.x509SSL.<ServletName>.SubjectToUidHandlerClass
which specifies your implementation.
<ServletName> within the property name refers to the servlet for which the SubjectToUidHandler implementation should be used.
* 
When writing a Java client to a service protected by SSL, you must supply the https URL of the WSDL for your service to the javax.xml.ws.Service constructor argument as an instance of java.net.URL. Your HTTP server’s SSL certificate must either be signed by a certificate authority or manually imported into the client’s <JAVA_HOME>/jre/lib/security/jssecacerts certificate store.
The security.properties File
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:
<Windchill>/bin/adminTools/WebServices/security.properties
It contains comments describing its contents.
For writing or testing Java clients, there is a parallel client properties file found at:
<Windchill>/bin/adminTools/WebServices/client/security.properties
It contains similar comments describing its contents.
* 
Both files, as released, contain a configuration that points to corresponding client and server truststore and keystore pairs, which can be generated for use with the web service examples discussed later in “Truststores and Keystores.”. While it is possible to use these generated truststores and keystores to secure web services, it is recommended that you acquire your own certificates and use them to populate truststores and keystores for your applications.
Truststores and Keystores
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:
<Windchill>/prog_examples/jws/jws-stores.xml
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:
% cd <Windchill>/prog_examples/jws
% ant -f jws-stores.xml
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:
server-keystore.jks
server-truststore.jks
client-keystore.jks
client-truststore.jks
server.p12
client.p12
server.cer
client.cer
* 
The .p12 (PKCS #12 Personal Information Exchange) files can be used to populate a Windows certificate store for .NET client access requiring certificates. The .cer files are the certificates used to populate the truststores and keystores.