Logo of 52°North

WAS Protocol

The WAS protocol is strongly follows the OGC Web Services apporach of specifying a service protocol. It consists of the four operations

Each operation is can be invoked by HTTP GET or POST. In both cases parameter names and values have to be encoded as defined by the application/x-www-form-urlencoded content type. Either the resulting query string is appended to the service's URL (HTTP GET) or part of the HTTP POST body. In most cases HTTP POST is the best choice, as you don't run into URL length limitation problems. But sometimes it is more convenient to perform an HTTP GET.

The following abbreviation will be used

  • R denotes a required element
  • O denotes an optional element

GetCapabilities Operation

The GetCapabilities operation returns a capabilities xml document that contains all data a client needs to interact with a particular WAS instance.

Request

Parameter Use Description
VERSION=<version> O Request version, should always be 1.1
SERVICE=Authentication R Service type
REQUEST=GetCapabilities R Request name

Example:

http://localhost:8080/was/WAS?SERVICE=Authentication&REQUEST=GetCapabilities

Response

The response is a capabilities XML file like this. Content type is application/vnd.gdinrw.authn_xml

GetSession Operation

With the GetSession operation a user is authenticated and receives a session id in return. This session id must be retrieved to call the GetSAMLResponse operation and receive a valid SAML ticket.

Request

Parameter Use Description
VERSION=<version> O Request version, should always be 1.1
SERVICE=Authentication R Service type
REQUEST=GetSession R Request name
METHOD=<method_identifier> R Identifier of the authentication method to be used, e.g. urn:oasis:names:tc:SAML:1.0:am:password
CREDENTIALS=<credential_list> R Authentication information like username and password
CREDENTIALS
The credentials parameter is a list of comma-separated, Base64 encoded authentication informations. In case of password authentication this list contains two entries, where the first is the username and the second one is the password, e.g. ZHJld25haw==,amFuamFu is the Base64-encoded form of username/password drewnak,janjan.

Example:

http://localhost:8080/was/WAS?SERVICE=Authentication&REQUEST=GetSession&METHOD=urn%3Aopengeospatial%3AauthNMethod%3AOWS%3A1.0%3Apassword&CREDENTIALS=ZHJld25haw%3D%3D%,amFuamFu

Please note, that the parameter values have to be URL-encoded!

Response

The response is an XML file like the following one. Content type is text/xml. The resulting session has a limited validity and can be renewed by subsequent GetSession requests.

<?xml version="1.0" encoding="UTF-8"?>
<session:Session 
        xmlns:session="http://gdi-nrw.uni-muenster.de/aa-service" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation=�http://gdi-nrw.uni-muenster.de/aa-service�
        id="634ha-0987gf-64ggh6-ee12d2"
        expirationDate="2007-08-22T08:30:45.284">
        <session:Issuer>
                <session:Name>52n WAS</session:Name>
                <session:URL>http://www.52north.org/was/WAS</session:URL>
        </session:Issuer>
        <session:Status>opened</session:Status>
</session:Session>

GetSAMLResponse Operation

The central GetSAMLResponse operation is used by clients to retreive a SAML ticket. The SAML ticket can be used as a user's proof of identity for any application/service that trust the issuing WAS.

Request

Parameter Use Description
VERSION=<version> O Request version, should always be 1.1
SERVICE=Authentication R Service type
REQUEST=GetSAMLResponse R Request name
SESSIONID=<session_id> R Id of a session that was retreived by calling the GetSession operation

Example:

http://localhost:8080/was/WAS?SERVICE=Authentication&REQUEST=GetSAMLResponse&SESSIONID=634ha-0987gf-64ggh6-ee12d2

Response

The response is a Base64-encoded SAMLResponse XML fragment. Content type of the response is text/plain. The SAMLResponse element is digitally signed with the WAS' private key.

The Base64-decoded form of the response.

CloseSession Operation

With the CloseSession operation a client signals that the session formerly created by GetSession shall be marked invalid. After a successful CloseSession call, the session id cannot be ised to retreive SAML tickets any more.

Request

Parameter Use Description
VERSION=<version> O Request version, should always be 1.1
SERVICE=Authentication R Service type
REQUEST=CloseSession R Request name
SESSIONID=<session_id> R Id of a session that was retreived by calling the GetSession operation

Example:

http://localhost:8080/was/WAS?SERVICE=Authentication&REQUEST=CloseSession&SESSIONID=634ha-0987gf-64ggh6-ee12d2

Response

The response is an XML file like the following one. Content type is application/vnd.gdinrw.session_xml. In contrast to the GetSession operation response the Status element has the value "closed".

<?xml version="1.0" encoding="UTF-8"?>
<session:Session 
        xmlns:session="http://gdi-nrw.uni-muenster.de/aa-service" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation=�http://gdi-nrw.uni-muenster.de/aa-service�
        id="634ha-0987gf-64ggh6-ee12d2"
        expirationDate="2007-08-22T08:30:45.284">
        <session:Issuer>
                <session:Name>52n WAS</session:Name>
                <session:URL>http://www.52north.org/was/WAS</session:URL>
        </session:Issuer>
        <session:Status>closed</session:Status>
</session:Session>

Exceptions

If any request yields an error the WAS returns a ServiceException. A ServiceException has the content type application/vnd.ogc.se_xml and look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ServiceExceptionReport SYSTEM "http://www.digitalearth.gov/wmt/xml/exception_1_1_0.dtd">
<ServiceExceptionReport version="1.1.0">                
        <ServiceException code="InvalidSessionID">
                Session ID invalid.
        </ServiceException>
</ServiceExceptionReport>
ServiceException codes
The code may be one of
  • AuthenticationFailed
  • InvalidSessionID
  • SessionExpired
  • InvalidFormat
  • ServiceError