FOR ARCHIVAL PURPOSES ONLY The following instructions apply to using Websec to authenticate for web applications. Websec was retired in December 2009 and replaced by a new authentication system, Penn Weblogin.

Customizing your application's authentication/login pages

• The application provider has the ability to customize the authentication pages to have the look and feel of all the other pages in the application.
• It eliminates the intermediate success page that is normally generated by the generic screens once a user has successfully authenticated.

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 page

For successful operation, the following form variables MUST be defined on the authentication/login screen:

1. pennnet_id - a text field to be filled in by the user
2. pennnet_password - a text field to be filled in by the user
3. ctime - A hidden field -- by placing $ISC_WEBSEC_CTIME as the value for this field, the Websec module will place the correct ctime in its place when it serves up the document to the screen
4. websec_app - A hidden field, specified by the application developer. This value is the name of the application as it has been registered.
5. rand_string - A hidden field -- by placing $ISC_RAND_STRING as the value for this field, the Websec module will place a random string value in its place when it serves up the document to the screen. Adds an element of randomness)
6. websec_page - A hidden field that is used only by applications that are using the Apache/Websec module -- by placing $WEBSEC_REQUESTED_PAGE as the value for this field, the process will automatically substitute this variable with the URL that was originally requested. This is needed for the next stage, so that the process knows where to redirect the user after successful authentication.

Additionally, you can pass arguments to your application by including a hidden input field in your login page.

Failed login page

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).

<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.

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.

Example of a starting page
Example of a starting page for an application using the Apache/Websec module

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 :
%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%

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  130.91.12.11

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.