This is a short introduction to programming with the SOSI-GW API.

Prerequisites: Web-services using SOAP, WS-Addressing. You should read the design-description of SOSI-GW first. See here.

Deployment is easy, using Apache Tomcat or Trifork T4; just deploy the sosigw.war archive and all is well. The default setup uses "pan.certificat.dk" as STS server, which is a test-server at TDC. The web-services are at http://localhost:8080/sosigw/service/sosigw as noted in sosigw.wsdl.

Using SOSI-GW.

You must be able to build WS-requests with a valid level 1 UserIDCard, in the SOAP-Header. This is required for all requests to and through SOSI-GW.

You can either implement the signing in your application, or leave it to the gateway to do so using a browser.

For the application-integrated signing case, the normal flow of requests is as follows:

1. requestIdCardDigestForSigning. This is the "login" step.
   In return you get a digest that you can sign, if you wish to perform this step in your client.
   Also returned is a URL that, when opened in a browser, starts an applet that performs the signing for you.
   Use either of them. Calling requestIdCardDigestForSigning sets the IDcard-state to "unsigned" so that no calls may go through "proxy".
2. getValidIdCard. This call enable your application to check if there is a signed card for the user in the gateway.
   A fault is returned if there is no card, or if the card is present, but unsigned.
   The purpose is to enable an application to poll while waiting for the browser-based signing to take place.
   If there is a signed card, it is returned. The purpose of this is to let the application inspect attributes such as the remaining period of validity.
3. signIdCard. Used in conjunction with requestIdCardDigestForSigning when not using browser-based signing.
   As input, supply the signed digest and the certificate used to perform the signing.
   The gateway then contacts the STS and stores the resulting IDcard in the cache.
4. proxy. This is the gateway operation, used to relay messages to other parties. Call it as many times as needed.
   Note that this operation is not in the wsdl for SOSI-GW.
   By default it lives on http://localhost:8080/sosigw/proxy/soap-request.
   If there is a valid, signed IDCard in the gateway, it relays the message to the destination provided in the WS-Addressing headers.
   If there is no signed IDCard in the gateway, a fault is returned, with the same information as is returned by requestIdCardDigestForSigning, but provided in a header.
   It is possible to require a maximum age of the cached IDCard by adding the SOAP-header-node "sosigw:MaxAge" with a text-content being the maximum number of minutes that may have passed since the IDCard was signed. If the IDCard is too old, proxy acts as if there was no IDCard.
   If SOSI-GW has client access restrictions configured, using a shared secret, you must include the shared secret as the text-contents of the header-node "sosigw:ClientAccessKey".
5. logout. When you want the cached IDcard to be invalidated.
   You should probably call this when the user logs out of your system, but not necessarily, as not doing so provides a kind of single sign on to the services used through the gateway.

For the browser-based signing case, the normal flow of requests is as follows:

1. requestIdCardDigestForSigning. As mentioned earlier.
   Use the URL returned to start a browser session.
2. getValidIdCard. As mentioned earlier.
   Call at regular intervals, probably no more than once a second or so, to know when the browser based signing has been completed.
   You will likely want to allow your user to redo the process, if the user has closed the browser by mistake or for some other reason wants to restart the signing process.
3. signIdCard. Not used for browser based signing, as this is handled by the gateway and applet.
4. proxy. As mentioned earlier.
5. logout. As mentioned earlier.

The complete set of fault codes returned by SOSI-GW is listed here. But please note that it is quite possible to get other fault codes, as faults from STS and faults from the proxied calls are also returned.

• no_valid_idcard_in_request - Returned when there is no UserIDCard in the SOAP-header
• missing_signinginfo_in_request - Returned when the key-info or signed digest is missing from the request to signIdCard.
• syntax_error_in_request - Returned when parsing the headers failed.
• awaiting_signing - Returned by getValidIdCard when there is a card in the cache, that has not been signed yet.
• no_valid_idcard_in_cache - Returned when there is no IDCard in the cache that matches the nameID of the input.
• access_denied - Returned when the IP-address and/or salt in the header is not in the whitelist of allowed clients.
• internal_error - Internal processing error in SOSI-GW.

-- MortenGrouleff - 26 Nov 2007