Logo of 52°North

WSS Protocol

The WSS 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 case of HTTP GET the parameter names and values have to be encoded as defined by the application/x-www-form-urlencoded content type. The resulting query string is appended to the service's URL (HTTP GET). In case of HTTP POST the requests are XML-encoded. The XML file is sent as part of the HTTP POST body. In most cases HTTP POST is the best choice, because the XML interface is more robust concerning length limitations and is more flexible.

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 WSS instance.

Request

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

HTTP GET example:

http://localhost:8080/wss/WSS?SERVICE=WSS&REQUEST=GetCapabilities

HTTP POST XML example:

<GetCapabilities service="WSS" version="1.1"/>

Response

The response is a capabilities XML file like this. Content type is text/xml

GetSession Operation

With the GetSession operation a user is authenticated and receives a session id in return. The use of this operation is optional. The session id is just another means to identify the user when performing a DoService request. Of course, it is not a good idea to use a SAML ticket for user identification for DoService reqeusts, because SAML ticket verification is quite expensive. It takes about one to two seconds to validate the signature of the issuing WAS and usually a user doesn't want to wait two seconds for a simple GetMap request.

Request

Parameter Use Description
VERSION=<version> O Request version, should always be 1.1
SERVICE=WSS R Service type
REQUEST=GetSession R Request name
AUTHMETHOD=<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. In case of WAS/SAML authentication the credentials parameter holds the Base64-encoded SAML ticket as received from the WAS. Caution: the ticket has to be URL-encoded, too.

HTTP GET example:

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

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

HTTP POST XML example:

<GetSession version="1.1">
   <AuthMethod>urn:opengeospatial:authNMethod:OWS:1.0:wauthns</AuthMethod>
   <Credentials>
PFJlc3BvbnNlIHhtbG5zPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoxLjA6cHJvdG9jb2wiIHht
bG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjEuMDphc3NlcnRpb24iIHhtbG5zOnNh
bWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoxLjA6cHJvdG9jb2wiIHhtbG5zOnhzZD0iaHR0
cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEiIHhtbG5zOnhzaT0iaHR0cDovL3d3dy53My5v
cmcvMjAwMS9YTUxTY2hlbWEtaW5zdGFuY2UiIElzc3VlSW5zdGFudD0iMjAwNy0wOC0xN1QxMzo1
Mzo0OC4zOTBaIiBNYWpvclZlcnNpb249IjEiIE1pbm9yVmVyc2lvbj0iMSIgUmVzcG9uc2VJRD0i
XzVhZGNmNDBhNzY2M2Q1OWFkMTljZWQ4ZmExYTdlYjJiIj48U3RhdHVzPjxTdGF0dXNDb2RlIFZh
bHVlPSJzYW1scDpTdWNjZXNzIj48L1N0YXR1c0NvZGU+PC9TdGF0dXM+PEFzc2VydGlvbiB4bWxu
cz0idXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6MS4wOmFzc2VydGlvbiIgQXNzZXJ0aW9uSUQ9Il84
OGMzZDA2ODIwODg5YzRjZjc1NzQ0MGQ4YzYwOTg0OSIgSXNzdWVJbnN0YW50PSIyMDA3LTA4LTE3
VDEzOjUzOjQ4LjM5MFoiIElzc3Vlcj0iNTJOVGVzdCIgTWFqb3JWZXJzaW9uPSIxIiBNaW5vclZl
cnNpb249IjEiPjxDb25kaXRpb25zIE5vdEJlZm9yZT0iMjAwNy0wOC0xN1QxMzo1Mzo0Ny40Njha
IiBOb3RPbk9yQWZ0ZXI9IjIwMDctMDgtMTdUMTQ6MDM6NDcuNDY4WiI+PC9Db25kaXRpb25zPjxB
dXRoZW50aWNhdGlvblN0YXRlbWVudCBBdXRoZW50aWNhdGlvbkluc3RhbnQ9IjIwMDctMDgtMTdU
MTM6NTM6NDcuNDY4WiIgQXV0aGVudGljYXRpb25NZXRob2Q9InBhc3N3ZCI+PFN1YmplY3Q+PE5h
bWVJZGVudGlmaWVyIEZvcm1hdD0iI0lEIiBOYW1lUXVhbGlmaWVyPSJ1cm46bjUyOmF1dGhlbnRp
Y2F0aW9uOnN1YmplY3Q6cHJpbmNpcGFsOnVzZXJuYW1lIj5kcmV3bmFrPC9OYW1lSWRlbnRpZmll
cj48L1N1YmplY3Q+PC9BdXRoZW50aWNhdGlvblN0YXRlbWVudD48QXR0cmlidXRlU3RhdGVtZW50
PjxTdWJqZWN0PjxOYW1lSWRlbnRpZmllciBGb3JtYXQ9IiNJRCIgTmFtZVF1YWxpZmllcj0idXJu
Om41MjphdXRoZW50aWNhdGlvbjpzdWJqZWN0OnByaW5jaXBhbDp1c2VybmFtZSI+ZHJld25hazwv
TmFtZUlkZW50aWZpZXI+PC9TdWJqZWN0PjxBdHRyaWJ1dGUgQXR0cmlidXRlTmFtZT0iZ3JvdXAx
IiBBdHRyaWJ1dGVOYW1lc3BhY2U9ImRlZiI+PEF0dHJpYnV0ZVZhbHVlPjUyTjwvQXR0cmlidXRl
VmFsdWU+PC9BdHRyaWJ1dGU+PC9BdHRyaWJ1dGVTdGF0ZW1lbnQ+PEF0dHJpYnV0ZVN0YXRlbWVu
dD48U3ViamVjdD48TmFtZUlkZW50aWZpZXIgRm9ybWF0PSIjSUQiIE5hbWVRdWFsaWZpZXI9InVy
bjpuNTI6YXV0aGVudGljYXRpb246c3ViamVjdDpwcmluY2lwYWw6dXNlcm5hbWUiPmRyZXduYWs8
L05hbWVJZGVudGlmaWVyPjwvU3ViamVjdD48QXR0cmlidXRlIEF0dHJpYnV0ZU5hbWU9InJvbGUi
IEF0dHJpYnV0ZU5hbWVzcGFjZT0iZGVmIj48QXR0cmlidXRlVmFsdWU+c29mdHdhcmUgZW5naW5l
ZXI8L0F0dHJpYnV0ZVZhbHVlPjxBdHRyaWJ1dGVWYWx1ZT5zb2Z0d2FyZSBhcmNoaXRlY3Q8L0F0
dHJpYnV0ZVZhbHVlPjwvQXR0cmlidXRlPjwvQXR0cmlidXRlU3RhdGVtZW50PjwvQXNzZXJ0aW9u
PjwvUmVzcG9uc2U+DQo=
   </Credentials>
</GetSession>

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 WSS</session:Name>
                <session:URL>http://www.52north.org/wss/WSS</session:URL>
        </session:Issuer>
        <session:Status>opened</session:Status>
</session:Session>

DoService Operation

The central DoService operation is used by clients to send service requests (like a WMS GetMap request) to the protected service. Together with the service request the client has to provide credentials, so the user/client can be identified. Usually this is a session id previously received from the WSS. But it is also possible to use any other authentication method accepted by the WSS.

Caution!
Don't use the HTTP GET variant because it is quite error-prone and subject to length restrictions imposed by the web server!

Request

Parameter Use Description
VERSION=<version> O Request version, should always be 1.1
SERVICE=WSS R Service type
REQUEST=DoService R Request name
SESSIONID=<session_id> R Id of a session that was retreived by calling the GetSession operation; mutual exclusive with METHOD and CREDENTIALS
METHOD=<method_identifier> R Identifier of the authentication method to be used, e.g. urn:opengeospatial:authNMethod:OWS:1.0:password (username/password) or urn:opengeospatial:authNMethod:OWS:1.0:wauthns (SAMLResponse) ; mutual exclusive with SESSIONID
CREDENTIALS=<credential_list> R Authentication information like username and password; mutual exclusive with SESSIONID
FACADEURL=<url> R This URL will be used to replace any occurance of the URL of the protected service. The facade URL will be the one that is published in the capabilities document of the protected service.
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. In case of WAS/SAML authentication the credentials parameter holds the Base64-encoded SAML ticket as received from the WAS.

HTTP GET example:

  [Don't use it!]

HTTP POST example:

<DoService xmlns="http://www.gdinrw.org/wss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" service="WSS" version="1.0">
        <ServiceRequest DCP="HTTP_POST" mimeType="text/xml" encoding="UTF-8"><![CDATA[REQUEST=GetCapabilities&SERVICE=WMS]]></ServiceRequest>
        <AuthMethod>urn:opengeospatial:authNMethod:OWS:1.0:password</AuthMethod>
        <Credentials>guest,guest</Credentials>
        <FacadeUrl>https://bern:8443/wss_umn_wms/WSS</FacadeUrl>
</DoService>
  • DCP is used to signal whether the ServiceRequestContent shall be forwarded to the protected service using HTTP_POST or HTTP_GET.
  • mimeType and encoding will be used to generate the header fields for the HTTP request against the protected service.

Response

The response is what you would get from the protected service including any HTTP header information that was returned from the service (e.g. a WMS generated png image). Of course, the response may have been manipulated by the WSS interceptors. It is also possible, that the WSS returns a an exception, if the authorization process fails.

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 used to identify the user for DoService requests.

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/wss/WSS?SERVICE=WSS&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 WSS</session:Name>
                <session:URL>http://www.52north.org/wss/WSS</session:URL>
        </session:Issuer>
        <session:Status>closed</session:Status>
</session:Session>

Exceptions

If any request yields an error the WSS 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