Web Services Stack has security facilities for securing the message
content, support for HTTP basic authentication, SSL support for securing the
communication channel, and user authentication based on Software AG SIN
LoginModules.
This document covers the following topics:
This section covers the following topics:
The symmetric message security and the asymmetric message security are both part of the WS-Security specification. Message-level security is applied between the web service client and the web service itself in both directions.
Message-level security secures the message content itself, but it does not secure the communication channel. This is in contrast to transport-level security, where the communication channel is secured. To apply message security, you have to make several configurations on both the client side and the server side.
There are many different ways you can configure message-level security, based on your security needs. For examples, see Web Services Security: SOAP Message Security 1.1 and WS-Security Policy Language.
Web Services Stack provides an Eclipse plug-in graphical user interface that can be used to create the needed security configuration. You can install the plug-in in Eclipse and use it to create web service archives (that is, AAR archives). For more information, see Eclipse Plug-in.
Security configurations in Web Services Stack are based on WS-Security Policy specification.
You can configure the server side by changing the properties in the services.xml file
You need a keystore file that contains the X.509 certificate of the server. It may also contain client public keys.
You can re-use initialized (loaded) keystore instances by caching them the first time they are loaded. Any other configuration (such as key aliases and password callback handlers) will be retrieved from the Rampart configuration separately for every invocation.
You have the option to set caching globally in the axis2.xml for all services that are deployed in Web Services Stack runtime, or for a service, service group, specific operation or message in the services.xml descriptor of your service. However, keep in mind that keystore caching is per message because the keystore configuration itself may be different for each message.
To enable keystore caching
Set the parameter cacheCryptoInstances to
“true”.
<parameter name="cacheCryptoInstances">true</parameter>
Note:
When a service is undeployed or simply stopped any cached keystores
will be removed. You can deactivate (stop) services using the
Administration
module or deacivate and undeploy (delete completely the
service and all its files) using the Administration Tool
of the System Management Hub.
Depending on the security policy, the client may be required to send the token used for encryption signature within the message itself. Thus, there is no need to have all client certificates at the server side. Rampart, however, still verifies whether the certificates are trustworthy and therefore requires that at least the certificate of the issuer is present in the truststore. In this case, instruct Rampart/WSS4J (used to sign the request) to use the client’s certificate.
Following is the value assigned to the <encryptionUser> field:
<encryptionUser>useReqSigCert</encryptionUser>
“useReqSigCert” is a special fictional encryption user that is recognized by the security module. In this case, your certificate (that is used to verify your signature) is used for the encryption of the response. Thus, it is possible to have only one configured encryption user for all clients that access the service.
Look at the following example of symmetric binding security configuration in the services.xml file:
<ramp:encryptionUser>client</ramp:encryptionUser>
The original value "client" is in fact an example of an alias for a client’s certificate that has to be stored into the keystore used at server side.
If you want to authenticate a client who uses a user name token, you
have to provide a password callback handler class to
validate the user name and the password received from the client.
When you provide a password using the callback handler class, you make a check towards a given authentication module. The module may be a JAAS module, or some other one.
Note:
This authentication mechanism applies to the user name security
token and is used in a similar way with other security tokens, too.
The keystore properties can be configured by adding a Rampart custom policy assertion to the services.xml file. Following is an example of symmetric binding security configuration in the services.xml file:
<wsp:Policy wsu:Id="User defined" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsp:ExactlyOne>
<wsp:All>
<sp:SymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:ProtectionToken>
<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
<wsp:Policy>
<sp:WssX509V3Token10/>
<sp:RequireDerivedKeys/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:ProtectionToken>
<sp:AlgorithmSuite xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:Basic128/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
</wsp:Policy>
</sp:SymmetricBinding>
<sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Policy>
<sp:MustSupportRefKeyIdentifier/>
<sp:MustSupportRefIssuerSerial/>
</sp:Policy>
</sp:Wss10>
<sp:SignedSupportingTokens xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy/>
</sp:SignedSupportingTokens>
<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<ramp:user>service</ramp:user>
<ramp:encryptionUser>client</ramp:encryptionUser>
<ramp:passwordCallbackClass>com.softwareag.wsstack.pwcb.PasswordCallbackHandler</ramp:passwordCallbackClass>
<ramp:signatureCrypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">service.jks</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">openssl</ramp:property>
</ramp:crypto>
</ramp:signatureCrypto>
<ramp:encryptionCypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">service.jks</ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">openssl</ramp:property>
</ramp:crypto>
</ramp:encryptionCypto>
</ramp:RampartConfig>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
You can configure the keystores for signing and encrypting using the custom Rampart configuration (the code listing in bold in the preceding example.
Configurations on the server side can also be done using the Web Services Stack Eclipse plug-ins. With the Eclipse plug-in, you can complete the preceding configuration using graphical user interface.
For more information, see Eclipse Plug-in, Web Services Security: SOAP Message Security 1.1, and WS-Security Policy Language.
When you use the client API to invoke web services that require security, you can specify security configuration settings through a properties file.
Specify in the client axis2.xml configuration file
the file name and the path to it. This file must be a part of the client’s
CLASSPATH file. This file holds the required parameters for the client
configuration, that is, the securityConfigFile
parameter:
<parameter name="securityConfigFile">D:/wsdev/SampleWSClient/wsclientsec.properties </parameter>
If you do not define such a parameter, the client implementation looks for a wsclientsec.properties file in the current working directory.
If a securityConfigFile parameter exists but the
file specified cannot be found, you get an exception. If the parameter is not
defined or a wsclientsec.properties file is not present in
the current working directory, then the configuration loading routine does not
throw any exceptions.
Note:
The loading of the security configuration settings takes place only
if the web service policy contains security assertions (that is only if the
security module is engaged).
Following is the list of the supported configuration keys:
| Key | Description |
|---|---|
| USERNAME | This is the user's name. It is used by the
WS-Security functions for the following functions:
|
| ENCRYPTION_USER |
The user's name for encryption. The encryption function uses the
public key of this user's certificate to encrypt the generated symmetric key.
If this parameter is not set, then the encryption function falls back to the
|
| USER_CERTIFICATE_ALIAS |
The alias of the key pair in the keystore, to get the private key
used for the signature. If this is not set, the signature function falls back
to |
| STS_ALIAS |
The STS alias is used as an encryption user in case of a STS authentication. |
| POLICY_VALIDATOR_CLASS |
The policy validator callback class is responsible for validating the security header against the security policy. The default callback class is the org.apache.rampart.PolicyBasedResultsValidator. |
| TIMESTAMP_PRECISION_IN_MS |
Defines whether timestamp precision is in milliseconds. The default value is TRUE. The expected values are TRUE or FALSE. This parameter is passed to wss4j WSSConfig. The setting concerns the Timestamp element that may be required/ included in the security header. If the precision is set to be in milliseconds, the timestamp is written in milliseconds, otherwise the time stamp is written in the following simple date format: yyyy-MM-dd'T'HH:mm:ss'Z' |
| TIMESTAMP_TTL |
Timestamp time-to-live in seconds. An integer value is expected. Default is 300. |
| TIMESTAMP_MAX_SKEW |
Used in timestamp validation where the timestamp creation timestamp must not be later than current time plus the time skew. The max time skew is an integer and is expected in seconds. Default is 300. |
| PASSWORD_CALLBACK_HANDLER_CLASS |
A class that implements the
|
| OPTIMIZE_PARTS_EXPRESSIONS |
A list of Xpath expressions that refer to nodes that must be MTOM-optimized. The configured value is a semicolon delimited list of Xpath expressions. Note that if this property is set, it overwrites any previously configured list of expressions and does not add them to the list. |
| OPTIMIZE_PARTS_NAMESPACES |
A list of namespaces that is taken into consideration when searching for the nodes that are to be MTOM-optimized. It is essential for the correct retrieval of the nodes from the document, that the namespace prefixes used in the OPTIMIZE_PARTS_EXPRESSIONS list are recognized by the optimizing utility. It has by default following registered namespaces: xmlns:ds=http://www.w3.org/2000/09/xmldsig#
xmlns:xenc=http://www.w3.org/2001/04/xmlenc#
xmlns:wsse=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
xmlns:wsu=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd
plus all the declared namespaces here. That property is expected
as a semicolon delimited list of XML namespace declarations (for example,
Note: |
| CRYPTO_PROVIDER_SIGN |
The WSS4J-specific Crypto implementation that is to be used for generating the signature. It can be set to one of the following:
|
| KEYSTORE_PROVIDER_SIGN |
The signature keystore provider. If not set the JVM uses the default (normally Sun’s) keystore
provider. For additional information, refer to
|
| KEYSTORE_TYPE_SIGN | The signature keystore type. If not set, the JVM
uses the default keystore type (normally “jks”). For additional information,
refer to the java.security.KeyStore#getDefaultType()
method javadocs.
|
| KEYSTORE_FILE_SIGN |
The signature keystore file. |
| KEYSTORE_PASSWORD_SIGN |
The signature keystore password. |
| CRYPTO_PROVIDER_ENCRYPT | The WSS4J-specific Crypto implementation to use
for encryption. It can be set to one of the following:
|
| KEYSTORE_PROVIDER_ENCRYPT |
The encryption keystore provider. If not set the JVM uses the default (normally Sun’s) keystore provider. For additional information, refer to
|
| KEYSTORE_TYPE_ENCRYPT |
The encryption keystore type. If not set, the JVM uses the default keystore type (normally “jks”). For additional information, refer to
|
| KEYSTORE_FILE_ENCRYPT | The encryption keystore file. |
| KEYSTORE_PASSWORD_ENCRYPT | The encryption keystore password. |
| CRYPTO_PROVIDER_STS | The WSS4J-specific Crypto implementation to use
for protection in case of a STS. Currently, it can be set to one of the
following:
|
| KEYSTORE_PROVIDER_STS |
The keystore provider used in case of a STS. If not set the JVM uses the default (normally Sun's) keystore provider For additional information, refer to
|
| KEYSTORE_TYPE_STS |
The keystore type used in case of a STS. If not set, the JVM uses the default keystore type (normally JKS). For additional information, refer to
the |
| KEYSTORE_FILE_STS |
The keystore file used in case of a STS. |
| KEYSTORE_PASSWORD_STS |
The keystore password used in case of a STS. |
| SSL_KEYSTORE_TYPE |
The type of the keystore specified under
|
| SSL_KEYSTORE_PASSWORD |
The password for the keystore specified under
KEYSTORE_SSL_LOCATION. This property corresponds to the |
| KEYSTORE_SSL_LOCATION |
The keystore file for SSL authentication.
This property corresponds to the JSSE
For more information, refer to the JSSE Reference Guide. Note: |
| TRUSTSTORE_SSL_LOCATION |
The truststore file for SSL authentication. The client requires
that the server's certificate is installed in this truststore and it is
trusted. This property corresponds to the JSSE
Note: |
| TRUSTSTORE_SSL_PASSWORD |
The password for the truststore specified under
Note: |
Note:
The last five entries actually refer to transport-level security
configuration (SSL settings).
The configuration loading routine puts all those entries in the client options. Thus, you can overwrite any particular option every other time Rampart is to be executed. For example, all security keys can be specified programmatically using the Web Services Stack client options:
//create the WS Stack client: IWSStaxClient client = ... ... IWSOptions options = client.getWSOptions(); options.setProperty(WSClientConstants.KEYSTORE_PASSWORD_SIGN, "changeit"); options.setProperty(WSClientConstants.KEYSTORE_FILE_SIGN, "C:\\client.jks"); //set the options, overwriting the ones loaded from the wsclientsec.properties //file: client.setOptions(options); //execute the client client.sendReceive(...);
The Rampart is afterwards configured through a Rampart assertion that
is generated by the RampartConfigLoader handler. The Web
Services Stack client takes care of engaging that handler if Rampart itself is
engaged. The function of the RampartConfigHandler is
basically to gather all the security configuration keys, build up the Rampart
configuration assertion, and put it as a property in the message context
options where Rampart can find it.
This section covers the following topics:
Transport-level security addresses the problem of securing web service conversation by securing the communication channel instead of the message data itself. Although the web service security policy specification does not state that the transport-level security requires the use of HTTP transport over SSL, it is the most typical use case.
This section provides details on the configuration and usage of web service communication over HTTPS.
To enable transport-level security, configure your application server to use SSL:
To configure Tomcat to use SSL at server side
Navigate to <TOMCAT_INSTALL_DIR>\conf and open the server.xml file to configure an SSL Connector.
Note:
<TOMCAT_INSTALL_DIR> is the path where
your copy of Tomcat is installed.
The configured scheme needed for the SSL communication is https. The required parameters are listed in the following table:
| Property name | Description |
|---|---|
| KEYSTORE_FILE_PATH | The path to the keystore file that is used by Tomcat to decrypt the requests and encrypt the responses. |
| KEYSTORE_PASSWORD | The password that protects the keystore. |
| ENCRYPTION_KEY_ALIAS | The alias that identifies the key pair in the keystore (in case there is more than one public-private key pair in the keystore). |
Following is a sample code listing for an SSL connector configuration:
<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150"
minSpareThreads="25" maxSpareThreads="75" enableLookups="false"
disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="="<KEYSTORE_FILE_PATH>"
keystorePass="<KEYSTORE_PASSWORD>"
keyAlias="<ENCRYPTION_KEY_ALIAS>"/>
Note:
The value of the connector port is
"8443" because this is the standard Tomcat HTTPS port.
If a server declares explicitly the use of the HTTPS transport in its services.xml, you have to define that such a transport listener is defined in the axis2.xml configuration file. Otherwise, the runtime throws an exception while trying to deploy the respective service.
As of Web Services Stack ver. 8.x, the
com.softwareag.wsstack.transport.http.HTTPListener and
the com.softwareag.wsstack.transport.http.HTTPSListener
are introduced to solve the problem when Web Services Stack is served by a
servlet container.
In that case, the actual transport receiver is the
SAGAdminServlet that registers itself as an HTTP
listener only. However, you still need to have an HTTPS listener configured in
the axis2.xml file. The
com.softwareag.wsstack.transport.http.HTTPSListener is a
full functional replacement of the previously available
org.apache.axis2.transport.http.HTTPSListener in Web
Services Stack 1.2.
To use the new HTTPS listener, uncomment the respective configuration in the axis2.xml file shipped with Web Services Stack. Following is a sample configuration:
<transportReceiver name="https"
class="com.softwareag.wsstack.transport.http.HTTPSListener">
<parameter name="port">8443</parameter>
</transportReceiver>
In this code listing, the configured port number must be set to the
port configured for the HTTPS connector of the servlet container. The newly
configured HTTPSListener is responsible for generating
correct endpoint addresses in the WSDL and supplying a
SessionContext, although the actual requests are served
by the SAGAdminServlet.
In this case, the SSL configuration uses only server authentication
(see clientAuth="false" in the preceding configuration) and the
client encrypts automatically the requests with the server public key.
To configure SSL at the client side
The client must send a request against HTTPS endpoint with a port that is equal to the one specified at server side (that is "8443").
Set the properties in your security configuration file. You can configure this file as a parameter in the axis2.xml configuration file:
<parameter name="securityConfigFile">your client security config file path </parameter>
For information on the axis2.xml configuration file, see Web Services Stack Runtime.
If you do not define a security configuration file, the client uses information in the wsclientsec.properties file in the current working directory.
Or:
Use the Web Services Stack client API to set the required
properties:
//create the WS Stack client: IWSStaxClient client = ... ... IWSOptions options = client.getWSOptions(); options.setProperty(WSClientConstants.KEYSTORE_PASSWORD_SIGN, "changeit"); options.setProperty(WSClientConstants.KEYSTORE_FILE_SIGN, "C:\\client.jks"); //set the options, overwriting the ones loaded from the wsclientsec.properties //file: client.setOptions(options); //execute the client client.sendReceive(...);
The following security properties at the client side relate to the SSL configuration:
| Property name | Description |
|---|---|
| SSL_KEYSTORE_TYPE | The type of the keystore specified under the KEYSTORE_SSL_LOCATION. |
| SSL_KEYSTORE_PASSWORD | The password for the keystore specified under
KEYSTORE_SSL_LOCATION. This property corresponds to the JSSE
javax.net.ssl.keyStorePassword system property.
|
| KEYSTORE_SSL_LOCATION |
The keystore file for SSL authentication. This property
corresponds to the For more information, refer to the JSSE Reference Guide. |
| TRUSTSTORE_SSL_LOCATION |
The truststore file for SSL authentication. The client requires
that the server's certificate is installed in this truststore and it is
trusted. This property corresponds to the JSSE For more information, refer to the JSSE Reference Guide. |
| TRUSTSTORE_SSL_PASSWORD |
The password for the truststore specified under
TRUSTSTORE_SSL_LOCATION. This property corresponds to the
For more information, refer to the JSSE Reference Guide. |
Server-side Configuration
The Tomcat web server may also be configured to use a client
certificate to encrypt the transferred data.
To use client authentication with Tomcat
Set the following parameters in the HTTPS connector settings in the Tomcat server.xml configuration file.
Set clientAuth to "true".
Set the keystore properties.
Set the truststore properties.
Important:
You can also configure the truststore location of Tomcat by
starting it with the respective Java system property, because if the truststore
properties are not set in your configuration, Tomcat uses the default Java
trusted authority keystore.
To configure the truststore location of Tomcat by starting it with
the respective Java system property
Add the following options when starting Tomcat:
-Djavax.net.ssl.trustStore=your_path_to/truststore.jks -Djavax.net.ssl.trustStorePassword=your_password )
Use the following settings to configure the truststore properties in the HTTPS connector:
| Property name | Description |
|---|---|
| truststoreFile |
The TrustStore file to use to validate client certificates. |
| truststorePass |
The password to access the truststore. This defaults to the
value of |
| truststoreType |
Add this element if your are using a different format for the
truststore than you are using for the keystore. The
|
Look at the following example to see a sample of the connector configuration:
<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="true" sslProtocol="TLS" keystoreFile="<KEYSTORE_FILE_PATH>" keystorePass="<KEYSTORE_PASSWORD>" keyAlias="<KEY_ALIAS>" truststoreFile="<TRUSTSTORE_FILE_PATH>" truststorePass="<TRUSTSTORE_PASSWORD>" truststoreType="<TRUSTSTORE_TYPE>"/>
Note:
If you encounter a problem with a service that declares the usage
of the HTTPS transport in its services.xml descriptor,
uncomment the respective HTTPS listener configuration in the
axis2.xml file shipped with Web Services Stack. For
details, see how to configure Tomcat to use SSL at server side in
Prerequisites for the Setup and
Use of Transport-Level Security
Client-side Configuration
It is also possible to use client certificate with the Web Services
Stack client, although additional work is needed to use the Java 1.4 compatible
HTTP sender (utilizing the Jakarta Commons HttpClient
component). In order to make the Commons HttpClient use
client certificate for the encryption one needs to register a new HTPPS socket
factory since the default one does not handle the case with the client
certificate. The Commons HttpClient library does not
provide the appropriate socket factory implementation but there is one in the
contrib package (commons-httpclient-contib) that is part
of the commons-httpclient project, namely
AuthSSLProtocolSocketFactory. This can be set in the
following way:
IWSStaxClient client = ...
...
ProtocolSocketFactory socketactory = new AuthSSLProtocolSocketFactory(
new File("keystore.jks").toURL(),
"keystorePassword",
new File("truststore.jks").toURL(),
"truststorePassword");
Protocol authhttps = new Protocol("https", socketactory, 8443);
client.getWSOptions().setProperty(HTTPConstants.CUSTOM_PROTOCOL_HANDLE,
authhttps);
To use the HTTP basic authentication, you must configure a specific endpoint that is to use the HTTP basic authentication scheme. The needed configuration is not server-specific and is part of the J2EE specification.
To configure a specific endpoint to use the HTTP basic authentication
scheme
Open your web application descriptor of Web Services Stack (the web.xml file that is located in the \webapps\wsstack\WEB-INF directory).
Add a security constraint for a particular URL.
In the following sample code listing, the constraint is the web
service endpoint. The relative URL that you are securing is
<url-pattern>/services/ut_asym_xpath</url-pattern>:
<security-constraint> <web-resource-collection> <web-resource-name>Protected Pages</web-resource-name> <url-pattern>/services/ut_asym_xpath</url-pattern> <http-method>POST</http-method> <http-method>GET</http-method> </web-resource-collection> <auth-constraint> <role-name>manager</role-name> </auth-constraint> </security-constraint> <security-role> <role-name>tomcat</role-name> <description>Web Services Stack user realm</description> </security-role> <login-config> <auth-method>BASIC</auth-method> <realm-name>Basic Authentication</realm-name> </login-config>
Note:
Set <role-name>tomcat</role-name> to
configure a role that ensures client authentication. This configuration is
server-specific.
The http methods from the preceding code
listing can be used for different purposes.
Note:
For more information, see
Java™
Servlet Specification version 2.4.
With the <http-method> tag, you can list the "http"
methods that require authentication. By removing
<http-method>GET</http-method>, you can access the
?wsdl formed URL without authentication (for example,
http://myhost:port/MyWebContext/MyService?wsdl). If no
http methods are listed explicitly in the
configuration, all http methods require authentication
by default.
When using Tomcat, you can use the HTTP basic authentication with tomcat-users.xml.
Note:
Software AG Tomcat Kit is not installed in one location as with any
other arbitrary installation of Apache Tomcat and does not contain a default
tomcat-users.xml. If tomcat-users.xml
is missing in your Tomcat configuration directory (\Documents and
Settings\All Users\Application Data\Software AG\Tomcat\v5.5\conf),
you must create it.
To use the HTTP basic authentication with
tomcat-users.xml
Define the role name in the tomcat-users.xml.
Following is a sample of a tomcat-users.xml file:
<?xml version='1.0' encoding='utf-8'?> <tomcat-users> </tomcat-users>
Note:
For information on how roles are defined in Tomcat, see Tomcat
documentation.
Restart Tomcat for the changes to take effect.
Once you have configured your endpoint for HTTP basic authentication, you can configure your web service client, so that it is aware of the changes.
To configure your web service client to use HTTP basic
authentication
Supply the
HttpTransportProperties.Authenticator object
Set the user name to “tomcat”.
Set the password to “tomcat”.
Set this configuration as an option of the web service client.
Following is a sample code listing of a web service client implementation when you want to use HTTP basic authentication:
IWSStaxClient client = (IWSStaxClient)WSClientFactory.newClient(
WSClientConstants.STAX_WSCLIENT,
"C:/ut_asym_xpath.wsdl",
null,
null,
"C:\\Software AG\\WS-Stack\\repository");
HttpTransportProperties.Authenticator auth = new
HttpTransportProperties.Authenticator();
auth.setUsername ("tomcat");
auth.setPassword ("tomcat");
auth.setPreemptiveAuthentication (true);
IWSOptions options = client.getWSOptions();
options.setProperty(
org.apache.axis2.transport.http.HTTPConstants.AUTHENTICATE,auth);
client.setOptions(options);
Important:
In the above example, you must supply the
HttpTransportProperties. Authenticator object first, and
then set up a user name and a password according to the configured Tomcat role.
Finally, you need to set this configuration as an option of the web service's
client.
Web Services Stack provides a mechanism for authenticating clients in Web Services Stack runtime layer using the common Java Authentication and Authorization Service (JAAS) security framework.
Software AG Security Infrastructure (SIN) provides you with an
implementation of JAAS LoginModules for client
authentication.
When you log on using JAAS LoginContext, a
javax.security.auth.Subject is produced. That subject
contains user principals and
credentials and is available to anyone on the execution
chain through the message context.
Web Services Stack collects all available security credentials from the
client request and populates them in SIN SagCredentials.
After that, the logon process is performed in the policy validator
implementation of Rampart.
The information is organized under the following headings:
Before you can log on, you must configure JAAS. For information about the JAAS configuration file, see SIN documentation in the webMethods Product Suite 8.0 folder on the Software AG Documentation Web site.
There are two types of user credentials that are used for authentication in Web Services Stack:
Transport-level credentials
Transport-level credentials refer to the communication channel used
for the message exchange and are specific for the respective transport that is
used. Web Services Stack extracts those credentials from the HTTP(S) transport
only:
User name and password, in the case of a basic HTTP authentication
A client certificate chain in the case of a client certificate used for encryption of the transferred data
Message-level credentials
In the case of message-level credentials, Web Services Stack can
extract those from the SOAP security header:
A user name and a password if you use
UsernameToken with plain text password
X509Certificate used for the signatures if there are signed parts or elements in the message
You use password callback handlers in particular identifiers to provide passwords, which are used in the following use cases:
Passwords that are needed by the Web Services Stack security module to build user name tokens and to create signatures to send messages.
Passwords that are required for validation of incoming username tokens and decryption of the content of incoming messages.
The callback handlers can retrieve passwords from configuration files, data bases, LDAP servers, or other application components which are used for user management (for example Security Infrastructure).
Web Services Stack has a predefined set of password callback handlers, which facilitate different scenarios for retrieving passwords. You can use these handlers directly or you can develop your own password callback handlers out of them. The following password callback handlers are available:
com.softwareag.wsstack.pwcb.ConfigFilePasswordCallbackHandler
The password callback handler retrieves identifier-password pairs from a configuration file and then loads the pairs which can be used to find the needed password for a particular identifier. The configuration file must be in XML format and similar to the configuration file of the Web Services Stack (axis2.xml). You can provide a configuration file to the callback handler as follows:
You can specify the configuration file in the Web service archive.
In the services.xml file, you add a
PWCBConfigFile parameter, which is set to point to
the configuration file resource on the service class path. The class path
includes the service archive, the libraries which are in the service archive,
the web application class path (all jar files in
WEB-INF/lib and the WEB-INF/classes
class folder) and so on.
<serviceGroup> <service name="Sample_Web_Service"> <parameter name="PWCBConfigFileLocation"> configuration_file_location </parameter> ... </service> </serviceGroup>
If you do not specify the configuration file resource, by default
the callback handler searches for a resource with name
users.xml in the service class path. If it is not
available, a FileNotFoundException is thrown.
The same password callback handler is also available at the client side if there is no service archive. Then, presumably, the configuration file is users.xml and is searched on the class path of the client. Then it is loaded as a resource.
com.softwareag.wsstack.pwcb.LdapPasswordCallbackHandler
The password callback handler retrieves identifier-password pairs from an LDAP server and then loads the pairs which can be used to find the needed password for a particular identifier. To retrieve data from the server, you set the URL of the LDAP server as well as some more properties in the handler. These properties are passed to the handler in a common properties file. You can provide a common properties file to the callback handler as follows:
You can specify the location of the common properties file in the
Web service archive. In the services.xml file, you add a
PWCBLDAPPropFile parameter, which is set to point
to the location of the properties file. The location of the file can be any
valid path from which the handler can load the file (for example,
conf/my-ldap.properties).
<serviceGroup> <service name="Sample_Web_Service"> <parameter name="PWCBLDAPPropFileLocation"> common_properties_file_location </parameter> ... </service> </serviceGroup>
You can set the name of the common properties file to ldap.properties and place the file into the root directory of the Web service archive. If you do not provide an explicit properties file in the services.xml file, the password callback handler is configured to use a default properties file (ldap.properties) from the root directory.
You can set the name of the common properties file to
ldap.properties and place the file into a Java archive
(.jar file) which resides in the /WEB-INF/lib or
WEB-INF/classes directories (for example,
pwcb-server.jar). If the password callback handler does
not discover the properties file in a pre-set directory, or in the root
directory of the Web service archive, it searches for the file into a central
location on the class path of the handler and loads the properties file as a
resource. If this process is unsuccessful, a
FileNotFoundException is thrown.
The same password callback handler is also available at the client side if there is no service archive. Then, presumably, the configuration file is users.xml and is searched on the class path of the client. Then it is loaded as a resource.
The Web Services Stack installation contains samples of custom password callback handlers (on provider and consumer sides) which retrieve identifier-password pairs from configuration files or LDAP servers. You can find the samples in the following location: /samples/PWCBHandlersExample. The folder contains the following projects:
PWCBHandlersExampleServices
This project enables you to create custom password callback handlers for the sample Web service providers. The sample Web service archives are ready to be deployed on the application server.
PWCBHandlersExampleClient
This project enables you to create custom client password callback handlers for the consumption of the sample Web service providers. The consumer samples are ready to be executed standalone and do not require an application server which hosts the Web service providers. However, you can modify the clients to discover and consume Web services that reside and are configured on a remote application server. For more information, see the readme.txt file which is in the consumer project.
Note that these sample projects enable you to create custom password callback handlers. They do not enable you to reuse handlers which retrieve identifier-password pairs from a common central location.
In the wsstack-jaas.jar module, there are ready-to-use policy validator implementations that may be configured and used easily to log on.
Following are examples of those implementations:
com.softwareag.wsstack.jaas.callback.SimpleSINPolicyValidatorCallback
Attempts to log on with all available credentials (message-level
credentials are with higher priority over transport-level credentials) against
the JAAS logon context. Specify the login context name as a parameter under the
key sin.jaas.login.context. The resulting JAAS login subject is
available as a property of the message context under the key
sin.jaas.subject.
com.softwareag.wsstack.jaas.callback.ServletRequestLoginPolicyValidatorCallback
Attempts to log on using the servlet request resource populated in
the SIN credentials list. Specify the login context name as a parameter under
the key sin.jaas.login.context. The resulting JAAS logon subject is
available as a property of the message context under the key
sin.jaas.subject.
com.softwareag.wsstack.jaas.callback.MultiLoginPolicyValidatorCallback
Attempts to log on first with transport-level credentials and then
again with message-level credentials. Specify the login context name as a
parameter under the key sin.jaas.login.context. The name of the
transport login context is available as a parameter under the key
sin.jaas.transport.login.context (the default value is
WSS_Transport_IS ) and for message-level credentials
logging on under sin.jaas.msg.login.context (the default value is
WSS_Message_IS). The resulting subjects are respecivtely
populated as properties of the message context under the keys
sin.jaas.transport.subject and sin.jaas.msg.subject.
These policy validator callbacks extend the standard callback that is provided by Rampart. This means that all basic functionality for validating security policy conformation is still present.
Note:
To use one of the preceding callbacks, specify the
policyValidatorCbClass in the Rampart policy
assertion.
This section provides you with guidelines on the authentication steps when you use SIN in Web Services Stack.
To authenticate using SIN
You must include the path to SIN JAR in the classpath. All classes that are used in the JAAS configuration file must also be set in the classpath.
Configure the JAAS configuration file.
Configure a web service to do the following:
Specify the policyValidatorCbClass in the
Rampart configuration policy assertion.
Following is a sample code listing of the Rampart policy assertion
with specified policyValidatorCbClass:
<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<ramp:user>service</ramp:user>
<ramp:encryptionUser>client</ramp:encryptionUser>
<ramp:policyValidatorCbClass>
com.softwareag.wsstack.jaas.callback.MultiLoginPolicyValidatorCallback
</ramp:policyValidatorCbClass>
Specify the LoginContext name as a
parameter on one of the web service levels (global level in
axis2.xml; service group level in the
services.xml; service level in
services.xml; operation level in
services.xml; message level in
services.xml)
With those settings, you are authenticated when logging on by SIN.
For information about the authentication steps, see SIN documentation in the webMethods Product Suite 8.0 folder on the Software AG Documentation Web site.