Embedthis Appweb 4.3.4
Home > Users Guide >

Quick Nav

See Also

Authentication

Authentication is the process by which a client's identity and abilities are verified before granting access to server resources. Authentication is essential when you have content that you wish to protect and provide only to specific, approved clients.

Appweb implements a powerful and flexible authentication mechanism that supports Basic, Digest and Form authentication schemes. Appweb employs unified and flexible authentication front and back ends that can be mixed and matched to meet most authentication needs.

Authentication Schemes

Appweb provides several authentication schemes.

Basic and Digest authentication are HTTP protocol mechanisms defined by the HTTP/1.1 RFC2616 specification. Because they operate at the protocol level, they offer a low level of capability and flexibility. When a client attempts to access secured content, the client's browser displays a generic pop-up dialog box to prompt for the user's credentials. When submitted, the Appweb server consults the appropriate user password store to authenticate the user. While this scheme works, applications increasingly need to utilize an application-level user login mechanism that is more integrated into the overall look-and-feel of the application. Such login facilities are defined using web forms and HTTP POST requests from standard web page forms. Appweb calls this scheme the the Form-based authentication scheme.

Basic Authentication

Basic authentication was the original HTTP/1.0 authentication scheme. It transmits user names and passwords using a trivial encoding that is no better than using plain text.

SECURITY WARNING: You should not use Basic Authentication if at all possible. Use Digest Authentication instead if it is supported by your clients. If you must use Basic Authentication, use it over TLS/SSL which will encrypt the password over the wire.

Basic Authentication Directives

Appweb basic authentication is controlled by configuration file directives that may be used inside a Route or VirtualHost block, or within the Default server configuration.

<Route /private/>
    AuthType basic
    AuthRealm "example.com"
    User julie 9d8873a123eb506e7f8e84d1f2a26916 view
    Require user julie
</Route>

This example restricts access to URIs beginning with "/private". It permits access to the user "julie" once authenticated.

The AuthType directive specifies that basic authentication is being used. The AuthRealm directive specifies the realm of access to Appweb. The realm is used in combination with the username and password to encrypt the password. The AuthUserFile directive specifies the location of the user password file. You may use a single password file for all authentication, or you can use different files for each authentication section.

The User directive defines a user by name with an encrypted password and zero or more roles for the user. Typically, User and Role directives are placed in a separate configuration file called auth.conf and are included via an "include auth.conf" directive. To create passwords, see the section below that describes the authpass utility.

Require Directive

The Require directive controls access to the resources managed by the route. There are three possibilities to control access: require specific named users, require a secure protocol such as TLS/SSL to be used, and require that the authenticated user possess a set of specified abilities.

When using Require ability, the abilities may be roles defined via the Role directive, or they may be simple words which represent a discrete ability that is explicitly specified in the User directive.

The require secure directive specifies that the SSL/TLS protocol must be used for the request to permit access.

Note: These three require directive alternatives may be used in combination. However, multiple Require user or multiple Require ability directives are not supported. The last directive will take precedence.

SECURITY WARNING: it is essential that the authentication file be stored outside the Documents directory or any directory serving content.

Digest Authentication

The Digest authentication scheme is a modern replacement for the Basic authentication scheme. It uses cryptographic techniques to encode passwords and does not transmit sensitive information in clear-text.

Digest Authentication Directives

Appweb digest authentication is controlled by configuration file directives that may be used within any Route, VirtualHost block or within the Default server configuration.

<Route /private/>
    AuthType Digest
    AuthRealm "example.com"
    include auth.conf
    Require user peter
</Route>

This example restricts access to the "/private" directory and all sub-directories to users whose username and password are validated against the designated user.db password file. The essential differences between this example and the Basic Authentication example is the AuthType directive.

Form Authentication

The Form-based authentication scheme uses a standard web page form that prompts the user to enter their name and password. These values are then submitted to Appweb via a standard Http POST request. Appweb analyzes the user and password, and if authenticated, a login session is created and a cookie is returned to the users's browser. Subsequent requests that include the cookie will be automatically authenticated and served.

The AuthType form directive controls how Form authentication operates. The form variant of AuthType specifies the login web page, the login service URI, the logout service URI and the destination web page once authenticated. The format is: 

AuthType form Login-Page Login-Service Logout-Service Logged-In-Destination

For example:

<Route ^/>
    AuthType form /auth/login.html /auth/login /auth/logout /
</Route>

This directive enables Form authentication for all requests and will redirect the client browser to /auth/login.html to prompt for the username and password. This example uses a plain HTML web page, but the web page can be created in ESP, PHP, CGI or any other web framework. The web page should submit the username and password to the /auth/login login service. When logout is required, the client should submit a HTTP POST request to the logout service URI /auth/logout. The last field in the AuthType directive is the destination URI to which the client's browser will be redirected once logged in.

Login Service

The Login-Service is URI that is bound to an internal service to receive the username and password and authenticate the user. This service expects the username/password to be submitted via POST data using the form input fields "username" and "password". You can supply your own login and logout service by specifying the empty string "" for the Login-Service in the AuthType directive. If using your own Login Service, you should call httpLogin to validate the user against the configured password store.

Web Form

Here is a minimal example login form:

<html><head><title>login.html</title></head>
<body>
    <p>Please log in</p>
    <form name="details" method="post" action="/auth/login">
        Username <input type="text" name="username" value=''><br/>
        Password <input type="password" name="password" value=''><br/>
        <input type="submit" name="submit" value="OK">
    </form>
</body>
</html>

The two submitted fields must be named username and password.

If the login attempt succeeds, the client will receive a response including a session cookie and will be redirected to the Destination URI. If the destination URI includes a referrer: prefix and the login form request contained a referrer URI in the HTTP header, then that referrer URI will be used as the destination instead of the hard-wired destination.

Securing the Password

SECURITY WARNING: The Form authentication mechanism submits the user password as plain text. To secure communications, the Form authentication scheme should be used over a secure connection using TLS/SSL. To achieve this, you should create a route which redirects the client to the secure login form. For example: 

Listen 443
<VirtualHost *:443>
    SSLEngine on openssl
    # More SSL directives if required
    AuthType form /login.html /login /logout referrer:/index.html
</VirtualHost>
<Route ^/>
    AuthType form https://example.com/login.html
</Route>

Password Stores

Appweb can retrieve passwords from the default system password database or from a text password configuration file. Selection of the password store is controlled by the AuthStore directive. For example:

AuthStore system
This selects the Unix system PAM password database. 
AuthStore file
User julie 9d8873a123eb506e7f8e84d1f2a26916 view

The Unix system password database is managed via the PAM interface. The Windows ActiveDirectory password store is not currently supported.

The AuthStore file option specifies that passwords will be defined by the User directive and will be stored internally in Appweb. The default password store for Appweb is "file". Typically, User directives are kept in a separate passwords are stored in a separate configuration file that is included from the appweb.conf master configuration file.

include auth.conf

Password Program

The authpass program supports the internal AuthStore and is used to create user passwords in an authentication file. Appweb uses the same authentication file and format for Basic, Digest and Form authentication types. This simplifies administration. The file simply contains User and Role directives and may be edited by hand if desired.

#
#   auth.conf - Authentication data
#
Role administrator view
Role executive manage direct
Role user view
User julie 9d8873a123eb506e7f8e84d1f2a26916 user
User peter 7cdba57892649fd95a540683fdf8fba6 user
User joshua 2fd6e47ff9bb70c0465fd2f5c8e5305e user administrator purchase
User mary 5b90553bea8ba3686f4239d62801f0f3 user executive

The authpass program will create and modify User directives in the authentication file.

The command line syntax for authpass is:

authpass [-c] [-p passWord] authFile realm username roles...

The authFile parameter specifies the name of the authentication file. If the -p password option is not used, authpass will prompt for the password. The -c option will cause authpass to create the authentication file if it does not already exist. Otherwise it will update the nominated file.

The Realm is the name used in the AuthRealm directive.

SECURITY WARNING: it is essential that the authentication file be stored outside the Documents directory or any directory serving content.

© Embedthis Software LLC, 2003-2013. All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.