~inc:header.inc~

Authentication

Many applications need to restrict access to authorized users. The HTTP server supports Basic HTTP Authentication to provide this functionality.

The HTTP server makes two calls to the HTTPAuthenticate() API during each request. The first occurs immediately after the file name is parsed. The filename parameter will contain the full filename currently being requested, but the other parameters will both be set to NULL. At this point, your application must decide whether or not authentication is required. Return a value of 0x80 or greater to allow access unconditionally. Return 0x79 or lower to require authorization.

The second call to HTTPAuthenticate occurs when an Authorization: header is encountered in the client's request. This call will have the user and pass pointers defined. At this stage, your application should return a value greater than 0x80 to permit access, or a value less than 0x79 to reject the password supplied. It is important to note that the filename parameter will not be defined during this call.

As an example, access this restricted page:

User Name: admin       Password: microchip
Access Restricted Page

Most applications will use only two values: one value to permit access and one to deny. For more sophisticated user access control, multiple values are supported. An application could set different values between 0x00 and 0x79 to indicate which page was requested. When the second call to HTTPAuthenticate is made, the application can base its decision on the value of curHTTP.isAuthorized (which holds the value returned from the previous call. Once authorization passes, setting curHTTP.isAuthorized to various values above 0x80 will allow later callbacks to HTTPPrint_*() to know which user was authenticated. While largely unnecessary for most applications, this additional flexibility can allow much more sophisticated user access control systems.

~inc:footer.inc~