<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry id="WS-S-5">
    <refmeta>
	<refentrytitle>WS Trust</refentrytitle>
	<refmiscinfo>tutorial</refmiscinfo>
    </refmeta>
    <refnamediv>
	<refname>Using a Secure SOAP Services</refname>
	<refpurpose>Exposing WS Trust SOAP Endpoints</refpurpose>
    </refnamediv>

    <refsect1 id="WS-S-5a">
	<title>Preliminaries</title>
	<para>
	    The WS Trust protocol is a SOAP based
	    secure service and client that can be used
	    to retrieve a security token (X.509 certificate or similar)
	    in order to be used for making secure operation with an
	    ultimate service in the client's operation.
	</para>
	<para>
	    In common scenario the client asks Token Issuer
	    for a security token. Then client uses token from
	    WS Trust response to perform second remote call
	    signed and/or encrypted to another service which
	    is a ultimate target service.
	    Usually Token Issuer, Client and Ultimate service are
	    located on different physical locations.
	</para>
    </refsect1>

    <refsect1 id="WS-S-5b">
	<title>Example</title>
	<para>
	    Before running this demo make sure that <ulink url="../ws_s_1/ws_s_1.vsp">WS-S-1</ulink> tutorial
	    is set-up and a valid X.509 certificate and corresponding private key
	    are imported (for server and client usage) via <ulink url="../ws_s_1/ws_s_1.vsp">WS-S-1</ulink> example certificate
	    upload utility.
	</para>
	<para>
	    This example uses WS Trust client to
	    obtain X.509 security token from a Token Issuer service
	    and then it uses to make signed request to
	    dummy Weblog service. In real situation the Weblog service
	    instead of echoing a random URL would create an entry in the
	    user's blog.
	    Note that in that demo all operations are performed in context
	    of a same server (i.e. Token Issuer, Weblog service and client are
	    running on one Virtuoso server instance).
	</para>
	<para>
	    The following are demo's main points.
	</para>
	<itemizedlist mark="bullet">
	    <listitem>Client uses a Username and password to digitally sign the
		request from Token Issuer.</listitem>
	    <listitem>Token Issuer will check the signature and user credentials
		and then will issue security token to the client</listitem>
	    <listitem>The Token Issuer service uses a PL hook
		to return appropriate X.509 token</listitem>
	    <listitem>Client uses the returned token (from Token Issuer service) to
		match it against local key storage and to digitally sign the
		second request (to the Weblog service)</listitem>
	    <listitem>The Weblog service will just verify the signature
		and will return an echo of the client's request plus
		an random URL string and post id. (In the real world such service should add data into a Database keeping the blog posts)</listitem>
	    <listitem>The Weblog service will digitally sign the response before
		sending it to client.</listitem>
	    <listitem>To see request/response messages from/to Token Issuer or Web service
	      use the radio group buttons.</listitem>
      </itemizedlist>
      <para>
	  Note: In this example Token Issuer, Weblog service and client uses same X.509
	  certificate.
      </para>
    </refsect1>
</refentry>
