Getting Started


The Concept

GSS is a general server application for providing several types of services with several types of interfaces.

gss overview

Service:

Interface:

You can authorize the interface with a service. You can authorize a service with another service.

Installing GSS Server

  1. Download and extract GSS Server archive file.
  2. Enter bin directory and execute the appropriate file to start running
  • gss-server.bat ..\conf\gss-server.xml 
  • gss-server ../conf/gss-server.xml

Configuration


GSS Server requires an XML file for configuration. The default configuration file is: <GSS_SERVER_HOME>/conf/gss-server.xml.

You can get the complete XML schema at: http://ilerian.com/documentation/gss_configuration/gss.html

Define Services

Executable Service:

For example, we have a perl script for creating an email address under a domain for our hosting company. Our script works as below:
hosting_operations.pl <operation_ID> <operation_param1> <operation_param2> ....
For creating email address: 
hosting_operations.pl create_email -domain=<domain_name> -email=<email_address> -quota=<quota> -password=<password>

Let's introduce a service for this facility.

<executableService name="createEmailAddress" executable="hosting_operations.pl" parameterSeparator=" ">
    <parameter name="domainName" prefix="create_email -domain=" required="yes"/>
    <parameter name="email" prefix="-email=" required="yes"/>
    <parameter name="quota" prefix="-quota=" required="false"/>    
    <parameter name="password" prefix="-password=" required="yes"/>
</executableService>

Define Interface

Let's define an HTTP interface for our GSS Server.

<communication>
    <httpInterface authorizationName="authHttpUserPass" hostname="localhost" port="1655" />
</communication>

It binds on host localhost and 1655 port. The authorization of this interface is performed through authHttpUserPass authorization policy. This will be explained on the next section.

You can setup more than one interface type.

Mastering The Basics


Authorization

All authorization policies are defined in <security> element of the configuration file.

..
<security>
    <executableAuthorization name="checkHttpUserPass" serviceName="concatUserPass" >               
	<parameterMapping >
        	<mapRow authParam="username" serviceParam="username"/>
		<mapRow authParam="password" serviceParam="password"/>
	</parameterMapping>
	<expectedResult><text>kurtulus123456</text></expectedResult>
    </executableAuthorization>       
    <executableAuthorization name="repeatAuthorization" serviceName="repeatMe" >
	<parameterMapping >
	    <mapRow authParam="username" serviceParam="whatToRepeat"/>
        </parameterMapping>
        <expectedResult><text>kurtulus</text></expectedResult>
    </executableAuthorization>
</security>
..

An authorization policy is a connector that gets the parameters from the request and maps to a specified service for authorization. In other words, it executes an already defined service for authorization and use some of the request parameters for input.

An interface or a service can use a defined authorization policy for usage restriction. It is optional to use authorization policies for interfaces and services.

Interface Authorization

Interface authorization is used for preventing unwanted access on GSS server. GSS provides authorization for your each interface separately.

<communication><httpInterface authorizationName="authHttpUserPass" hostname="localhost" port="1655" /></communication>

You can control authorization of an interface by referencing the name of an already defined authorization policy on interface definition.

The username and password attributes of the client request are used for Interface authorization.

Service Authorization

GSS provides authorization for your each service separately.
<executableService name="createEmailAddress" authorizationName="authDomainOwnerCheck"
executable="hosting_operations.pl" parameterSeparator=" ">
You can control authorization of a service by referencing the name of an already defined authorization policy on service definition.
The request parameters received for the service are also used for authorization process. 

Sending Request


 Until now, a sample configuration should be as below:
<?xml version="1.0" encoding="UTF-8"?>
<tns:gss xmlns:tns="http://www.example.org/gss/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="gss.xsd">
<server name="" version="">
<repositoryPath>repository</repositoryPath>
<services>
    <executableService name="createEmailAddress" executable="hosting_operations.pl" parameterSeparator=" ">
<parameter name="domainName" prefix="create_email \-domain=" required="yes"/>
<parameter name="email" prefix="-email=" required="yes"/>
<parameter name="quota" prefix="-quota=" required="false"/> &nbsp;
<parameter name="password" prefix="-password=" required="yes"/>
</executableService>
<executableService name="concatArguments" executable="echo_executable.bat" parameterSeparator="">&nbsp;
<parameter name="argument1" default=""/>
<parameter name="argument2" default=""/>
</executableService>

   </services>
 <communication>
 <httpInterface authorizationName="checkHttpUserPass" hostname="localhost" port="1655"></httpInterface>
 </communication>
<security>
<executableAuthorization name="checkHttpUserPass" serviceName="concatArguments" >

<parameterMapping >
<mapRow authParam="username" serviceParam="argument1"/>
<mapRow authParam="password" serviceParam="argument2"/>
</parameterMapping>
<expectedResult><text>kurtulus123456</text></expectedResult>
</executableAuthorization>

<executableAuthorization name="echoAuthorization" serviceName="concatArguments" >
<parameterMapping >
<mapRow authParam="param1" serviceParam="argument1"/>
<mapRow authParam="param2" serviceParam="argument2"/>
</parameterMapping>
<expectedResult><text>mykeyword</text></expectedResult>
&nbsp;&nbsp; </security>
&nbsp;</server>
</tns:gss>

Request for Executable Service

The complete xml schema for request XML is at : http://ilerian.com/documentation/request/request.html

<request username="kurtulus" password="123456">
        <job serviceName="createEmailAddress">
                <parameter name="domainName" value="mydomain.com" />
                <parameter name="email" value="[email protected]" />   
                <parameter name="quota" value="990" />
                <parameter name="password" value="hyt939" />
        </job> 
</request>

This request runs hosting_operations.pl on the server machine with the following parameters:

hosting_operations.pl create_email -domain=mydomain.com [email protected] -quota=990  -password=hyt939

The response will include the output of the executable:

<response>
    <serviceResponse name="createEmailAddress">OK</serviceResponse>e
</response>

The username and password attributes on the request are for interface authorization only.

For  the configuration above,

  1. GSS Server checks the interface authorization by sending the username and password values to checkHttpUserPassService 
  2. For createEmailAddress job, GSS server checks the service authorization by sending the domainName and emailAddress values to emailOwnerAuthorization
  3. GSS Server sends the job parameters (emailAddress....) to createEmailAddress service.
  4. As createEmailAddress is an executable service, GSS Server runs "/var/server.pl create_email reseller_id realdomain.com [email protected] 7887" and returns the output to the client.
Gss Server Request Processing

Client Usage

Java Client:

  This example post an xml file, it depends on Jakarta HttpClient API (jakarta.apache.org)
import java.io.File;
import java.io.FileInputStream;

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.InputStreamRequestEntity;
import org.apache.commons.httpclient.methods.PostMethod;

/**
 * This is a sample application that demonstrates
 * how to use the Jakarta HttpClient API.
 *
 * This application sends an XML document
 * to a remote web server using HTTP POST
 *
 * @author Sean C. Sullivan
 * @author Ortwin Glück
 * @author Oleg Kalnichevski
 */
public class PostXML {

    /**
     *
     * Usage:
     * java PostXML http://mywebserver:80/ c:\foo.xml
     *
     * @param args command line arguments
     * Argument 0 is a URL to a web server
     * Argument 1 is a local filename
     *
     */
    public static void main(String[] args) throws Exception {

        if (args.length != 2) {
            System.out.println(
                "Usage: java -classpath <classpath> [-Dorg.apache.commons."+
                "logging.simplelog.defaultlog=<loglevel>]" +
                " PostXML <url> <filename>]");

            System.out.println("<classpath> - must contain the "+
                "commons-httpclient.jar and commons-logging.jar");

            System.out.println("<loglevel> - one of error, "+
                    "warn, info, debug, trace");

            System.out.println("<url> - the URL to post the file to");
            System.out.println("<filename> - file to post to the URL");
            System.out.println();
            System.exit(1);
        }

        // Get target URL
        String strURL = args[0];

        // Get file to be posted
        String strXMLFilename = args[1];
        File input = new File(strXMLFilename);

        // Prepare HTTP post
        PostMethod post = new PostMethod(strURL);

        // Request content will be retrieved directly
        // from the input stream
        // Per default, the request content needs to be buffered
        // in order to determine its length.
        // Request body buffering can be avoided when
        // content length is explicitly specified
        post.setRequestEntity(new InputStreamRequestEntity(
                new FileInputStream(input), input.length()));

        // Specify content type and encoding
        // If content encoding is not explicitly specified
        // ISO-8859-1 is assumed
        post.setRequestHeader(
                "Content-type", "text/xml; charset=ISO-8859-1");

        // Get HTTP client
        HttpClient httpclient = new HttpClient();

        // Execute request
        try {

            int result = httpclient.executeMethod(post);

            // Display status code
            System.out.println("Response status code: " + result);

            // Display response
            System.out.println("Response body: ");
            System.out.println(post.getResponseBodyAsString());

        } finally {
            // Release current connection to the connection pool
            // once you are done
            post.releaseConnection();
        }
    }
}

PHP Client 

  Example how to use HttpRequest to post data and receive the response:
Example how to use HttpRequest to post data and receive the response:
<?php
//set up variables
$theData = '<?xml version="1.0"?>
<note>
    <to>php.net</to>
    <from>lymber</from>
    <heading>php http request</heading>
    <body>i love php!</body>
</note>';
$url = 'http://www.example.com';
$credentials = '[email protected]:password';
$header_array = array('Expect' => '',
                'From' => 'User A');
$ssl_array = array('version' => SSL_VERSION_SSLv3);
$options = array(headers => $header_array,
                httpauth => $credentials,
                httpauthtype => HTTP_AUTH_BASIC,
                protocol => HTTP_VERSION_1_1,
                ssl => $ssl_array);
                
//create the httprequest object                
$httpRequest_OBJ = new httpRequest($url, HTTP_METH_POST, $options);
//add the content type
$httpRequest_OBJ->setContentType = 'Content-Type: text/xml';
//add the raw post data
$httpRequest_OBJ->setRawPostData ($theData);
//send the http request
$result = $httpRequest_OBJ->send();
//print out the result
echo "<pre>"; print_r($result); echo "</pre>";
?>

 

  • No labels
Write a comment…