required parameter: 'destination'

There is one mandatory parameter which must be sent in a standard WIND Authentication request: 'destination'. This is the URI to which the user should be directed after authenticating.

sample

            
    <!-- This html form might be a part of http://myserver.com/chat_login. -->
    <form method="post" action="https://wind.columbia.edu/login">
    <input type="hidden" name="destination" value="http://myserver.com/chat__service">
    <input type="submit" value="Log in to the chat service."></form>
    <!-- The URI http://myserver.com/chat__service must handle validation. -->
            
          

This snippet of HTML shows how the provider of an online chat service might generate a WIND authentication request. WIND will accept both POST and GET requests for logins.

response

Web applications using WIND do not get a direct reponse to an authentication request. If the authentication request is successful, the web application can anticipate that the user will soon be redirected to the destination URI using a request that includes a WIND ticketid parameter.

overview

At the destination URI, browsers must present a ticket. Your web application must extract the ticket from the request and validate it.

The validation request is an HTTPS request sent from the web application which manages the destination URI to the WIND server. The actual end-user does not participate in this transaction.

The validation URI looks like this:

https://wind.columbia.edu/validate?ticketid=TICKETID_TO_BE_VALIDATED

response

The authentication response can be in 1 of 2 formats for a given web appilcation, XML or plain text. If it's in XML, the WIND server will answer with an XML document whose root element is a <wind:serviceResponse>. This will contain either a <wind:authenticationSuccess> or a <wind:authenticationFailure> element.

A successful authentication will look like:

            
         <wind:serviceResponse xmlns:wind='http://www.columbia.edu/acis/rad/authmethods/wind'>
           <wind:authenticationSuccess>
             <wind:user>UNI</wind:user>
             <wind:passwordtyped>true</wind:passwordtyped>
             <wind:logintime>1078117200</wind:logintime>
             <wind:passwordtime>1072933200</wind:passwordtime>
             <wind:passwordchangeURI>
               https://www1.columbia.edu/sec/acis/manageaccount/passwd.html
             </wind:passwordchangeURI>
           </wind:authenticationSuccess>
         </wind:serviceResponse>    
            
          

In the example above, user "UNI" authenticated successfully and had to type a password to obtain this ticket. The details of the response fields are explained below (in the "XML-Format Response Details" section).

An authentication failure will look like:

            
         <wind:serviceResponse xmlns:wind='http://www.columbia.edu/acis/rad/authmethods/wind'>
           <wind:authenticationFailure code="ERROR_CODE">ERROR_MESSAGE</wind:authenticationFailure>
         </wind:serviceResponse>
            
          

In addition to the XML-formatted response, WIND supports a plain text response, a "yes" (followed by an anonymous identifier or UNI) for success, or "no" for failure. Each line in the response ends with a newline character.

A successful authentication will look like:

            
         yes
         UNI
            
          

An authentication failure will look like:

            
         no
            
          

Sample Perl code for parsing the XML response:

            
    #
    # Ticket validation subroutine
    #
    # $validateURI = 'https://wind.columbia.edu/validate?ticketid=';
    #
    sub validateTicket {
        use LWP::Simple 'get';
        use XML::Simple;
        my $ticketId = shift;
        my $windResponse;
        $windResponse = LWP::Simple::get($validateURI.$ticketId);
        my $ref = XMLin($windResponse);
        if (exists $ref->{'wind:authenticationSuccess'}) {
            my $username = $ref->{'wind:authenticationSuccess'}{'wind:user'};
            print "$username is logged in now"
        } elsif (exists $ref->{'wind:authenticationFailure'}){
            # Ticket rejected. User should have an option to try again.  To
            # try again, another authentication request needs to be generated.
            print "the ticket was already used or was invalid";
        } else {
            # Unexpected response
            print "did not receive an expected response";
        }
    }
            
          

This snippet shows how validation of a ticketid might occur for an application that receives XML-formatted responses. (Perl must be configured with SSL support in order for the LWP module to connect to an HTTPS URI.) WIND will accept both POST and GET requests for validation.

successful response

A successful XML-formatted validation response returns several fields in addition to the UNI. These include:

The <passwordtyped> field is a boolean value ("true" or "false"). If it is "true" then the user had to type a username and password to obtain the ticket that was validated; otherwise it was issued through a session cookie or a proxy granting ticket (see the "Proxiable Credentials" section for more on this).

The <logintime> and the <passwordtime> fields are both expressed in epoch time format (seconds since `00:00:00 1970-01-01 UTC'). If an application determines that it has been too long since the most recent password change for a given UNI, it can redirect the user to the password change application URI that is listed in the <passwordchangeURI>.

In the XML-formatted sample response above, for instance, the user "UNI" had to type a password; the login time was 1078117200 (00:00:00 EST on March 1st, 2004); the password was most recently updated at 1072933200 (00:00:00 EST on January 1st, 2004); and the URI to the password change application page is "https://www1.columbia.edu/sec/acis/manageaccount/passwd.html".

unsuccessful response

The possible error codes and messages are listed below. Errors that refer to "PGT" or "PT" involve proxiable credentials, which are explained in greater detail later.

overview

The Single Sign-On (SSO) system allows a user who has established a WIND session to log in to any SSO service without having to re-type a password. This is an opt-in feature, meaning that Single Sign-On only works between services that have it enabled. WIND sets a browser cookie that permits the user to skip the login form. A redirection to the WIND login URI is still necessary, and a redirection to the destination URI with a ticket occurs as usual.

Before you enable the SSO feature, you should consider its security implications. For example, you will probably want to know what other services have SSO enabled. Please contact cuit-wind@columbia.edu for additional information.

It is important for all applications that enable SSO access to implement logout. This clears the cookie in the browser and closes the WIND session, preventing unauthorized logins from that browser. Applications performing simple authentication, however, do not need to send logout requests.

optional parameters

There are three optional parameters when accessing logout: 'destination', 'destinationtext', and 'passthrough'.

sample

            
 <a href="https://wind.columbia.edu/logout?destination=http://www.columbia.edu/&destinationtext=back%20to%20Columbia">
  Click here to Logout</a>
            
          

This snippet of HTML shows how a simple link can be constructed to support logging out.

response

Web applications do not get a direct response to a logout request. The WIND server closes any WIND session with the user's browser, and displays a page using the destination and destinationtext parameters. If the passthrough parameter is set the user's browser is redirected to the destination.