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.
You can configure message-level security in many different ways, 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 Software AG Designer 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 Software AG Designer 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.
If you want to enable keystore caching, follow this step:
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 deactivate and undeploy (delete completely the
service and all its files) using the Administration Tool
of the System Management Hub.
You can also enable caching of initialized password callback handler classes to additionally improve performance (depending on the cost of instantiation and initialization of the password callback handler). The option to enable caching may be set either globally in the axis2.xml configuration, or per service - as a parameter of the service in services.xml descriptor. The callback handler instance is always cached on the service instance and will be lost once the service is undeployed.
If you want to enable password callback handler caching, follow this step:
To enable password callback handler caching
Set the parameter cachePasswordCallbackHandler to
"true".
<parameter name="cachePasswordCallbackHandler">true</parameter>
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="UserDefined" 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).
The sp:RequiredElements and sp:RequiredParts
assertion may not be resolved and validated properly if they are available in
the security policy. By default, when XPath expressions are handled in
sp:RequiredElements assertion, the expressions are validated
against the soap:Envelope element (instead the soap:Header element). If you
want to configure sp:RequiredElements and sp:RequiredParts assertions
validation, follow these steps:
To configure sp:RequiredElements and
sp:RequiredParts assertions validation
Open one of the following configuration files for editing:
axis2.xml
The configuration of axis2.xml file enables the change on the entire runtime.
services.xml
The configuration of services.xml file enables the change on the particular Web service only.
Add the following parameter to the XML file content:
... <parameter name="enableRequiredElementsXPathCompatibility">true</parameter> <parameter name="enableRequiredPartsValidation">true</parameter> ...
Save your changes.
Alternatively, you can enable sp:RequiredElements and
sp:RequiredParts assertions in the business logic of a Web service
client using the following code snippet:
IWSStaxClient client = SampleService;
client.getWSOptions().setProperty("enableRequiredElementsXPathCompatibility", "true");
Configurations on the server side can also be done using the Web Services Stack Designer plug-ins. With the Software AG Designer plug-in, you can complete the preceding configuration using graphical user interface.
For more information, see Software AG Designer Plug-in, Web Services Security: SOAP Message Security 1.1, and WS-Security Policy Language.
The wsiBSPCompliant boolean parameter in the
services.xml file for your service enables you to activate
and deactivate the WS-I Basic Security Profile compliance mode. By default,
this parameter is set to "true".
To deactivate the WS-I Security Profile compliance mode
Set the wsiBSPCompliant to
"false".
<ramp:wsiBspComplient>false</ramp:wsiBspComplient>
Note:
Any value other than "false" is interpreted as
"true".
For more information about the usage of the WS-I Basic Security Profile compliance mode, see its specification at http://ws-i.org/profiles/BasicProfile-2.0-2010-11-09.html.
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 Oracle) 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 Oracle) 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 Oracle) 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 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"); //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.
If you want to configure Tomcat to use SSL at server side, follow these steps:
To configure Tomcat to use SSL at the server side
Navigate to <Software AG_directory>/profiles/CTP/configuration/tomcat/conf and open the server.xml file to configure an SSL Connector.
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="10011" 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 default value of the connector
port is 10011. The port number is calculated during the
installation of the product.
If a server declares explicitly the use of the HTTPS transport in its services.xml, you have to make sure 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.
<transportReceiver name="https"
class="com.softwareag.wsstack.transport.http.HTTPSListener">
<parameter name="port">10011</parameter>
</transportReceiver>
The 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.
If you want to configure SSL at the client side, follow these steps:
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 (in the previous example "10011").
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"); //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. |
The information in this topic is organized under the following headings:
The Tomcat web server may also be configured to use a client certificate to encrypt the transferred data
If you want to use client authentication with Tomcat, do the following:
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.
If you want to configure the truststore location of Tomcat by starting it with the respective Java system property, follow this step:
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="10011" 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 HTTPS, see how to configure Tomcat to use SSL at server side in
Prerequisites for the Setup and
Use of Transport-Level Security
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 HTTPS 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);
The basic HTTP authentication is a common transport security mechanism. The server sends requests to the client to provide its credentials in an HTTP authorization header. Thus the mechanism provides both authentication and authorization means. The enforcement of the basic HTTP authentication request can be delegated to the servlet container or can be left to the Web Services Stack security module (rampart). More information and examples of how to set up your basic HTTP authentication scenario is given below.
If you want to configure a specific endpoint to use the HTTP basic authentication scheme, follow these steps:
To configure a specific endpoint to use the HTTP basic
authentication scheme
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.
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.
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:
By default, the installed Tomcat does not contain a
tomcat-users.xml file. If
tomcat-users.xml is missing in the configuration directory
of Tomcat Server, you must create it manually.
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 about 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.
If you want to validate basic HTTP authentication in Rampart, do the following:
To validate basic HTTP authentication in Rampart
The Rampart security module validates the usage of basic HTTP authentication. Rampart does not authenticate the user credentials sent in the HTTP header and only asserts whether the credentials are available. To authenticate successfully, you can use JAAS integration in Web Services Stack. For more information about that, see Client Authentication
To avoid malfunction of the functionality, the wsstack must be running inside a servlet container or a server such as Software AG Integration Server. This is required because rampart must be able to interact with the actual transport layer by accessing the transport level credentials and sending authorization request in case the basic HTTP authentication header is missing.
To validate basic HTTP authentication, rampart must be informed that the service is secured by Web service Security Policy. The following security policy snippet denotes the basic HTTP authentication requirement:
<service name="ExampleService" ...> ... <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="user"> <wsp:ExactlyOne> <wsp:All> <sp:TransportBinding xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"> <wsp:Policy> <sp:TransportToken> <wsp:Policy> <sp:HttpsToken> <wsp:Policy> <sp:HttpBasicAuthentication /> </wsp:Policy> </sp:HttpsToken> </wsp:Policy> </sp:TransportToken> <sp:AlgorithmSuite> <wsp:Policy> <sp:Basic256 /> </wsp:Policy> </sp:AlgorithmSuite> <sp:Layout> <wsp:Policy> <sp:Lax /> </wsp:Policy> </sp:Layout> <sp:IncludeTimestamp /> </wsp:Policy> </sp:TransportBinding> ... </wsp:All> </wsp:ExactlyOne> </wsp:policy> </service>
The sp:HttpBasicAuthentication assertion can appear
only inside of an sp:HttpsToken assertion which means that the
server also requires the usage of HTTPS transport. To use this feature you must
engage rampart for your Web service. To engage rampart for the Web Service, add
the following lines in the service descriptor
(services.xml):
<service name="ExampleService" ...> ... <module ref="rampart"/> </service>
Add a policy that contains the
sp:HttpBasicAuthentication to your Web service (such as in the
example snippet above).
<service name="ExampleService" ...> ... <sp:HttpsToken> <wsp:Policy> <sp:HttpBasicAuthentication /> </wsp:Policy> </sp:HttpsToken> ... </service>
If you want to configure your Web service client to use HTTP basic authentication, follow these steps:
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);
Important:
In the example above, you must supply the
HttpTransportProperties Authenticator object first, and
then set up a user name and a password. 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 JAAS-based
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 directory 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
User implemented password callback handlers are used to:
Retrieve passwords to be placed inside a UsernameToken (corresponding to a given user name).
Retrieve passwords to access user private keys from a keystore (the keystore password itself is directly set in the ramart configuration)
Verify password in received UsernameToken (corresponding to a given user name).
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>
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.
The file may be also placed in a Java archive (.jar file) which
resides in the WEB-INF/lib (for example,
pwcb-server.jar) or directly in
WEB-INF/classes directory. 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 in 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.
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 (in the Platfrom Tomcat Server, SIN artifacts are already available for Web services deployed as “aar” archives). 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)
To detect any changes in the configuration, the built-in policy
validators provided by Web Services Stack automatically refresh the JAAS
configuration prior to each login attempt. Since the configuration is shared
for the entire Java virtual machine instance, this detection results in
increased synchronization wait time on the server side. To improve the
performance, you can disable the automatic refresh feature by setting the
autoRefreshJaasConfig parameter to false.
The parameter can be set globally in the axis2.xml configuration file or locally in the services.xml service descriptor. The following excerpt outlines the configuration of the parameter:
<parameter
name="autoRefreshJaasConfig">false</parameter>
With those settings, you are authenticated when logging on by Security Infrastructure.
For information about the authentication steps, see SIN documentation in the webMethods Product Suite directory on the Software AG Documentation Web site.