312 lines
19 KiB
HTML
312 lines
19 KiB
HTML
|
<!-- BeginDsi "dsi/head.html" -->
|
||
|
|
<!DOCTYPE html>
|
||
|
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>Embedthis Appweb 4.3.4 Documentation</title>
|
||
|
|
<meta name="keywords" content="embedded web server, web server software, embedded HTTP, application web server,
|
||
|
|
embedded server, small web server, HTTP server, library web server, library HTTP, HTTP library" />
|
||
|
|
<meta name="description" content="Embedthis Sofware provides commercial and open source embedded web servers for
|
||
|
|
devices and applications." />
|
||
|
|
<meta name="robots" content="index,follow" />
|
||
|
|
<link href="../../../doc.css" rel="stylesheet" type="text/css" />
|
||
|
|
<link href="../../../print.css" rel="stylesheet" type="text/css" media="print"/>
|
||
|
|
<!--[if IE]>
|
||
|
|
<link href="../../../iehacks.css" rel="stylesheet" type="text/css" />
|
||
|
|
<![endif]-->
|
||
|
|
<link href="http://www.google.com/cse/style/look/default.css" type="text/css" rel="stylesheet" />
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
<div class="top">
|
||
|
|
<a class="logo" href="http://appwebserver.org/"> </a>
|
||
|
|
<div class="topRight">
|
||
|
|
<div class="search">
|
||
|
|
<div id="cse-search-form"></div>
|
||
|
|
<div class="version">Embedthis Appweb 4.3.4</div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="crumbs">
|
||
|
|
<a href="../../../index.html">Home</a>
|
||
|
|
<!-- EndDsi -->
|
||
|
|
> <a href="index.html">Users Guide</a> > <b>
|
||
|
|
|
||
|
|
</b>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="content">
|
||
|
|
<div class="contentRight">
|
||
|
|
<h1>Quick Nav</h1>
|
||
|
|
<ul class="nav">
|
||
|
|
<li><a href="#basicAuthentication">Basic Authentication</a></li>
|
||
|
|
<li><a href="#digestAuthentication">Digest Authentication</a></li>
|
||
|
|
</ul>
|
||
|
|
<!-- BeginDsi "dsi/usersGuideSeeAlso.html" -->
|
||
|
|
<h1>See Also</h1>
|
||
|
|
<ul class="nav">
|
||
|
|
<li><a href="../../../guide/appweb/users/index.html">User Guide Overview</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/configuration.html">Configuring Appweb</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/ports.html">Ports and Binding</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/lang.html">Multi-Language Support</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/authentication.html">User Authorization</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/logFiles.html">Log Files</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/vhosts.html">Virtual Hosts</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/security.html">Security Considerations</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/ssl.html">SSL</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/modules.html">Appweb Modules</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/stages.html">Pipeline Stages</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/client.html">HTTP Client</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/webSockets.html">WebSockets</a></li>
|
||
|
|
<li><a href="../../../guide/appweb/users/frameworks.html">Web Frameworks</a></li>
|
||
|
|
<li><a href="../../../ref/appweb/architecture.html">Appweb Architecture</a></li>
|
||
|
|
</ul>
|
||
|
|
<!-- EndDsi -->
|
||
|
|
</div>
|
||
|
|
<div class="contentLeft">
|
||
|
|
<h1>Authentication</h1>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<a id="basicAuthentication"></a>
|
||
|
|
<h2>Authentication Schemes</h2>
|
||
|
|
<p>Appweb provides several authentication schemes.
|
||
|
|
<ul>
|
||
|
|
<li>Basic Authentication</li>
|
||
|
|
<li>Digest Authentication</li>
|
||
|
|
<li>Form Authentication</li>
|
||
|
|
<li>Custom via API</li>
|
||
|
|
</ul>
|
||
|
|
<p>Basic and Digest authentication are HTTP protocol mechanisms defined by the <a href=
|
||
|
|
"http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP/1.1 RFC2616</a> 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.</p>
|
||
|
|
<h2 class="section">Basic Authentication</h2>
|
||
|
|
<p>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.</p>
|
||
|
|
<p><b>SECURITY WARNING</b>: 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.</p>
|
||
|
|
<h2>Basic Authentication Directives</h2>
|
||
|
|
<p>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.</p>
|
||
|
|
<pre>
|
||
|
|
<Route /private/>
|
||
|
|
<b>AuthType basic</b>
|
||
|
|
AuthRealm "example.com"
|
||
|
|
User julie 9d8873a123eb506e7f8e84d1f2a26916 view
|
||
|
|
Require user julie
|
||
|
|
</Route>
|
||
|
|
</pre>
|
||
|
|
<p>This example restricts access to URIs beginning with "/private". It permits access to the user
|
||
|
|
"julie" once authenticated.</p>
|
||
|
|
<p>The <a href="dir/auth.html#authType">AuthType</a> directive specifies that basic authentication is being
|
||
|
|
used. The <a href="dir/auth.html#authName">AuthRealm</a> directive specifies the realm of access to Appweb.
|
||
|
|
The realm is used in combination with the username and password to encrypt the password.
|
||
|
|
The <a href="dir/auth.html#User">AuthUserFile</a> 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.</p>
|
||
|
|
<p>The <a href="dir/auth.html#user">User</a> 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 <em>auth.conf</em> and are included via an <em>"include auth.conf"</em> directive.
|
||
|
|
To create passwords, see the section
|
||
|
|
below that describes the <a href="#authpass">authpass</a> utility.</p>
|
||
|
|
<h3>Require Directive</h3>
|
||
|
|
<p>The <a href="dir/auth.html#require">Require</a> 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. </p>
|
||
|
|
<ul>
|
||
|
|
<li>Require user username ...</li>
|
||
|
|
<li>Require ability name...</li>
|
||
|
|
<li>Require secure</li>
|
||
|
|
</ul>
|
||
|
|
<p>When using <em>Require ability</em>, the abilities may be roles defined via the
|
||
|
|
<a href="dir/auth.html#role">Role</a> directive, or they may be simple words which represent a discrete
|
||
|
|
ability that is explicitly specified in the <a href="dir/auth.html#user">User</a> directive.
|
||
|
|
<p>The <em>require secure</em> directive specifies that the SSL/TLS protocol must be used for the
|
||
|
|
request to permit access.</p>
|
||
|
|
<p>Note: These three require directive alternatives may be used in combination. However, multiple
|
||
|
|
<em>Require user</em> or multiple <em>Require ability</em> directives are not supported. The last
|
||
|
|
directive will take precedence.</p>
|
||
|
|
<p><b>SECURITY WARNING</b>: it is essential that the authentication file be stored outside
|
||
|
|
the Documents directory or any directory serving content.</p>
|
||
|
|
|
||
|
|
<a id="digestAuthentication"></a>
|
||
|
|
<h2 class="section">Digest Authentication</h2>
|
||
|
|
<p>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.</p>
|
||
|
|
<h2>Digest Authentication Directives</h2>
|
||
|
|
<p>Appweb digest authentication is controlled by configuration file directives that may be used within any
|
||
|
|
Route, VirtualHost block or within the Default server configuration.</p>
|
||
|
|
<pre>
|
||
|
|
<Route /private/>
|
||
|
|
<b>AuthType Digest</b>
|
||
|
|
AuthRealm "example.com"
|
||
|
|
include auth.conf
|
||
|
|
Require user peter
|
||
|
|
</Route>
|
||
|
|
</pre>
|
||
|
|
<p>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.</p><a id="auth"></a>
|
||
|
|
<a id="formAuthentication"></a>
|
||
|
|
<h2 class="section">Form Authentication</h2>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>The <a href="dir/auth.html#authType">AuthType form</a> 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:
|
||
|
|
<pre>AuthType form Login-Page Login-Service Logout-Service Logged-In-Destination</pre>
|
||
|
|
<p>For example:</p>
|
||
|
|
<pre>
|
||
|
|
<Route ^/>
|
||
|
|
<b>AuthType form /auth/login.html /auth/login /auth/logout /</b>
|
||
|
|
</Route>
|
||
|
|
</pre>
|
||
|
|
<p>This directive enables Form authentication for all requests and will redirect the client browser to
|
||
|
|
<em>/auth/login.html</em> 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 <em>/auth/login</em> login service. When logout is required, the client should submit
|
||
|
|
a HTTP POST request to the logout service URI <em>/auth/logout</em>. The last field in the AuthType
|
||
|
|
directive is the destination URI to which the client's browser will be redirected once logged in. </p>
|
||
|
|
<h3>Login Service</h3>
|
||
|
|
<p>The Login-Service is URI that is bound to an internal service to receive the <em>username</em> and
|
||
|
|
<em>password</em> 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 <em>""</em> for the Login-Service in the AuthType directive.
|
||
|
|
If using your own Login Service, you should call <em>httpLogin</em> to validate the user against the
|
||
|
|
configured password store.</p>
|
||
|
|
|
||
|
|
<h3>Web Form</h3>
|
||
|
|
<p>Here is a minimal example login form:</p>
|
||
|
|
<pre>
|
||
|
|
<html><head><title>login.html</title></head>
|
||
|
|
<body>
|
||
|
|
<p>Please log in</p>
|
||
|
|
<form name="details" method="post" <b>action="/auth/login"</b>>
|
||
|
|
Username <input type="text" <b>name="username"</b> value=''><br/>
|
||
|
|
Password <input type="password" <b>name="password"</b> value=''><br/>
|
||
|
|
<input type="submit" name="submit" value="OK">
|
||
|
|
</form>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
</pre>
|
||
|
|
<p>The two submitted fields must be named <em>username</em> and <em>password</em>.
|
||
|
|
<p>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 <em>referrer:</em> 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.</p>
|
||
|
|
<h3>Securing the Password</h3>
|
||
|
|
<p><b>SECURITY WARNING:</b> 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: </p>
|
||
|
|
<pre>
|
||
|
|
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>
|
||
|
|
</pre>
|
||
|
|
<a id="authStores"></a>
|
||
|
|
<h2 class="section">Password Stores</h2>
|
||
|
|
<p>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 <a href="dir/auth.html#authStore">AuthStore</a>
|
||
|
|
directive. For example:</p>
|
||
|
|
<pre>
|
||
|
|
AuthStore system
|
||
|
|
</pre>
|
||
|
|
This selects the Unix system PAM password database.
|
||
|
|
<pre>
|
||
|
|
AuthStore file
|
||
|
|
User julie 9d8873a123eb506e7f8e84d1f2a26916 view
|
||
|
|
</pre>
|
||
|
|
<p>The Unix system password database is managed via the <a href="http://kb.iu.edu/data/anpn.html">PAM</a>
|
||
|
|
interface. The Windows ActiveDirectory password store is not currently supported.</p>
|
||
|
|
<p>The <em>AuthStore file</em> option specifies that passwords will be defined by the
|
||
|
|
<a href="dir/auth.html#user">User</a> 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 <em>appweb.conf</em>
|
||
|
|
master configuration file.</p>
|
||
|
|
<pre>
|
||
|
|
include auth.conf
|
||
|
|
</pre>
|
||
|
|
<a name="authpass"></a>
|
||
|
|
<h2 class="section">Password Program</h2>
|
||
|
|
<p>The <em>authpass</em> program supports the <em>internal</em> 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.</p>
|
||
|
|
<pre>
|
||
|
|
#
|
||
|
|
# 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
|
||
|
|
</pre>
|
||
|
|
<p>The <em>authpass</em> program will create and modify User directives in the authentication file.</p>
|
||
|
|
<p>The command line syntax for authpass is:</p>
|
||
|
|
<pre>
|
||
|
|
authpass [-c] [-p passWord] authFile realm username roles...
|
||
|
|
</pre>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>The Realm is the name used in the AuthRealm directive.
|
||
|
|
<p><b>SECURITY WARNING</b>: it is essential that the authentication file be stored outside
|
||
|
|
the Documents directory or any directory serving content.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<!-- BeginDsi "dsi/bottom.html" -->
|
||
|
|
<div class="bottom">
|
||
|
|
<p class="footnote">
|
||
|
|
<a href="../../../product/copyright.html" >© Embedthis Software LLC, 2003-2013.
|
||
|
|
All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.</a>
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<script src="http://www.google.com/jsapi" type="text/javascript"></script>
|
||
|
|
<script type="text/javascript">
|
||
|
|
google.load('search', '1', {language : 'en'});
|
||
|
|
google.setOnLoadCallback(function() {
|
||
|
|
var customSearchControl = new google.search.CustomSearchControl(
|
||
|
|
'000262706376373952077:1hs0lhenihk');
|
||
|
|
customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET);
|
||
|
|
var options = new google.search.DrawOptions();
|
||
|
|
options.enableSearchboxOnly("http://appwebserver.org/search.html");
|
||
|
|
customSearchControl.draw('cse-search-form', options);
|
||
|
|
}, true);
|
||
|
|
</script>
|
||
|
|
<script type="text/javascript">
|
||
|
|
var _gaq = _gaq || [];
|
||
|
|
_gaq.push(['_setAccount', 'UA-179169-2']);
|
||
|
|
_gaq.push(['_trackPageview']);
|
||
|
|
(function() {
|
||
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
||
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
||
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
||
|
|
})();
|
||
|
|
</script>
|
||
|
|
</body>
|
||
|
|
</html>
|