• SingleSignOn

Protocol (stable-0.7.5)

• The following describes the ServiceProviderInterfaceToolkit (SPIT) Assertion Consumer as implemented in stable-0.7.5

  • The description is somewhat PHP centric.

• See HowTo/InstallSingleSignOn for how to configure and set up a ServiceProvider to implement this protocol.

• the Assertion Consumer actions are always triggered by xri_cmd or xri_local_cmd in a query string of a URI on a Service Provider web application

  • xri_cmd trigger function calls that begin with ac_...

  • xri_local_cmd trigger function calls that begin with sp_...

  • both xri_cmd and xri_local_cmd may trigger function calls in spit.php. All spit.php function names begin with spit_...

• Service Providers must customize both ac_... and sp_... functions for their local architecture

• Service Providers are free to implement their own direct calls to spit.php functions, but the Assertion Consumer should handle most cases.

• for simplicity, conditions which result in xri_result=0 are not described here. See spit/assertion_consumer.php for further investigation

I've posted some issues with the protocol at SsoProtocolCritique. --EugeneKim

Logging In

1. User enters i-name in login_iname field of login form

2. form minimally contains

   <input type='hidden' name='xri_local_cmd' value='login' />
   <input type="text" name="login_iname" size="16" value="" />
   

3. form points to a page that invokes the Assertion Consumer (meaning that the page calls require_once "spit/assertion_consumer.php";

4. the Assertion Consumer catches ?xri_local_cmd=login and calls sp_login()

5. sp_login() returns array(LOGIN_INAME, RETURN_URL). The RETURN_URL will be a page that also invokes the Assertion Consumer
6. the Assertion Consumer manages the rest of the authentication process ending in a redirect to the IDA for authentication
7. after authentication, the i-broker redirects the user to RETURN_URL which invokes the Assertion Consumer

8. the Assertion Consumer catches the xri_cmd=login&xri_result=1 which calls spit_verify()

   • if verified, the Assertion Consumer calls ac_login_success($resolver) which implements local SP procedures to handle a successful login

   • if not verified, the Assertion Consumer calls ac_login_failure() which implements local SP procedures to handle a failed login

Logging Out

1. User initiates logout request by taking an action which sends a ?xri_local_cmd=logout command to an SP page which invokes the Assertion Consumer

2. the Assertion Consumer catches the ?xri_local_cmd=logout and calls sp_logout()

3. sp_logout() initiates local logout procedures and returns an array ('iname'=>LOGIN_INAME, 'xri_rtn'=>RETURN_URL)

4. the Assertion Consumer calls spit_isso_logout() which redirects to the IDA with a request to log out. SP must have the correct value in egistrar_keys in spit.config for the registry in which the user i-name is registered

5. the IDA does it's ISSO logout procedures and redirects the user to RETURN_URL?xri_cmd=logout&xri_result=1

   • RETURN_URL invokes the Assertion Consumer which catches the ?xri_cmd=logout&xri_result=1 and calls ac_logout()

6. ac_logout() initiates local procedures to handle the newly logged out state

Create New I-Name

1. User initiates new registration with SP which sends ?xri_local_cmd=create to an SP page which invokes the Assertion Consumer

2. the Assertion Consumer catches the xri_local_cmd=create and calls sp_create()

   • sp_create() implements local SP procedures to determine if user is qualified to register an i-name

     • if yes, returns array ("registry"=>REGISTRY, "local_id"=>LOCAL_ID, 'xri_return'=>RETURN_URL);

       • REGISTRY: the registry in which to create the i-name. SP must have the correct value in registrar_keys in spit.config for REGISTRY

       • LOCAL_ID: a unique value that identifies the user.

       • RETURN_URL: the URL to which the i-broker returns the user when the registration is complete

     • if no, returns false;

3. if result is not false, the Assertion Consumer calls spit_encode_registrar_uri() which redirects to the i-broker with the appropriate values to initiate a new i-name registration

4. after successful i-name registration the i-broker redirects the user to RETURN_URL?registry=REGISTRY&local_id=LOCAL_ID&t=TIME&iname=INAME&inumber=INUMBER&rrsid=RRSID&iname_status=INAME_STATUS&xri_cmd=create&xri_result=1

   • the INAME_STATUS will be either 'ok' or 'hold'. The value is defined in the i-broker in lib/config/ibroker.inc $registry_data[REGISTRY]initial_iname_status

5. Assertion Consumer catches the xri_cmd=create&xri_result=1 and calls ac_create($fully_qualified_iname);

   • ac_create() initiates local procedures to handle a new i-name registration

     • if INAME_STATUS is 'hold', SP must change the status to 'ok' before the user can use the i-name for SSO. The i-name will not resolve with status = 'hold'. SP may require additional actions by user before changing the status. SP changes status with this:

       require_once "spit/delegated_registrar.php";
       $registrar = new Delegated_Registrar();
       $registrar->modify_iname(INAME, 'ok', '', REGISTRY);
       

       • INAME: the last segment of the registered i-name. eg. if fully qualified i-name is @community*user.name INAME is "user.name"

       • REGISTRY: the remainder of the registered i-name. eg. if fully qualified i-name is @community*user.name REGISTRY is "@community"

       • see sp_assertion_consumer.php.sample New_Iname->iname_status_ok () for an example implementation

Implementation Notes

• There are three levels of login in the ISSO realm:

  1. new i-name created: The user is logged in on their i-broker/your registrar. The i-name won't resolve since its registry status is on hold. You, the SP, are certain of the i-name validity because the Assertion Consumer has called spit_verify_rsid().

  2. i-name authenticated: You, the SP, are sure they are authenticated because the Assertion Consumer called spit_verify() and got a 'true' response

  3. known user: You, the SP, matched the authenticated i-name or, even better, the i-number with a stored value on your system. I-numbers were passed to ac_login_success($resolver);

• a typical new user registration pattern
  1. user initiates desire to create Service Provider account (SP account always includes an i-name for SSO)
  2. SP requires SSO login or offers to enable the user to create an i-name. The status of the i-name the offers to create may be 'ok' or 'hold'. I-names on hold won't function in SSO until the status is changed to 'ok'.
     1. user logs in with i-name and returns to SP

        1. sp_assertion_consumer creates Login object (see sp_assertion_consumer.php.sample for example class)

     2. or creates i-name and returns to SP

        1. sp_assertion_consumer creates New_Iname object (see sp_assertion_consumer.php.sample for example class)

  3. SP collects user information and creates a new User
  4. if i-name creation status was 'hold', SP converts the status to 'ok'

Other Resources

• ServiceProviderInterfaceToolkit

• IssoSpecs - this "commercial grade" SAML 2.0 based solution will be used by all i-brokers soon

• HowTo/InstallSingleSignOn - updated for beta code used by current stable release

• SSO - the original alpha spec