The UA NetID WebAuth Service: An Introduction

What is WebAuth?

The UA NetID WebAuth service (WebAuth) is an authentication protocol for web-based applications which leverages the UA NetID authentication directory.  It allows web applications to perform NetID authentication via a simple series of HTTP requests; no LDAP API programming, nor direct interaction with the UA NetID authentication directory, is required.

WebAuth provides a form of single sign-on between applications that utilize it for authentication.  A user is required to authenticate via the UA NetID on the first attempt to login to a service using WebAuth.  Once successfully authenticated, the user will not be required to re-authenticate for the duration of the WebAuth login session (which lasts for either the duration of the browser session or 2 hours of inactivity, whichever comes first).

The UA NetID WebAuth service uses software developed by the JASIG CAS (Central Authentication Service) project.

When/Why to Use WebAuth?

The UA NetID WebAuth service can be utilized by any web application that wishes to perform authentication based upon the UA NetID.  As described below, two different methods of using WebAuth are available to developers, which provide different amounts of information and vary in complexity.

Any web-based applications that authenticate via the UA NetID can benefit from using WebAuth, as it provides a consistent authentication interface between applications.  Applications that use WebAuth also provide a greater convenience to the end user, who is not required to reauthenticate as often between applications.  Additionally, as the WebAuth authentication model never divulges the user's password to the application, WebAuth is safe to use with external, vendor-maintained, applications where there may be concern about disclosure of sensitive information.

Note that WebAuth provides authentication; that is, it determines that your users are who they say they are. WebAuth should not be viewed as an access-control system; in particular, providers of applications that grant access to anyone who possesses a UA NetID should understand that loose affiliates of UA may be granted NetIDs.

How WebAuth Works

The WebAuth service consists of 4 major components:

The process by which a web application uses WebAuth is illustrated in the following diagram:

To use WebAuth, an application redirects its users, or simply creates a hyperlink, to the login URL.  Users may also access this URL manually if they wish to pre-authenticate their sessions.

The login URL handles actual, "primary" authentication. That is, it prompts the user for a NetID and a password and validates the pair against the UA NetID LDAP directory.  To allow for the possibility of automatic re-authentication later, WebAuth also attempts to send an in-memory cookie (one that expires automatically when the browser closes) back to the browser. This cookie, which we call a "ticket-granting cookie," (TGC) identifies the user as one who has already logged in successfully.  The TGC has a default maximum lifetime of 2 hours.  If the user goes for longer than this without accessing a WebAuth-enabled application, the TGC will be automatically expired, and the user will be forced to re-login the next time WebAuth authentication is requested.  Users who desire a longer/shorter WebAuth timeout period (the permitted timeout range is 1 - 1440 minutes), or wish to disable single sign-on completely, may set their own WebAuth preferences at https://netid.arizona.edu.  Regardless of the timeout duration, the TGC will always be destroyed upon exiting the browser.

It is worth noting that the TGC cookie is an optional part of the WebAuth authentication mechanism. With it, the user achieves the appearance of "single sign-on" to multiple web applications; that is, he enters his NetID and password only once but gains access to any services that use the CAS. Without the cookie, the user will need to enter his NetID and password every time an application redirects him to WebAuth. (Users can direct WebAuth to destroy the cookie by going to a logout URL).

In addition to handling primary authentication, WebAuth also notes the service that the user was redirected or linked from. It can do this because applications that redirect or link a user to the login URL are required also to pass WebAuth a service identifier (labelled service name in the diagram above). If authentication is successful, WebAuth creates a long, random number, which we call a ticket. It then associates this ticket with the user who successfully authenticated and the service to which the user was trying to authenticate. That is, if user peon is passed from service S, WebAuth creates ticket T which allows peon to access service S. This ticket is intended as a one-time-use-only credential; it is useful only for peon, only for service S, and only once. It expires as soon as it is used.

Once primary authentication is complete, WebAuth redirects the user's browser back to the application from which it came. It knows what URL to redirect the user to because the service name discussed above also functions as a "callback URL." That is, the identifier that an application uses must represent a URL that is part of, or at least associated with, that application. WebAuth redirects the user's browser back to this URL, adding the ticket discussed above as a request parameter.

A Programmer's View of WebAuth

Before you begin to integrate your application with WebAuth, you should understand a few details about the way WebAuth operates. First and more importantly, WebAuth is unlike many familiar authentication systems because it is not simply a password-validation tool. In a traditional environment, your web application will ask users for an ID and a password, and it will then call logic to determine whether this ID/password pair is valid. With WebAuth, however, your application never gains access to the user's password; to improve systemwide security, users supply their passwords only to the WebAuth server directly.

Therefore, although using WebAuth in your application may seem more circuitous than you initially imagined, be assured that the process is still straightforward and easy to master. When you first encounter a new user (e.g., one that has not yet established a session with your application), you'd normally display a username/password form in HTML. With WebAuth you don't do this; instead, you simply redirect the browser to WebAuth's login URL, which is

https://webauth.arizona.edu/webauth/login

WebAuth then authenticates the user. If authentication fails -- e.g., if the user cannot supply a correct password -- then you'll never hear from the user again. (At least, you won't hear formally through any WebAuth protocol!) Instead, the user will remain at WebAuth's site and will have the option to choose various "help" links that point to the UITS Online Support, or allow the user to perform various UA NetID management functions.

Only if a user succesfully authenticates does that user's browser return to your application. Specifically, the user returns because WebAuth redirects the browser back to your application. WebAuth knows how to find your application because when you initially redirected the user to WebAuth, you supplied a service parameter, in the form

https://webauth.arizona.edu/webauth/login?service=http://my/url

(Note that any metacharacters in your service URL, such as question marks, ampersands, and equals signs, must be escaped appropriately using the standard URL encoding algorithm: %26 for &, %3D for =, and %3F for ?. This will be necessary if your service URL contains parameters of its own. Note also that while it is necessary that you use HTTPS to safeguard your own application's authentication in secure environments, WebAuth's overall security is not weakened if your application merely uses HTTP; instead, WebAuth still authenticates the user securely, and then it relays this fact to your application in a best-efforts fashion.)

When WebAuth redirects the authenticated user back to your application, it will append a parameter named ticket to your URL. For instance, the URL you supplied WebAuth may be called as follows:

http://my/url?ticket=ST-92834-m34Aa83f7a3f

We call this ticket opaque because, unlike an X.509 certificate or a Kerberos TGT, it is not possible for your application to decipher its meaning in isolation or from first principles. It has no internal structure useful to your application. The only thing you can do with this ticket is to send it back to WebAuth, which involves opening an HTTPS connection to

https://webauth.arizona.edu/webauth/serviceValidate

- or -

https://webauth.arizona.edu/webauth/validate

and sending two query parameters: service, which must match the service URL you initially supplied to WebAuth when redirecting the user there, and ticket, which is the ticket you just received. WebAuth then responds either with an explicit refutation of this ticket (think "it's not meaningful to me and does not represent a valid user") or an acknowledgement that the ticket proves authentication. In the latter case, WebAuth also supplies the user's NetID (and, depending on which validation URL you use, other information from the user's UA NetID directory entry) so that you know the identity of the user.

Note that this final connection to WebAuth occurs directly between your application and WebAuth; your application opens an HTTPS connection and retrieves information from the WebAuth server. You do not redirect the browser; you speak directly to WebAuth, effectively closing the loop and completing the authentication process.

What is Returned from the WebAuth Validation URL?

As hinted at above, two different validation URLs are available to applications using the WebAuth service.  Both URLs perform the basic service ticket validation described above; they differ only in the amount, and style, of information returned.

Due to security concerns, and to prevent inappropriate use of the UA NetID as an authentication mechanism (e.g., by non-affiliated, external applications), access to both validation mechanisms is restricted by an IP-based access control list.  Any application attempting validation of a WebAuth service ticket needs to be in this list.  Developers and application administrators may request the addition of addresses to this list by emailing netid-admin@email.arizona.edu.

Basic Validation

The basic validation mechanism, which is accessed via the following URL:

    https://webauth.arizona.edu/webauth/validate

The basic validation mechanism returns back a simple text response, which will be one of:

The <NL> characters in the above responses are ASCII "newline" characters (0xA).

Extended Validation

The basic validation mechanism will let you know whether or not a valid UA NetID holder is trying to access your service.  However, if you need to perform authorization, using some other key than the NetID itself, the basic validation mechanism won't be terribly useful.  The NetID directory stores a few useful keys to other institutional data stores, including the Student ID, Employee ID, and the UA_ID (assigned by UIS).  These attributes, and others contained in the NetID directory schema, are accessible to the web application when using the extended validation mechanism.  For a full description of the UA NetID schema, please refer to the UA NetID Programmer's Guide.

The extended validation mechanism is accessed via the following URL:

https://webauth.arizona.edu/webauth/serviceValidate


The result of the extended validation mechanism is an XML document, which will contain the status of the validation attempt along with attributes for the NetID, if the validation is successful. The structure of the document for a successful validation is as follows :

        <cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
          <cas:authenticationSuccess>
            <cas:user>NetID username</cas:user>
            <cas:NetID Attribute 1>value</cas:NetID Attribute 1>
            .
            .
            <cas:NetID Attribute n>value</cas:NetID Attribute n>
          </cas:authenticationSuccess> 
        </cas:serviceResponse>

Note: The <cas:NetID Attribute x> nodes will really be titled things like "<cas:dbKey>" and "<cas:employeeId>". Each attribute readable by the user, in the user's NetID directory entry, will be represented by such a node, except for the following attributes (all attributes are described in the UA NetID Programmer's Guide):

The structure of the XML document following an unsuccessful validation is as follows:

        <cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
          <cas:authenticationFailure code='ERROR CODE'>
          descriptive error message
          </cas:authenticationFailure>
        </cas:serviceResponse>

The set of possible error codes is as follows:

What to Do Once You Authenticate a User with WebAuth

WebAuth is not a session-management mechanism; it provides no facility for helping you keep track of users once they're authenticated. Typically, applications will want to track users just as they would if they'd validated a user's password themselves. That is, you'll probably want to establish your own session -- using application-specific, in-memory cookies or a similar mechanism -- right after you validate a user's authenticity with WebAuth.

As a convenience mechanism to some applications, upon successful login WebAuth will attempt to set a cookie in the user's browser called "CASAUTHOK".  This cookie, if present, simply indicates that the user's browser--at some point since it was started--performed a successful WebAuth authentication.  The value of CASAUTHOK will be 1 (one) upon successful WebAuth login, and 0 (zero) upon logout.  Applications that make use of multiple, disparate authentication mechanisms may find this information useful.   This cookie does not indicate that the user's browser is currently authenticated--only that it was, at some point since the browser session began.  Since the domain of this cookie is ".arizona.edu" it cannot be trusted (as it can be easily spoofed) and, therefore, should never be used to make authentication/authorization decisions.

WebAuth is a single sign-on facility; once a user authenticates to WebAuth, the user need not continue to supply a password for other applications that redirect the user to WebAuth. Additionally, WebAuth has the ability to link application logout with WebAuth session logout, on a per-application basis.

Handling user logout

Logging-Out of WebAuth

WebAuth provides a "logout" URL; when a browser visits this URL, WebAuth will destroy the user's authentication credentials.  Applications may link to this URL at

https://webauth.arizona.edu/webauth/logout

This "logout" URL accepts two, optional, GET ("query string") parameters, which provides a mechanism for WebAuth-enabled applications to specify a "return" URL, along with descriptive text.  Both parameters must be properly URL-encoded.  The parameters are:

Following is an example of how to use these parameters for the hypothetical web application myapp.arizona.edu :

https://webauth.arizona.edu/webauth/logout?logout_href=https://myapp.arizona.edu&logout_text=Return%20To%20MyApp

Note: Because users may intend to continue to use WebAuth (and other WebAuth-protected applications) after they finish using your application, it is considered inappropriate to redirect to this URL automatically or to otherwise suggest that all users visit this URL when they sign-off of your application. Instead, we encourage application providers to provide a link to this URL on their logout page, as an option, and label it with descriptive text.  Following is an example:

<application name> logout successful.  WebAuth login may still be active.
Finished accessing secure applications?  Logout of WebAuth

Notifying Applications of WebAuth Logout

WebAuth provides an optional mechanism that can be utilized by application developers who need/desire to link WebAuth session logout with their own application-specific logout function.

An additional GET parameter, logout_notify, may be passed in the extended validation query string. This parameter's presence (the value is irrelevant) instructs WebAuth to remember the service URL associated with the ticket parameter passed in the validation request. Upon logout from WebAuth, each application requesting logout notification, to which the user has authenticated during the context of the current WebAuth session, will be contacted at the service URL with a modified ticket parameter. This "logout ticket" will exactly match the original service ticket (the ticket sent by the application to WebAuth for validation), except that it will be prefixed with a "-" (minus) character.

NOTE: There are no guarantees that WebAuth will successfully transmit the logout notification to a given application. If your application is not functioning correctly, is unreachable on the network, etc, WebAuth will simply give up and report a failure in the status message displayed to the user (see below). Additionally, WebAuth will only send the logout notification over HTTPS. Therefore, your original service parameter must specify an HTTPS URL, and the certificate used to secure this site must be signed by a "known" (e.g., Verisign, Thawte, etc) certificate authority. Please contact netid-admin@email.arizona.edu with any questions concerning this requirement.

How does this "logout ticket" work? When the application originally receives the service ticket (sent by WebAuth), and successfully verifies it (via the extended validation mechanism), it should tie the service ticket to whatever session ID is internally assigned to the user's application session. It is expected that this association will be stored in a database table, a hash table in shared memory, or some other "lookup table". Upon receipt of an HTTP GET request containing a ticket parameter that begins with a "-" character, the application should reference this table for the ticket value (after stripping off the leading "-"), retrieve the internal session ID, and destroy the applicable session. The appropriate response to the GET request depends on the situation. WebAuth only examines the Status-Code element of the Status-Line (as defined in RFC 2616), contained in the HTTP response; any body content is ignored. The three different types of responses, WebAuth's interpretation of each, and the conditons in which they should be used, are as follows:

NOTE: WebAuth session expiration will not trigger application logouts, as this is not a user-initiated action.

Upon WebAuth logout, the user will be presented with a summary of each attempted application logout, and the result (Success or Failure). For each application, the value of the banner parameter, if sent during the initial WebAuth login redirect, will be displayed. If the banner parameter was not supplied, the URL specified in the service parameter will be displayed instead. An example WebAuth logout screen is provided below:




Other Things WebAuth Can Do

WebAuth recognizes a number of request parameters, which influence the behavior of different phases of the WebAuth process:

Advanced Topics: Proxy Authentication

In addition to the two validation mechanisms previously discussed--basic and extended--WebAuth provides a third validation mechanism, which is more involved and will be primarily useful to developers attempting to integrate multiple WebAuth-enabled applications.  Applications using the "proxy validation" mechanism must supply an additional parameter, pgtUrl (in addition to the standard service and ticket parameters), and use the "proxy validation" URL:

    https://webauth.arizona.edu/webauth/proxyValidate

As before, the format of the request is the same, but the response, on success, contains an extra element providing new information:

  <cas:serviceResponse>
    <cas:authenticationSuccess>
        <cas:user>NetID</cas:user>
        <cas:NetID Attribute 1>value</cas:NetID Attribute 1>
        .
        .
        <cas:NetID Attribute n>value</cas:NetID Attribute n>
        <cas:proxyGrantingTicket>PGTIOU</cas:proxyGrantingTicket>
    </cas:authenticationSuccess>
  </cas:serviceResponse>

The proxyGrantingTicket element contains, as its body content, information identifying the Proxy-Granting Ticket (PGT) to be sent to the web application--essentially a PGT "IOU".  This value is not the typical opaque identifier for the actual PGT; it is simply a unique value that indexes this PGT.  Synchronously, WebAuth will send the PGT's actual (opaque) value as a request parameter to a URL owned by the application (and identified by the request parameter pgtUrl in the validation request to WebAuth).  The callback request contains two query parameters: pgtId, containing the actual value representing the PGT, and pgtIou, containing the PGTIOU contained in WebAuth's response to the web application's request.  The "callback" application, residing at the URL specified by pgtUrl, is responsible for maintaining a "table" of PGTs indexed by PGTIOU; this "table" can reside in a database table, flat file, or shared memory--the implementation is left up to the application developer.

This indirection is necessary to let WebAuth validate the service using its server certificate, which was deemed the simplest way to provide for mutual authentication, in the field, of services. Custom certificates, and locally shared secrets, are other options, but both were deemed less convenient.

Once this PGT has been received and matched appropriately by the web application, it enables a new protocol (exposed to web applications) that allows the retrieval of specific-use proxy tickets (PTs), which can be viewed as a "proxied" service ticket.

To obtain a proxy ticket, an application does the following:

Request: The web application sends a request with two query parameters: pgt and targetService, representing respectively a PGT and the unique identifier (URL) corresponding to the target web application to which the present web application (i.e., the proxy) wishes to gain access.  The URL to which to send this request is:
                https://webauth.arizona.edu/webauth/proxy
Response: A cas:proxyFailure message can be returned here for invalid or expired PGTs. On success, a message of the following format is sent by WebAuth to the application:
  <cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
    <cas:proxySuccess>
      <cas:proxyTicket>PT</cas:proxyTicket>
    </cas:proxySuccess>
  </cas:serviceResponse>

This PT may then be sent by the application to the target service (via the ticket query parameter), which validates it with WebAuth using the following protocol.

Request: The target service validates the proxy ticket just as it would a "normal" service ticket, only using the aforementioned proxyValidate URL.
Response: As before, authenticationFailure is an option here. On success, a message with the following form is returned:
  <cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
    <cas:authenticationSuccess>
        <cas:user>NetID</cas:user>
        <cas:NetID Attribute 1>value</cas:NetID Attribute 1>
        .
        .
        <cas:NetID Attribute n>value</cas:NetID Attribute n>
        <cas:proxyGrantingTicket>PGTIOU</cas:proxyGrantingTicket>
        <cas:proxies>
           <cas:proxy>proxy1</cas:proxy>
           <cas:proxy>proxy2</cas:proxy>
           <cas:proxy>proxy3</cas:proxy>
           ...
        </cas:proxies>
    </cas:authenticationSuccess>
  </cas:serviceResponse>

The target service may then make any access-control decisions it needs to make, based both on the username and the proxy "path" conveyed by the response from CAS.  The <cas:proxy> element will be the contents of the pgtUrl query parameter passed by the proxying application, as described above.

As the general format of this latest response message suggests, proxies may be "chained" -- that is, applied successively -- before an ultimate target is reached.  This chaining is achieved by the added PGTIOU to this recent message -- when target services implement the "proxy granting" protocol.  Thus, a target service may act as a proxy as well.

A "target" service that does not use the proxy mechanism for ticket validation will not be able to successfully validate proxy tickets (PTs).  Therefore, the decision of whether or not an application should accept proxied credentials is up to the developer.  The proxy validation mechanism will also validate normal service tickets (STs), but neither the basic nor the extended validation mechanisms will validate PTs. 



The structure, and majority of content, in this document was adapted from the documentation
provided at the JA-SIG CAS website:
https://wiki.jasig.org/display/CASUM/Home

Adapted for the UA NetID WebAuth project by:
Gary Windham
The University of Arizona, University Information Technology Services
URL: https://netid.arizona.edu/apidocs/webauth
Last updated: 09/09/2013