The tas3_sso() API is essentially a Single Sign-On protocol state machine. Unless the application already has a valid active session established, it should call tas3_sso() upon every HTTP request, passing in the query string or form submission part as the qs argument. The argument is a string and must be formatted as a query string. The tas3_sso() then returns a string which the calling application needs to interpret to decide what to do next. Possible actions include performing HTTP redirect, sending the returned string as HTTP response, or completing a successful single sign on.
When Single Sign-On is completed, the tas3_sso() establishes a session object for holding received attributes and bootstrap EPRs. These can be accessed from the session either by the calling application, or by other TAS3 API functions such as tas3_az() and tas3_call(). The tas3_sso() may incorporate a configurable frontend policy enforcement point. Such configuration is implementation dependent.
There are many options. Most of these have sensible default values or can be specified in a configuration file. The first parameter either is a configuration object, or a configuration string that modifies or adds to the default configuration. Some aspects of operation of tas3_sso() are affected by the auto_flags parameter.
Table 1:tas3_sso() configuration options that all implementations MUST support
| Option | Description |
|---|---|
| PATH | Path of configuration directory, which contains the configuration file and may contain other implementation dependent information. |
| URL | Base URL from which the EntityID is formed. |
Table 2:tas3_sso() AUTO flags
| Dec | Hex | Symbol | Description |
|---|---|---|---|
| 1 | 0x01 | TAS3_AUTO_EXIT | Call exit(2), 0=return "n", even if auto CGI |
| 2 | 0x02 | TAS3_AUTO_REDIR | Automatic. handle redirects, assume CGI (calls exit(2)) |
| 4 | 0x04 | TAS3_AUTO_SOAPC | SOAP response handling, content gen |
| 8 | 0x08 | TAS3_AUTO_SOAPH | SOAP response handling, header gen |
| 16 | 0x10 | TAS3_AUTO_METAC | Metadata response handling, content gen |
| 32 | 0x20 | TAS3_AUTO_METAH | Metadata response handling, header gen |
| 64 | 0x40 | TAS3_AUTO_LOGINC | IdP select / Login page handling, content gen |
| 128 | 0x80 | TAS3_AUTO_LOGINH | IdP select / Login page handling, header gen |
| 256 | 0x100 | TAS3_AUTO_MGMTC | Management page handling, content gen |
| 512 | 0x200 | TAS3_AUTO_MGMTH | Management page handling, header gen |
| 1024 | 0x400 | TAS3_AUTO_FORMF | In IdP list and mgmt screen, generate form fields |
| 2048 | 0x800 | TAS3_AUTO_FORMT | In IdP list & mgmt screen, wrap in |
| 4095 | 0xfff | TAS3_AUTO_ALL | Enable all automatic CGI behaviour. |
| 4096 | 0x1000 | TAS3_AUTO_DEBUG | Enable debugging output to stderr. |
| 8192 | 0x2000 | TAS3_AUTO_OFMTQ | Output Format Query String |
| 16384 | 0x4000 | TAS3_AUTO_OFMTJ | Output Format JSON |
Example Usage
01 res = tas3_sso(conf, request['QUERY_STRING'], 0x1800);
02 switch (substr(res, 0, 1)) {
03 case 'L': header(res); return 0; # Redirect
04 case 'n': return 0; # already handled
05 case 'b': return my_send_metadata();
06 case 'e': return my_render_idp_selection_screen();
07 case 'd': return my_start_session_and_render_protected_content();
08 default: error_log("Unknown tas3_sso() res(%s)", res); return 0;
09 }
Return values
The return value starts by an action letter and may be followed by data that is relevant for the action.
Redirection request (L as in Location header). The full contents of the res is the redirection request, ready to be printed to stdout of a CGI. If you want to handle the redirection some other way, you can parse the string to extract the URL and do your thing. This res is only returned if you did not set TAS3_AUTO_REDIR.
Example:
Location: https://sp1.zxidsp.org:8443/zxid?o=C
Content with Content-type header. The res is ready to be printed to the stdout of a CGI, but if you want to handle it some other way, you can parse the res to extract the header and the actual body.
Example:
CONTENT-TYPE: text/html
<title>Login page</title>
...
Example (metadata):
CONTENT-TYPE: text/xml
<m:EntityDescriptor>
...
Content without headers. This could be HTML content for login page or metadata XML. To know which (and set content type correctly), you would have to parse the content. This res format is only applicable if you did not specify TAS3_AUTO_CTYPE (but did specify TAS3_AUTO_CONTENT).
Do nothing. The operation was somehow handled internally but the exit(2) was not called (e.g. TAS3_AUTO_SOAP was NOT specified). The application should NOT attempt generating any output.
Indication that the application should send SP metadata to the client. This res is only returned if you did not set TAS3_AUTO_META.
Indication that the application should send SP CARML declaration to the client. This res is only returned if you did not set TAS3_AUTO_META.
Indication that the application should display the IdP selection page. This res is only returned if you did not set TAS3_AUTO_CONTENT.
Indication that SSO has been completed or that there was an existing valid session in place. The res is an LDIF entry containing attributes that describe the SSO or session.
dn: idpnid=Pa45XAs2332SDS2asFs,affid=https://idp.demo.com/idp.xml
objectclass: zxidsession
affid: https://idp.demo.com/idp.xml
idpnid: Pa45XAs2332SDS2asFs
authnctxlevel: password
sesid: S12aF3Xi4A
cn: Joe Doe
Usually your application would parse the attributes and then render its application specific content.
SSO completed, if JSON output was chosen. Processing should be same as for "d".
Authorization failure. Application MUST NOT display protected content. Instead, it should offer user interface where the user can understand what happened and possibly gain the extra credentials needed.
Although any unknown letter should be interpreted as an error, we follow convention of prefixing errors with an asterisk ("*").