Customizing your application's authentication/login pagesWhen registering your Websec application with ISC, you must indicate that you will be taking advantage of the custom login screens option. Once registered, the flow of control for applications which use customized login screens is similar to those which do not use the customized login screens, except that the application provider provides the actual login, success, and failed login screens. The advantages are:
All custom login screens are located on the application provider's non-SSL webserver. The Websec module retrieves and serves these pages on its SSL webserver. The login and failed login screens are static HTML documents. The successful login, or first screen of the application, can either be a static HTML document or a POST/CGI script; you must specify which when registering your application.
Authentication/login pageThis is the page where users will type in the PennNet ID and password.
For successful operation, the following form variables MUST be defined on the authentication/login screen:
Additionally, you can pass arguments to your application by including a hidden input field in your login page.Example of a login page
Example of a login page for an application using the Apache/Websec module
Failed login pageThis is the page explaining that the user authentication failed. The possible reasons for this is either that the username/password pair is incorrect, or that the formed timed out before the user finished entering his or her PennNet ID and Password.
No variables must be defined for the failed login screen. If you wish to provide a link back to the login page, it is a good idea to call the login page with an additional argument, unique argument (the CTIME, as defined by $ISC_WEBSEC_CTIME, is a good way to do so).If using the Apache/Websec module and if you wish to provide a link back to the login page, be sure to include the 'websec_page', $WEBSEC_REQUESTED_PAGE, as an argument, or the process will not know where to direct the user's browser after authentication. For example:
<a href="https://rosetta.upenn.edu/cgi-bin/websec/websec_authform?app=app_name&requested_page=$WEBSEC_REQUESTED_PAGE">Return to the login page</a> to try again.
Example of a failed login page
Example of a failed login page for an application using the Apache/Websec module
First page of the application
If the first page of the application after successful authentication is a static HTML document, the provider should define a hidden field where the Websec token is placed. This way, the application can check the validity of the token at the next page of the application. The hidden field must contain the value $ISC_WEBSEC_TOKEN. When the Websec module serves up the page, the token will replace this variable.
If the first page of the application after successful authentication is a POST/CGI script running on the application provider's webserver, the Websec module will pass the application provider's CGI script the websec_token via its standard input (as any other POST/CGI program would be executed). The CGI script should then query for information about that token from the Websec module to verify that the user has authenticated.
If using the Apache/Websec module, this is a static HTML page that
will typically provide a link back to the originally requested page. Again, this is what the
$WEBSEC_REQUESTED_PAGE value will be used for. It is suggested, for ease of use for
the user, that the page automatically redirect the browser back to the originating page.
Encryption between the Websec client and server
Note that all messages between the Websec server and the Websec client are encrypted. However, for applications which utilize custom screens AND the first page of the application is a CGI script which is invoked by the Websec server, the default behavior is to NOT encrypt the 'websec_token' as it is passed to the CGI script. Therefore, it is possible that somebody eavesdropping on the line could extract the token and use it to gain access to the application.
To remedy this problem, the application administrator should contact ISC and ask that Websec server encrypt the 'websec_token' when invoking the application's first page. This is a special option in the registration of your application. Once this has been taken care of, you may modify the application's CGI script to handle the decryption.
Once the application registration change has been made, the websec client also has the ability to decrypt encrypted strings that are passed to the application CGI script from the Websec module. The commands 'decrypt_and_query' and 'decrypt_and_expire' can be used to first decrypt the incoming query string and then communicate with the Websec server to 'query_token' or 'expire_token'. For example, a typical usage would be as follows:
Encrypted query_string passed to application's CGI script may be :
Therefore, the command to the Websec client would be:
% websec_client application_name decrypt_and_query %EF%1B%3F%A5%C1%E7%C3%F6F%0E%9D%9B%0D%F5%18%1B3%80%18O%A4NJy%94*%A35%06%C8%3%80%18O%A4NJy%94*%A35%06%C8%%EF%1B%3F%A5%C1%E7%C3%F6F%0E%9D%9B%0D%F5%18%1B3%80%18O%A4NJy%94*%A35%06%C8%3%80%18O%A4NJy%94*%A35%06%C8%
Note that the encrypted query string is passed to the Websec client via its standard input. (Note that while all other commands allow its final arguments to be passed via the command line and standard input, the decrypt commands require that the final arguments be passed via standard input.) The output from the Websec client would first return the decrypted string, and then it would return the results from the 'query_token' or 'expire_token'.
Decrypted Result websec_token=dd662e77fcbddec6c965888303e8038f3 203-PennNet ID nss 203-9-digit PennID 123456433 203-Timestamp 907354005 203 IP Address 188.8.131.52
In the above example, the decrypted result is the URL query string passed to the CGI script. The CGI script must still perform URL decoding and other processing, such as stripping out malicious characters.
Information Systems and Computing
University of Pennsylvania
Comments & Questions