10.1 Hello World

Consider the follwing "Hello World" CGI example in C (the zxid_simple() API is available in all language bindings):

  01 #include <zx/zxid.h>
  02 #define CONF "PATH=/var/zxid/\&URL=https://sp1.zxidsp.org:8443/zxid"
  03 void main() {
  04   char* res = zxid_simple(CONF, 0, 255);
  05   switch (res[0]) {
  06   case 'd': /* Logged in case */
  07     my_parse_ldif(res);
  08     my_render_content();
  09     exit(0);
  10   default:
  11     ERR("Unknown zxid_simple() response(%s)", res);
  12   }
  13 }

What happens here:

1. The CGI script calls zxid_simple() to handle SAML protocol according to the configuration

2. The last argument with value 255 tells zxid_simple() to automatically handle redirections, login screen and any other protocol interaction needed to make SSO happen.

3. If zxid_simple() returns, we have either succeeded in SSO or we have failed (all other cases are handled internally by zxid_simple() which calls exit(2) so it never returns).

4. In the success case, zxid_simple() returns an LDIF entry (as a nul terminated C string) describing the SSO and the attributes received. For example

        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

   where

   dn

   LDAP distinguished name (part of LDIF format). Always first.

   objectclass

   Part of LDIF format.

   affid

   Specifies which IdP was used for SSO

   idpnid

   The federated ID, or pseudonym (IdP assigned NameID)

   authnctxlevel

   Rough indication of how IdP authenticated user

   sesid

   Session ID, as may be stored in cookie or used for file name in the session cache (/var/zxid/ses)

   cn

   Common Name. This attribute just exemplifies how any additional attributes the IdP may have set will appear. Typically the LDAP attribute names are used.

   The dn line will always be the first. All other lines may appear in any order. String representation of LDIF was chosen as it is easy to parse in most programming languages.