GD32F450_BMC_BaseCode/app/goahead-3.6.5/doc/contents/users/authentication.html

{
    title:  'User Authentication',
    crumbs: [
        { "User's Guide": '../users/' },
    ],
}
            <h1>User Authentication</h1>
            <p>Authentication is the process by which a client's identity and capabilities 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>GoAhead implements a powerful and flexible authentication framework that verifies username and password and
            verifies client capabilities using a role based authorization mechanism.</p>

            <h2>Authentication Schemes</h2>
            <p>GoAhead provides several authentication protocol schemes.</p>
            <ul>
                <li><a href="#form">Web Form Authentication</a></li>
                <li><a href="#basic">Basic Authentication</a></li>
                <li><a href="#digest">Digest Authentication</a></li>
            </ul>
            <p>The Form authentication scheme uses a HTML web form for the user to enter their username and password
                credentials and HTTP Post requests to submit to the server for verification. It may also be used
                programmatically va HTTP POST requests.</p>
            <p>

            <p>The 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 lower 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.</p>

            <div class="ui icon message">
                <i class="warning icon"></i>
                <div class="content">
                    <div class="header">SECURITY NOTE</div>
                    <p>You should only use Basic and Digest authentication as a last resort. Basic and Digest authentication
                    standards employ weak ciphers, repeatedly send credentials over the wire and and are not sufficiently
                    secure. Basic authentication transmits passwords as clear-text in each and every request. Digest
                    authentication uses the weak MD5 cipher, and both require use of SSL on all requests to be minimally
                    secure. Further, both Basic and Digest do not provide a reliable log out mechanism. Logout works on some
                    browsers but not on others or even different versions of the same browser. We strongly recommend
                    using Form authentication, with "blowfish" encryption for a more usable, secure and reliable 
                    solution.</p>
                </div>
            </div>

            <a name="configuration"></a>
            <h2>Configuration</h2>
            <p>Authentication is controlled by two configuration files:</p>
            <ul>
                <li><i>auth.txt</i> &mdash; which contains authorization directives</li>
                <li><i>route.txt</i> &mdash; which contains URI routing directives</li>
            </ul>
            <p>Together these two files define the authentication scheme to be used for each and every request to
            GoAhead. When GoAhead is run, the auth.txt and route.txt file are read and authenticated routes are created
            for each specified URI pattern. When client requests are received, they are matched against the URI routes
            to find the required authentication scheme. This enables great flexibility as different requests can use
            different authentication schemes.</p>

            <h3>Authorization Configuration</h3>
            <p>The <i>auth.txt</i> file contains <i>user</i> and <i>role</i> definitions to establish an authentication
            database. If running on a Unix system, the standard Unix user database may be used instead of defining users in
            <i>auth.txt</i>.</p>

            <h4>User directive</h4>
            <p>Users can be defined via the <i>user</i> directive. This specifies the username, encrypted password
            and the authentication roles played by the user.</p>
            
            <h4>Role directive</h4>
            <p>Roles can be defined via the <i>role</i> directive. This specifies the role name and a set of ability
            words. URI routes may require that a user has certain abilities before access is granted.</p>
            <pre class="ui code segment">
role name=manager abilities=view,edit,delete
user name=joshua password=2fd6e47ff9bb70c0465fd2f5c8e5305e roles=manager
</pre>
            <h3>Routing</h3>
            <p>The <i>route.txt</i> file contains <i>route</i> definitions that specify how each request URI will
            be processed and what, if any, kind of authentication will be required for the request. For example:</p>
<pre class="ui code segment">
route uri=/private/ auth=digest abilities=edit
route uri=/cgi-bin handler=cgi
</pre>
            <p>The <i>auth</i> keyword takes an argument set to <i>digest</i>, <i>basic</i> or <i>form</i>. The 
            <i>abilities</i> keyword takes a comma separated list of ability words.</p>


            <a id="form"></a>
            <h2 >Form Authentication</h2>
            <p>The Form authentication scheme uses a standard web page form that prompts for the user to enter their
            name and password. This scheme allows the user login interface to have the same look and feel as the rest of the
            web application. </p>
            
            <p>The Form authentication scheme submits the username and password  to GoAhead via a standard Http POST
            request. GoAhead 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. Because the username and password are sent in the clear, it is 
            important that Form authentication only be used over SSL connections.</p>
            <p>The form authentication scheme is enabled via the <i>auth=digest</i> keyword on required routes.
            For example:</p>
            <pre class="ui code segment">
route uri=/ auth=form handler=continue redirect=401@/login.html
</pre>
            <h3>Secure Form-based Authentication</h3>
            <p>To effectively secure an application using Form authentication requires five routes to implement
            the login and logout process. These are:</p>
            <ul>
                <li>Route to redirect all HTTP traffic over SSL</li>
                <li>Route for the login page which must be accessible when unauthenticated</li>
                <li>Route for the login service</li>
                <li>Route for the logout service</li>
                <li>Route to require authentication for all URIs</li>
            </ul>
            <p>For example:</p>
<pre class="ui code segment">
route uri=/ protocol=http redirect=*@https handler=redirect
route uri=/pub/
route uri=/proc/login methods=POST handler=proc redirect=200@/ redirect=401@/pub/login.html
route uri=/proc/logout methods=POST handler=proc redirect=200@/pub/login.html
route uri=/ auth=form handler=continue redirect=401@/pub/login.html
</pre>
            <h3>Redirect over SSL</h3>
            <pre class="ui code segment">route uri=/ protocol=http redirect=*@https handler=redirect</pre>
            <p>This directive is responsible for redirecting all HTTP traffic over SSL.
            The <i>uri=/</i> defines a URI prefix. Since all URIs start with <i>/</i>, this route will match all requests
            that use http:// and not https://.</p>


            <h3>Unauthenticated Access to the Login Page</h3>
            <pre class="ui code segment">route uri=/pub/</pre>
            <p>This directive permits unauthenticated access to any documents in the <i>/pub</i> directory. This is 
            where the <i>login.html</i> form and any required CSS or Javascript files should be located.</p>

            <h3>The Login Service</h3>
            <pre class="ui code segment">route uri=/proc/login methods=POST handler=proc redirect=200@/ redirect=401@/pub/login.html</pre>
            <p>This directive defines the login service route. The proc handler bind the login service to the URI 
            <i>/proc/login</i>. This service expects a POST request with username and password form fields. If the 
            user authenticates, the
            user is redirected via <i>redirect=200@/</i>. The redirection form is: STATUS@URI. If the user credentials
            cannot be authenticated successfully, the user is redirected back to the login page 
            via: <i>redirect=401@/pub/login.html</i>.</p>

            <h3>The Logout Service</h3>
            <pre class="ui code segment">route uri=/proc/logout methods=POST handler=proc redirect=200@/pub/login.html</pre>
            <p>This directive defines the logout service. This simply deletes the user's login session and redirects 
            the user back to the login page.</p>

            <h3>Authentication Required</h3>
            <pre class="ui code segment">route uri=/ auth=form handler=continue redirect=401@/pub/login.html</pre>
            <p>This final directive defines a route that matches all other URIs and stipulates form-based authentication.
            The <i>continue</i>
            handler authenticates the user and if the user is successfully authenticated, processing continues on 
            to let other handlers service the request and generate a response. If authentication fails, the user
            is redirected back to the login page.</p>

            <h3>Web Form</h3>
            <p>Here is a minimal example login form:</p>
            <pre class="ui code segment">
&lt;html&gt;&lt;head&gt;&lt;title&gt;login.html&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;
    &lt;p&gt;Please log in&lt;/p&gt;
    &lt;form name="details" method="post" <b>action="/auth/login"</b>&gt;
        Username &lt;input type="text" <b>name="username"</b> value=''&gt;&lt;br/&gt;
        Password &lt;input type="password" <b>name="password"</b> value=''&gt;&lt;br/&gt;
        &lt;input type="submit" name="submit" value="OK"&gt;
    &lt;/form&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
            <p>The two submitted fields must be named <em>username</em> and <em>password</em>. </p>
            <h3>Securing the Password</h3>
            <p><b>SECURITY WARNING:</b> The Form authentication scheme submits the user password as plain text. To secure
            communications, the Form authentication scheme should be used over a secure connection using TLS/SSL.</p>

            <a name="basic"></a>
            <h2>Basic Authentication</h2>
            <p>Basic authentication was the original HTTP/1.0 authentication scheme. It captures usernames and
                passwords via a fixed browser-based popup dialog and then transmits credentials
                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. It transmits
                user credentials with each request, has no encryption for the password and does not have a means
                for users to reliably logout. If you must use Basic Authentication, use it over
                TLS/SSL which will encrypt the password over the wire.</p>

            <h3>Basic Authentication Directives</h3>
            <p>GoAhead basic authorization is defined by specifying <i>auth=basic</i> in the required routes in 
            <i>route.txt</i>. For example:</p>
<pre class="ui code segment">
# In auth.txt
role name=operator abilities=start,stop
user name=julie password=9d8873a123eb506e7f8e84d1f2a26916 roles=operator
# In route.txt
route uri=/machinery auth=basic abilities=start,stop
</pre>
            <p>This example restricts access to URIs beginning with "/machinery". It permits access to the users with
            the <i>start, stop</i> abilities. This means that the user "julie" will be granted access once authenticated.</p>

            <p>The <i>auth=basic</i>keyword specifies that basic authorization is being
            used. The Authentication Realm used by Basic and Digest authentication is set when GoAhead is built via
            the <em>realm</em> property in the main.me configuration file.  The realm is used in combination with 
            the username and password to encrypt the password.</p>

            <a id="digest"></a>
            <h2>Digest Authentication</h2>
            <p>The Digest authentication scheme
            cryptographic techniques is a minor improvement over the Basic scheme. It captures usernames and
            passwords via a fixed browser-based popup dialog and then transmits credentials
            using the weak MD5 encoding format.</p>

            <p><b>SECURITY WARNING</b>: You should not use Digest Authentication if at all possible. It transmits
                user credentials with each request, has weak encryption for the password and does not have a means
                for users to reliably logout. If you must use Digest Authentication, use it over
                TLS/SSL which will securely encrypt the credentials over the wire.</p>

            <p>GoAhead digest authorization is very similar to Basic authentication and is 
            is controlled by the <i>auth=digest</i> keyword on required routes.</p>


            <a id="stores"></a>
            <h2 >Password Stores</h2>
            <p>GoAhead can be built to retrieve passwords from the Unix system password database or from password text
            configuration file. 
            The Unix system password database is managed via the <a href="http://kb.iu.edu/data/anpn.html">PAM</a> 
            interface. GoAhead can be configured to use PAM with the command:</p>
            <pre class="ui code segment">configure --set pam=true</pre>

            <h3>Determining Abilities with PAM</h3>
            <p>When using PAM, <i>user</i> records are not required in auth.txt. However, to determine the users's
            abilities, the Unix group membership for the user and role definitions are used. For each Unix group that
            the user is a member of, a corresponding <i>role</i> in auth.txt is checked. If a role of the same name as the
            group exists, the abilities specified by that role are added to the set of abilities for the user. In other
            words, you should create a role definition for each group in <i>auth.txt</i> that will specify the abilities for
            users in that Unix group. For example, say a user joshua was a member of the Unix group "staff". The following
            auth.txt definitions would give joshua the abilities: <i>add,edit,delete</i>.</p>
            <pre class="ui code segment">
Role staff add,edit,delete
</pre>

            <a name="gopass"></a>
            <h2 >Password Program</h2>
            <p>To create the required encrypted password fields for <i>user</i> definitions, the  <em>gopass</em> program
            is used. It can generate passwords and edit the <i>auth.txt</i> with updated user definitions.
            The command line syntax for gopass is:</p>
            <pre class="ui code segment">
gopass [--cipher cipher] [--file path] [--password password] realm user roles...
</pre>
            <p>The file parameter specifies the name of the authentication file which is typically "auth.txt".
            If the --file option is omitted, the calculated hash for the password will be displayed to the console.
            If the --password option is omitted, gopass will prompt for the password. 
            The realm is the name specified by the <em>realm</em> property in the main.me configuration
            file when GoAhead was built. It defaults to: "example.com". You may set this to any string you like. 
            If you are using Basic or Digest authentication, this string will be displayed at the top of the login 
            popup dialog. If using Form authentication, it is never displayed to the user and is only used to salt 
            the encryption of the passwords.</p>

            <p>The gopass program supports the MD5 and Blowfish ciphers. MD5 must be used if you are using digest
            authentication. If using a web-based authentication scheme, it is strongly advised that you use the 
            blowfish cipher as it is much more resistant to cracking the password hashes.</p>

            <p><b>SECURITY WARNING</b>: it is essential that the authentication file be stored outside
            the DocumentRoot or any directory serving content.</p>