How the Authentication Works

This cartridge will log into an Oracle database in one of two ways:

As you are accustomed to OWA logging in, using the username/password in the DCD found in the OWA.CFG file
Using the username/password supplied by the end user (the client) via BASIC authentication

The method of logging in used by this cartridge is controlled on a DCD by DCD basis. In the svXXXX.app file, you will have a section called [DBAUTH]. In this section, you may list DCD's that you want to use BASIC AUTHENTICATION with. For example, given the following DBAUTH section in a svXXXX.app file:

	[DBAUTH]
	owa.cfg            = /usr/oracle/ows2/admin/owa.cfg
	server.cfg         = /usr/oracle/ows2/admin/svdbaut2.cfg
	authenticate	   = ows-bin  owa_dba
	web_authent_prefix = web$
	dirSeparator       = /

We can see that

Any request using the ows-bin or owa_dba DCD will require a username/password from the client to log in. We will NOT use the username/password found in the owa.cfg file. In fact, the password may be removed from this file (but keep the username there, we still need that).
Any request serviced by this cartridge that is not using the ows-bin or owa_dba DCD will get the username and password from the owa.cfg file and not require the user to enter one.
The web_authent_prefix variable will tell us to add the prefix 'WEB$' to the front of a user name. If a client supplies us with SCOTT/TIGER, we will log in using WEB$SCOTT/TIGER. web_authent_prefix is analogous to an 'OPS$' style prefix. We implemented this to keep our web users separate from our other users. You do not need to set a web_authent_prefix. If you leave this not set, then SCOTT/TIGER will be used.
The file /usr/oracle/ows2/admin/owa.cfg will be read to figure out
- ORACLE_HOME
- ORACLE_SID
- SQL*Net 2.0 Connect String
- Password (if needed)
- Username (if needed)
- Valid Ports (ports that are allowed to run a specified DCD request)
- Log Directory (where errors are written to)
- Error Page (the error page to return upon unsuccessful completion)

This authentication mechanism, logging users in using their own username/password, is really quite simple. Using WebServer 2.0.3 and up, we can supply a replacement routine for doing Basic Authentication. This routine is called immediately before the routine that produces the page and returns either TRUE or FALSE signifying success (yes, this client can get this page) or failure (deny access to this page, put up the 'Authorization Failed' dialog).

When our cartridge is started up, it will process the contents of the svXXXX.cfg (to discover valid mime types and the like), svXXXX.app (to get the DBAUTH section), and the owa.cfg file. Using the information from the DBAUTH section of the svXXXX.app, we can determine what DCD's will require a username/password and which ones won't.

Every time a request comes into our cartrige, we determine from the URL what the DCD name is. The general form of any OWA URL is:

	http://YourHost/X/Y/Z/DCDName/owa/ProcedureName
	eg:
	http://aria.us.oracle.com/wa/ows-bin/owa/owa_util.print_cgi_env

where

/X/Y/Z is an optional virtual path you can put on front of a DCD when mapping it. It is not generally used but we support it. For example, I use /wa and mapped /wa to the DBAUTH cartridge. I no longer make an entry for each and every DCD I configure. As soon as a DCD is created, it is accessible via /wa/DCDName/....
DCDName is the name of a Database Connection Description you have set up in the owa.cfg file. Also known as the 'web agent' name. For example, ows-bin is the DCD Name in the above.
owa is a constant. It must be there and separates the DCDName from the stored procedure name.
ProcedureName is the name of a procedure/package.procedure, optionally qualified with a schema name.

The same is true of this cartridge with the following exceptions:

owa is not constant. It can be any one of
- owa
- owai
- owaup
- owassi
The meaning and purpose of each of these is explained in how URLS are resolved.
ProcedureName need not be a procedure name. For example, using this cartridge the URL
```
	http://aria.us.oracle.com/wa/ows-bin/owa/x/y/z/index.html
```
is a valid URL that can return a page. It would be using our version of Database Server Side Includes. The assumption would be that
```
	http://aria.us.oracle.com/x/y/z/index.html
```
would map to some physical file and would return such a file. Our Web Agent replacement will find the same file, look for <ORACLE> tags in it and preprocess it, inserting the output of pl/sql blocks into it.

Using the last note above, we can see how to protect files and not just database procedures using this mechanism. If you have authentication enabled for the ows-bin DCD and you have a virtual directory mapped to some files (for example /x/y/z -> /usr/oracle/docs) you can use database authentication to protect the files in /x/y/z. That is, a user (client) will have to supply a valid Oracle Username/Password to gain access to the files in the virtual directory /x/y/z. You can do this simply by

Enabling any for of authentication in the web listener for the /x/y/z virtual directory and making it such that no one can access http://yourHost/x/y/z (eg: Use IP restrictions and put in 0.0.0.0 for the IP or use domain restrictions and put in no.such.domain.exists.anywhere. That will make /x/y/z inaccessible via the listener).
Next, make sure the authenticate string contains ows-bin in the DBAUTH section of your svXXXX.app file

Lastly, refer to anything in /x/y/z using:

	http://YourHost/ows-bin/owa/x/y/z/document.name
	for example
	http://YourHost/ows-bin/owa/x/y/z/sensitive.pdf

That will force your client to supply a valid Oracle username/password to get the file sensitive.pdf (and since the file sensitive.pdf does not have a mime type of text/html, the cartridge will simply send it back, it will not attempt to pre-process it).

See Database Server Side Includes. For more info on this capability.

Logging Off

In order to understand how we 'logoff', it is useful to understand how Basic Authentication works in the first place. This is not a basic question actually, it's pretty complex. Lets start with a freshly loaded browser. Lets say at site1, the url /foo/ is protected via basic authentication. Then......

you enter http://site1/foo/hello.html in the browser. This will cause a GET request to be submitted to the webserver at site1. This will request will look something like:
```
----------------------------------------- 
GET /foo/hello.html  HTTP/1.0 
 
----------------------------------------- 
```

The webserver gets the request. It determines that it needs a userid and password for this document. It does not see one in the request above (just a GET so far). It will return a document such as:

 
------------------------------------------- 
Content-Type: text/html 
Status: 401 Unauthorized 
WWW-Authenticate: Basic realm="SomeRealmName" 
 
This document is protected. You must send the proper authorization information 
to access it.  
-------------------------------------------

The browser gets back that document and views the header. it sees the 401 Unauthorized and looks for the WWW-Authenticate line to get the realm. It looks in its little list of REALM=user/passwords it caches in memory (empty right now, we just started the browser). Therefore, it prompts you for the username/password for the realm "SomeRealmName". If you hit cancel right now, it just displays the document (which is "This document is protected. You must send the proper authorization information to access it. ", you've probably seen that before). If you put in a username/pass the browser (MOST browsers anyway) will save the username/password in a list that contains the
- realm name
- host name requesting the user/pass
- port the web server was running on on that host
The browser then submits a request that looks something like:
```
------------------------------------- 
GET /foo/hello.html HTTP/1.0 
Username: scott:tiger 
 
------------------------------------------------- 
```
(the username: part is wrong, I forget what the client puts there but the point is made... some other word then username goes there)
the webserver recieves this new request, sees foo needs basic auth, sees the user/pass in the header, verifies it. If the username/password don't match, goto 2 and start over. If it does match the page /foo/hello.html is returned. Assumed it matched.
I now goto http://site2/something/else.html

I now goto http://site1/foo/another_page.html. The GET request goes up, the webserver rejects with:

-------------------------------------------                                   
Content-Type: text/html                                                       
Status: 401 Unauthorized                                                      
WWW-Authenticate: Basic realm="SomeRealmName"                                 
                                                                              
This document is protected. You must send the proper authorization information 
to access it.                                                                 
-------------------------------------------

the browser will take the hostname/portno/someRealmName and look in its little in memory cache. this time it will find it since we just did it a couple of pages ago. It will resend the request with the username and password and we get our page.....

In short, the browser remembers your password for you. It associates a username/passowrd with a HOST, PORT, and REALM. The webserver asks the browser for this information by rejecting the request.....

This brings us now to, how do you log off. What we need to do is trick the browser into remembering a 'bad' username/password pair for a given Realm/Host/Port. We do this in the cartridge (or cgi-bin) application by recognizing a special URL, 'LogMeOff'. In order to log off you will:

	http://YourHost:YourPort/YourDCDName/owa/LogMeOff

This will alway cause the cartridge to fail authentication (unless the magic username is used). It will not attempt to log in or do anything in the database, it will just fail the authentication.

This will cause the browser to pop up the basic authentication dialog. No matter what combination of username/password you put in, it will fail at this point (unless the magic username is used). In order to complete the 'logout', you would enter "bye" in the username field. This will cause the cartridge to signal success on the authorization and send back a static page to the web browser. This page simply states "You are de-authenticated". The next time you visit a regular page, you will be prompted for a username/password since the username 'bye' is not a valid username for the page.

This implies 2 things:

You can never have a procedure/page called "LogMeOff"
You should never have a database user named "Bye"

Changing Password

In the file owarepl/sql/owarepl.sql, there exists a package called "Change_Password". This package allows any existing user to change their password in the database immediately. This is accomplished with the dbms_sql package issueing an "alter user USERNAME identified by PASSWORD" command.

The owner of this package needs the 'ALTER USER' privilige. They need this privilige granted directly to them. They cannot get this privilige via a role.

The simplest way to use this package is to:

	http://YourHost:YourPort/YourDCDName/owa/change_password.show_form

This will generate a form that looks like:

Changing Password for user tkyte

New Password	Confirm Password

This form will ONLY appear if the current web agent (YourDCDName) is using database Authentication. If it is not, the user will get an error message.

You should review the code for change_password to ensure you are comfortable with it.