Skip to main content

Authentication Developer Information

Integrating with Stanford's Authentication System

This document is intended for application developers who want to integrate with Stanford's network, computing, and authentication environment. It explains what to think about while adding or modifying the security and authentication for applications so that they can use Stanford's existing centralized authentication infrastructure and namespace.

This document does not get into installation details, but rather is intended to give a mid-level overview of the design and workings of the authentication system and an overview of the various integration options for an application. In particular, this document focuses on the various protocols that the system supports and delves into options for integrating Stanford's Web Authentication (WebAuth) into a web-enabled application.

This document is divided into the following sections:

Overview

Authentication on the campus network is done using Kerberos v5.

The SUNet ID (Stanford University Network IDentifier) is a unique authentication identity associated with a single individual or application. Stanford affiliates receive a single primary ("login") SUNet ID, which matches their Kerberos principal and their Unix login identity. This is the identifier that will be returned by any authentication service, and is currently limited to between 3 and 8 alphanumeric characters.

Primary SUNet IDs are currently, by policy, never reassigned to anyone else once they have been used, but applications should not rely on this. They may, however, safely assume that primary SUNet IDs are not reassigned until the affiliated person has not been associated with the university for at least five (5) years.

Users may also create up to three additional alternate SUNet IDs, or aliases. These identifiers may be longer and contain other characters (such as period or dash), and are only useable in a small subset of places that SUNet IDs may be used. They are primarily intended for use as additional e-mail addresses or URLs for personal web pages. Alternate SUNet IDs are never returned by campus authentication services as a user's identity.

Protocols

Stanford's network infrastructure uses, among other technologies, a core of Kerberos, SASL and GSSAPI security layers, and SSL encryption transport.

Kerberos

Originally developed as part of Massachusetts Institute of Technology's Project Athena, Kerberos is at the core of Stanford's centralized authentication services. Kerberos is a network authentication protocol designed to provide strong authentication for client/server applications by using secret-key cryptography. It provides mutual authentication and assumes the general network is a hostile environment. It is provided as part of the operating system by most Unix systems, Mac OS X, and Microsoft Windows and is used extensively by the Microsoft Active Directory infrastructure. Further Kerberos documentation is available at the MIT Kerberos pages.

Note: Network protocols frequently use Kerberos v5 in the form of GSSAPI, a generic authentication API and protocol layer that standardizes application usage of several authentication protocols, including Kerberos.

At Stanford, on Unix systems, MIT's implementation of Kerberos is used primarily, although libraries from the Heimdal implementation from KTH are used for some applications. Either implementation will work well with Stanford's Kerberos infrastructure. Kerberos is also used as part of Stanford's Microsoft Windows Domain infrastructure.

Stanford is a member of the Kerberos Consortium.

SASL

The Simple Authentication and Security Layer (SASL) is a framework and protocol for adding authentication to connection-based network protocols. It allows any network protocol, regardless of its command syntax, to use standard libraries (like the Cyrus SASL libraries widely used at Stanford) to handle the details of the authentication. SASL can also be used to negotiate encryption for the rest of the connection.

SASL is used as the authentication mechanism for connecting to Stanford's OpenLDAP directory servers (including in the WebAuth mod_webauthldap Apache module mentioned below). It is also used as the authentication protocol for the campus e-mail servers and is the preferred way to add authentication support to any new network protocol.

SSL (TLS) Transport

Originally designed by Netscape, Secure Sockets Layer (SSL) is a protocol to enable encrpyted communications across the Internet using public-key cryptography. (SSL was standardized by the IETF under the name Transport Layer Security, TLS, so that term is also often used for newer versions.) SSL is widely used for encrypted transport of data. While it does also support authentication using x509 client certificates, this use is much less widely deployed and only used at Stanford in a small number of applications at the current time.

Considerations about Authenticating at Stanford: There are two options available for authenticating to many network services at Stanford: Kerberos authentication and sending passwords over an encrypted SSL connection. Whenever possible, the former is strongly preferred because it provides a stronger security model. Using Kerberos, the user's password never leaves their local system. However, many desktop clients either do not use Kerberos at all or do not use it well, and therefore user-facing authentication services frequently have to support password authentication over SSL.

Be careful not to confuse true Kerberos authentication, which usually uses GSSAPI or SASL or both and which doesn't send the user's credentials over the network, and sending the username and password over SSL to be verified against Kerberos on the server. The latter also uses Kerberos to check the password, but it is not as secure as true Kerberos authentication since the password is exposed to the server.

For web applications, both the decision of which authentication mechanism to use and the (risky) process of accepting passwords and validating them are handled for the application (and application developer) centrally by the weblogin service provided that the application is built to use Stanford WebAuth for authentication. In some cases, such as for WebDAV servers where WebAuth will not work with the client application, it may instead be appropriate to send the user's password over an SSL-protected session and then check it using Kerberos (such as with the Apache mod_auth_krb module).

Note: The Stanford OpenLDAP service only supports Kerberos authentication and does not accept passwords, even over SSL.

WebAuth

Stanford WebAuth is a cookie-based web authentication system that handles all authentication (and therefore the most serious risk of exposing user passwords or credentials) on a central weblogin server. WebAuth is available as Apache modules easily usable in any web application that runs under a standard Apache 2.x web server and is designed to function, from the application perspective, exactly like any other Apache security mechanism. This means that few or no modifications are required in order to use WebAuth with many standard web applications. (The hardest part is frequently convincing these applications to not use their own inferior internal authentication mechanism and instead just trust the Apache mechanism!)

Under the hood, Stanford's WebAuth uses Kerberos v5 service tickets. When the user authenticates to the weblogin server, WebAuth creates a security token for the application server that the server can verify and use to determine the user's primary SUNet ID.

WebAuth also contains support, via an additional Apache module, for querying the Stanford directory service for information about the user (such as preferred name, affiliation, e-mail address, or university ID number, among many other pieces of data), and for using privilege groups represented in the directory to do authorization and access control (see the next section).

The user's credentials are maintained as session cookies in the browser, meaning that the credentials will be automatically destroyed as soon as the user exits that browser. While there is a mechanism for selectively destroying some of the user's credentials, the user authenticates independently to each protected web site visited, and therefore it is important to stress to the user that in order to completely log out of all web authentication, the browser process must be completely closed down.

NOTE: After the March 30, 2018 changes to the Web Login services, SPNEGO is no longer supported for Stanford Web single sign-on. In the near future certificate-based authentication will be available which will provide similar functionality as SPNEGO.

Workgroup authorization

If you want to restrict access to web content to a particular set of people using WebAuth, you can maintain a list of their SUNet IDs in a .htaccess file or in the Apache configuration, but it's easier to use a privilege group. A privilege group is an attribute associated with individuals and stored in the Stanford LDAP directory that the WebAuth module knows how to query. For example, all Stanford students are members of the stanford:student privilege group, staff are members of the stanford:staff privilege group, faculty are members of the stanford:faculty privilege group, and stanford:stanford contains the merger of those three.

In addition to using the system-generated privilege groups like those mentioned above, groups can maintain their own workgroups using Workgroup Manager and publish them as privilege groups in the directory so that they can be used with WebAuth. For more information, see the workgroup documentation.

Content providers are strongly encouraged to use privilege groups rather than to allow access to anyone with a valid SUNet ID. SUNet IDs may be given out to people who are only loosely affiliated with the university or who only need to authenticate for particular purposes and should not have access to protected university resources. A good default choice of privilege group to use when restricting access to Stanford affiliates is stanford:stanford (for regular staff, faculty, and students) or stanford:administrative (which also includes temporary workers and contractors).

Note: There is a distinction between a workgroup and a privilege group, but it's subtle and mostly isn't noticeable to the average user. A workgroup is (in general) something you see in Workgroup Manager, and a privilege group is something present in the directory. While all groups found in workgroup manager are present in the directory as privilege groups, some system-generated privilege groups such as stanford:student are not available via workgroup manager. For the most part, you can ignore this distinction and treat the two concepts as equivalent.

Proxy service

Not every web server nor every web application can deal with having a WebAuth/Apache server as its web server. In order to get Stanford WebAuth in front of such systems, a WebAuth proxy service has been established. With this service, the web application/server needing Stanford user authentication will need to be able to support three main items:

  • Use of SSL with HTTPS for all authenticated interactions with the application.
  • Ability to limit what systems the HTTPS requests are accepted from.
  • Ability to parse an HTTP header and use the parsed data to assert the identity of the user within the application.

All HTTP transactions with that application will go through the WebAuth proxy service instead of directly to the application server. Using proxying, the WebAuth proxy service will then forward the URL request to the actual web application service adding in an additional HTTP header to the request. This header (Webauthproxy) will contain a data string with colon-delimited fields, always including in the first field the authenticated user's SUNet ID. Additional directory, host, and timestamp information can be included, depending upon the needs of the application. The web application service will need to ensure that it is only accepting requests from those systems identified as part of the Stanford WebAuth proxy service and, it will need to parse the Webauthproxy HTTP header and use that data for authentication and user identification purposes.

A general proxy example

Many vendor applications support an external callback or callout to establish the identity of a user. For this sort of application, a developer will need to modify all of its ASPs, JSPs, servlets, or similar pages that are directly accessible by a user to use the data provided in the HTTP header.

For a Java application, this process would look like:

  • Check for the existence of a SUNetID in the HttpSession object.
  • If the HttpSession has not been created, then parse the Webauthproxy HTTP header from the HttpServletRequest object and create the HttpSession object with the parsed SUNetID.
  • If no SUNetID is found in the HttpSession, invalidate the HttpSession object. Then parse the Webauthproxy HTTP header from the HttpServletRequest object and create a new HttpSession object with the parsed SUNetID.
  • If no SUNetID is found in the Webauthproxy HTTP header, invalidate the HttpSession object and return an error page.

A specific proxy example

The user torg opens his web browser and goes to the application in question. The URL for the application actually goes to the WebAuth proxy server, so this user is first redirected to the weblogin server. He logs in with his username and password over SSL, and is then sent back to the proxy server. The proxy server extracts his identity and then proxies the request to the application server, adding the header:

Webauthproxy: :torg:

to the HTTP request.

The application server notices that it has no session already set for this user, and therefore needs to parse the Webauthproxy header. It extracts the authenticated identity, torg, and stores that in its local session, returning the first page (which likely sets a session cookie with that information).

From this point on, user torg uses the application as normal, and since the session information containing the authenticated identity is retained from page visit to page visit, the application can use that information to validate whatever user torg wants to do. All these transactions actually go through the WebAuth proxy server, which just passes the browser requests through to the application.

When user torg is done using this application, he closes his browser, which destroys both the session information from the application and all WebAuth credentials.

Certificates

The use of client-side certificates with SSL is something that Stanford would like to pursue but the management of these identities is still less than optimal and Stanford would like to tie these certificates to the existing centralized authentication services so that the more loosely-controllable certificates could be validated for shorter terms of service.

Stanford does have a central certificate purchasing service for web server certificates. See the SSL service pages for more information.

Last modified