Liberty: The ibm-ws-bnd.xml file

You can customize web services endpoints and configure security settings for both web services providers and web service clients by using the ibm-ws-bnd.xml file in Liberty. You must store this file in the /WEB-INF directory of your web application or in the /META-INF directory of your EJB module.

The ibm-ws-bnd.xml file provides the following element hierarchy:

<webservices-bnd>

The description of each element in the ibm-ws-bnd.xml file is as follows:

<webservice-endpoint-properties>

This element is used to define the default properties for all the web services endpoints in the same module. Only one webservice-endpoint-properties element can be specified for one module. You can specify any name and value pairs that are applicable to web services endpoint as attributes of the webservice-endpoint-properties element.

If you add the enableLoggingInOutInterceptor property, you can log SOAP requests and responses for both client- and server-side:

<webservice-endpoint-properties enableLoggingInOutInterceptor="false">

Note: If you set the enable LoggingInOutInterceptor="true", your credentials are displayed in the message.log.

Unlike WebSphere® Application Server traditional, Liberty does not include an XML declaration in SOAP response messages by default. If you need to include an XML declaration header in SOAP response messages, set the org.apache.cxf.stax.force-start-document property to true in the webservice-endpoint-properties element, as shown in the following example:

<?xml version="1.0" encoding="UTF-8"?>
<webservices-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee"
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee 
                        http://websphere.ibm.com/xml/ns/javaee/ibm-ws-bnd_1_0.xsd"
		        version="1.0">

    <webservice-endpoint-properties org.apache.cxf.stax.force-start-document="true" />

</webservices-bnd>

This setting is important for web services applications that are migrating to Liberty from WebSphere Application Server traditional. It can also help ensure that the response message is processed consistently across different platforms and by parsers or validators that require an XML declaration.

<webservice-endpoint>

This element is used to specify the binding for a specified service instance. It has the following attributes:

port-component-name: This attribute is required. It is used to specify the name of a port component.
address: This attribute is optional. It is used to specify the overridden address of a service endpoint.

If you add the <enableLoggingInOutInterceptor> property, you can log SOAP requests and responses for both client- and server-side:

	<webservice-endpoint port-component-name="Hello">
		<properties enableLoggingInOutInterceptor="true"/>
	</webservice-endpoint>

Note: If you set the enable LoggingInOutInterceptor="true", your credentials will be displayed in the message.log.

<http-publishing>

This element is used to specify the publishing configurations when using HTTP protocol for all the web services endpoints. Only one <http-publishing> element can be specified in each module. It has the following attribute:

context-root: This attribute is optional. It is used to specify the context root of the EJB module in an EJB-based JAX-WS application.

<webservice-security>

This element is used to configure role-based authorization for POJO web services and EJB-based web services. It has the following attributes:

security-constraint: This attribute is optional. It is used to associate security constraints with one or more web resource collections, and only works as complementary configuration of the deployment descriptors or annotations in web applications.
security-role: This attribute is optional. It contains the definition of a security role, and only works as complementary configuration of the deployment descriptors or annotations in web applications.
login-config: This attribute is optional. It is used to configure the authentication method and realm name, and takes effect only for the EJB-based web services in a JAR file. If the same attribute is specified in the deployment descriptor file, the value from the deployment descriptor is used. The value of this attribute must be BASIC or CLIENT_CERT.

<service-ref>

This element is used to define the web services reference configurations for a web services client. It has the following attributes:

name: This attribute is required. It is used to specify the name of a web services reference.
component-name: This attribute is optional. It is used to specify the EJB bean name if the service reference is used in an EJB module.
port-address: This attribute is optional. It is used to specify the address of the web services port if the referenced web services has only one port.
wsdl-location: This attribute is optional. It is used to specify the URL of a WSDL to be overridden.

<port>

This element is used to define port configurations that are associated with the web services reference. Multiple port elements can be defined within a service-ref element. It has the following attributes:

name: This attribute is required. It is used to specify the name of the web services port.
namespace: This attribute is optional. It is used to specify the namespace of the web services port. If the namespace attribute is present, the binding is applied to the port that has the same name and namespace. Otherwise, the binding is applied to the port that has the same name.
address: This attribute is optional. It is used to specify the address for the web services port. If present, it overrides the value of port-address attribute that is defined in the service-ref element.
username: This attribute is optional. It is used to specify the user name for the basic authentication.
password: This attribute is optional. It is used to specify the password for the basic authentication. The password can be encoded.
ssl-ref: This attribute is optional. It refers to the ssl element that is configured in the server.xml file by using the id attribute. If the attribute is not specified but the server supports the transport level security by enabling the transportSecurity-1.0 feature, the service client uses the default SSL configuration of Liberty.
key-alias: This attribute is optional. It is used to specify the alias of client certificate. If the attribute is not specified, and the web service provider supports the client certificate, then the first certificate in the keystore is used as the value of this attribute. The attribute can also override the clientKeyAlias attribute that is defined in the ssl element of the server.xml file.

<properties>

This element is used to define the properties for a web services endpoint or client. The attributes can be any name and any value.

For web service clients, you can specify client.ConnectionTimeout, authorization.UserName, tlsClientParameters.disableCNcheck and other attributes.
For web service endpoint, you could specify publishedEndpointUrl, org.apache.cxf.wsdl.create.imports and other attributes.

The following example shows the typical configuration of a ibm-ws-bnd.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<webservices-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee"
					  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
					  xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-ws-bnd_1_0.xsd"
						version="1.0">

    <!-- optional Web service endpoint default properties -->
    <webservice-endpoint-properties org.apache.cxf.wsdl.create.imports="true" ... />

    <!-- 0 to many endpoint descriptions -->
    <webservice-endpoint port-component-name="..." address="optional override address">
        <!-- optional Web service endpoint properties -->
        <properties publishedEndpointUrl="http://www.example.com/services/hello"
					org.apache.cxf.wsdl.create.imports="false" />
    </webservice-endpoint>
    ...

    <!-- optional http publishing module overrides -->
    <http-publishing context-root="optional override of module's context root">
        <!-- optional web.xml fragment for security -->
        <webservice-security>
            <!-- SECURITY CONSTRAINTS -->
            <security-constraint>
                <web-resource-collection>
                    <web-resource-name>SayHelloServiceName</web-resource-name>
                    <url-pattern>/SayHelloService</url-pattern>
                </web-resource-collection>
                <auth-constraint>
                    <description>SayHelloServiceAuth</description>
                    <role-name>group123</role-name>
                </auth-constraint>
                <user-data-constraint>
                    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
                </user-data-constraint>
            </security-constraint>
            <!-- SECURITY CONSTRAINTS -->
            <security-constraint>
                <web-resource-collection>
                    <web-resource-name>SecuredSayHelloServiceName</web-resource-name>
                    <url-pattern>/Secured*</url-pattern>
                </web-resource-collection>
                <auth-constraint>
                    <description>SecuredSayHelloServiceAuth</description>
                    <role-name>group123</role-name>
                </auth-constraint>
                <user-data-constraint>
                    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
                </user-data-constraint>
            </security-constraint>
            <!-- SECURITY ROLES -->
            <security-role id="group123_id">
                <role-name>group123</role-name>
            </security-role>
            <!-- AUTHENTICATION METHOD: Client certificate or basic authentication -->
            <login-config>
                <auth-method>BASIC</auth-method>
            </login-config>
        </webservice-security>
    </http-publishing>

    <!-- 0 to many client refs -->
    <service-ref name="services/sayHelloService"
			port-address="http://productServer:productPort/context-root/SayHelloService"/>
    <service-ref name="services/securedSayHelloService"
			port-address="http://productServer:productPort/context-root/SecuredSayHelloService"
			wsdl-location="optional override of WSDL document" />
</webservices-bnd>