[Prev]

3.1.5 Web Service Call: ret_soap = tas3_call(cf, ses, svctype, url, di_opt, az_cred, req_soap)

tas3_call() first checks if reqsoap string is already a SOAP envelope. If not, it will supply missing <Envelope>, <Header>, and <Body> elements. You still need to pass something in reqsoap as tas3_call() can not guess the contents of the <Body> - it can only add the wrapping. The idea is that the programmer can concentrate on application layer and the tas3_call() will supply the rest automatically. If, however, the programmer wishes to pass some SOAP headers, he can do so by passing the entire envelope. Even if entire envelope is passed, tas3_call() will add TAS3 specific headers and signatures to this envelope.

Similarly on return, tas3_call() will check all TAS3 relevant SOAP headers and signatures, but will still return the entire SOAP envelope as a string so that the application layer can, if it wants, look at the headers.

Next, tas3_call() will attempt to locate an EPR for the service type. This may already be in the session cache, or a discovery step may be performed. If discovery is needed it will be automatically made. The discovery can be constrained using url and di_opt parameters. For example, if there is a predetermined (list of) service provider(s), the url parameter can be used to force the choice. Discovery may still be done to obtain credentials needed for the call, but the discovery result will be constrained to match the supplied url. See section tas3_get_epr() for description of explicit discovery.

Before actual SOAP call, tas3_call() may contact a PDP to authorize the outbound call. This corresponds to application independent Requester Out PEP and is configurable: you can disable it if you prefer to make an explicit application dependent call to tas3_az(). The attributes for the XACML request are mainly derived from the session, but additional attributes can be supplied with az_cred parameter, which has query string format. Functioning of the authorization step can be controlled using configuration, which is implementation dependent.

Then tas3_call() augments the XML data structure with Liberty ID-WSF mandated headers. It will look at the security mechanism and token specified in the EPR and perform appropriate steps to create WS-Security header and apply signature as needed.

Next tas3_call(), using its built-in http client, opens TCP connection to the web service provider and sends the SOAP envelope using HTTP protocol. It then waits for the HTTP response, blocking until the response is received.

After executing the SOAP call and verifying any returned TAS3 relevant headers and signatures, tas3_call() may contact a PDP to authorize receiving data, and to pass on any obligations that were received. This corresponds to application independent Requester In PEP and is configurable: you can disable it if you prefer to make explicit application dependent call to tas3_az(). The contents of the XACML request are determined based on the response, session, azcred parameter, which is shared for both Responder Out and Responder In PDP calls, and configuration, which is implementation dependent.

cf

Configuration object, see tas3_new_conf_to_cf()

ses

Session object, used to locate EPRs, see tas3_new_ses()

svctype

Service type and namespace URN that is applicable to the body. Passed as a string.

url

(Optional) If provided, this argument has to match either the ProviderID, EntityID, or actual service endpoint URL.

di_opt

(Optional) Additional discovery options for selecting the service, query string format

az_cred

(Optional) Additional authorization credentials or attributes, query string format. These credentials will be populated to the session's attribute pool in addition to the ones obtained from SSO and other sources. Then a PDP is called to get an authorization decision (as well as obligations we pledge to support). This implements generalized (application independent) Requester Out and Requester In PEPs. To implement application dependent PEP features you should call tas3_az() directly.

req_soap

string used as SOAP body or as SOAP envelope template.

return

SOAP envelope as a string.

Example 

  01 env = tas3_callf(cf, ses, "urn:hrxml:idhrxml", 0,0,0,
  02         "<idhrxml:Modify>"
  03           "<idhrxml:ModifyItem>"
  04             "<idhrxml:Select>%s</idhrxml:Select>"
  05             "<idhrxml:NewData>%s</idhrxml:NewData>"
  06           "</idhrxml:ModifyItem>"
  07         "</idhrxml:Modify>", cgi.select, cgi.data);
  08 if (env) {
  09   xml = xml_parse(env);
  10   if (xml->Status->code == "OK") {
  11     INFO("Data is " + xml->Data);
  12   } else {
  13     ERR("Web service error " + xml->Status->code);
  14   }
  15 } else {
  16   ERR("HTTP failure");
  17 }

As can be seen, the paradigm is to supply the payload data as a string. Although it could be supplied as a data structure, constructed with many constructors, our experience has shown that string representation is most intuitive and self documenting for most programmers. Despite abandoning the constructor approach, all relevant syntax and schema checks are internally done by simply parsing the string and then reserializing it before sending to the wire. This tends to be necessary anyway due to signature generation.

[Prev | Next]