WSS 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 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!
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:oasis:names:tc:SAML:1.0:am:password; ; 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. |
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
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
