WebISO: Web Application Agent (WAA) Questionnaire Webauth Duke University Prepared by Karsten Huneycutt, 2003-01-08 1. Model & Capabilities of the Web Authentication Agent (WAA) 1.1 Which high-level integration model(s) does your WAA support? [x] Server module [x] Apache 1.3 [x] Apache 2.0 [x] Java Servlet (Tomcat 4.x -- user-contributed) [ ] Microsoft ISAPI [ ] Other [x] Developer's API [x] C/C++ [x] Java/JSP [x] Perl [x] Python (in progress -- user-contributed) [x] Other (PHP) 1.2 If applicable, describe the method(s) your WebISO solution provides for the WAA to handle N-tier (proxied, delegated) authentication (cf http://middleware.internet2.edu/webiso/docs/draft-lajoie- trust_and_delegation-02.html): Several of the 'additional information' items the application (this is available only in the API) available are Kerberos credentials valid from the addresses requested by the application. This allows the application to proxy-authenticate to any service that allows authentication via Kerberos credentials. In addition, it is possible to add any other data item for any other authentication mechanism, as long as it's available from the username/password the user entered for authentication. See 3.1.3. 2. Authentication Request 2.1 Describe the API your WAA provides to Web applications to initiate authentication. What functions can it invoke? What parameters can it pass? The API is relatively simple. At the beginning, there's a call to parse a configuration file (and a corresponding ending cleanup call). After that, the application creates a request object for authentication given a specific authentication mechanism, adds any number of data requests (optionally with arguments), requests additional authentication mechanisms be tried, and then "processes" the request in one of two ways: use the template provided in the file to redirect the user, or request the URL to which the user should be redirected to perform authentication in that manner. See for the header file that defines the C API. 2.2 Describe any other options your WAA provides to Web applications to influence the authentication process. For example, can it request the technology or policy used to handle authentication? The application can request that authentication be performed in any way supported by the server, in a queue. One authentication mechanism is required; the sky is the upper limit, though practically, the server only supports three authentication mechanisms at the moment. 3. Authentication Delivery 3.1 Describe the information delivered by your WAA to Web applications: 3.1.1 What user information is provided to the application? What is the format? How does it relate to the identifier presented to the verification backend? The user name is the only thing always provided on successful authentication. The application requests it with a function call, and it's returned in simple string format, with no realm qualifiers (at the moment; this could change in future versions). It is the same as the identifier presented to the verification backend; if a user enters "kph" as his username and the correct password for the principal kph in the default realm, the application currently gets back "kph". We haven't had a demand for multi-realm authentication, so it hasn't been added, though it wouldn't be hard. 3.1.2 Does the WAA deliver additional user attributes (e.g., lookup key value associated with login identifier, studentid, group membership)? What is the format of this? It can. They're delivered as data items to applications that are allowed to have the information and which request the information. See 3.1.3. 3.1.3 Can additional information be delivered on request? Yes. Anything at all that the server knows how to retrieve. Access control is per-application per-data-item. (IE, webmail is allowed to access mail service credentials but not the Duke Unique ID; the online residential services bill application is exactly the opposite). The data is returned in the "encrypted data" section of the authentication token, encrypted in an authentication mechanism-specific fashion. 3.2 Describe the means by which your WAA provides authentication information to your application. Please be as specific as possible. The Apache modules set $REMOTE_USER, and nothing else (no data items are available when using the Apache module). The Tomcat valve sets the Tomcat server's idea of what the authenticated user is. Individual applications using the API retrieve the token in a way specific to how they requested it be returned, using their language's functions for accessing GET/POST arguments or cookies, and then hand the cookie off to the webauth library, using (after the same configuration initialization routines as in the request) a decode/verify function that returns the authentication status. Then, there are functions for returning the authenticated user, the authentication mechanism, the authentication status, and any data items returned. 4 Authentication Session 4.1 Briefly describe how authentication session information is maintained (if not already covered in section 2 above): For the most part, the application author is expected to do this himself, using his language's functions. Instead of attempting to maintain two separate sessions, using a Servlet/JSP/PHP/Perl session handling library for one and webauth for another, it seemed more logical to let the library handle management of the session in its entirity. It simplifies the webauth library, and it simplifies the logout procedures. However, the apache module does not do this, and just uses the authentication token as the session identifier. It is returned to the apache module via a GET argument that is "magical" and which is consumed by the module. The module then sets a locally-scoped cookie with the value of the GET argument. By doing this in this fashion, one avoids the "scoped to the entire domain" cookie problem. Cookies have a built-in issue time; there are no idle timeouts. Each application specifies the time from issue to expiry, and cookies become "invalid" after this, whether they're used for session management or not. 4.2 Is it possible to for an application to set the session duration? If not already covered above, please describe: For the apache module, the session expires at the same time the cookie becomes invalid. Otherwise, the session duration is independent of webauth 4.3 Is it possible to terminate authentication session globally? How is that information conveyed to the application? Not at the moment, unfortunately. One can sign out of the "single-sign-on", and one can sign out of each application, but global logout hasn't yet been implemented. 5. Messaging (Weblogin Service (WLS) <-> WAA) 5.1 Describe the message format used between your WAA and weblogin service to request and receive authentication information: The arguments from the WAA to the WLS to request authentication are passed in a single GET request (though a POST request would also be supported; the authentication pages use POST to protect password privacy). There are a standard set of arguments in a standard format; invalid arguments are ignored, and invalid values produce an error. A sample authentication request string would be: https://webauth.duke.edu/cgi-bin/ webauth?authmech=1&lifetime=600&retmech=2&service=test&host=verloren%2eo it%2eduke%2eedu&redir=http%3a%2f%2fverloren%2eoit%2eduke%2eedu%2fcgi%2db in%2fwatest&datarequest=AAAABGZ1bGxuYW1lAAAAAAAAAAAARFVJRAAAAAAAAAAAAG1h aWxfc2VydmljZV90aWNrZXQAAAAAAmltYXAAMTUyLjMuMjAyLjExOAAAAAAAYWZzX3NlcnZp Y2VfdGlja2V0AAAAAAExNTIuMy4yMDIuMTE4AAAAAAAAAAAAAAAA&return=cookie The authentication token itself is returned in one of three ways, as requested by the client: 1) cookie (scoped to .duke.edu). This is deprecated! 2) GET argument, specified in the configuration. 3) POST argument, specified in the configuration. It is of the following format, regardless of the return mechanism: int32_t: authentication mechanism int32_t: authentication data length authentication data of length specified above int32_t: encrypted data length encrypted data of length specified above. Each authentication mechanism specifies the format of the authentication data and the encrypted data, and each authentication mechanism is responsible for integrity checking and expiration of the cookie. The most commonly used authentication mechanism, Kerberos, uses the encrypted portion of a service credential for the specific service and host as the authentication data (which has, internally, an issue time), and the data is encrypted in the session key of that service credential. 5.2 Describe the protocol used by the WAA to handle the above (e.g. SAML POST Profile): Simple redirections for cookie/GET; for POST, it's an auto-submit form. 6. Wish List 6.1 What changes or additions to the services provided by the WAA would you like to see in your system? Currently, data items are keyed on a string, and only one instance of that data item is ever returned. This is less flexible than it could be; for example, an application authorized to request a service credential for ANY service/host pair in the realm can only request one of these, instead of multiple different ones. To get around this, and to provide finer-grained access control, we have defined separate data item types for each credential, but it might be nice to allow that sort of thing. Authentication mechanisms are statically linked into the server and the client. This should change. 6.2 At a high level, what other changes would you like to see in your system? There isn't a Windows version, yet. The next version is slated to be based on APR, so it should be trivial to get a highly-portable server and client.