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