Index Changes

Basic Authentication in HTTP SOAP BC

1. About Basic Authentication:

The basic authentication scheme is a method designed to allow a client program, to provide credentials – in the form of a user name and password – when making a request.
Specifically, the credentials are passed as plaintext.
To prevent the user name and password being read directly by a person, they are encoded as a sequence of base-64 characters before transmission.
For example, the user name "Aladdin" and password "open sesame" would be combined as "Aladdin:open sesame" – which is equivalent to QWxhZGRpbjpvcGVuIHNlc2FtZQ== when encoded in base-64.

The basic authentication scheme was originally defined by RFC 1945 (Hypertext Transfer Protocol – HTTP/1.0) although further information regarding security issues may be found in RFC 2616 (Hypertext Transfer Protocol – HTTP/1.1) and RFC 2617 (HTTP Authentication: Basic and Digest Access Authentication).

If a webservice is a provider, a request message from a client contains the user name and password fields in the request header. If the webservice is a consumer, invoking a webservice with basic authentication enabled, the user name and password are appended to the request headers for authentication.

2. Features supported in the BC.

Basic authentication is supported by specifying a policy in the wsdl.
A basic authentication policy assertion can be added to the wsdl manually or using WSIT.
A basic authentication policy is specified at the root level of the wsdl and a reference to the policy is made in the wsdl Port type section, binding the
policy to the endpoint.

MustSupportBasicAuthentication and UsernameToken elements are defined by HTTP BC to support Basic Authentication. And they should be defined in the "http://sun.com/ws/httpbc/security/BasicauthSecurityPolicy" namespace. The MustSupportBasicAuthentication element has an attribute called on which can be used to turn authentication on or off; this attribute accepts the values: true or false.

The following is a sample wsdl which contains the policy and its reference.

  • Prefix "sp" should be defined in "http://schemas.xmlsoap.org/ws/2005/07/securitypolicy".
  • Prefix "wsp" should be defined in "http://schemas.xmlsoap.org/ws/2004/09/policy".
  • Prefix "wsu" should be defined in "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd".
  • Prefix "mysp" should be defined in "http://sun.com/ws/httpbc/security/BasicauthSecurityPolicy".

The element MustSupportBasicAuthentication within a policy is a required element to enable basic authentication in the endpoint.
The element UsernameToken specifies the user name and password fields to either Authenticate the request. (The endpoint is a provider)
or invoke a webservice with basic authentication enabled. (The configured endpoint is a consumer)
The user name and password fields can be:
  1. specified as plain text in the wsdl.
  2. pecified as tokens in the wsdl and configured at runtime.


For a webservice consumer endpoint, three types of authentication mechanism is supported: WssToken Compare, Access Manager, and Sun Realm. A consuming endpoint may be configured to use one of these mechanisms. To enable WssToken Compare, the element WssTokenCompare can be added as a child element to the MustSupportBasicAuthentication element of the endpoint's Policy. Otherwise, to enable Sun Access Manager authentication, the element AccessManager can be added as a child element to the MustSupportBasicAuthentication element of the endpoint's Policy. Finally, to enable Sun Realm authentication, the element Realm can be added as a child element to the MustSupportBasicAuthentication element of the endpoint's Policy. The following will describe these three mechanisms in more detail. The elements WssTokenCompare, AccessManager, and Realm are also defined in the namespace "http://sun.com/ws/httpbc/security/BasicauthSecurityPolicy".

WssTokenCompare

When using WssTokenCompare, the Policy element must be present and specifies the username and password that will be used for authentication. This authentication mechanism simply compares the username and password, extracted from the HTTP Authorization request header, with the username and password specified in the Policy's WssUsernameToken10 and WssPassword elements.

The following is a sample wsdl which contains the policy and its reference for using WssTokenCompare. Please note that an application variable token is used for the password because we don't want to expose the password in the WSDL. The value of the password can be specified in the component's Application Variables property in Netbeans.
        
    <wsdl:service name="echoService">
        <wsdl:port name="echoPort" binding="tns:echoBinding">
            <soap:address location="http://pponnala-tecra-xp.stc.com:18181/echoService/echoPort"/>
            <wsp:PolicyReference URI="#HttpBasicAuthBindingBindingPolicy"/>
        </wsdl:port>
    </wsdl:service>

    <wsp:Policy wsu:Id="HttpBasicAuthBindingBindingPolicy">
        <mysp:MustSupportBasicAuthentication on="true">
            <mysp:BasicAuthenticationDetail>
               <mysp:WssTokenCompare/>
            </mysp:BasicAuthenticationDetail>
        </mysp:MustSupportBasicAuthentication>
        <mysp:UsernameToken mysp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
           <wsp:Policy>
                <sp:WssUsernameToken10>wilma</sp:WssUsernameToken10>
                <sp:WssPassword>${pass_token}</sp:WssPassword>
           </wsp:Policy>
      </mysp:UsernameToken>
    </wsp:Policy>

AccessManager

When the AccessManager element is used, a consuming endpoint is configured to utilize Sun Access Manager to authenticate the HTTP client's credentials. The HTTP Soap BC integrates seamlessly with Sun Access Manager allowing it to authenticate the HTTP client's credentials (username and password extracted from the HTTP Authorization header) against the user's credentials in the Sun Access Manager's database. Before authentication with Sun Access Manager can be used, however, an additional Binding Component configuration is required to configure the HTTP Soap BC to use the Access Manager; this is a component-level configuration. This configuration is called Sun Access Manager Configuration Directory and its value is the directory where the Sun Access Manager's AMConfig.properties file can be found. You can configure Sun Access Manager Configuration Directory in the HTTP Soap BC's properties sheet within NetBeans as shown here:
http://wiki.open-esb.java.net/attach/HTTPBasicAuthentication/httpBCSunAMConfigDir.png

The following is a sample wsdl which contains the policy and its reference for using AccessManager.
        
    <wsdl:service name="echoService">
        <wsdl:port name="echoPort" binding="tns:echoBinding">
            <soap:address location="http://pponnala-tecra-xp.stc.com:18181/echoService/echoPort"/>
            <wsp:PolicyReference URI="#HttpBasicAuthBindingBindingPolicy"/>
        </wsdl:port>
    </wsdl:service>

    <wsp:Policy wsu:Id="HttpBasicAuthBindingBindingPolicy">
        <mysp:MustSupportBasicAuthentication on="true">
            <mysp:BasicAuthenticationDetail>
               <mysp:AccessManager/>
            </mysp:BasicAuthenticationDetail>
        </mysp:MustSupportBasicAuthentication>
    </wsp:Policy>

Realm

When the Realm element is used, a consuming endpoint is configured to utilize Sun Realm security to authenticate the HTTP client's credentials. The HTTP Soap BC integrates seamlessly with Sun Realm security allowing it to authenticate the HTTP client's credentials (username and password extracted from the HTTP Authorization header) against the user's credentials in the specified Realm. The name of the realm is specified using the Realm element's attribute called realmName. For example, your Glassfish installation should come with a pre-configured file realm which is essentially a file-based user database. Consult the Glassfish documentation on Realm security for creating realm(s) and adding user(s) to realm(s).
Taking the file realm as an example, here is a sample wsdl which contains the policy and its reference for using Realm.
    <wsdl:service name="echoService">
        <wsdl:port name="echoPort" binding="tns:echoBinding">
            <soap:address location="http://pponnala-tecra-xp.stc.com:18181/echoService/echoPort"/>
            <wsp:PolicyReference URI="#HttpBasicAuthBindingBindingPolicy"/>
        </wsdl:port>
    </wsdl:service>

    <wsp:Policy wsu:Id="HttpBasicAuthBindingBindingPolicy">
        <mysp:MustSupportBasicAuthentication on="true">
            <mysp:BasicAuthenticationDetail>
               <mysp:Realm realmName="file"/>
            </mysp:BasicAuthenticationDetail>
        </mysp:MustSupportBasicAuthentication>
    </wsp:Policy>


3. How to configure Basic Authentication using HTTPSOAP BC


Design time tooling support is yet to be implemented. PolicyReference and Policy elements must be added to WSDLs manually.

4. Sample WSDL.


A sample WSDL showing 3 web service endpoints, each one using one of the 3 supported security mechanisms for securing web service endpoints

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="SoapBasicAuth" targetNamespace="http://j2ee.netbeans.org/wsdl/SoapBasicAuth"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="http://j2ee.netbeans.org/wsdl/SoapBasicAuth"
    xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"
    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"
    xmlns:mysp="http://sun.com/ws/httpbc/security/BasicauthSecurityPolicy">
    <types/>
    <message name="SoapBasicAuthOperationRequest">
        <part name="request-part" type="xsd:string"/>
    </message>
    <message name="SoapBasicAuthOperationReply">
        <part name="response-part" type="xsd:string"/>
    </message>
    <portType name="SoapBasicAuthAMPortType">
        <operation name="SoapBasicAuthOperation">
            <input name="input1" message="tns:SoapBasicAuthOperationRequest"/>
            <output name="output1" message="tns:SoapBasicAuthOperationReply"/>
        </operation>
    </portType>
    <portType name="SoapBasicAuthRealmPortType">
        <operation name="SoapBasicAuthOperation">
            <input name="input1" message="tns:SoapBasicAuthOperationRequest"/>
            <output name="output1" message="tns:SoapBasicAuthOperationReply"/>
        </operation>
    </portType>
    <portType name="SoapBasicAuthWssTokenPortType">
        <operation name="SoapBasicAuthOperation">
            <input name="input1" message="tns:SoapBasicAuthOperationRequest"/>
            <output name="output1" message="tns:SoapBasicAuthOperationReply"/>
        </operation>
    </portType>
    <binding name="SoapBasicAuthAMBinding" type="tns:SoapBasicAuthAMPortType">
        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="SoapBasicAuthOperation">
            <soap:operation/>
            <input name="input1">
                <soap:body use="literal" namespace="http://j2ee.netbeans.org/wsdl/SoapBasicAuth"/>
            </input>
            <output name="output1">
                <soap:body use="literal" namespace="http://j2ee.netbeans.org/wsdl/SoapBasicAuth"/>
            </output>
        </operation>
    </binding>
    <binding name="SoapBasicAuthRealmBinding" type="tns:SoapBasicAuthRealmPortType">
        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="SoapBasicAuthOperation">
            <soap:operation/>
            <input name="input1">
                <soap:body use="literal" namespace="http://j2ee.netbeans.org/wsdl/SoapBasicAuth"/>
            </input>
            <output name="output1">
                <soap:body use="literal" namespace="http://j2ee.netbeans.org/wsdl/SoapBasicAuth"/>
            </output>
        </operation>
    </binding>
    <binding name="SoapBasicAuthWssTokenBinding" type="tns:SoapBasicAuthWssTokenPortType">
        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="SoapBasicAuthOperation">
            <soap:operation/>
            <input name="input1">
                <soap:body use="literal" namespace="http://j2ee.netbeans.org/wsdl/SoapBasicAuth"/>
            </input>
            <output name="output1">
                <soap:body use="literal" namespace="http://j2ee.netbeans.org/wsdl/SoapBasicAuth"/>
            </output>
        </operation>
    </binding>
    <service name="SoapBasicAuthService">
        <port name="SoapBasicAuthPortAM" binding="tns:SoapBasicAuthAMBinding">
            <soap:address location="http://localhost:12081/SoapBasicAuthService/SoapBasicAuthAMPort"/>
            <wsp:PolicyReference URI="#HttpBasicAuthBindingBindingAMPolicy"/>
        </port>
        <port name="SoapBasicAuthPortRealm" binding="tns:SoapBasicAuthRealmBinding">
            <soap:address location="http://localhost:12081/SoapBasicAuthService/SoapBasicAuthRealmPort"/>
            <wsp:PolicyReference URI="#HttpBasicAuthBindingBindingRealmPolicy"/>
        </port>
        <port name="SoapBasicAuthPortWssToken" binding="tns:SoapBasicAuthWssTokenBinding">
            <soap:address location="http://localhost:12081/SoapBasicAuthService/SoapBasicAuthWssTokenPort"/>
            <wsp:PolicyReference URI="#HttpBasicAuthBindingBindingWssTokenPolicy"/>
        </port>
    </service>
    <wsp:Policy wsu:Id="HttpBasicAuthBindingBindingAMPolicy">
        <mysp:MustSupportBasicAuthentication on="true">
            <!-- authenticationType is one of simple, am, or realm -->
            <mysp:BasicAuthenticationDetail>
               <mysp:AccessManager/>            
            </mysp:BasicAuthenticationDetail>
        </mysp:MustSupportBasicAuthentication>
        <!--
        <mysp:UsernameToken mysp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
           <wsp:Policy>
                <sp:WssUsernameToken10>wilma</sp:WssUsernameToken10>
                <sp:WssPassword>pebbles</sp:WssPassword>
           </wsp:Policy>
        </mysp:UsernameToken>
        -->
    </wsp:Policy>
    <wsp:Policy wsu:Id="HttpBasicAuthBindingBindingRealmPolicy">
        <mysp:MustSupportBasicAuthentication on="true">
            <mysp:BasicAuthenticationDetail>
               <mysp:Realm realmName="file" />
            </mysp:BasicAuthenticationDetail>
        </mysp:MustSupportBasicAuthentication>
        <!--
        <mysp:UsernameToken mysp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
           <wsp:Policy>
                <sp:WssUsernameToken10>wilma</sp:WssUsernameToken10>
                <sp:WssPassword>pebbles</sp:WssPassword>
           </wsp:Policy>
        </mysp:UsernameToken>
        -->
    </wsp:Policy>    
    <wsp:Policy wsu:Id="HttpBasicAuthBindingBindingWssTokenPolicy">
        <mysp:MustSupportBasicAuthentication on="true">
            <!-- authenticationType is one of simple, am, or realm -->
            <mysp:BasicAuthenticationDetail>
               <mysp:WssTokenCompare/>
            </mysp:BasicAuthenticationDetail>
        </mysp:MustSupportBasicAuthentication>
        <mysp:UsernameToken mysp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
           <wsp:Policy>
                <sp:WssUsernameToken10>wilma</sp:WssUsernameToken10>
                <sp:WssPassword>pebbles</sp:WssPassword>
           </wsp:Policy>
        </mysp:UsernameToken>
    </wsp:Policy>        
    <plnk:partnerLinkType name="SoapBasicAuthAM">
        <!-- A partner link type is automatically generated when a new port type is added. Partner link types are used by BPEL processes. 
In a BPEL process, a partner link represents the interaction between the BPEL process and a partner service. Each partner link is associated with a partner link type.
A partner link type characterizes the conversational relationship between two services. The partner link type can have one or two roles.-->
        <plnk:role name="SoapBasicAuthAMPortTypeRole" portType="tns:SoapBasicAuthAMPortType"/>
    </plnk:partnerLinkType>
    <plnk:partnerLinkType name="SoapBasicAuthRealm">
        <!-- A partner link type is automatically generated when a new port type is added. Partner link types are used by BPEL processes. 
In a BPEL process, a partner link represents the interaction between the BPEL process and a partner service. Each partner link is associated with a partner link type.
A partner link type characterizes the conversational relationship between two services. The partner link type can have one or two roles.-->
        <plnk:role name="SoapBasicAuthRealmPortTypeRole" portType="tns:SoapBasicAuthRealmPortType"/>
    </plnk:partnerLinkType>
    <plnk:partnerLinkType name="SoapBasicAuthWssToken">
        <!-- A partner link type is automatically generated when a new port type is added. Partner link types are used by BPEL processes. 
In a BPEL process, a partner link represents the interaction between the BPEL process and a partner service. Each partner link is associated with a partner link type.
A partner link type characterizes the conversational relationship between two services. The partner link type can have one or two roles.-->
        <plnk:role name="SoapBasicAuthWssTokenPortTypeRole" portType="tns:SoapBasicAuthWssTokenPortType"/>
    </plnk:partnerLinkType>
</definitions>

Caution: the HTTP Binding Component User's Guide at https://open-esb.dev.java.net/kb/preview3/ep-http-bc.html shows a syntax for the <mysp:MustSupportBasicAuthentication> tag that is no longer correct. In the current HTTP BC, the way to enable this feature is with the attribute on="true", as shown in the examples above.

JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This page (revision-12) was last changed on 20-Feb-08 11:57 AM, -0800 by BobPollack